feat: initial implementation with build_rig + build_animation
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.
This commit is contained in:
Axel Meyer
181
init.lua
Normal file
181
init.lua
Normal file
@@ -0,0 +1,181 @@
|
||||
-- lib-core.puppet v0.1.0
|
||||
-- Skeletal animation: skeleton + bones + tracks + rest + keyframe
|
||||
-- + procedural + look-at constraint. No footplant in v0.1.
|
||||
|
||||
local M = {}
|
||||
|
||||
-- ====================================================================
|
||||
-- Module state (lib-singleton)
|
||||
-- ====================================================================
|
||||
local all_puppets = {} -- {[handle] = puppet_instance}
|
||||
local next_handle = 1
|
||||
|
||||
-- ====================================================================
|
||||
-- Utility helpers
|
||||
-- ====================================================================
|
||||
local function deep_copy(t)
|
||||
if type(t) ~= "table" then return t end
|
||||
local copy = {}
|
||||
for k, v in pairs(t) do copy[k] = deep_copy(v) end
|
||||
return copy
|
||||
end
|
||||
|
||||
local function clamp_angle_rad(a)
|
||||
-- Normalize to [-pi, pi]
|
||||
local pi = math.pi
|
||||
while a > pi do a = a - 2 * pi end
|
||||
while a < -pi do a = a + 2 * pi end
|
||||
return a
|
||||
end
|
||||
|
||||
-- Subsequent tasks add: sample_animation,
|
||||
-- spawn, despawn, update, render, set_look_target, clear_look_target,
|
||||
-- bone_angle, set_procedural, clear_procedural, write_bone, play, stop,
|
||||
-- stop_all, is_playing, position, facing, move_to, register_animation,
|
||||
-- load_rig, load_animation.
|
||||
|
||||
-- ====================================================================
|
||||
-- Rig validation + build
|
||||
-- ====================================================================
|
||||
function M.build_rig(rig_table)
|
||||
if type(rig_table) ~= "table" then
|
||||
error("puppet.build_rig: rig_table must be a table")
|
||||
end
|
||||
if type(rig_table.bones) ~= "table" or #rig_table.bones == 0 then
|
||||
error("puppet.build_rig: rig.bones must be a non-empty array")
|
||||
end
|
||||
if type(rig_table.tracks) ~= "table" then
|
||||
error("puppet.build_rig: rig.tracks must be an array")
|
||||
end
|
||||
|
||||
-- Build bones_by_id with shallow copies of rest pose.
|
||||
local bones_by_id = {}
|
||||
for _, b in ipairs(rig_table.bones) do
|
||||
if type(b.id) ~= "string" then
|
||||
error("puppet.build_rig: bone.id must be string")
|
||||
end
|
||||
if bones_by_id[b.id] ~= nil then
|
||||
error("puppet.build_rig: duplicate bone id: " .. b.id)
|
||||
end
|
||||
bones_by_id[b.id] = {
|
||||
id = b.id,
|
||||
parent = nil, -- resolved below
|
||||
rest = {
|
||||
x = b.rest.x, y = b.rest.y,
|
||||
-- JSON angles in degrees; convert to radians once.
|
||||
angle = math.rad(b.rest.angle or 0),
|
||||
},
|
||||
look_at = (b.look_at == true),
|
||||
color = b.color or { 200, 200, 200 },
|
||||
}
|
||||
end
|
||||
|
||||
-- Resolve parents (object references).
|
||||
for _, b_src in ipairs(rig_table.bones) do
|
||||
local b = bones_by_id[b_src.id]
|
||||
if b_src.parent ~= nil then
|
||||
local parent_obj = bones_by_id[b_src.parent]
|
||||
if parent_obj == nil then
|
||||
error("puppet.build_rig: parent '" .. tostring(b_src.parent)
|
||||
.. "' of bone '" .. b.id .. "' not found")
|
||||
end
|
||||
b.parent = parent_obj
|
||||
end
|
||||
end
|
||||
|
||||
-- Build tracks + validate each bone is in EXACTLY ONE track.
|
||||
local bone_to_track = {}
|
||||
local tracks_by_id = {}
|
||||
for _, t in ipairs(rig_table.tracks) do
|
||||
if type(t.id) ~= "string" then
|
||||
error("puppet.build_rig: track.id must be string")
|
||||
end
|
||||
if tracks_by_id[t.id] ~= nil then
|
||||
error("puppet.build_rig: duplicate track id: " .. t.id)
|
||||
end
|
||||
local bones_in_track = {}
|
||||
for _, bid in ipairs(t.bones) do
|
||||
if bones_by_id[bid] == nil then
|
||||
error("puppet.build_rig: track '" .. t.id
|
||||
.. "' references unknown bone '" .. bid .. "'")
|
||||
end
|
||||
if bone_to_track[bid] ~= nil then
|
||||
error("puppet.build_rig: bone '" .. bid
|
||||
.. "' assigned to multiple tracks ('"
|
||||
.. bone_to_track[bid] .. "' and '" .. t.id .. "')")
|
||||
end
|
||||
bone_to_track[bid] = t.id
|
||||
bones_in_track[#bones_in_track + 1] = bid
|
||||
end
|
||||
tracks_by_id[t.id] = { id = t.id, bones = bones_in_track }
|
||||
end
|
||||
|
||||
return {
|
||||
id = rig_table.id or "anonymous",
|
||||
bones = rig_table.bones, -- keep original-order array
|
||||
bones_by_id = bones_by_id,
|
||||
tracks_by_id = tracks_by_id,
|
||||
bone_to_track = bone_to_track,
|
||||
}
|
||||
end
|
||||
|
||||
-- ====================================================================
|
||||
-- Animation validation + build
|
||||
-- ====================================================================
|
||||
function M.build_animation(anim_table, rig)
|
||||
if type(anim_table) ~= "table" then
|
||||
error("puppet.build_animation: anim_table must be a table")
|
||||
end
|
||||
if type(anim_table.track) ~= "string" then
|
||||
error("puppet.build_animation: animation.track must be string")
|
||||
end
|
||||
if rig.tracks_by_id[anim_table.track] == nil then
|
||||
error("puppet.build_animation: animation.track '"
|
||||
.. anim_table.track .. "' not found in rig")
|
||||
end
|
||||
if type(anim_table.duration) ~= "number" or anim_table.duration <= 0 then
|
||||
error("puppet.build_animation: animation.duration must be positive number")
|
||||
end
|
||||
if type(anim_table.keyframes) ~= "table" or #anim_table.keyframes == 0 then
|
||||
error("puppet.build_animation: animation.keyframes must be non-empty array")
|
||||
end
|
||||
|
||||
-- Validate each keyframe: t in [0, duration], bones referenced are in this animation's track.
|
||||
local track_bones = {}
|
||||
for _, bid in ipairs(rig.tracks_by_id[anim_table.track].bones) do
|
||||
track_bones[bid] = true
|
||||
end
|
||||
|
||||
local keyframes = {}
|
||||
for i, kf in ipairs(anim_table.keyframes) do
|
||||
if type(kf.t) ~= "number" or kf.t < 0 or kf.t > anim_table.duration + 1e-9 then
|
||||
error("puppet.build_animation: keyframe[" .. i .. "].t out of [0, duration]")
|
||||
end
|
||||
local cooked = { t = kf.t, bones = {} }
|
||||
for k, v in pairs(kf) do
|
||||
if k ~= "t" then
|
||||
if rig.bones_by_id[k] == nil then
|
||||
error("puppet.build_animation: keyframe references unknown bone '" .. k .. "'")
|
||||
end
|
||||
if not track_bones[k] then
|
||||
error("puppet.build_animation: keyframe writes bone '" .. k
|
||||
.. "' which is not in animation's track '" .. anim_table.track .. "'")
|
||||
end
|
||||
cooked.bones[k] = {
|
||||
angle = math.rad(v.angle or 0), -- JSON degrees → radians
|
||||
}
|
||||
end
|
||||
end
|
||||
keyframes[i] = cooked
|
||||
end
|
||||
|
||||
return {
|
||||
id = anim_table.id or "anonymous",
|
||||
track = anim_table.track,
|
||||
duration = anim_table.duration,
|
||||
loop = (anim_table.loop == true),
|
||||
keyframes = keyframes,
|
||||
}
|
||||
end
|
||||
|
||||
return M
|
||||
Reference in New Issue
Block a user