Multi-look-target API: set_look_target(handle, target_id, x, y),
clear_look_target(handle, target_id). Bones declare look_at as string
target-id; legacy look_at=true maps to target_id="default". Slerp-style
smoothing: look_at_slerp field (exponential approach, clamped to [0,1]
per frame). Linear look_at_speed kept for backward-compat. Virtual bone
flag: virtual=true skips render pass but participates in compute_world.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds optional 'sprite_rot' field (degrees in JSON, radians stored) to
bone schema. Applied at render: world.rot + sprite_rot. Substrate
convention (puppet.c:295, 2101). Use case: head_001.png has face-right
at rot=0 (asymmetric sprite); without sprite_rot=-90 the look-at result
appears 90° off because math computes rotation assuming sprite-top=
forward but the sprite's natural forward is sprite-right.
Default sprite_rot=0 keeps body, shoulder, arm bones unchanged.
Previously the look-at-rate-limit read p.bone_state[bid].rot as 'current'
and advanced from it. But bone_state.rot is reset-to-rest + keyframe-
sampled at frame start, so 'current' was always near rest (~0) and the
rate-limit only advanced one frame's worth (~7deg) per frame. Visual
result: head/body rotation appeared capped at ~10deg.
Fix: persistent p.look_at_state[bid] table carries angle across frames.
Rate-limit operates on look_at_state.angle (not bone_state.rot). After
rate-limit + clamp, value is written to bone_state.rot.
Init: look_at_state[bid].angle = b.rest.rot on first encounter, so the
first frame advances from rest pose toward target (matches substrate
LookAtState init convention).
- Look-at uses math.atan(dx, -dy) (substrate sprite-top convention):
rot=0 means sprite top points up (in -Y), rot=pi/2 means right.
- New rest.rot_min/rot_max fields (degrees in JSON; clamped after look-at)
- New look_at_speed field (deg/s; rate-limits look-at via dt)
- write_bone now accepts rot/pos/scl channels (legacy 'angle' rejected)
- Bones not in any track are allowed; write_bone bypasses track-guard
for them. Enables procedural root-rotation while keyframe-anims play.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- 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.
- set_foot_sprite_reach_test_only(handle, leg_index, value)
- foot_state_test_only(handle, leg_index)
- bone_animated_test_only(handle, bone_id)
Test-only helpers (not for production use) to enable headless unit tests
of the procedural-locomotion-layer and bone_animated keyframe-priority
flag. Used by puppet-test Groups 9-11.
- build_rig parses optional rig.locomotion block (mode/step_trigger/
step_placement/step_duration/step_height/idle_return_delay/legs[])
- spawn initializes per-puppet foot_state[] table (planted/stepping
state, anchor/cur world-positions, sprite_reach from leg-texture)
- apply_locomotion (substrate puppet.c:1000-1156 port): step-trigger
on hip-displacement > step_trigger; smoothstep step-progression with
arc-height; leg-aim via atan2(-dx, dy); leg-stretch via scl_y clamp
[0.2, 2.5]; foot world-pos override
- Skips legs where bone_animated is set on leg or foot (keyframe priority)
- Integrated as step 4 in M.update post-cascade
- load_textures caches texture_width/height per bone for sprite_reach
No new tests yet (added in Phase 3e). Existing 24 assertions remain
GREEN (locomotion is no-op for rigs without locomotion-block).
Returns cascaded world.scl_x and scl_y for a bone. Used by puppet-test
Group 8 scale-cascade assertions; future: vagrant-skeleton or other
modules can query world-scale for compositing/effects.
Previously the render path read per-bone constant `b.scale` and
`ws.angle`. With multi-channel keyframes + scale-cascade, the rendered
sprite-scale comes from the cascaded `world.scl_x/y` and angle from
`world.rot`. No new tests — visual verification at Phase-4 manual test.
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.
