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>

LANGUAGE.md

@@ -257,6 +257,32 @@ there is no per-tick array of matched entities. Consequences worth knowing:
 * An entity **spawned during the loop at a higher id is visited in the same
   tick**. Spawn into a later phase if you don't want that.
 
+### Engine-owned systems
+
+Some systems are run by the **engine**, not written as a `handler`. A game opts
+in by declaring a well-known component and carrying it on a model; the compiler
+inserts the matching system into the frame loop, so the component is ticked with
+no handler wired. The systems stand on the by-name reflection ABI, so they never
+compile against a fixed layout — a component with the right field names is
+enough, and a game that declares none is byte-for-byte unchanged.
+
+| Component | Phase | Effect |
+|---|---|---|
+| `SpriteAnim { ticks, fps, frames, mode, frame }` | `Update` | advances `frame` — spritesheet frame animation (`mode` 0 loop, 1 once, 2 ping-pong) |
+| `Motion { ticks, dur, from, to, ease, value, done }` | `Update` | advances `value` — value tween (`ease` 0 linear, 1 in, 2 out, 3 in-out), latches `done` |
+
+```ludic
+# doc-check: skip — illustrative engine-owned system
+property SpriteAnim { ticks: int = 0, fps: int = 0, frames: int = 0, mode: int = 0, frame: int = 0 }
+model Hero { Pos, SpriteAnim }
+# spawn a walking 6-frame clip at 10 fps; the engine advances SpriteAnim.frame
+spawn Hero { Pos { x: 0, y: 0 }  SpriteAnim { fps: 10, frames: 6, mode: 0 } }
+```
+
+Everything is integer and deterministic (the frame clock ticks at a fixed 60/s),
+so animation and motion reproduce exactly under replay and lockstep netcode. See
+`examples/library/anim_ecs.ludic`.
+
 ## Annotations
 
 Declarations carry `@annotations` in front of them — `@export`, `@edge`, `@pure`,

changes/engine-systems.md

@@ -0,0 +1,3 @@
+bump: minor
+type: feat
+Engine-owned systems over user components (#43) — the ECS hook that runs a system automatically each frame over a component a game merely declares and carries, no `handler` wired. Declaring the well-known `SpriteAnim { ticks, fps, frames, mode, frame }` gives sprite-sheet frame animation (loop / once / ping-pong) that advances `frame` for free; `Motion { ticks, dur, from, to, ease, value, done }` gives value tweening (linear / in / out / in-out) that advances `value`. The systems stand on the reflection ABI, resolving fields by name, so they no-op cleanly when a component or field is absent and cost nothing in a game that declares neither — that build is byte-for-byte unchanged.

examples/library/anim_ecs.ludic

@@ -0,0 +1,64 @@
+# anim_ecs.ludic — engine-owned systems over user components (#43). A game
+# declares the well-known SpriteAnim / Motion components, carries them on a
+# model, and the engine advances them every frame with NO handler wired by the
+# game. Driving the sim from `entry` (tick_fixed runs the Update phase, where the
+# engine systems live), we sample the auto-advanced fields at known tick counts.
+#
+#   bin/ludic examples/library/anim_ecs.ludic
+# A full run prints:  1 5 2 10 0 2 10 1 1
+program AnimEcs {
+  # The engine auto-advances `frame` from `ticks` (runtime/native/systems.ludic).
+  property SpriteAnim { ticks: int = 0, fps: int = 0, frames: int = 0, mode: int = 0, frame: int = 0 }
+  # The engine auto-advances `value` / `done` from `ticks` over `dur`.
+  property Motion { ticks: int = 0, dur: int = 0, from: int = 0, to: int = 0, ease: int = 0, value: int = 0, done: int = 0 }
+
+  model Sprite  { SpriteAnim }
+  model Mover   { Motion }
+  model Bouncer { SpriteAnim }
+
+  entry {
+    # a 4-frame clip at 12 fps, looping: a new cell every 5 ticks (60/12).
+    spawn Sprite { SpriteAnim { fps: 12, frames: 4, mode: 0 } }
+    # a 4-frame ping-pong clip at 12 fps: 0 1 2 3 2 1 0 1 …
+    spawn Bouncer { SpriteAnim { fps: 12, frames: 4, mode: 2 } }
+    # a linear 0..10 tween over 10 ticks.
+    spawn Mover { Motion { dur: 10, from: 0, to: 10, ease: 0 } }
+
+    let sa  = World.prop_id("SpriteAnim")
+    let saf = World.field_id(sa, "frame")
+    let mo  = World.prop_id("Motion")
+    let mov = World.field_id(mo, "value")
+    let mod = World.field_id(mo, "done")
+
+    let sprite  = World.query_next(sa, 0)              # lowest id: the Sprite
+    let bouncer = World.query_next(sa, sprite + 1)     # next SpriteAnim: the Bouncer
+    let mover   = World.query_next(mo, 0)
+
+    tick_n(5)                                          # ticks = 5
+    print(World.get(sprite, sa, saf))                 # loop: (5*12/60) % 4 = 1
+    print(World.get(mover, mo, mov))                  # linear: 5
+
+    tick_n(5)                                          # ticks = 10
+    print(World.get(sprite, sa, saf))                 # (10*12/60) % 4 = 2
+    print(World.get(mover, mo, mov))                  # clamped at dur -> 10
+
+    tick_n(10)                                         # ticks = 20
+    print(World.get(sprite, sa, saf))                 # (20*12/60) % 4 = 0
+    print(World.get(bouncer, sa, saf))                # pingpong, elapsed 4, period 6 -> 2
+
+    # the Mover finished: value rests at `to`, done latched.
+    print(World.get(mover, mo, mov))                  # 10
+    print(World.get(mover, mo, mod))                  # 1
+
+    tick_n(5)                                          # ticks = 25
+    print(World.get(bouncer, sa, saf))                # pingpong, elapsed 5, 6-5 = 1
+
+    quit()
+  }
+
+  # run the Update phase n times; the engine systems advance one tick each call.
+  function tick_n(n: int) -> void {
+    var i = 0
+    while i < n { tick_fixed();  i = i + 1 }
+  }
+}

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)
+  }
+}

