DND Engine Registry
Module Registry / enemy_encounter

enemy_encounter

Registers under Enemy Encounters · source: modules/enemy_encounter/v1

`race_id` must reference an enemy-only (`playerSelectable: False`) Race record — this module doesn't enforce that cross-reference itself (see toolchain-architecture.md → Open Items: "Content validation pass" is still an unresolved separate concern). `level` is this encounter's own difficulty dial — shown to players and usable for future level-gating, a categorical/display concern rather than a computed combat stat, same spirit as a dungeon's own `difficulty`. `resistances` maps a resistanceGroupId or individual DamageType id to a Resistance% contribution — same shape as armor's, resolved via engine.damage_types.total_resistance. `weapon_exp_granted` feeds a weapon's `gearEXP` when this encounter is defeated (see combat-engine-readme.md → Weapon and Armor Leveling) — same generic action-tag pattern used for Stat EXP, just keyed to combat outcome instead of a player action. Schema-allowed (2026-10-14) so a Pipeline-rolled value survives a rebuild — in practice it's rolled from a `level`-scaled baseline times content/tuning.py's enemyExpGrantedMultiplierRange (see registry_site/pipeline.py), clamped here to VALID_WEAPON_EXP_GRANTED_RANGE as a backstop rather than protected by exclusion, same shape as weapon's damage_multiplier. `world_boss_min_level`, if set, marks this encounter as a World Boss and is its per-boss minimum character-level gate (see combat-engine-readme.md → Content Access by Level: "individual World Bosses come in different tiers, each with its own minimum character-level requirement" — checked via gamemaster.engine.dungeon.can_join_world_boss, see bot/cogs/ worldboss.py). None (the default) means a regular, non-World-Boss encounter — nothing else in content sets this today. `icon_id` (2026-10-13): the filename stem of this encounter's portrait in assets/enemies/ (see bot/enemy_icons.py) — pure display data, used by bot/duel_status_image.py's live-duel combat render. Several encounters can share one piece of art (same convention as item icon_id — see assets/items/README.md), e.g. every goblin-race trash encounter pointing at the same "goblin" icon while a boss gets its own. Empty (or no such file) falls back to a generated placeholder.

Example Usage

# Migrated from content/enemies/goblin_chieftain.py (2026-10-14) -- see
# content/enemies/goblins.resource's own header comment for what makes
# this reachable as a trusted .resource file.
#
# The first `isBoss`-tagged encounter -- see gamemaster/engine/dungeon.py's
# is_boss_encounter/is_world_boss_encounter. Attacks with `blunt` rather
# than the other goblins' `piercing` -- was originally chosen so a player
# wearing leather_chestplate (piercing-only resistance) got none of its
# usual mitigation here, demonstrating Typed Resistance actually
# mattering. leather_chestplate lost its resistances entirely once
# converted to .resource (resistances aren't community-settable), so
# that specific demonstration no longer holds; left as `blunt` anyway
# since it's still a harmless, reasonable choice for a goblin leader's
# weapon.

resource "goblin_chieftain" {
  source: modules/enemy_encounter/v1
  id: "goblin_chieftain"
  race_id: "goblin"
  level: 4
  evasiveness: 15.0
  resistances: {piercing: 10.0, blunt: 5.0}
  agility: 9.0
  attack_hitdie: {diceCount: 2, dieSize: 6}
  attack_to_hit_percent: 60.0
  attack_relevant_stat: 16.0
  attack_luck: 5.0
  attack_damage_type_id: "blunt"
  # loot_table was ["chieftain_signet"] -- an accessory removed in an
  # earlier content trim, dangling ever since (flagged 2026-10-13,
  # cleared 2026-10-17). Empty until real boss-tier loot exists.
  loot_table: []
  weapon_exp_granted: 25.0
  description: "A hulking goblin chieftain, warhammer in hand -- the stronghold's boss."
  icon_id: "goblin_brute"
}

Arguments Reference

The following arguments are supported:

  • id - (Required) The unique id this record is registered and referenced under — what a `.resource` file's own filename-independent identity is, and what any other content's foreign-key-style field (a dungeon node's `next`, a skill node's `parent_id`, and so on) points at. community
  • race_id - (Required) `race_id` must reference an enemy-only (`playerSelectable: False`) Race record — this module doesn't enforce that cross-reference itself (see toolchain-architecture.md → Open Items: "Content validation pass" is still an unresolved separate concern). community
  • level - (Required) `level` is this encounter's own difficulty dial — shown to players and usable for future level-gating, a categorical/display concern rather than a computed combat stat, same spirit as a dungeon's own `difficulty`. community
  • evasiveness - (Optional) Defaults to 0.0. developer
  • resistances - (Optional) `resistances` maps a resistanceGroupId or individual DamageType id to a Resistance% contribution — same shape as armor's, resolved via engine.damage_types.total_resistance. Defaults to None. developer
  • agility - (Optional) Defaults to 5.0. developer
  • attack_hitdie - (Optional) Defaults to None. developer
  • attack_to_hit_percent - (Optional) Defaults to 50.0. developer
  • attack_relevant_stat - (Optional) Defaults to 5.0. developer
  • attack_luck - (Optional) Defaults to 0.0. developer
  • attack_damage_type_id - (Optional) Defaults to None. community
  • loot_table - (Optional) Defaults to None. community
  • weapon_exp_granted - (Optional) `weapon_exp_granted` feeds a weapon's `gearEXP` when this encounter is defeated (see combat-engine-readme.md → Weapon and Armor Leveling) — same generic action-tag pattern used for Stat EXP, just keyed to combat outcome instead of a player action. Defaults to 0.0. community
  • world_boss_min_level - (Optional) `world_boss_min_level`, if set, marks this encounter as a World Boss and is its per-boss minimum character-level gate (see combat-engine-readme.md → Content Access by Level: "individual World Bosses come in different tiers, each with its own minimum character-level requirement" — checked via gamemaster.engine.dungeon.can_join_world_boss, see bot/cogs/ worldboss.py). Defaults to None. developer
  • description - (Optional) Flavor text shown to players — pure display data with no effect on game mechanics. community
  • icon_id - (Optional) `icon_id` (2026-10-13): the filename stem of this encounter's portrait in assets/enemies/ (see bot/enemy_icons.py) — pure display data, used by bot/duel_status_image.py's live-duel combat render. community