feat(ecs): engine-owned systems auto-tick user components (#43)

Adds the ECS hook issues #43 and #47 named as their real dependency: a
system the *engine* owns, inserted into the frame loop over a component a
game merely declares and carries — no `handler` wired.

- runtime/native/systems.ludic: esys_spriteanim (SpriteAnim frame advance:
  loop/once/pingpong) and esys_motion (Motion value tween: linear/in/out/
  in-out), both on the by-name reflection ABI, integer + deterministic.
- backend: emit_engine_systems_for_phase inserts the calls after every user
  handler in a phase (auto-loop and the drivable tick helpers alike);
  uses_engine_systems() drives the systems.ludic splice, the world-table
  force-emit, and makes a component-only game count as a systems game.
- A game that declares neither component is byte-for-byte unchanged.

Worked example + regression: examples/library/anim_ecs.ludic. Full suite
73 passed, self-host C-free bootstrap fixpoint intact.

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

runtime/native/systems.ludic

@@ -0,0 +1,136 @@
+# ============================================================================
+# systems.ludic — engine-owned systems that run automatically over user
+# components, each frame, without the game wiring a handler.
+#
+# This is the ECS hook issues #43 and #47 named as their real dependency: until
+# now every system was a `handler` the game wrote. These `esys_*` functions are
+# systems the *engine* owns — the compiler splices this file and inserts a call
+# to each one at the right phase of the frame loop (see emit_engine_systems_for_
+# phase in emit_game.ludic), so a component the game merely *declares and carries*
+# is ticked for free.
+#
+# They stand entirely on the reflection ABI (World.prop_id / field_id / get /
+# set / query_next — the same by-name world table a mod reads), so they never
+# compile against a fixed field layout: a system resolves its fields by name and
+# no-ops cleanly when the component (or a field) is absent. Everything is integer
+# and deterministic — the frame clock ticks at a fixed 60/s — so replays and
+# lockstep netcode reproduce animation and motion exactly.
+#
+# The opt-in is declaring the well-known component. A game that wants sprite
+# animation declares `property SpriteAnim { ticks, fps, frames, mode, frame }`
+# and puts it on a model; the engine advances `frame` every tick. No component,
+# no system emitted — a game without them is byte-for-byte unchanged.
+# ============================================================================
+
+# floor of a/b for non-negative a (the frame clock only ever counts up).
+function esys_div(a: int, b: int) -> int {
+  if b <= 0 { return 0 }
+  return a / b
+}
+
+# ---- SpriteAnim: spritesheet frame advance (#43) ---------------------------
+# Component contract — `property SpriteAnim { ticks: int, fps: int, frames: int,
+# mode: int, frame: int }`:
+#   ticks   engine frames elapsed since the clip started (the engine advances it)
+#   fps     playback rate in frames per second
+#   frames  number of cells in the clip
+#   mode    0 = loop, 1 = once (clamp on last), 2 = pingpong (bounce)
+#   frame   OUTPUT: the cell index to draw this frame
+# elapsed = ticks * fps / 60 whole animation frames; `mode` maps that back into
+# 0..frames-1. Pure integer, so the same tick count always yields the same cell.
+function esys_spriteanim() -> void {
+  let p = World.prop_id("SpriteAnim")
+  if p < 0 { return }
+  let f_ticks  = World.field_id(p, "ticks")
+  let f_fps    = World.field_id(p, "fps")
+  let f_frames = World.field_id(p, "frames")
+  let f_mode   = World.field_id(p, "mode")
+  let f_frame  = World.field_id(p, "frame")
+  if f_ticks < 0 { return }
+  if f_frame < 0 { return }
+  var e = World.query_next(p, 0)
+  while e >= 0 {
+    let ticks = World.get(e, p, f_ticks) + 1
+    World.set(e, p, f_ticks, ticks)
+    let fps    = World.get(e, p, f_fps)
+    var frames = World.get(e, p, f_frames)
+    let mode   = World.get(e, p, f_mode)
+    if frames < 1 { frames = 1 }
+    let elapsed = esys_div(ticks * fps, 60)          # whole animation frames elapsed
+    var fr = 0
+    if mode == 1 {                                   # once: clamp on the last frame
+      fr = elapsed
+      if fr > frames - 1 { fr = frames - 1 }
+    } else {
+      if mode == 2 {                                 # pingpong: bounce 0..frames-1..0
+        let period = max(1, frames * 2 - 2)
+        let m = elapsed % period
+        if m < frames { fr = m } else { fr = period - m }
+      } else {                                       # loop (mode 0 / default)
+        fr = elapsed % frames
+      }
+    }
+    World.set(e, p, f_frame, fr)
+    e = World.query_next(p, e + 1)
+  }
+}
+
+# ---- Motion: value tween advance (#43) -------------------------------------
+# Component contract — `property Motion { ticks: int, dur: int, from: int,
+# to: int, ease: int, value: int, done: int }`:
+#   ticks   engine frames elapsed since the tween started (engine advances it)
+#   dur     duration in engine frames (ticks); dur <= 0 snaps straight to `to`
+#   from,to the interpolation endpoints (integer game units — position, alpha…)
+#   ease    0 = linear, 1 = in (t^2), 2 = out, 3 = in-out
+#   value   OUTPUT: the interpolated value this frame
+#   done    OUTPUT: 1 once ticks has reached dur, else 0
+# progress is carried in 0..1024 so easing curves are exact in integer math.
+function esys_motion_ease(t: int, ease: int) -> int {
+  if ease == 1 { return t * t / 1024 }               # ease-in: t^2
+  if ease == 2 {                                      # ease-out: 1-(1-t)^2
+    let u = 1024 - t
+    return 1024 - (u * u / 1024)
+  }
+  if ease == 3 {                                      # ease-in-out
+    if t < 512 { return (t * t / 1024) * 2 }
+    let u = 1024 - t
+    return 1024 - (u * u / 1024) * 2
+  }
+  return t                                            # linear
+}
+
+function esys_motion() -> void {
+  let p = World.prop_id("Motion")
+  if p < 0 { return }
+  let f_ticks = World.field_id(p, "ticks")
+  let f_dur   = World.field_id(p, "dur")
+  let f_from  = World.field_id(p, "from")
+  let f_to    = World.field_id(p, "to")
+  let f_ease  = World.field_id(p, "ease")
+  let f_value = World.field_id(p, "value")
+  let f_done  = World.field_id(p, "done")
+  if f_ticks < 0 { return }
+  if f_value < 0 { return }
+  var e = World.query_next(p, 0)
+  while e >= 0 {
+    let dur = World.get(e, p, f_dur)
+    var ticks = World.get(e, p, f_ticks) + 1
+    if ticks > dur { ticks = dur }                    # clamp so `value` rests at `to`
+    World.set(e, p, f_ticks, ticks)
+    let from = World.get(e, p, f_from)
+    let to   = World.get(e, p, f_to)
+    let ease = World.get(e, p, f_ease)
+    var t = 1024
+    if dur > 0 { t = esys_div(ticks * 1024, dur) }
+    if t > 1024 { t = 1024 }
+    let te = esys_motion_ease(t, ease)
+    let value = from + (to - from) * te / 1024
+    World.set(e, p, f_value, value)
+    if f_done >= 0 {
+      var d = 0
+      if ticks >= dur { d = 1 }
+      World.set(e, p, f_done, d)
+    }
+    e = World.query_next(p, e + 1)
+  }
+}