diff --git a/changes/core-components.md b/changes/core-components.md new file mode 100644 index 00000000..c21c5bb8 --- /dev/null +++ b/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`. diff --git a/docs/CONTROLLERS.md b/docs/CONTROLLERS.md index eb5ea103..67567b79 100644 --- a/docs/CONTROLLERS.md +++ b/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`. | diff --git a/examples/library/core_components.ludic b/examples/library/core_components.ludic new file mode 100644 index 00000000..20d1c01b --- /dev/null +++ b/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 + } +} diff --git a/packages/ludic.core/components.ludic b/packages/ludic.core/components.ludic new file mode 100644 index 00000000..f3bd4e9b --- /dev/null +++ b/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 } diff --git a/packages/ludic.core/package.ludic b/packages/ludic.core/package.ludic new file mode 100644 index 00000000..1bf388c4 --- /dev/null +++ b/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" diff --git a/tools/x/test.ludic b/tools/x/test.ludic index 62f5f2f4..95096e8c 100644 --- a/tools/x/test.ludic +++ b/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)")