draugnorak/AGENTS.md

Draugnorak Project Guidelines

Engine Reference

• If unsure about NVGT behavior or API details, consult the engine source in nvgt-git/.

Asset Usage

CRITICAL: The bloodshed/ directory is for reference only. DO NOT use any assets from the bloodshed directory in this game. It exists solely to help with coding examples and understanding patterns, but none of its files should be included or referenced in the actual game code.

Project Structure

• src/ - Game source code modules
  • constants.nvgt - Game configuration and constants
  • player.nvgt - Player state and global timers
  • world_state.nvgt - World object orchestration (legacy coordinator, modules are in src/world/ and src/enemies/)
  • item_registry.nvgt - Item definitions and inventory arrays
  • inventory_items.nvgt - Equipment, quick slots, stack limits
  • inventory_menus.nvgt - Menu orchestrator for inventory/storage/equipment/actions
  • crafting.nvgt - Crafting orchestrator
  • quest_system.nvgt - Quest queue + mini-game menu
  • bosses/adventure_system.nvgt - Adventure menu + boss routing
  • inventory.nvgt - Inventory system orchestrator (item registry, menus, crafting, runes)
  • environment.nvgt - Trees, climbing, falling damage, rope climbing, and environmental interactions
  • combat.nvgt - Combat system (spear/axe/sling)
  • time_system.nvgt - Time, day/night, invasions, expansions, blessings, weather ticks
  • weather.nvgt - Wind/rain/thunder ambience system
  • save_system.nvgt - Save/load (AES encrypted, versioned)
  • base_system.nvgt - Base automation (residents, food, defense, collection)
  • ui.nvgt - UI helpers, terrain lookup
  • audio_utils.nvgt - Audio helper functions
  • creature_audio.nvgt - Creature voice/footstep/attack audio helpers
  • notify.nvgt - Notification system (queue + history)
  • speech_history.nvgt - Screen reader message history (comma/period navigation)
  • text_reader.nvgt - Accessible text reader window
• src/world/ - World objects
  • world_fires.nvgt, world_snares.nvgt, world_drops.nvgt
  • world_buildings.nvgt - Firepit, Herb Garden, Storage, Pasture, Stable, Altar
  • world_streams.nvgt - Streams + water audio
  • mountains.nvgt - Mountain ranges, elevation, streams
  • barricade.nvgt - Base barricade health and reinforcement
• src/enemies/ - Enemies and creatures
  • undead.nvgt (zombies), bandit.nvgt (invasions/wandering), ground_game.nvgt (boars), flying_creatures.nvgt (geese)
• src/crafting/ - Crafting categories and recipes
  • crafting_core.nvgt, craft_weapons.nvgt, craft_tools.nvgt, craft_materials.nvgt, craft_clothing.nvgt, craft_buildings.nvgt, craft_barricade.nvgt, craft_runes.nvgt
• src/menus/ - Menu subsystems (inventory, storage, equipment, action, base info, altar, character info)
• src/runes/ - Rune data + effects
• src/quests/ - Quest mini-games
• src/bosses/ - Adventure/boss encounters
• sounds/ - Game audio assets
• draugnorak.nvgt - Main game file

Game Mechanics

Inventory Limits

• Personal inventory stacks are capped at 9
• Skin pouches add +2 stack capacity, backpacks add +9

Map Layout

• Base area: x 0-4 (wood terrain)
• Grass area: x 5-19 (grass terrain, contains trees)
• Gravel area: x 20-34 (gravel terrain, contains stones)

Healing System

• Base area provides passive healing when player health < max
• Without herb garden: 1 HP every 2.5 minutes (150000ms)
• With herb garden: 1 HP every 30 seconds (30000ms)
• Herb garden can only be built in base area (x <= 4)
• Only one herb garden allowed per base

Fire System

• Fires require a firepit to build
• New fires start with 12 minutes (720000ms) of fuel
• Warning at 30 seconds remaining
• Fire goes out when fuel depletes
• Fire sound plays within 3 tiles distance
• Jumping over fire prevents damage
• Feeding fire is done from the Action menu (A)

Snare System

• Snares become active when player moves away
• Check every hour for catching/escaping small game
• Catch chance starts at 5%, increases by 5% per hour (max 75%)
• Escape chance: 0% for first hour after catch, then increases by 2% per hour (max 95%)
• Snare sound plays within 2 tiles distance
• Residents can retrieve game from snares (daytime only, requires meat in storage)

Tree System

• Trees regenerate fully after ~5 minutes (minute-by-minute refill logic)
• Tree ambient sound plays within 4 tiles distance
• Trees only play sound when not chopped
• Climb down only when in a tree (Down arrow does nothing during jumps or when not in a tree)
• Trees have height; falling damage is applied when falling from height

Notification System

