Struct KfaSprite 

pub struct KfaSprite {
    pub limbs: Vec<Sprite>,
    pub hinges: Vec<Hinge>,
    pub hinge_sort: Vec<usize>,
    pub kfaval: Vec<BoneXform>,
    pub p: [f32; 3],
    pub s: [f32; 3],
    pub h: [f32; 3],
    pub f: [f32; 3],
    pub frmval: Vec<Vec<BoneXform>>,
    pub seq: Vec<Seq>,
    pub kfatim: i32,
    pub okfatim: i32,
}

One animated KFA sprite — bones + hinges + per-bone live animation values.

The host owns one of these per animated model, updates kfaval[] over time, and passes it to roxlap-core’s draw_kfa_sprite each frame. Construction is data-only (this crate); rendering is in roxlap-core.

Fields

limbs: Vec<Sprite>

One crate::sprite::Sprite per bone. Limb i’s (s, h, f, p) is computed per frame by the renderer from the parent’s transform + hinge math; the kv6 field holds the bone’s kv6 mesh and never changes.

hinges: Vec<Hinge>

Bone hierarchy. Mirror of voxlap’s kfatype.hinge[].

hinge_sort: Vec<usize>

Topological sort of bone indices — populated once at construction, used by the renderer’s per-frame loop.

kfaval: Vec<BoneXform>

Per-bone resolved local transform for the current frame (translation, quaternion rotation, scale). Generalises voxlap’s vx5.kfaval[] (which was a single Q15 hinge angle) to full TRS. Updated per frame by Self::animsprite, or poked directly by the host.

p: [f32; 3]

World-space anchor of the root limb’s hinge.p[0]. The root limb is positioned so hinge.p[0] lands at this point given the world basis below.

s: [f32; 3]

World-space basis for the root limb. Mirror of vx5sprite.{s, h, f} for the root.

h: [f32; 3]

f: [f32; 3]

frmval: Vec<Vec<BoneXform>>

Animation keyframe table — frmval[frame][hinge] local transforms. Empty until Self::set_animation; an empty table makes Self::animsprite a no-op so hosts that poke kfaval directly keep working.

seq: Vec<Seq>

Animation sequence — ordered (tim, frm) keyframes. Mirror of kfatype.seq. tim is an absolute timestamp (ms); frm is a frame index into frmval, or !target (bitwise-NOT, hence negative) for a jump/loop to seq entry target.

kfatim: i32

Current animation time (ms) — voxlap’s vx5sprite.kfatim. Advanced by Self::animsprite.

okfatim: i32

Previous animation time (ms) — voxlap’s vx5sprite.okfatim, used to cross-fade when the active sequence entry is itself a blend marker (seq[z].frm < 0). Host sets it when switching animations; Self::animsprite never writes it.

Implementations

impl KfaSprite

pub fn new( limbs: Vec<Sprite>, hinges: Vec<Hinge>, root_pos: [f32; 3], ) -> KfaSprite

Build a KFA sprite from a list of (Sprite, Hinge) bones. limbs.len() must equal hinges.len(). The first bone with parent < 0 is the root.

kfaval is initialised to all zeros; the host should set per-bone angles before / between render calls.

Panics

Panics if limbs.len() != hinges.len().

pub fn set_animation(&mut self, frmval: Vec<Vec<BoneXform>>, seq: Vec<Seq>)

Attach an animation curve — the frmval + seq tables parsed from a Kfa. After this, Self::animsprite drives kfaval from playback time instead of the host poking individual bones.

pub fn animsprite(&mut self, ti: i32)

Advance the animation by ti milliseconds and recompute every child bone’s kfaval — a faithful port of voxlap’s animsprite (voxlap5.c:11125).

Walks the sequence forward from the current kfatim (honouring !target jump/loop entries), then piecewise-linearly interpolates the two bracketing keyframes per hinge. Interpolation is angle-wrap-aware: a free hinge (vmin == vmax) takes the shortest path, a limited hinge winds in its allowed direction. When the active entry is itself a blend marker (seq[z].frm < 0), the pose cross-fades from the okfatim-derived frame.

No-op when no animation curve is attached (see Self::set_animation).

Trait Implementations

impl Clone for KfaSprite

fn clone(&self) -> KfaSprite

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.