feat(ecs): engine-owned systems auto-tick user components (#43)
All checks were successful
bootstrap / cfree-fixpoint (push) Successful in 18s
ci / build-and-test (push) Successful in 1m17s
commit-lint / conventional-commits (push) Successful in 4s
docs / build-and-deploy (push) Successful in 20s

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>
This commit is contained in:
Orkun ÇAKILKAYA 2026-08-31 15:41:44 +03:00
parent 9452557f3c
commit b0143337d9
10 changed files with 15109 additions and 14658 deletions

View file

@ -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`,