• Important events use notify() function (plays sounds/notify.ogg + speaks message)
• Last 10 notifications stored in history
• Navigation keys:
  • \ - Repeat most recent notification
  • ] - Next (newer) notification
  • [ (Shift+Comma) - Previous (older) notification
• Navigating history speaks message without notification sound
• Speech history (screen_reader_speak wrapper) uses , and . for previous/next message

Search System

• Hold Shift for 1 second to search
• Search completes after 1-second delay

Undead System

• At night, zombies spawn (5 max) and wander outside the base
• Zombies cannot enter the base while barricade health > 0
• Zombies attack the barricade for 4-6 damage when they reach it; play sounds/enemies/zombie_hit.ogg
• Zombies vanish at daybreak
• Player can hit zombies with spear (1-tile range) or sling (8-tile range)

Barricade System

• Base starts with 100 barricade health, capped at 500
• In base, press B to report barricade health
• Crafting menu includes Barricade category for reinforcement
• Reinforcement costs and health: 3 sticks (+10), 5 vines (+15), 1 log (+30), 5 stones (+20)
• Barricade health does not reset during gameplay

Mountains, Rope Climbing, Falling

• Mountain ranges can appear during area expansion with elevation-based terrain
• Steep slopes require a rope; the player is prompted to press Up/Down to climb
• Moving left/right during rope climb cancels and causes a fall
• Falling damage is applied beyond a safe height (10 feet)

World Expansion & Invasions

• After day 2, bandit invasions can trigger and expand the map to the east
• Expansion is either a 30-tile biome strip or a 60-tile mountain range
• Invasions last 1 hour and spawn bandits in the expanded area during daytime

Weather & Ambience

• Weather transitions between clear, windy, rainy, stormy with wind/rain/thunder audio
• Day/night ambience crossfades on hour changes

Inventory + Equipment

• Item definitions live in src/item_registry.nvgt (personal + storage inventories)
• Equipment includes spear, axe, sling, bow, clothing, pouches, backpacks
• Combat logic currently supports spear/axe/sling; bow attacks are not implemented yet
• Quivers gate arrow capacity (12 arrows per quiver)
• Quick slots (keys 1-0) bind equipment from the Equipment menu

Buildings

• Firepit, Fire, Herb Garden, Storage, Pasture, Stable, Altar
• Storage enables base inventory menus and increases resident recruitment chance

Residents and Base Automation

• Residents consume meat daily, can repair the barricade, defend with stored weapons, and collect resources
• Residents use spears or slings (requires stones) for defense
• Daily weapon breakage occurs based on resident count

Favor, Altars, Incense, Blessings

• Altar sacrifices (S key, base only) convert items to Favor
• Burning incense (A key action) grants Favor per hour while active
• Blessings can trigger (heal, speed boost, barricade repair) and consume Favor

Quests (Mini-Games)

• Quest menu (Q, base only) appears after altar/favor requirements
• Max 4 active quests; rewards grant Favor and resources

Adventures & Bosses

• Adventure menu (Tab) available outside base; limited to once per day
• Mountain adventure: Unicorn boss; victory grants Favor and unlocks Rune of Swiftness

Runes

• Rune system in src/runes/ (data + effects)
• Runes are crafted in Crafting > Runes after unlock (requires knife + clay + favor)
• Rune of Swiftness grants move speed and gathering bonuses; runed items are tracked separately

Menu Structure

Crafting Menu (C key, base only)

Organized into categories:

• Weapons: Spear, Sling
• Tools: Knife, Snare, Stone Axe, Fishing Pole, Rope, Reed Basket, Clay Pot
• Materials: Butcher Game, Incense
• Clothing: Skin gear, Moccasins, Pouch, Backpack
• Buildings: Firepit, Fire, Herb Garden, Storage, Pasture, Stable, Altar
• Barricade: Reinforcement options
• Runes: Available after rune unlocks

Equipment Menu (E key)

• Only shows items player actually has
• Shows equipped status
• Says "Nothing to equip" if inventory is empty

Inventory Menu (I key)

• Base + storage built: root menu for personal vs storage
• No storage: personal inventory only

Action Menu (A key)

• Place snares, feed fires, burn incense (context-sensitive)
• Tab in menu performs “max” action for the selected option

Base Info (B key)

• Barricade health, residents, storage totals, base buildings

Quest Menu (Q key)

• Base-only quest selection for mini-games

Adventure Menu (Tab key)

• Terrain-based adventures outside the base (once per day)

Testing

• Always run ./nvgt -c draugnorak.nvgt after code changes
• This compiles without opening the game window and prevents it from taking over the terminal

Code Standards

• Use notify() for important game events that should be reviewable
• Use screen_reader_speak() for immediate feedback that doesn't need to be stored
• All menus must call menu_background_tick() each loop to keep game state updating
• Time references: When discussing time (hours, minutes, days), assume game time unless explicitly stated as "real time". Game time runs at 60x speed: 1 real minute = 1 game hour, 24 real minutes = 1 game day.
• See docs/patterns.md for module and creature patterns
• See docs/rune_system.md for rune data/effects/save requirements