Home Complete Combat System Reference

Complete Combat System Reference

How combat works in the current revision: pools, defense, abilities, damage types, status effects, heals, timers, loadouts, rotations, and wildlife AI.

Deep dives: Active stats & damage, Runtime architecture §3.8, Aggro & leash, Status effects, NPC lifecycle.

11.1 Target slots

Players have T1 (primary) and T2 (secondary) — PLAYER_TARGET_SLOT_CAP = 2.

Input (gfx) Result
Left-click attackable NPC Set T1
Shift+left-click Set T2
Tab / Shift+Tab Cycle T1 / T2
Clear binds Clear slot

Filters: hostile / friendly / all (heal slots use friendly/self).

11.2 Capability layers

flowchart TB subgraph t1 [T1 primary] mh[Mainhand weapon_ability] auto1[Auto toggle r] pursue[Auto-pursue when out of band] end subgraph slots [T1/T2 bindings] rot[Rotation preset steps] autoN[Per-slot auto Shift+r] end subgraph manual [Manual] hotbar[Hotbar 1-9 Cast] dodge[Dodge / Block] end mh --> resolve[Resolver] rot --> resolve hotbar --> resolve

Rules

  • Slot-1 auto always uses equipped mainhand ability (or unarmed).
  • Only T1 auto-attack drives auto-pursue.
  • Manual casts fail loudly when out of range / no LoS / on CD / OOM — no silent fallback.
  • Pursue band: advance if too far; hold if in band or inside range_min_m (no forced backpedal).

11.3 Loadout (l)

Assign which rotation preset is bound to T1 / T2, and whether auto is on. Persisted on StoredCombatProfile (immediate sync + checkpoint).

11.4 Rotation editor (o)

Presets are ordered ability id lists (plus conditions via gates like HP% / required status). Max 12 presets. Mind / slot scoring uses combat.rotation_mind.* in server settings. Only auto-rotation-eligible abilities may be saved in a preset (see §5.2 rotation_in_auto); the picker hides ineligible ids.

Example mental model

  1. T1 + melee preset + auto + pursue → walk into sword range and swing
  2. T2 + support preset targeting self → auto heal_touch when HP < 90%
  3. Hotbar 3 → manual fireball when you want burst

11.5 Macros

ExecuteMacro expands named openers (e.g. burst_opener) into ordered intents.

12.1 Spawn & roam

Segment YAML wildlife_spawns place anchors (npc_ref, x/y, radius_m, count). Instances scatter in the disk. Behavior YAML / spawn movement.mode: wander with boundary_radius_m keeps idle roam near home.

NPC defs need kind: wildlife, combat block, loot, behavior_ref, and pools.hp: true.

12.2 Predator FSM

Plugin predator_fsm (wolf, goblin, shadow stalker, spider with wolf-style behavior):

stateDiagram-v2 [*] --> idle idle --> alert: see_prey alert --> chase: in_range chase --> combat: in_attack_range combat --> chase: out_of_melee alert --> return: home_leash chase --> return: home_leash_or_lost combat --> return: home_leash_or_dead return --> idle: arrived_home return --> alert: see_prey_near_home
Field Meaning
aggro_radius_m Detection / acquire
leash_radius_m Max distance of NPC or focus from home while fighting; 0 → ≈ max(aggro×2, 12)
abilities Ordered NPC ability ids (empty = no attack). Range comes from the abilities.

Leash break: clear threat table, clear target, path home, resume wander.

Passive critters (flee_on_damage) use flee utility instead of chase.

12.3 Threat table

flowchart TD hit[Player damages NPC] --> threat["threat += damage × aggro_modifier"] threat --> table[Per-NPC threat map] table --> focus[Highest alive threat in leash = focus] pack[Pack assist] --> table leash[Leash / return] --> clear[Clear table]

Tank-friendly design: raise aggro_modifier on high-threat abilities.

12.4 NPC telegraphs

Abilities like wolf_lunge telegraph before resolve — players can dodge in the window. Presentation uses NPC sprite_modes (telegraph, combat, chase, …) and paperdoll / tile sheets.

Player parity: casted spatial telegraphed AoE (impact_lock defaulting to snapshot) freezes the blast center at cast start the same way NPC spatial telegraphs and Shift+click ground aim do. Walking out of the red zone avoids the hit.

12.4.1 Caster motion