selfhost/backend/emit_decl.ludic

@@ -160,7 +160,7 @@ function emit_program() -> void {
     i = i + 1
   }
   if len(g_events) > 0 { emit_event_fns() }       # EV0: @ev_<E> event-dispatch functions
-  if has_ecs() and (len(g_events) > 0 or g_uses_query or g_uses_reflect) { emit_world_table() }   # EV2/EV8: the mod reflection ABI (also powers Query.* / Reflect.*)
+  if has_ecs() and (len(g_events) > 0 or g_uses_query or g_uses_reflect or g_uses_esys) { emit_world_table() }   # EV2/EV8: the mod reflection ABI (also powers Query.* / Reflect.* / engine systems)
   if has_ecs() { emit_ecs_allocator();  emit_snapshot() }
   if has_ecs() { emit_net() }                     # N2/N3: @Sync serializers + @Owned storage (gated internally)
   if has_ui() { emit_ui_build() }

selfhost/backend/game/emit_ecs.ludic

@@ -8,6 +8,10 @@ const MAX_ENT: int = 1024
 function has_systems() -> bool {
   var i = 0
   while i < len(prog) { if prog[i].kind == N_SYS { return true };  i = i + 1 }
+  # a game with no hand-written handler but a well-known engine component still
+  # runs a frame loop — the engine owns the system that ticks that component
+  # (#43/#47). Treat it as a systems game so the loop / tick helpers are emitted.
+  if uses_engine_systems() { return true }
   return false
 }
 function has_models() -> bool {
@@ -15,6 +19,19 @@ function has_models() -> bool {
   while i < len(prog) { if prog[i].kind == N_ARCH { return true };  i = i + 1 }
   return false
 }
+# does the program declare a well-known engine component? Each one is auto-ticked
+# by an engine-owned system (systems.ludic, wired in emit_engine_systems_for_
+# phase). Answering this drives the systems.ludic splice (parse.ludic) and the
+# reflection-ABI force-emit (emit_decl) — a game with none is byte-for-byte the
+# same as before the feature existed. Keep this list in sync with the phase table
+# in emit_engine_systems_for_phase.
+function uses_engine_systems() -> bool {
+  if find_comp("SpriteAnim") != null { return true }
+  if find_comp("Motion") != null { return true }
+  if find_comp("Light2D") != null { return true }
+  if find_comp("Occluder") != null { return true }
+  return false
+}
 # N5: does the program have an `entry` block? A game with both handlers and an
 # `entry` drives its own loop (calling tick_fixed/tick_render), instead of the
 # compiler's auto frame loop. A game with handlers and no entry uses the auto-loop.

selfhost/backend/game/emit_game.ludic

@@ -46,10 +46,33 @@ function emit_call_one(d: Node) -> void {
   emit("  br label %");  emit(skip);  emit("\n");  emit(skip);  emit(":\n")
 }
 
+# Engine-owned systems (#43/#47): systems the compiler injects into the frame
+# loop over a component the game merely declares and carries — the ECS hook the
+# animation and lighting follow-ups both stand on. Each entry is (component,
+# runtime fn, phase); the call is emitted only when the game declares that
+# component (so systems.ludic was spliced and the fn exists). They run *after*
+# the game's own handlers for the phase, so gameplay this frame is already
+# settled when the engine advances animation / accumulates light. Keep the
+# component list in sync with uses_engine_systems (emit_ecs.ludic).
+function emit_one_engine_system(comp: pointer, fn: pointer) -> void {
+  if (find_comp(comp) != null) and (find_fn(fn) != null) {
+    emit("  call void @fn_");  emit(fn);  emit("()\n")
+  }
+}
+function emit_engine_systems_for_phase(phase: pointer) -> void {
+  if (phase == "Update") {
+    emit_one_engine_system("SpriteAnim", "esys_spriteanim")
+    emit_one_engine_system("Motion", "esys_motion")
+  }
+  if (phase == "Render") {
+    emit_one_engine_system("Light2D", "esys_light2d")
+  }
+}
+
 # Global handlers run first, then the active scene's layer handlers in
 # declaration (draw) order. The active scene is snapshotted once per phase, so a
 # `become` mid-phase takes effect at the next phase boundary — exactly one scene
-# is active within any single phase.
+# is active within any single phase. Engine-owned systems for the phase run last.
 function emit_calls_for_phase(phase: pointer) -> void {
   var i = 0
   while i < len(prog) {
@@ -61,21 +84,23 @@ function emit_calls_for_phase(phase: pointer) -> void {
   var has_sc = false
   i = 0
   while i < len(prog) { let d = prog[i];  if d.kind == N_SYS and (d.ty == phase) and (d.c != null) { has_sc = true };  i = i + 1 }
-  if not has_sc { return }
-  let cs = emit_bind("load i32, ptr @L_scene")
-  i = 0
-  while i < len(prog) {
-    let d = prog[i]
-    if d.kind == N_SYS and (d.ty == phase) and (d.c != null) {
-      let ce = emit_bind(`icmp eq i32 {cs}, {itoa(d.c.ival)}`)
-      let run = lbl("scrun");  let skip = lbl("scskip")
-      emit("  br i1 ");  emit(ce);  emit(", label %");  emit(run);  emit(", label %");  emit(skip);  emit("\n")
-      emit(run);  emit(":\n")
-      emit_call_one(d)
-      emit("  br label %");  emit(skip);  emit("\n");  emit(skip);  emit(":\n")
+  if has_sc {
+    let cs = emit_bind("load i32, ptr @L_scene")
+    i = 0
+    while i < len(prog) {
+      let d = prog[i]
+      if d.kind == N_SYS and (d.ty == phase) and (d.c != null) {
+        let ce = emit_bind(`icmp eq i32 {cs}, {itoa(d.c.ival)}`)
+        let run = lbl("scrun");  let skip = lbl("scskip")
+        emit("  br i1 ");  emit(ce);  emit(", label %");  emit(run);  emit(", label %");  emit(skip);  emit("\n")
+        emit(run);  emit(":\n")
+        emit_call_one(d)
+        emit("  br label %");  emit(skip);  emit("\n");  emit(skip);  emit(":\n")
+      }
+      i = i + 1
     }
-    i = i + 1
   }
+  emit_engine_systems_for_phase(phase)               # engine-owned systems run after every user handler
 }
 
 # on enter / on exit compile to void functions @scene_enter_<Name> /

selfhost/frontend/parse.ludic

@@ -407,6 +407,7 @@ var g_uses_reflect: bool = false  # a program mentioned Reflect.* -> force-emit
 var g_uses_light: bool = false    # a program mentioned Light.* -> splice the 2D light pass
 var g_uses_value: bool = false    # Value.*/Json.*/Reflect.serialize -> splice the value tree + JSON (#44)
 var g_uses_reflect_io: bool = false  # Reflect.serialize/apply -> splice the reflection serializer
+var g_uses_esys: bool = false     # an engine-owned system component (SpriteAnim/Motion/Light2D) is declared -> splice systems.ludic + force the reflection ABI
 
 function already_loaded(full: pointer) -> bool {
   var i = 0
@@ -603,6 +604,18 @@ function maybe_splice_runtime() -> void {
     do_import("runtime/native/reflect_io.ludic")
     cur_dir = saved
   }
+  # engine-owned systems (#43/#47): a game that declares a well-known engine
+  # component (SpriteAnim / Motion / Light2D / Occluder) gets systems.ludic
+  # spliced, and the compiler inserts a call to each esys_* at its frame phase
+  # (emit_engine_systems_for_phase). The systems read/write components through the
+  # reflection ABI, so g_uses_esys also force-emits the world table (emit_decl).
+  # Light2D/Occluder additionally consume the 2D light pass, so pull it in too.
+  if uses_engine_systems() {
+    g_uses_esys = true
+    cur_dir = ""
+    do_import("runtime/native/systems.ludic")
+    cur_dir = saved
+  }
 }
 
 function parse_program() -> void {
@@ -623,6 +636,7 @@ function parse_program() -> void {
   g_uses_regex = false
   g_uses_query = false
   g_uses_reflect = false
+  g_uses_esys = false
   g_uses_light = false
   g_uses_value = false
   g_uses_reflect_io = false

tools/x/test.ludic

@@ -242,6 +242,11 @@ function cmd_test() -> int {
   net_case("ecs/world_mixed", "99")
   net_case("ecs/world_query", "2 110")
 
+  # #43: engine-owned systems auto-advance the SpriteAnim / Motion components a
+  # game merely declares and carries — no handler wired. Entry-driven so it can
+  # assert the auto-advanced fields at known tick counts.
+  net_case("library/anim_ecs", "1 5 2 10 0 2 10 1 1")
+
   feat_case("events/recurse", "", "16", "recurse.ludic (EV6: re-entrant emit is depth-bounded, no runaway cycle)")
   net_case("events/scoped", "2")
   net_case("ecs/world_dyn", "0 1 30 100 1 30")