Enemy Archetypes, Combat Kits, And Named Encounters

What This System Is

The enemy-content system composes existing mob visuals, attacks, stats, loot, spawn geometry, and encounter lifecycle rules into reusable gameplay roles. A mob definition still owns its presentation and concrete attacks. An enemy archetype assigns that mob a level, combat kit, tags, passive metadata, and status immunities. A combat kit decides which authored mob attack is appropriate for the current range and health state. A named encounter arranges archetypes into ordered waves and carries encounter-level difficulty and reward metadata.

The shared domain owns parsing, validation, deterministic action selection, wave expansion, and difficulty summaries. The game server repeats cross-catalog validation, hydrates archetypes into authoritative mob projections, chooses attacks during authoritative contact damage, enforces status immunities, and spawns named waves through the existing scene-spawner safety and population policies.

How Authors Use It

Edit assets/gameplay/enemy_content_catalog.json. Keep visual and concrete combat numbers in the existing mob catalog. Add an archetype when that mob should have a tactical identity, then point it at a reusable combat kit. Add encounter definitions when a composition should be addressable as an ordered set of waves.

Combat-kit rules refer to attack ids already declared by the archetype's mob_id. Higher priority wins. Rules at the same priority use deterministic weighted selection. Range and health thresholds remove ineligible rules before selection. Mobs without an archetype continue using the first contact or melee attack, preserving existing content.

The Mob Catalog Workbench shows the selected mob's archetype, level, combat kit, tactical role, and named-encounter usage count. The runtime hot-reload lane reloads enemy content atomically with abilities, status effects, and passives.

To bind a scene spawner to a named wave, add encounter:<encounter id> and wave:<zero-based index> to its existing tags. For example, encounter:encounter.starter_roadblock,wave:0 makes the normal server spawn path expand the first authored wave through that spawner. The scene spawner remains responsible for activation, lifecycle, memory scope, bounds, safety, and population cap.

Rules And Invariants

• Archetype, combat-kit, encounter, and wave ids are unique and case-insensitive.
• Every archetype references an existing mob and combat kit.
• Every combat-kit action references an attack on the archetype's mob definition.
• Action weights are positive, ranges are ordered, and health thresholds are between zero and one hundred.
• Every named encounter has at least one non-empty wave, and every wave references known archetypes with positive counts.
• Attack choice is deterministic for the same actor, decision sequence, kit, and range.
• Named waves reuse scene-authored bounds, walkability, occupancy, population caps, actor ids, and server authority. They do not bypass the existing encounter lifecycle.
• Missing archetypes are backward compatible and use legacy contact-attack selection.
• Status immunities are checked before ability, legacy proc, or passive-proc status application.

Validation And Debugging

Catalog parsing performs structural validation first. Server loading then checks mob ids, mob attack ids, passive ids, and status-effect ids against the authoritative catalogs. Invalid references become required catalog-health failures.

When an attack is selected, server debug logs include actor id, selected action id, combat kit, archetype, and the decision explanation. If an enemy cannot attack, inspect its kit conditions, current range, health thresholds, and concrete mob attack range. If a named wave spawns fewer actors than authored, inspect the linked scene spawner's concurrent population cap and spawn safety diagnostics.

Use the shared difficulty summary for tooling: it reports wave count, total enemy count, total level budget, peak wave level budget, recommended level, and authored difficulty rating.

Examples

The shipped encounter.starter_roadblock has two waves. The first spawns two slippery-slime skirmishers. The second spawns a wayward-wasp diver and greedy-gremlin brawler. The slime kit uses slime_spurt against a target at forty percent health or below, otherwise uses slime_spit at range and slick_bump up close.

{
  "id": "kit.slime.skirmisher",
  "role": "skirmisher",
  "target_priority": "lowest_health",
  "actions": [
    {
      "action_id": "slime_spurt",
      "priority": 30,
      "min_range_tiles": 2,
      "max_range_tiles": 4,
      "target_health_below_percent": 40
    }
  ]
}

Related Systems

• Mob Encounters And Scene Combat
• Passive Traits And Procs
• Status Effects And Combat Modifiers
• Character Stats And Equipment Modifiers
• Game Data Catalog