Optional caster_motion on an ability dashes the caster when the cast resolves (after the telegraph). It works for NPCs and players. Shift+Space lunge stays a separate movement burst.

Field Meaning
mode toward_target (entity; snapshot aim when impact locks) or toward_aim (ground / frozen point)
distance_m Maximum travel
stop_gap_m Standoff so the caster does not stack on the target

range_min_m / range_max_m are the start window. melee_reach_m is the hit after the landing. The red zone previews that short arc at the predicted landing. A wall stops the dash short, and a short landing misses. Dodge i-frames still cover the impact. Sidestepping the landing misses, and the caster still jumps.

Authoring:

  1. Abilities — set caster_motion, the start window, and the landing reach.
  2. Simple monster — add the leap next to a shorter melee on combat.abilities. Once they land inside range_min_m, the tighter swing is next (wolf_bite after wolf_lunge).
  3. Behavior — put both on a rotation and set that rotation on the behavior state. berserk_melee leaps with wolf_lunge from 2–5.5 m, then bites inside 2.4 m.
  4. Fight mode — assign that rotation to an HP phase or enrage. The phase only names the rotation.

content editor: Abilities → Dash on resolve. Rotations show a hint on entries whose ability dashes.

12.5 Respawn

npc.respawn + optional per-anchor overrides: delay ticks, max instances, block while corpse remains.

Gfx (typical)

Bind Action
WASD Move (combat facing can decouple)
Click ground Pathfind walk
Click NPC T1 target
Shift+click NPC T2 target
Tab / Shift+Tab Cycle targets
r / Shift+r Toggle autos
1–9 Hotbar cast
l / o Loadout / rotations
c / q Dodge / block
Inventory Enter Equip weapon / armor

Admin (content)

Tab Edit
Abilities Damage, heal, range, costs, on_hit, gates
Status effects DoTs, mods, durations
Items / Weapons / Armor weapon_ability_id, armor, resists, on_hit_effects
NPCs Combat, vitals pools, abilities, leash, loot
Behaviors FSM / wander
Map Wildlife spawn anchors
Settings Pacing, heal auto threshold, regen

Publish content after batch edits so the worker hot-reloads.

14. Content map (files)

Path Owns
the content files*.yaml Ability templates
the content files*.yaml Status catalog
the content files Weapons → abilities
the content files Cloth / leather / resists
the content files Potions, oils, scrolls
the content files*.yaml NPC combat + pools
the content files*.yaml Roam / predator FSM
the content files*.yaml Death drops
the content files*.yaml Spawn anchors
the content files Pacing, regen, heal gate

15. Worked example — spider fight

  1. Anchor wildlife_* with npc_ref: spider, wander radius 12 m.
  2. Spider def: pools.hp/stamina: true, behavior_ref: wolf_predator, abilities: [spider_bite], aggro/leash set.
  3. spider_bite: damage_type: poison (instant typed hit) + on_hit → poison (8 s DoT + regen cut).
  4. Player equips leather + sword, sets T1 auto + pursue, drinks anti-venom if needed (clears_status_ids).
  5. If player kites past leash_radius_m from spider home → spider returns and clears threat.
  6. On kill → loot table + optional carcass harvest.
flowchart LR spawn[Spawn at anchor] --> roam[Wander home disk] roam --> aggro[Player in aggro_radius] aggro --> chase[Chase] chase --> bite[spider_bite] bite --> typed[Poison-typed hit] bite --> dot[Apply poison status] chase --> leash{Beyond leash?} leash -->|yes| home[Return home] leash -->|no| chase

16. Related pages

Page Focus
Active stats & damage Pools and mitigation design
NPCs & creatures NPC schema
Runtime architecture Process layout and feature inventory
NPC lifecycle & ground loot Death, drops, carcass, respawn
Aggro, leash & threat Home leash and hate
Status effects Catalog and attach points
Combat raycast & attack FX Map footprints, beams, hit markers
Death & respawn Player death

17. Out of this revision

The following are not part of the current combat ruleset (they are not documented as live behavior on this site):

  • Skill-scaled target slot counts beyond T1/T2
  • Party hate meters / healer threat from heals
  • Full mid-flight ballistic projectiles and ground-target AoE placement UX (map FX footprints for melee/cone/sphere/beam are live — see 39)
  • Ability discovery / creation progression systems (skill books + vendors/loot/quest paths are live — see; deeper creation systems still later)

When those ship, this reference and the related pages above are updated to match.