feat(core): #77 ship canonical Position/Body/Collider from ludic.core package

The engine-owned esys_move (#65) reads Position/Body/Collider/Solids by name,
but no package defined them — every game and example re-declared identical
bundles by hand. Ship them as the source package ludic.core; games import
instead of copy-pasting, and extend by composition (attach their own
components on the same model). AOT → compiles into the consumer's ECS with no
seam; integer + Q16.16 deterministic. Adds examples/library/core_components
(driven by esys_move, composed with a game Health component) as a
controller_case (104/0).

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

changes/core-components.md

@@ -0,0 +1,3 @@
+bump: minor
+type: feat
+Canonical engine-ABI components (#77) — the shared `Position` / `Body` / `Collider` / `Solids` bundles the engine-owned movement system (`esys_move`, #65) reads by name are now shipped from a base source package, **ludic.core**, instead of being re-declared by hand in every game and example. A game `import "ludic.core/components.ludic"` and the engine moves and collides its entities for free; extend by *composition* (attach your own components on the same model). AOT means the properties compile straight into the consumer's compile-time ECS with no ABI seam, and everything stays integer + Q16.16 deterministic (lockstep / replay / `world_save` hold). Example: `examples/library/core_components.ludic`.

docs/CONTROLLERS.md

@@ -53,6 +53,7 @@ controller.
 
 | Package | Issue | What it gives you |
 | --- | --- | --- |
+| **ludic.core** | #77 | The canonical engine-ABI components the movement system reads by name — `Position`, `Body`, `Collider`, `Solids` — so a game imports them instead of hand-declaring the bundles. Extend by composition (attach your own components alongside). |
 | **ludic.gameplay** | #57 | The shared foundation: `Cooldown` timer, `Stats` + a timed modifier stack, a `Faction` friend/enemy/neutral table, and a `Combat` damage pipeline (`cancellable DamageAboutToApply` with a mutable amount, `Damaged`/`Died`/`Healed`). |
 | **ludic.platformer** | #58 | Jump-feel `Platformer` (apex/coyote/buffer/variable-height/multi-jump), decomposed input/move/gravity/jump/anim sub-systems, `JumpRequested`/`Landed`/`StateChanged` events, a gravity policy enum, and opt-in scaffolding (moving/crumble platforms with rider carry, pickups+`Score`, springs, hazards+`Life`, checkpoints/goal). |
 | **ludic.shooter** | #60 | `TopDown` decoupled move + aim (mouse / stick / move-dir / nearest-enemy auto-aim), a name-keyed `Weapon` registry (fire-rate/spread/pellets/pattern + data-driven pierce/homing), a deterministic `Projectile` pool (faction-filtered hits through `Combat`, pierce, ring/spiral patterns, homing), and a budgeted wave `Spawner`. |

examples/library/core_components.ludic

@@ -0,0 +1,45 @@
+# core_components.ludic — exercises the ludic.core canonical components (#77):
+# Position / Body / Collider imported from the package instead of hand-declared,
+# driving the engine-owned esys_move (#65) exactly as a copy-pasted bundle would,
+# and composed with a game-defined Health component on the same model.
+#
+# Deterministic; a full run prints:  110 30 184 1
+#
+# Build (from the repo root, so runtime/native resolves):
+#   LUDIC_MODULES=packages ludicc --headless examples/library/core_components.ludic
+program CoreComponents {
+  import "ludic.core/components.ludic"
+
+  # a game-defined component, composed alongside the canonical engine ones — no
+  # subclassing, just another property on the same model.
+  property Health { hp: int = 0 }
+
+  function tick_n(n: int) -> void { var i = 0;  while i < n { tick_fixed();  i = i + 1 } }
+
+  entry {
+    let pp = World.prop_id("Position")
+    let pb = World.prop_id("Body")
+    let ph = World.prop_id("Health")
+    let f_x = World.field_id(pp, "x")
+    let f_y = World.field_id(pp, "y")
+    let f_grd = World.field_id(pb, "on_ground")
+    let f_hp = World.field_id(ph, "hp")
+
+    # A. top-down constant velocity over the *package* Body/Position bundles.
+    spawn Mover { Position { x: 100, y: 50 }, Body { vx: fixed(2), policy: 1 }, Collider { w: 16, h: 16 }, Health { hp: 30 } }
+    let a = World.query_next(pb, 0)
+    tick_n(5)
+    print(World.get(a, pp, f_x))                     # 110 — +2px/frame, exact
+    print(World.get(a, ph, f_hp))                    # 30  — the composed game component coexists
+    despawn a
+
+    # B. a gravity body falls and lands on a solid floor entity — the engine reads
+    # the package-defined Position/Body/Collider by name, no local re-declaration.
+    spawn Floor  { Position { x: 0, y: 200 }, Collider { w: 400, h: 16 } }
+    spawn Faller { Position { x: 50, y: 40 }, Body { gravity: fixed(1), max_fall: fixed(6) }, Collider { w: 16, h: 16 } }
+    let b = World.query_next(pb, 0)
+    tick_n(80)
+    print(World.get(b, pp, f_y))                     # 184 — feet rest on the floor top (200)
+    print(World.get(b, pb, f_grd))                   # 1   — on_ground
+  }
+}

packages/ludic.core/components.ludic

@@ -0,0 +1,47 @@
+# components.ludic — the canonical engine-ABI components (#77).
+#
+# These are the exact bundles runtime/native/systems_move.ludic (#65) reads by
+# name. Import this file instead of re-declaring them, and the engine-owned
+# `esys_move` system moves and collides your entities for free — declare a Body
+# (and optionally a Collider) and it is ticked in the Update phase.
+#
+# Every field is defaulted so a game overrides only what it needs, and any field
+# the move system does not find on an entity no-ops cleanly. Extend by
+# *composition*: attach your own components (Health, Sprite, an AI brain) on the
+# same model next to these; nothing here needs subclassing.
+
+# The world anchor: integer pixels. This is the *rendered* location — a
+# framebuffer pixel is the smallest drawable unit — so it stays integer. Sub-pixel
+# motion accumulates in Body.rx/ry (Q16.16) and only the whole-pixel carry reaches
+# Position (see docs/RFC-POSITION-TYPES.md, #78).
+property Position { x: int = 0, y: int = 0 }
+
+# A moving body: Q16.16 velocity, optional gravity, engine-owned sub-pixel
+# accumulators, and the polled contact outputs the move system writes each frame.
+#   policy 0 = platformer (gravity applies)   policy 1 = top-down (no gravity)
+# on_ground / hit_wall / hit_ceiling and the optional contact normal hit_nx/hit_ny
+# are OUTPUTS: read them in a handler to raise your own landing / bonk events
+# (the SpriteAnim.event_fired pattern — polled flags, no engine coupling).
+property Body {
+  vx: fixed = 0.0, vy: fixed = 0.0,
+  gravity: fixed = 0.0, max_fall: fixed = 0.0,
+  rx: fixed = 0.0, ry: fixed = 0.0,
+  policy: int = 0,
+  on_ground: int = 0, hit_wall: int = 0, hit_ceiling: int = 0,
+  hit_nx: int = 0, hit_ny: int = 0
+}
+
+# An axis-aligned box off the Position anchor. A solid Collider resolves swept-AABB
+# collisions; a trigger (is_trigger = 1) reports overlap without resolving. layer /
+# mask are collision bitmasks (0 = all); one_way = 1 is a platform that blocks only
+# a downward landing. hit / entered / exited are trigger OUTPUTS.
+property Collider {
+  w: int = 0, h: int = 0, offx: int = 0, offy: int = 0,
+  is_trigger: int = 0, one_way: int = 0, layer: int = 0, mask: int = 0,
+  hit: int = 0, entered: int = 0, exited: int = 0
+}
+
+# Optional single config entity that turns the tile-grid broadphase on: solids are
+# read from the Map.* tilemap. tile > 0 sets the tile size in px; wall is the solid
+# glyph; oneway is an optional one-way-platform glyph (0 = none).
+property Solids { tile: int = 0, wall: int = 0, oneway: int = 0 }

packages/ludic.core/package.ludic

@@ -0,0 +1,22 @@
+# ludic.core — the canonical engine-ABI components (#77).
+#
+# The engine-owned movement system (runtime/native/systems_move.ludic) reads
+# Position / Body / Collider / Solids *by name* through the reflection ABI, but
+# no package defined them — so every game and every example re-declared identical
+# `property Position/Body/Collider` bundles by hand, copy-pasting the engine ABI.
+# That is exactly the kind of thing a game developer should never hand-write.
+#
+# This package ships those bundles as the one canonical definition. A game
+# imports them instead of copy-pasting, and extends by *composition* — attach
+# your own components alongside on the same model; the engine still resolves
+# Position/Body/Collider by name, and any field a game does not need simply keeps
+# its default. It is an ordinary source package: AOT means the properties compile
+# straight into the consumer's compile-time ECS with no ABI seam, and everything
+# stays integer + Q16.16 deterministic (lockstep / replay / world_save hold).
+package "ludic.core"
+version "0.1.0"
+kind source
+provides "Position"
+provides "Body"
+provides "Collider"
+provides "Solids"

tools/x/test.ludic

@@ -240,6 +240,7 @@ function cmd_test() -> int {
   feat_case("library/physics", "", "184 1 1 284 1 1 50 51 104 1 134 1 120 0 1 1 1 0 1 1 1", "physics.ludic (Body + Collider + esys_move: gravity/land, wall stop, sub-pixel, entity platform, one-way, triggers — entity broadphase; issue #65)")
   feat_case("library/physics_tiles", "", "112 1 80 1 48 1 60", "physics_tiles.ludic (esys_move tile-grid broadphase: tile floor/wall + one-way tile land-from-above / rise-through; issue #65)")
   # builtin gameplay controllers, consumed as in-repo packages (issues #57-#61)
+  controller_case("library/core_components", "", "110 30 184 1", "core_components.ludic (ludic.core #77: canonical Position/Body/Collider imported from a package, driving esys_move, composed with a game Health component)")
   controller_case("library/gameplay_foundation", "", "2 0 1 5 24 0 2 1 15 85 7 1 1", "gameplay_foundation.ludic (ludic.gameplay #57: Cooldown timer + Stats/modifier stack + Faction table + Combat cancel/mutable pipeline)")
   controller_case("games/platformer_demo", "", "1 1 1 1 1 1 1 1", "platformer_demo.ludic (ludic.platformer #58: gravity/land, jump apex, coyote, veto-gated double jump, wall collision + disable-system lever)")
   controller_case("games/platformer_scaffolding", "", "1 1 1 1 1 1", "platformer_scaffolding.ludic (ludic.platformer #58 layers 4-5: moving-platform rider carry, pickup->score, spring, hazard+Life i-frames)")