96ccb410d3
- apply_locomotion idle-return: after (now - last_move_time) > idle_return_delay, the most-displaced planted leg steps back to its current hip position (over idle_step_duration). Group-stagger via bumping last_move_time forward by idle_return_stagger. - M.move_to tracks p.last_move_time when position actually changes. - README v0.3.0 changelog entry.
161 lines
6.0 KiB
Markdown
161 lines
6.0 KiB
Markdown
# lib-core.puppet
|
|
|
|
Skeletal animation primitive for top-down 2D characters: bones,
|
|
tracks, rest pose, keyframe animations, procedural animations
|
|
(Lua-side), and look-at constraint. No footplant IK in v0.1
|
|
(deferred).
|
|
|
|
**Version:** 0.3.0
|
|
**Lib-ID:** lib-core.puppet
|
|
**Requires:** (none — pure Lua + engine.render.*)
|
|
**Tags:** animation, skeleton, puppet, character
|
|
|
|
## Topology
|
|
|
|
<!-- topology:start (auto-generated; do not edit) -->
|
|
<!-- topology:end -->
|
|
|
|
## API
|
|
|
|
### `puppet.build_rig(rig_table)`
|
|
|
|
Validates a rig table (parsed from `*.rig.json`) and returns an
|
|
internal representation with `bones_by_id`, parent-resolved object
|
|
references, and track-membership maps. Raises on invalid data
|
|
(missing parents, bones in 2 tracks, etc.).
|
|
|
|
### `puppet.build_animation(anim_table, rig)`
|
|
|
|
Validates an animation table against a built rig (bones referenced
|
|
in keyframes must exist and be in the animation's declared track).
|
|
|
|
### `puppet.sample_animation(animation, t)`
|
|
|
|
Returns a frame `{ <bone_id> = { angle = <number>, ... }, ... }`
|
|
sampling the animation at time `t` with linear interpolation. Wraps
|
|
on `t > duration` if `animation.loop` is true.
|
|
|
|
### `puppet.spawn(rig, { x, y })`, `puppet.despawn(handle)`
|
|
|
|
Spawn a new puppet instance at world position (x, y). Returns an
|
|
opaque handle. `despawn` removes the instance.
|
|
|
|
### `puppet.update(dt)`, `puppet.render(handle)`
|
|
|
|
`update(dt)` runs the pipeline for ALL spawned puppets (rest →
|
|
look-at → keyframes → procedural). `render(handle)` draws ONE
|
|
puppet via `engine.render.draw_rect_rotated` per bone.
|
|
|
|
### `puppet.set_look_target(p, world_x, world_y)`, `puppet.clear_look_target(p)`
|
|
|
|
Set or clear the look-at target. Bones marked `look_at: true` in the
|
|
rig rotate to face the target.
|
|
|
|
### `puppet.bone_angle(p, bone_id)`
|
|
|
|
Returns the current world-space angle of `bone_id` (after the
|
|
full pipeline tick). Used by tests + by callers needing bone-state.
|
|
|
|
### `puppet.set_procedural(p, name, callback)`, `puppet.clear_procedural(p, name)`
|
|
|
|
Register or unregister a per-frame procedural callback. Callback
|
|
signature: `function(handle, dt)`. Inside the callback, mutate
|
|
bones via `puppet.write_bone(handle, bone_id, { angle = <number> })`.
|
|
|
|
### `puppet.play(p, animation_name, { loop, speed })`, `puppet.stop(p, animation_name)`, `puppet.stop_all(p)`, `puppet.is_playing(p, animation_name)`
|
|
|
|
Keyframe-layer controls. Animation must be registered via
|
|
`puppet.register_animation(p, anim)` first.
|
|
|
|
### `puppet.register_animation(p, animation)`
|
|
|
|
Binds a built animation (from `build_animation`) to a puppet
|
|
instance, making it available to `play`.
|
|
|
|
### `puppet.load_rig(path, asset_aliases?)`
|
|
|
|
Loads a rig from a JSON file and optionally resolves its bone textures
|
|
via `puppet.load_textures`. Pass the module's `asset_aliases` table
|
|
(from `engine.module.asset_aliases()`) to enable sprite-mode rendering;
|
|
omit for colored-rect-only rigs.
|
|
|
|
### `puppet.load_textures(rig, asset_aliases)`
|
|
|
|
For each bone with a `texture` field, resolves the atlas-id to a
|
|
texture-handle via the asset-lib indirection: read `asset_aliases[rig.asset_pack]`
|
|
to get the lib-id, load `<lib-id>/assets/atlas.json`, look up the
|
|
atlas-entry by id, and call `engine.asset.load_texture` on the file
|
|
path. Also resolves bone anchors from the atlas (unless bone has an
|
|
explicit `anchor` field).
|
|
|
|
### `puppet.bone_world_transform(handle, bone_id)`
|
|
|
|
Returns the bone's cached world-transform `(x, y, angle)` from the
|
|
last `puppet.update` tick. Used by tests and by modules needing world-
|
|
space queries (e.g., for spawning effects at a bone position).
|
|
|
|
### `puppet.write_bone_test_only(handle, bone_id, angle_rad)`
|
|
|
|
Test-setup helper: directly write a bone angle bypassing the track-
|
|
conflict-guard. Not for production use; modules should write via
|
|
procedural callbacks.
|
|
|
|
### `puppet.load_animation(path, rig)`
|
|
|
|
Convenience wrapper: reads a JSON file and calls `build_animation`.
|
|
|
|
### `puppet.position(p)`, `puppet.facing(p)`, `puppet.move_to(p, x, y)`
|
|
|
|
Puppet owns its world position. `move_to` sets it instantly (caller
|
|
applies speed). `facing` returns the last-movement-direction angle.
|
|
|
|
### `puppet.write_bone(handle, bone_id, { angle })`
|
|
|
|
Procedural-callback-only API to mutate a bone. Validates track
|
|
ownership at write time.
|
|
|
|
## Conventions
|
|
|
|
- World-coords + pixel-units throughout (per ADR-0031).
|
|
- Bone angles in radians (internal). JSON rest-angles and animation
|
|
keyframe angles are in degrees, converted on load.
|
|
- Update pipeline runs once per frame (`puppet.update(dt)`) for ALL
|
|
spawned puppets. `render` is per-puppet so callers can interleave
|
|
with other rendering.
|
|
|
|
## CHANGELOG
|
|
|
|
### v0.3.0
|
|
- BoneState multi-channel (rot/pos/scl) with world.scl_x/y and world.rot
|
|
- Cascaded world-transform with scale propagation (compute_world)
|
|
- Procedural locomotion layer via rig.locomotion block (apply_locomotion):
|
|
step-trigger, step-placement, step-height, leg-aim + leg-stretch
|
|
- Idle-return logic in apply_locomotion: after (now - last_move_time) >
|
|
idle_return_delay, the most-displaced planted leg steps back to its hip
|
|
position over idle_step_duration; group-stagger via idle_return_stagger
|
|
- M.move_to tracks p.last_move_time when position actually changes
|
|
- Schema changes: rest.rot/scl required; legacy rest.angle rejected with
|
|
clear error message (Substrate-Parity v0.3.0 schema)
|
|
- Bone-rig top-level scale field removed; per-frame world state replaces it
|
|
- New APIs: bone_world_scale, set_foot_sprite_reach_test_only,
|
|
foot_state_test_only, bone_animated_test_only
|
|
|
|
### v0.2.0
|
|
- Rig-format extension (texture, z_order, scale, anchor, asset_pack
|
|
fields on bones; rig.bones_z_sorted for render-order)
|
|
- Multi-level parent-chain transform with depth-first update pipeline
|
|
- Sprite-mode render via engine.render.draw_sprite_transform
|
|
- New API: load_textures, bone_world_transform, write_bone_test_only
|
|
- All v0.1.0 rigs continue to work (texture-less bones fall back to
|
|
colored-rect render)
|
|
|
|
### v0.1.0
|
|
- Initial release: skeleton + bones + tracks + rest + keyframe +
|
|
procedural + look-at constraint. Footplant IK deferred.
|
|
|
|
## References
|
|
|
|
- `architecture/puppet.md` (Reference)
|
|
- ADR-0037 (Tests-as-Libs)
|
|
- ADR-0038 (API-Doc-Convention)
|