feat(controllers): #57 foundation — ludic.gameplay package + lever 5 (disable system)

Shared building blocks for the builtin gameplay controllers (#57): the
ludic.gameplay source package (Cooldown timer, Stats + timed modifier stack,
Faction table, Combat damage pipeline with cancel/mutable hooks), plus the
compiler `disable system <esys_fn>` extensibility lever. Deterministic,
integer-only; C-free bootstrap fixpoint holds.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packages/ludic.gameplay/combat.ludic

@@ -0,0 +1,76 @@
+# combat.ludic — the shared damage pipeline (#57 foundation).
+#
+# One place every family routes hits through, so buffs/armor/crits/lifesteal are
+# written once as event listeners rather than re-invented per genre. The pipeline
+# is the honest no-closure realisation of lever 4 (events) + lever 6 (a mutable
+# hook):
+#
+#   1. mitigate the raw amount by the target's effective defence (Stats.total);
+#   2. publish the pending amount and emit `cancellable DamageAboutToApply` —
+#      a listener may veto the hit (cancel) or *rewrite the number* by calling
+#      Combat.set_amount(n) (the mutable channel, since `emit` only returns the
+#      cancelled flag);
+#   3. apply the final amount to Stats.hp, emit `Damaged`, and emit `Died` when hp
+#      reaches zero.
+#
+# Determinism: integer arithmetic, fixed listener order, no wall-clock — a hit
+# replays identically. Combat never moves or despawns bodies itself; the game
+# reacts to `Died` (respawn, ragdoll, loot) so the policy stays with the game.
+
+event cancellable DamageAboutToApply { target: int = 0, src: int = 0, amount: int = 0 }
+event Damaged { target: int = 0, src: int = 0, amount: int = 0 }
+event Died { e: int = 0, src: int = 0 }
+event Healed { e: int = 0, amount: int = 0 }
+
+# the mutable channel for lever 6: listeners rewrite the pending damage here.
+var combat_pending: int = 0
+
+@Namespace(Combat) function combat_amount() -> int { return combat_pending }
+@Namespace(Combat) function combat_set_amount(n: int) -> void { combat_pending = n }
+
+# Combat.mitigate(target, raw) — raw minus effective defence, floored at 1 so any
+# landed hit chips at least a point (a common, tunable default). A game that wants
+# a different formula overrides via the DamageAboutToApply hook.
+@Namespace(Combat) function combat_mitigate(target: int, raw: int) -> int {
+  let d = stats_total(target, 2)          # stat 2 = def
+  var v = raw - d
+  if v < 1 { v = 1 }
+  return v
+}
+
+# Combat.damage(target, src, amount) — the full pipeline. Returns the damage
+# actually applied (0 when vetoed or the target has no Stats/hp).
+@Namespace(Combat) function combat_damage(target: int, src: int, amount: int) -> int {
+  let P = World.prop_id("Stats")
+  if P < 0 { return 0 }
+  if World.has(target, P) == 0 { return 0 }
+  let fhp = World.field_id(P, "hp")
+  if fhp < 0 { return 0 }
+
+  combat_pending = combat_mitigate(target, amount)
+  if emit DamageAboutToApply(target: target, src: src, amount: combat_pending) != 0 { return 0 }
+  var dmg = combat_pending
+  if dmg < 0 { dmg = 0 }
+
+  var hp = World.get(target, P, fhp) - dmg
+  if hp < 0 { hp = 0 }
+  World.set(target, P, fhp, hp)
+  emit Damaged(target: target, src: src, amount: dmg)
+  if hp <= 0 { emit Died(e: target, src: src) }
+  return dmg
+}
+
+# Combat.heal(e, amount) — restore hp, clamped to max_hp (effective, so a +max_hp
+# buff raises the ceiling), and emit `Healed`.
+@Namespace(Combat) function combat_heal(e: int, amount: int) -> void {
+  let P = World.prop_id("Stats")
+  if P < 0 { return }
+  if World.has(e, P) == 0 { return }
+  let fhp = World.field_id(P, "hp")
+  if fhp < 0 { return }
+  let cap = stats_total(e, 0)             # stat 0 = max_hp
+  var hp = World.get(e, P, fhp) + amount
+  if (cap > 0) and (hp > cap) { hp = cap }
+  World.set(e, P, fhp, hp)
+  emit Healed(e: e, amount: amount)
+}

packages/ludic.gameplay/cooldown.ludic

@@ -0,0 +1,53 @@
+# cooldown.ludic — a generic deterministic frame timer (#57 foundation).
+#
+# Ubiquitous across the controllers: jump buffers, fire rate, ability cooldowns,
+# AI re-plan intervals, i-frames. A body carries a `Cooldown` and the engine ticks
+# it down one frame at a time (never below zero); the game reads `Cooldown.ready`.
+# It is the smallest possible engine system and the template for the rest: resolve
+# fields by name, no-op on anything absent, mutate in place, no allocation.
+#
+# For more than one timer on one entity a controller carries its own countdown
+# fields (the platformer keeps coyote/buffer counters inside `Platformer`); this
+# component is the shared, drop-in single timer.
+
+property Cooldown { t: int = 0, max: int = 0 }
+
+# esys_cooldown (Update): decrement every live Cooldown toward zero. Registered on
+# the compile-time engine-system registry via @EngineSystem, so a game that merely
+# declares `Cooldown` gets it ticked for free, and a game that never mentions
+# Cooldown compiles byte-identically (the call is component-gated).
+@EngineSystem(Cooldown, Update) function esys_cooldown() -> void {
+  let P = World.prop_id("Cooldown")
+  if P < 0 { return }
+  let ft = World.field_id(P, "t")
+  if ft < 0 { return }
+  var e = World.query_next(P, 0)
+  while e >= 0 {
+    let t = World.get(e, P, ft)
+    if t > 0 { World.set(e, P, ft, t - 1) }
+    e = World.query_next(P, e + 1)
+  }
+}
+
+# Cooldown.start(e, n) — begin an n-frame countdown (also records `max` so a UI can
+# draw a fill ratio). Cooldown.ready(e) is 1 once it hits zero; Cooldown.left(e) is
+# the frames remaining.
+@Namespace(Cooldown) function cooldown_start(e: int, frames: int) -> void {
+  let P = World.prop_id("Cooldown")
+  if P < 0 { return }
+  let ft = World.field_id(P, "t")
+  let fm = World.field_id(P, "max")
+  if ft >= 0 { World.set(e, P, ft, frames) }
+  if fm >= 0 { World.set(e, P, fm, frames) }
+}
+@Namespace(Cooldown) function cooldown_left(e: int) -> int {
+  let P = World.prop_id("Cooldown")
+  if P < 0 { return 0 }
+  let ft = World.field_id(P, "t")
+  if ft < 0 { return 0 }
+  return World.get(e, P, ft)
+}
+@Namespace(Cooldown) function cooldown_ready(e: int) -> int {
+  if cooldown_left(e) <= 0 { return 1 }
+  return 0
+}

packages/ludic.gameplay/faction.ludic

@@ -0,0 +1,70 @@
+# faction.ludic — a friend/enemy/neutral relationship table (#57 foundation).
+#
+# Shared by shooter targeting and NPC AI: "who may hit / hunt / help whom". Each
+# body carries a `Faction { id }`; a small square matrix records the relationship
+# between two faction ids. Unset pairs fall back to the classic default — same id
+# is friendly, different ids are hostile — so a game that never touches the table
+# still gets sensible enemy/ally behaviour. The matrix is a plain integer buffer
+# in a module var, so it is deterministic and captured by world_save.
+
+property Faction { id: int = 0 }
+
+const FAC_MAX: int = 32
+const REL_FRIEND: int = 0
+const REL_NEUTRAL: int = 1
+const REL_HOSTILE: int = 2
+
+# relationships stored as (rel + 1); a zero slot means "unset -> use the default".
+# A global var initialiser must be a literal, so it is allocated lazily.
+var fac_tbl: words = null
+
+function fac_ensure() -> void {
+  if fac_tbl == null { fac_tbl = words(FAC_MAX * FAC_MAX) }
+}
+
+# Faction.set(a, b, rel) — record a symmetric relationship between two factions.
+@Namespace(Faction) function faction_set(a: int, b: int, rel: int) -> void {
+  fac_ensure()
+  if (a < 0) or (a >= FAC_MAX) { return }
+  if (b < 0) or (b >= FAC_MAX) { return }
+  fac_tbl[a * FAC_MAX + b] = rel + 1
+  fac_tbl[b * FAC_MAX + a] = rel + 1
+}
+
+# Faction.rel(a, b) — the relationship code (0 friend, 1 neutral, 2 hostile).
+@Namespace(Faction) function faction_rel(a: int, b: int) -> int {
+  fac_ensure()
+  if (a >= 0) and (a < FAC_MAX) and (b >= 0) and (b < FAC_MAX) {
+    let v = fac_tbl[a * FAC_MAX + b]
+    if v != 0 { return v - 1 }
+  }
+  if a == b { return REL_FRIEND }
+  return REL_HOSTILE
+}
+
+# Faction.hostile(a, b) / Faction.friendly(a, b) — the common yes/no queries.
+@Namespace(Faction) function faction_hostile(a: int, b: int) -> int {
+  if faction_rel(a, b) == REL_HOSTILE { return 1 }
+  return 0
+}
+@Namespace(Faction) function faction_friendly(a: int, b: int) -> int {
+  if faction_rel(a, b) == REL_FRIEND { return 1 }
+  return 0
+}
+
+# Faction.id_of(e) — the faction id an entity carries (-1 if it has no Faction).
+@Namespace(Faction) function faction_id_of(e: int) -> int {
+  let P = World.prop_id("Faction")
+  if P < 0 { return 0 - 1 }
+  if World.has(e, P) == 0 { return 0 - 1 }
+  let f = World.field_id(P, "id")
+  if f < 0 { return 0 - 1 }
+  return World.get(e, P, f)
+}
+
+# Faction.enemies(a, b) — true when the two entities' factions are hostile; the
+# one-call test the shooter and AI reach for. Missing factions read as hostile
+# (an unaligned hazard hits anyone) unless the ids happen to match.
+@Namespace(Faction) function faction_enemies(ea: int, eb: int) -> int {
+  return faction_hostile(faction_id_of(ea), faction_id_of(eb))
+}

packages/ludic.gameplay/package.ludic

@@ -0,0 +1,18 @@
+# ludic.gameplay — the shared foundation for the builtin gameplay controllers.
+#
+# This is the "foundation" phase of the controller layer (#57): the cross-cutting
+# building blocks every genre package (platformer / shooter / RPG / NPC-AI) leans
+# on — a deterministic timer, a stats + timed-modifier stack, a faction
+# relationship table, and a combat pipeline with cancellable/mutable hooks.
+#
+# It ships as an ordinary source package: AOT means these declarations compile
+# straight into the consumer's compile-time ECS, so there is no ABI seam, and the
+# whole thing stays deterministic (integer only) — lockstep, replay and
+# world_save snapshots all hold.
+package "ludic.gameplay"
+version "0.1.0"
+kind source
+provides "Cooldown"
+provides "Stats"
+provides "Faction"
+provides "Combat"

packages/ludic.gameplay/stats.ludic

@@ -0,0 +1,111 @@
+# stats.ludic — attributes + a timed modifier stack (#57 foundation).
+#
+# `Stats` is a POD attribute bundle shared by the RPG, shooter and NPC families.
+# On top of the raw fields sits a *modifier stack*: each buff/debuff is its own
+# tiny `Modifier` entity (target + stat + op + amount + ttl), so the stack is
+# unbounded, captured by world_save, and expired by one engine system. A queried
+# stat is `base + flat`, then scaled by the summed percent — the standard
+# flat-then-percent order — computed on demand, never mutating the base.
+#
+# Stat codes (the `stat` argument everywhere below):
+#   0 = max_hp   1 = atk   2 = def   3 = spd   4 = max_mp
+
+property Stats {
+  hp: int = 0, max_hp: int = 0,
+  mp: int = 0, max_mp: int = 0,
+  atk: int = 0, def: int = 0, spd: int = 0,
+  level: int = 1, xp: int = 0
+}
+
+# a single timed modifier, carried on its own entity so the stack is dynamic.
+# op: 0 = flat add, 1 = percent add. ttl: frames left (0 or less = permanent).
+property Modifier { target: int = 0, stat: int = 0, op: int = 0, amount: int = 0, ttl: int = 0 }
+model ModifierFx { Modifier }
+@OnSpawn(ModifierFx) handler ModifierFxInit { }
+
+# esys_modifier (Update): count down every timed modifier and despawn the expired
+# ones. Permanent modifiers (ttl <= 0) are left alone.
+@EngineSystem(Modifier, Update) function esys_modifier() -> void {
+  let P = World.prop_id("Modifier")
+  if P < 0 { return }
+  let fttl = World.field_id(P, "ttl")
+  if fttl < 0 { return }
+  var e = World.query_next(P, 0)
+  while e >= 0 {
+    let ttl = World.get(e, P, fttl)
+    var nxt = World.query_next(P, e + 1)
+    if ttl > 0 {
+      let left = ttl - 1
+      if left <= 0 { despawn e } else { World.set(e, P, fttl, left) }
+    }
+    e = nxt
+  }
+}
+
+# map a stat code to the matching Stats field name.
+function stat_field(stat: int) -> pointer {
+  if stat == 0 { return "max_hp" }
+  if stat == 1 { return "atk" }
+  if stat == 2 { return "def" }
+  if stat == 3 { return "spd" }
+  if stat == 4 { return "max_mp" }
+  return "atk"
+}
+
+# Stats.base(e, stat) — the raw stored field, no modifiers.
+@Namespace(Stats) function stats_base(e: int, stat: int) -> int {
+  let P = World.prop_id("Stats")
+  if P < 0 { return 0 }
+  let f = World.field_id(P, stat_field(stat))
+  if f < 0 { return 0 }
+  return World.get(e, P, f)
+}
+
+# Stats.total(e, stat) — the effective value: (base + flat) * (100 + percent)/100.
+@Namespace(Stats) function stats_total(e: int, stat: int) -> int {
+  let base = stats_base(e, stat)
+  let P = World.prop_id("Modifier")
+  if P < 0 { return base }
+  let ft = World.field_id(P, "target")
+  let fs = World.field_id(P, "stat")
+  let fo = World.field_id(P, "op")
+  let fa = World.field_id(P, "amount")
+  var flat = 0
+  var pct = 0
+  var m = World.query_next(P, 0)
+  while m >= 0 {
+    if (World.get(m, P, ft) == e) and (World.get(m, P, fs) == stat) {
+      let amt = World.get(m, P, fa)
+      if World.get(m, P, fo) == 1 { pct = pct + amt } else { flat = flat + amt }
+    }
+    m = World.query_next(P, m + 1)
+  }
+  return (base + flat) * (100 + pct) / 100
+}
+
+# Stats.modify(target, stat, op, amount, ttl) — push a modifier onto the stack.
+@Namespace(Stats) function stats_modify(target: int, stat: int, op: int, amount: int, ttl: int) -> int {
+  let m = World.model_id("ModifierFx")
+  if m < 0 { return 0 - 1 }
+  let e = World.spawn(m)
+  let P = World.prop_id("Modifier")
+  World.set(e, P, World.field_id(P, "target"), target)
+  World.set(e, P, World.field_id(P, "stat"), stat)
+  World.set(e, P, World.field_id(P, "op"), op)
+  World.set(e, P, World.field_id(P, "amount"), amount)
+  World.set(e, P, World.field_id(P, "ttl"), ttl)
+  return e
+}
+
+# Stats.clear_mods(e) — drop every modifier targeting an entity (e.g. on unequip).
+@Namespace(Stats) function stats_clear_mods(target: int) -> void {
+  let P = World.prop_id("Modifier")
+  if P < 0 { return }
+  let ft = World.field_id(P, "target")
+  var m = World.query_next(P, 0)
+  while m >= 0 {
+    var nxt = World.query_next(P, m + 1)
+    if World.get(m, P, ft) == target { despawn m }
+    m = nxt
+  }
+}