Combat

The combat system is turn-based with initiative rolls, attack/defend/flee actions, weapon bonuses, and healing items. Combat starts when a player attacks a creature.

Starting Combat

Combat begins when the player types attack [creature]. The engine then:

1. Finds the creature in the current room
2. Initializes player health if not already set (default: 10 HP)
3. Rolls initiative for both sides (1d20 each)
4. Whoever rolls higher goes first
5. If the creature wins initiative, it immediately attacks

Combat Actions

During combat, the player's commands are restricted to combat-related actions:

Command	Effect
attack	Attack the creature. Damage = 5 + weapon_damage + rand(-2..2) - creature defense. Creature counterattacks.
defend / block / guard / parry	Raise your guard. Adds +3 to defense for this round. Creature still attacks but deals less damage.
flee / run / escape / retreat	50% chance to escape. On failure, creature gets a free attack.
use [item]	Use a combat item (e.g., healing potion). Creature counterattacks after.
inventory	Check your inventory (no turn cost).
examine [target] / look	Examine something (no turn cost).

Damage Calculation

Player Attacking

base_attack      = 5
weapon_bonus     = max(weapon_damage from inventory items)
variance         = rand(-2..2)
creature_defense = creature.defense

damage = base_attack + weapon_bonus + variance - creature_defense
damage = max(damage, 1)  // always at least 1

Creature Attacking

creature_attack  = creature.attack  // default: 5
variance         = rand(-2..2)
player_defense   = sum(defense_bonus from inventory items)
defending_bonus  = 3 if player used "defend", else 0

damage = creature_attack + variance - player_defense - defending_bonus
damage = max(damage, 1)  // always at least 1

Weapon & Armor Bonuses

Using Items in Combat

Items with combat_effect can be used during combat. Currently only "heal" is supported.

// Using a health potion in combat:
// 1. Player uses the item
// 2. Health is restored (capped at max_health)
// 3. Item is consumed if consumable: true
// 4. Creature counterattacks

"health_potion": {
  "name": "Health Potion",
  "consumable": true,
  "combat_effect": {
    "type": "heal",
    "amount": 15
  }
}

Using an item in combat costs your turn — the creature gets to attack afterward.

Fleeing

Creature Defeat

When a creature's HP reaches 0:

1. The on_defeat_msg is displayed (if set)
2. All loot items are dropped into the current room
3. The creature is removed from the room
4. The sets_flag_on_defeat flag is set (if specified)
5. Combat ends

Player Death

When the player's HP reaches 0:

1. A game over message is displayed
2. The game enters pending_restart mode
3. The player is prompted to restart the game

Combat Flow Diagram

Player types: "attack goblin"
         |
    [Initiative Roll]
    Player: 1d20    Creature: 1d20
         |
    Higher goes first
         |
    +-----------+
    | COMBAT    |
    | ROUND     |
    +-----------+
         |
    Player chooses action:
    |             |           |            |
  ATTACK       DEFEND       FLEE       USE ITEM
    |             |           |            |
  Deal dmg    +3 defense   50/50       Heal/effect
    |             |         /    \          |
    |             |     Escape  Fail       |
    |             |       |      |         |
    +------+------+       |   Free atk    |
           |              |      |         |
    Creature attacks      End    |         |
           |              combat |         |
    Check player HP        +-----+---------+
           |                     |
    Dead? --YES--> Game Over + Restart
           |
    Check creature HP
           |
    Dead? --YES--> Victory + Loot
           |
    Next round...