puppet.load_textures(rig, asset_aliases):
- Resolves bone.texture atlas-ids to texture-handles via the asset-
lib indirection. Reads asset_aliases[rig.asset_pack] to get the
asset-lib id, loads the lib's atlas.json, looks up the atlas-entry
by id, then calls engine.asset.load_texture on the resolved file
path.
- Resolves bone.anchor from the atlas entry unless the bone has an
explicit anchor override.
- Raises clear errors when alias/atlas-pack/atlas-id is missing.
puppet.load_rig(path, asset_aliases?) now optionally calls
load_textures after build_rig if asset_aliases is supplied.
README updated with new API entries (load_rig signature, load_textures,
bone_world_transform, write_bone_test_only) and CHANGELOG v0.2.0 entry.
Walks bones in z-sorted order (rig.bones_z_sorted, lowest first =
back). For each bone:
- If texture_handle present: draw via engine.render.draw_sprite_transform
using bone.scale and bone.anchor (negative scale mirrors the sprite,
anchor is the in-texture pivot).
- Else: fall back to colored rotated 16x4 rect via draw_rect_rotated
(Phase 1 behavior preserved).
bone_state[bid].world (cached by M.update's depth-first pipeline) is
the source of (x, y, angle).
Rewrites M.update to traverse the rig depth-first, computing each
bone's world-transform from its parent's already-cascaded world-pose
plus its own rest-offset and animated angle. Replaces the previous
single-level direct-from-origin transform.
Per-frame per-bone steps inside the traversal:
1. Sample keyframe from any playing anim on the bone's track
2. Apply look-at (uses parent's world from cascade)
3. Run procedural callbacks (once per puppet at root visit)
4. Compute and cache world-transform from parent.world + own rest + own angle
bone_state[bid].world = {x, y, angle} is the cache; render reads it.
New public API:
- puppet.bone_world_transform(handle, bone_id) -> (wx, wy, wa)
- puppet.write_bone_test_only(handle, bone_id, angle_rad) for test setup
Look-target previously interpreted as world-coords with bone-world-pos
= puppet origin + bone.rest. New implementation computes bone-world-pos
from cascaded parent transform, then subtracts the parent's accumulated
world-angle to store the LOCAL angle (so subsequent cascade in step 3.d
produces the correct final world-angle for the look-at bone).
spawn now initializes bone_state[bid].world = {x, y, angle} cache.
Additive extension to build_rig output, preserving backward-compat
with existing rigs that lack the new fields:
- bone.texture: optional atlas-id (string) for sprite-mode rendering;
resolved to a texture-handle by puppet.load_textures(). When absent
the bone falls back to colored-rect render via draw_rect_rotated.
- bone.z_order: render-sort key (lower = back, higher = front);
default 0.
- bone.scale: [sx, sy] pair; default [1, 1]; negative components
mirror the sprite.
- bone.anchor: optional [x, y] override of the atlas-supplied anchor.
- rig.asset_pack: alias-key into the consumer module's asset_aliases
manifest field; lets puppet.load_textures resolve atlas-ids to
texture-handles via the asset-lib.
- rig.bones_z_sorted: array of bones pre-sorted by z_order; render
walks this once per frame.
Version bumped to 0.2.0. Subsequent commits add multi-level parent-
chain transform, sprite-mode render, and load_textures.
The pipeline now stores radians uniformly in bone_state, matching the
look-at branch's math.atan output and the render path's draw_rect_rotated
expectations. JSON degrees are converted at the boundary (build_animation,
write_bone). sample_animation returns radians.
Three fixes to make puppet-test 14/14 assertions pass:
1. build_animation/sample_animation: store and interpolate keyframe
angles in degrees (remove premature math.rad conversion). Previously
the round-trip math.deg(math.rad(-15)) produced -15.0 which failed
strict equality against integer -15 in Lua 5.4.
2. write_bone + update keyframe apply: store angles directly without
math.rad conversion; bone_state now uses degrees for keyframe and
procedural channels (look_at still stores radians from math.atan).
3. update procedural loop: wrap each callback in pcall, disarm the
offending procedural on track-conflict error, then re-raise. This
prevents a failed procedural from one puppet leaving other puppets
un-updated on subsequent calls.
Render: each bone drawn as a rotated rect of fixed length+thickness
(16x4 px) centered at the bone's world-position with its current
angle. Sprite-based rendering deferred to Phase 2 when tilesets exist.
Load helpers: engine.asset.load_json(path) + build_rig/build_animation.
The engine provides a single-call JSON loader (reads file + parses JSON
-> Lua table) via engine.asset.load_json; there is no separate cjson.decode
API. Confirmed by engine_lua_asset.c and maps lib usage.
v0.1 complete: skeleton + bones + tracks + rest + keyframe + procedural
+ look-at + render + load. Footplant deferred.
Per-puppet instance state: position, facing, bone-state cache,
look-target, playing animations, registered procedural callbacks.
Per-frame update pipeline:
1. Reset bones to rest pose
2. Apply look-at constraint (bones marked look_at: true rotate to
face the target's world-position)
3. Advance + sample keyframe animations on their tracks
4. Run procedural callbacks (write_bone validates that the bone's
track is not currently keyframe-active)
Look-at math: bone world-pos = puppet origin + bone.rest offset
(parent-chain resolution stays simple in v0.1 since the only
look-at bone (head) attaches directly to torso at the origin).
Full parent-chain transform reserved for v0.2 when multi-level
rigs exist.
Samples an animation at time t. Wraps t for loops. Finds the
keyframe segment containing t and linearly interpolates per-bone
angles. Returns frame with angles in degrees (intuitive for tests
and callers; internal storage uses radians).
Edge cases handled:
- t = 0 returns first-keyframe values
- t = duration returns last-keyframe values (no overshoot)
- t > duration with loop=true wraps via modulo
- Keyframes with disjoint bone-sets: each bone interpolated where
available, snapped where only one side has it.
Validates and cooks rig + animation data into internal representations:
- build_rig: parses bones (with parent-resolution to object refs) and
tracks (with bone-uniqueness validation). Converts rest angles
from JSON degrees to radians.
- build_animation: validates each keyframe references only bones in
the animation's declared track. Converts keyframe angles from
degrees to radians.
Remaining functions (sample_animation, spawn, update, look-at,
procedural, render, lifecycle) follow in subsequent commits.
