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.

1. What combat is in Flatland

Flatland has no separate combat mode. The world stays interactive. A player is in_combat while dealing/taking hostile actions; after ~6 seconds of idle combat activity (COMBAT_IDLE_EXIT_TICKS = 180 @ 30 Hz), the flag clears and out-of-combat regen ramps apply.

The region worker is authoritative. Clients (gfx, TUI, agents) only emit intents. The sim validates range, line of sight, resources, cooldowns, GCD, and facing — never “key 3 was pressed.”

flowchart TB subgraph clients [Clients] gfx[Gfx / TUI / Agent] end gfx -->|intents| gw[Gateway] gw --> worker[Region worker 30 Hz] worker --> resolve[Ability resolver] resolve --> dmg[Damage / heal / status] dmg --> hud[Combat HUD snapshot] hud --> gfx

Tick order (simplified): combat pursue → auto-attacks / NPC telegraphs → status DoT ticks → movement integrate → AOI snapshot.

2. Vitals pools (HP, mana, stamina, hunger)

Players always carry full vitals. NPCs only carry pools flagged on the definition (npc.pools):

Pool	Player	Typical wildlife	Typical town NPC
HP	Yes	`pools.hp: true` (required to appear alive)	Often true
Stamina	Yes	Combat predators usually true	Optional
Mana	Yes	Usually false	Optional
Hunger / thirst	Yes	Usually false	Optional

Critical designer rule: wildlife with pools.hp: false spawn at 0 HP, never appear in NPC views, and show as the gfx ? placeholder. Enable HP (and stamina if abilities cost stamina) on the NPCs → Combat → Vitals pools form.

2.1 Spend & regen

flowchart LR action[Attack / cast / dodge / sprint] --> spend[PoolSpend] spend --> hp[HP] & sta[Stamina] & mana[Mana] idle[Out of combat] --> ramp[Regen ramp curves] ramp --> hp & sta & mana combatFlag[in_combat] -.->|slows rest regen| ramp

Abilities declare stamina_cost / mana_cost.
Regen uses server-settings.yaml → regen_ramp.* (seconds_to_full, min/max multipliers, curve power) per pool.
Status mods can scale regen.health, drain.*, etc. (see §8).
Consumables restore pools via item fields (health_restore, mana_restore, …).

2.2 Death

When HP reaches 0: death rules from 07 apply for players; wildlife roll loot / carcass (25) and may queue respawn from the spawn anchor.

3. Attributes, skills, and raw damage

Primaries (STR, DEX, VIT, STA, INT, WIS, CHA) feed derived pools and combat math.

Melee raw damage (legacy swing path):

[ \text{raw} = \text{base} \times (1 + \text{swords_tier} \times 0.08) \times (1 + \text{STR_display}/50) ]

Modern path: ability templates define primary_damage.min/max, then skill scaling (skill_scaling.primary_damage, cast/attack speed, range) and global pacing multipliers apply before mitigation.

Pacing knobs (assets/config/server-settings.yaml → combat.pacing):

Key	Role
`wildlife_hp_multiplier`	Scales NPC max HP
`ability_damage_multiplier`	Scales ability damage dealt
`attack_interval_multiplier`	Stretches attack intervals
`wildlife_damage_multiplier`	Scales NPC outbound damage

4. Defense: cloth, leather, armor, vitality

Defense is not a class. Worn pieces contribute armor_physical and typed resists; vitality always adds a mitigation contribution.

flowchart TD worn[Worn pieces + offhand] --> armor[Sum armor_physical] vit[Vitality] --> vitContrib["VIT_display × 0.8"] armor --> rating[total_mitigation_rating] vitContrib --> rating rating --> curve["DR = rating / (rating + K) K=50"] raw[Incoming raw] --> afterMit["raw × (1 − DR)"] afterMit --> floor["max(result, MIN_DAMAGE=1)"]

4.1 Armor pieces

Content: assets/items/armor.yaml (cloth / leather / specialty). Each template has:

equip_slot — head, chest, arms, legs, feet, rings, …
armor_physical — adds to mitigation rating (cloth shirt ≈ 3, leather chest ≈ 8)
resists — map of damage type → fraction (e.g. fire: 0.15)

Equip via inventory; Defense HUD shows per-piece armor and resists.

4.2 What armor does vs resists

Layer	Applies to	Effect
Armor + VIT mitigation	Almost all hit damage	Soft DR curve (§4 diagram)
Type resists	Non-physical types (`fire`, `frost`, `poison`, `cold`, …)	Multiplier from gear resists + status `resist.<type>`
Physical subtypes	`physical`, `slash`, `pierce`, `blunt`	Type-resist path currently returns 1.0 (armor/VIT only)

