Creatures

Creatures are hostile entities that players can attack to initiate turn-based combat. They have health, attack power, and can drop loot when defeated.

Schema

"creature_id": {
  "name": "Cave Troll",
  "description": "A massive troll with stone-like skin.",
  "keywords": ["troll", "monster"],
  "health": 30,
  "attack": 8,
  "defense": 2,
  "hostile": true,
  "talk_text": "The troll grunts at you, clearly unimpressed.",
  "aggro_text": "The Cave Troll roars and lunges at you!",
  "attack_condition": { "moves": 3 },
  "on_defeat_msg": "The troll crashes to the ground with a thunderous boom!",
  "on_flee_msg": "The troll roars as you escape!",
  "loot": ["troll_gem", "troll_club"],
  "sets_flag_on_defeat": "troll_slain"
}

Fields

Field	Type	Default	Description
`name`	string	required	Display name shown to the player.
`description`	string	required	Text shown when the player examines the creature.
`keywords`	array	`[]`	Alternative names for fuzzy matching.
`health`	number	required	Maximum hit points. This is both starting and max HP.
`attack`	number	`5`	Base attack power. Actual damage = attack + rand(-2..2) - player defense.
`defense`	number	`0`	Defense value subtracted from player's attack damage.
`hostile`	boolean	`false`	If `true`, the creature can auto-attack the player. See Hostile Creatures.
`talk_text`	string	—	What the creature "says" when the player uses `talk to [creature]`. Defaults to "It has no clue what you're saying."
`aggro_text`	string	—	Message shown when a hostile creature begins attacking. Defaults to "The [name] attacks you!"
`attack_condition`	object	—	When a hostile creature auto-attacks. See Attack Conditions.
`movement`	object	—	Optional patrol or triggered movement. See Movement on the NPCs page — the schema is identical.
`on_defeat_msg`	string	—	Custom message displayed when the creature is defeated.
`on_flee_msg`	string	—	Custom message displayed when the player flees from combat.
`loot`	array	`[]`	Array of item IDs dropped into the room when the creature is defeated.
`sets_flag_on_defeat`	string	—	Global flag set to `true` when the creature is defeated.

Talking to Creatures

Creatures don't have dialogue trees like NPCs, but the player can still talk to [creature]. The engine responds with the creature's talk_text — useful for flavor, warnings, or hostile creatures with an on_talk attack condition.

"tavern_rat": {
  "name": "Tavern Rat",
  "description": "A fat, lazy rat lounging near the fireplace.",
  "keywords": ["rat", "tavern rat"],
  "health": 3,
  "attack": 1,
  "talk_text": "The rat squeaks and twitches its whiskers at you."
}

NPC priority:

If a room contains both an NPC and a creature matching the same keyword, the NPC wins — talk to bob always prefers an NPC named Bob over a creature named Bob the Beast.

Hostile Creatures

Set "hostile": true to let a creature auto-attack the player without waiting to be attacked first. After every player action in the same room, the engine checks whether the creature should initiate combat.

1. The player takes any action (look, take, go, talk, etc.)

2. The engine checks each hostile creature in the current room

3. If the creature's attack_condition is met (or there is none), it initiates combat

4. The aggro_text is displayed, then initiative is rolled

Non-hostile creatures:

A creature without hostile: true will never initiate combat on its own. The player must attack it directly.

Attack Conditions

An attack_condition controls when a hostile creature actually attacks. Without one, a hostile creature attacks on the very first player action in the room.

// Attack after the player has taken 3 actions in the room
"attack_condition": { "moves": 3 }

// Attack the second time the player enters the room
"attack_condition": { "room_entries": 2 }

// Attack only when the player tries to talk to the creature
"attack_condition": { "on_talk": true }

Condition	Type	Behavior
`moves`	number	Creature attacks after the player has taken at least this many actions in the current room. Lets the player look around and prepare first.
`room_entries`	number	Creature attacks once the player has entered the room at least this many times. Useful for "first visit is safe" encounters.
`on_talk`	boolean	Creature only attacks when the player `talk`s to it. Great for a creature that you can try to parley with, but that turns hostile when provoked.

Only one condition type is evaluated per creature. If an unknown key is set, the creature defers attacking indefinitely.

Balancing Combat Stats

Damage formula:

// Creature attacking player:
damage = creature.attack + rand(-2..2) - player_defense
damage = [damage, 1].max  // minimum 1 damage

// Player attacking creature:
damage = 5 + weapon_damage + rand(-2..2) - creature.defense
damage = [damage, 1].max  // minimum 1 damage

Player base attack: 5 (hardcoded)

Player starting HP: 10 (default)

Variance: -2 to +2 on each attack

Minimum damage: 1 (always deal at least 1 HP)

Example Difficulty Tiers

Tier	Health	Attack	Defense	Notes
Easy	10-15	3-5	0	Beatable without weapons
Medium	20-30	5-8	1-2	Weapon recommended
Hard	40-60	8-12	3-5	Needs good gear + potions
Boss	80+	12+	5+	Bring everything you've got

Loot System

When a creature is defeated, all items in its loot array are dropped into the current room. Players can then take them normally.

// The items must be defined in the top-level "items" object
"loot": ["dragon_scale", "gold_coins"]

Loot items should be defined in your items object but don't need to be placed in any room initially — they'll appear when the creature drops them.

Example

"forest_spider": {
  "name": "Giant Forest Spider",
  "description": "A spider the size of a dog, with dripping fangs and eight gleaming eyes.",
  "keywords": ["spider", "giant spider"],
  "health": 15,
  "attack": 4,
  "defense": 0,
  "hostile": true,
  "talk_text": "The spider hisses at you menacingly.",
  "aggro_text": "The Giant Forest Spider lunges at you!",
  "attack_condition": { "moves": 3 },
  "on_defeat_msg": "The spider curls up and stops moving. A silk-wrapped bundle falls from its web.",
  "on_flee_msg": "You stumble backward through the webs as the spider hisses.",
  "loot": ["spider_silk"],
  "sets_flag_on_defeat": "spider_cleared"
}

The player enters the room, has three turns to look around, grab items, or prepare, and on the fourth action the spider attacks.