# 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