So a cloth set gives low armor_physical (light DR). A leather set raises rating. Elemental/poison resists matter when the ability’s damage_type is elemental — not when it is slash/pierce/blunt.

4.3 Active defense (player)

Action	Intent	Effect
Dodge	`Dodge`	Short i-frame window (`dodge_until_tick`); costs stamina; starts GCD
Block	`Block`	While active, frontal melee damage × 0.5; splash cover × 0.5 while blocking

Gfx / TUI: typically c dodge, q block.

5. Weapons and ability kinds

Combat actions are ability templates in assets/combat/abilities/*.yaml, not hard-coded weapon names.

5.1 Ability kinds

Kind	Typical use	Auto on T1?
`weapon_attack`	Mainhand swing / bow shot / NPC bite	Yes — slot 1 uses equipped `weapon_ability_id`
`spell`	Fireball, heal, poison dart	Via rotation / hotbar / slot binding
`consumable`	Potions (also usable outside combat)	Via rotation / use item

5.2 Key ability fields

Field	Meaning
`range_min_m` / `range_max_m`	Valid distance band (bows often 3–22 m)
`range_mode`	`melee_reach` or `radius`
`effect_shape`	`melee_arc`, `sphere`, `cone`
`melee_arc_deg` / `melee_reach_m`	Melee geometry
`primary_damage`	Instant hit min/max + `damage_type`
`primary_heal`	Instant heal min/max (optional)
`stamina_cost` / `mana_cost`	Resource gates
`cooldown_sec`	Per-ability cooldown
`cast_time_sec`	Channel before resolve
`complexity`	Move-while-casting tier (INT/WIS mitigate)
`ignores_gcd`	Skip global cooldown when true
`blast_radius_m`	Splash sphere around impact
`allows_self`	Required for self-heals
`auto_cast_below_hp_pct`	Auto/rotation heal gate (else settings default)
`on_hit`	Apply status effects (§8)
`requires_target_status` / `requires_self_status`	Rotation gates (e.g. shatter after frost)
`aggro_modifier`	Threat multiplier on damage (§10)

5.3 Weapon types (content)

Item	Ability	Band
(none)	`unarmed`	Melee ~1.8 m
`wooden_sword`	`short_sword_slash`	Melee slash
`hunting_bow` / `short_bow`	`bow_shot`	3–22 m, pierce
NPC wolf	`wolf_bite`, `wolf_lunge`	Melee + telegraphed lunge
NPC spider	`spider_bite`	Melee poison + on-hit poison

Characters start with unarmed only in the skill-book era; weapons grant their innate ability on equip; spells arrive via books / discovery (docs/skill-books-and-hotbar.md).

6. Damage types (instant hit tags)

primary_damage.damage_type labels the instant hit packet. It does not by itself apply a DoT or debuff.

flowchart TD hit[Ability resolves] --> typed[damage_type on primary_damage] typed --> armorPath[Armor + VIT mitigation] typed --> resistPath{Type resists?} resistPath -->|physical / slash / pierce / blunt| skip[Resist mult = 1.0] resistPath -->|poison / fire / frost / cold / …| gear[Gear resists + status resist.type] armorPath --> final[Final HP loss] gear --> final

Type family	Examples	Resist path
Physical subtypes	`physical`, `slash`, `pierce`, `blunt`	Armor/VIT only today
Elemental / exotic	`fire`, `frost`, `cold`, `poison`, `lightning`, …	Gear `resists` + `resist.<type>` status mods
None / empty	`none`, `""`	Treated as untyped for resists

Not the same as status effects. A spider bite with damage_type: poison and on_hit → poison deals a poison-typed chunk and applies the Poison DoT. Either alone is valid design.

7. Hit resolution pipeline

End-to-end path for a damaging ability:

sequenceDiagram participant C as Caster participant S as Sim participant T as Target C->>S: Cast / Attack / auto rotation step S->>S: GCD, CD, mana/stamina, range, LoS, facing alt Fail S-->>C: Reject with reason else OK S->>S: Roll primary damage × pacing × damage_dealt mods S->>S: Type resists × damage_taken mods S->>S: Block / dodge windows S->>S: Armor+VIT mitigation (floor 1) S->>T: Apply HP loss + threat S->>S: Run on_hit effects / weapon on_hit_effects S-->>C: HUD + floaters end

Line of sight: 3D LoS with terrain elevation and segment z_walls. Blocked geometry cancels the hit.

Splash: entities in blast_radius_m take falloff damage (splash_damage_multiplier_min floor). Friendly fire is on for splash.

8. Status effects, DoTs, and on-hit

Catalog: assets/combat/status_effects/*.yaml (admin → Status effects). Full attach-point map: 35.

8.1 Effect anatomy

Piece	Role
`duration_sec`	How long the entity buff/debuff lasts
`stacking`	`refresh` in v1
`mods`	`add` / `mul` / `override` on closed stat keys
`periodic`	Damage or heal every `interval_sec` (optional `damage_type`)
`clear_on_death`	Drop on death when true

Poison sample: halves regen.health, ticks 4 poison damage / second for 8 s.

Frost sample: slows move, −armor, +damage taken, frost DoT.

8.2 How effects get applied

flowchart TB catalog[Status catalog by id] catalog --> ability[Ability on_hit apply_status] catalog --> weapon[Item on_hit_effects] catalog --> wear[grant_effects_while_equipped] catalog --> drink[Consumable apply_status_ids] catalog --> grant[grants_item_status on a gear instance] ability --> active[ActiveStatus on entity] weapon --> active wear --> active drink --> active grant --> active active --> mods[Stat mods each tick] active --> dots[Periodic damage/heal]

Source	When	Duration
Ability `on_hit`	On successful hit	Effect default (or override `duration_sec`)
Weapon / ammo `on_hit_effects`	On weapon hit	Effect default
Wearable `grant_effects_while_equipped`	While worn	Cleared on unequip
Consumable self-apply	On use	Effect default
Instance grant `on_hit` / `while_equipped`	Bound to one gear instance	Binding TTL separate from effect duration

8.3 Ability gates

Rotations can require statuses:

requires_target_status: frost_effect — only fire if target is frosted
requires_self_status: battle_shout — only fire if you have the buff

9. Healing

Heals are abilities with primary_heal (and usually allows_self: true).

Concern	Behavior
Range	Same as damage — `range_max_m` (e.g. `heal_touch` = 4 m)
Target	Friendly / self; hostile heals rejected
Resources	Mana + stamina as authored
Auto heal gate	`auto_cast_below_hp_pct` on ability, else `combat.heal_auto_below_hp_pct` (default 90)
LoS	Required like other casts

Typical Support rotation: bind heal_touch on T2 (self or ally) with auto enabled; it only fires when HP% is below the gate.

10. Timeouts, GCD, cooldowns, channels

Sim runs at 30 Hz. Convert seconds → ticks × 30.

Timer	Constant / field	Approx wall time
GCD	`GCD_TICKS = 30`	~1.0 s between most manual combat actions
Ability cooldown	`cooldown_sec`	Per ability id
Attack interval	`attack_interval_sec` × pacing	Weapon auto cadence
Cast channel	`cast_time_sec`	Must finish (or be interrupted) before resolve
Dodge window	~12 ticks	~0.4 s i-frames
in_combat exit	180 ticks	~6 s without combat activity
Status duration	effect `duration_sec`	Per catalog
NPC telegraph	Ability / AI until tick	Dodge window for lunges

ignores_gcd: true lets an ability bypass the global cooldown (rare; use carefully).

11. Targeting, loadouts, and rotations

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.

Example mental model

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

11.5 Macros

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

12. Wildlife: roam, aggro, leash, attacks

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)`
`attack_range_m`	Enter combat / melee band
`abilities`	Ordered NPC ability ids (bite, lunge, …)

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.

12.5 Respawn

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

13. Player UX cheat sheet

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
`assets/combat/abilities/*.yaml`	Ability templates
`assets/combat/status_effects/*.yaml`	Status catalog
`assets/items/weapons.yaml`	Weapons → abilities
`assets/items/armor.yaml`	Cloth / leather / resists
`assets/items/consumables.yaml`	Potions, oils, scrolls
`assets/npcs/*.yaml`	NPC combat + pools
`assets/npcs/behaviors/*.yaml`	Roam / predator FSM
`assets/loot/*.yaml`	Death drops
`assets/world/segments/*.yaml`	Spawn anchors
`assets/config/server-settings.yaml`	Pacing, regen, heal gate

Code: region_combat.rs, abilities.rs, combat.rs, combat_slots.rs, combat_status.rs, defense.rs, wildlife AI modules.

15. Worked example — spider fight

Anchor wildlife_* with npc_ref: spider, wander radius 12 m.
Spider def: pools.hp/stamina: true, behavior_ref: wolf_predator, abilities: [spider_bite], aggro/leash set.
spider_bite: damage_type: poison (instant typed hit) + on_hit → poison (8 s DoT + regen cut).
Player equips leather + sword, sets T1 auto + pursue, drinks anti-venom if needed (clears_status_ids).
If player kites past leash_radius_m from spider home → spider returns and clears threat.
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
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 projectile simulation and ground-target AoE polish
Ability discovery / creation progression systems

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