feat(stdlib): add Anim.* + Tween.* — deterministic 2D animation & tweening (#5)
Two ECS-native, deterministic namespaces for 2D motion, driven off the fixed
frame clock so replays and lockstep netcode reproduce every frame and every
eased value exactly. Both are pure computed-inline Q16.16 / integer math (no new
runtime, no heap) — the game stores a timer on a component and calls these each
frame, exactly the way Collision.* / Grid.* are used.
Anim.* — spritesheet frame animation:
- Anim.frame(timer,fps,count) -> int looping frame index
- Anim.once(timer,fps,count) -> int one-shot, clamps on the last frame
- Anim.pingpong(timer,fps,count) -> int bounce 0..count-1..0
- Anim.finished(timer,fps,count) -> bool has a one-shot run past its end?
- Anim.duration(fps,count) -> fixed seconds for one cycle
- Anim.cell_x/cell_y(frame,cols,cell) -> int source rect on a grid sheet
Tween.* — value interpolation over a timeline:
- Tween.progress/loop/yoyo(timer,duration) -> fixed normalized amount
- Tween.done(timer,duration) -> bool
- Tween.ease(t, mode) -> fixed shape by a literal curve 0..6,
the same curves as Ease.* (now
factored into a shared ease_eval)
- Tween.number/round/point/tint(from,to,t) blend a fixed / int / Vector / color
The typed blends reuse the existing fixed / Vector / color helpers, and
Tween.ease shares Ease.*'s exact formulas via the new ease_eval(mode,t) — one
source of truth for every easing curve in the engine.
examples/library/anim.ludic asserts 34 cases (frame math, clamping, ping-pong,
cell geometry, timeline clamp/loop/yoyo, rounding, color/vector blends, and
Ease.in == Tween.ease(.,1)); wired into x test (now 62 passed). Docs: Anim +
Tween sections with 16 per-symbol pages, inventory/coverage green. Seed
reseeded; the C-free bootstrap fixpoint holds.
The stateful sugar the proposal sketches (named clips, Anim.play, fluent
Tween.chain/parallel handles, and an auto-injected advance system) is deliberately
left as a follow-up — this lands the deterministic math core both halves stand on.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parent
07e5a20c0e
commit
e4d1e95dcb
25 changed files with 12379 additions and 9910 deletions
174
selfhost/backend/stdlib/emit_anim.ludic
Normal file
174
selfhost/backend/stdlib/emit_anim.ludic
Normal file
|
|
@ -0,0 +1,174 @@
|
|||
# emit_anim.ludic — 2D animation: the Anim.* (spritesheet frame animation) and
|
||||
# Tween.* (value interpolation over a timeline) namespaces. Both are pure,
|
||||
# deterministic Q16.16 / integer math driven off the game's fixed frame clock —
|
||||
# the game stores a timer in a component and calls these each frame, exactly the
|
||||
# way Collision.* / Grid.* are used. Same inputs -> same frame and same eased
|
||||
# value on every run, so replays and lockstep netcode reproduce motion exactly.
|
||||
#
|
||||
# Conventions: a `timer` is elapsed seconds as a fixed (Q16.16); `fps` and frame
|
||||
# counts are plain ints; interpolation amounts `t` are a fixed in 0.0..1.0.
|
||||
|
||||
# ------------------------------------------------------------------ Anim.* ----
|
||||
# spritesheet frame animation: turn an elapsed timer into the frame index to
|
||||
# draw. floor(timer * fps) is the number of whole frames elapsed; the flavour
|
||||
# (loop / once / ping-pong) decides how that maps back into 0..count-1.
|
||||
|
||||
function is_anim_ns(meth: pointer) -> bool {
|
||||
if (meth == "frame") or (meth == "once") or (meth == "pingpong") { return true }
|
||||
if (meth == "finished") or (meth == "duration") { return true }
|
||||
if (meth == "cell_x") or (meth == "cell_y") { return true }
|
||||
return false
|
||||
}
|
||||
|
||||
# floor(timer * fps) -> i32 code of whole frames elapsed (i64 intermediate so a
|
||||
# long-running timer can't overflow the multiply).
|
||||
function anim_elapsed(timer: pointer, fps: pointer) -> pointer {
|
||||
let t64 = emit_bind(`sext i32 {timer} to i64`)
|
||||
let f64 = emit_bind(`sext i32 {fps} to i64`)
|
||||
let m = emit_bind(`mul i64 {t64}, {f64}`) # Q16.16 frames
|
||||
let sh = emit_bind(`ashr i64 {m}, 16`)
|
||||
return emit_bind(`trunc i64 {sh} to i32`)
|
||||
}
|
||||
|
||||
# max(1, v) — guard a divisor / modulus against a zero or negative count.
|
||||
function anim_atleast1(v: pointer) -> pointer {
|
||||
let c = emit_bind(`icmp slt i32 {v}, 1`)
|
||||
return emit_bind(`select i1 {c}, i32 1, i32 {v}`)
|
||||
}
|
||||
|
||||
function emit_anim_ns(meth: pointer, e: Node) -> Val {
|
||||
if (meth == "frame") { # looping frame: elapsed mod count
|
||||
let timer = emit_expr(e.kids[0]); let fps = emit_expr(e.kids[1]); let count = emit_expr(e.kids[2])
|
||||
let el = anim_elapsed(timer.code, fps.code)
|
||||
let cnt = anim_atleast1(count.code)
|
||||
return val(emit_bind(`srem i32 {el}, {cnt}`), "int")
|
||||
}
|
||||
if (meth == "once") { # one-shot: min(elapsed, count-1)
|
||||
let timer = emit_expr(e.kids[0]); let fps = emit_expr(e.kids[1]); let count = emit_expr(e.kids[2])
|
||||
let el = anim_elapsed(timer.code, fps.code)
|
||||
let last = emit_bind(`sub i32 {count.code}, 1`)
|
||||
let c = emit_bind(`icmp slt i32 {el}, {last}`)
|
||||
return val(emit_bind(`select i1 {c}, i32 {el}, i32 {last}`), "int")
|
||||
}
|
||||
if (meth == "pingpong") { # bounce 0..count-1..0
|
||||
let timer = emit_expr(e.kids[0]); let fps = emit_expr(e.kids[1]); let count = emit_expr(e.kids[2])
|
||||
let el = anim_elapsed(timer.code, fps.code)
|
||||
let two = emit_bind(`mul i32 {count.code}, 2`)
|
||||
let p2 = emit_bind(`sub i32 {two}, 2`) # 2*count - 2
|
||||
let period = anim_atleast1(p2)
|
||||
let m = emit_bind(`srem i32 {el}, {period}`)
|
||||
let back = emit_bind(`sub i32 {period}, {m}`)
|
||||
let c = emit_bind(`icmp slt i32 {m}, {count.code}`)
|
||||
return val(emit_bind(`select i1 {c}, i32 {m}, i32 {back}`), "int")
|
||||
}
|
||||
if (meth == "finished") { # has a one-shot run past its last frame?
|
||||
let timer = emit_expr(e.kids[0]); let fps = emit_expr(e.kids[1]); let count = emit_expr(e.kids[2])
|
||||
let el = anim_elapsed(timer.code, fps.code)
|
||||
let c = emit_bind(`icmp sge i32 {el}, {count.code}`)
|
||||
return val(emit_bind(`zext i1 {c} to i32`), "bool")
|
||||
}
|
||||
if (meth == "duration") { # seconds for one cycle: count / fps -> fixed
|
||||
let fps = emit_expr(e.kids[0]); let count = emit_expr(e.kids[1])
|
||||
let num = emit_bind(`shl i32 {count.code}, 16`) # count as fixed
|
||||
let den = anim_atleast1(fps.code)
|
||||
return val(emit_bind(`sdiv i32 {num}, {den}`), "fixed")
|
||||
}
|
||||
if (meth == "cell_x") { # source x of a frame: (frame mod cols) * cell_w
|
||||
let frame = emit_expr(e.kids[0]); let cols = emit_expr(e.kids[1]); let cw = emit_expr(e.kids[2])
|
||||
let c1 = anim_atleast1(cols.code)
|
||||
let col = emit_bind(`srem i32 {frame.code}, {c1}`)
|
||||
return val(emit_bind(`mul i32 {col}, {cw.code}`), "int")
|
||||
}
|
||||
# cell_y — source y of a frame: (frame / cols) * cell_h
|
||||
let frame = emit_expr(e.kids[0]); let cols = emit_expr(e.kids[1]); let ch = emit_expr(e.kids[2])
|
||||
let c1 = anim_atleast1(cols.code)
|
||||
let row = emit_bind(`sdiv i32 {frame.code}, {c1}`)
|
||||
return val(emit_bind(`mul i32 {row}, {ch.code}`), "int")
|
||||
}
|
||||
|
||||
# ----------------------------------------------------------------- Tween.* ----
|
||||
# value interpolation over a timeline. The timeline helpers turn (timer,
|
||||
# duration) into a normalized amount with a chosen boundary behaviour; ease()
|
||||
# shapes that amount through one of the engine's easing curves (shared with
|
||||
# Ease.*); the typed interpolators blend two endpoints by an amount.
|
||||
|
||||
function is_tween_ns(meth: pointer) -> bool {
|
||||
if (meth == "progress") or (meth == "loop") or (meth == "yoyo") or (meth == "done") { return true }
|
||||
if (meth == "ease") or (meth == "number") or (meth == "round") { return true }
|
||||
if (meth == "point") or (meth == "tint") { return true }
|
||||
return false
|
||||
}
|
||||
|
||||
# a positive divisor for the timeline: duration if > 0, else 1.0 (65536).
|
||||
function tween_den(dur: pointer) -> pointer {
|
||||
let dpos = emit_bind(`icmp sgt i32 {dur}, 0`)
|
||||
return emit_bind(`select i1 {dpos}, i32 {dur}, i32 65536`)
|
||||
}
|
||||
|
||||
function emit_tween_ns(meth: pointer, e: Node) -> Val {
|
||||
if (meth == "progress") { # clamp(timer / duration, 0, 1) -> fixed
|
||||
let timer = emit_expr(e.kids[0]); let dur = emit_expr(e.kids[1])
|
||||
let dpos = emit_bind(`icmp sgt i32 {dur.code}, 0`)
|
||||
let den = emit_bind(`select i1 {dpos}, i32 {dur.code}, i32 65536`)
|
||||
let r = fx_div_code(timer.code, den)
|
||||
let neg = emit_bind(`icmp slt i32 {r}, 0`)
|
||||
let lo = emit_bind(`select i1 {neg}, i32 0, i32 {r}`)
|
||||
let over = emit_bind(`icmp sgt i32 {lo}, 65536`)
|
||||
let r1 = emit_bind(`select i1 {over}, i32 65536, i32 {lo}`)
|
||||
return val(emit_bind(`select i1 {dpos}, i32 {r1}, i32 65536`), "fixed") # dur<=0 -> done
|
||||
}
|
||||
if (meth == "loop") { # frac(timer / duration) in [0,1) -> fixed
|
||||
let timer = emit_expr(e.kids[0]); let dur = emit_expr(e.kids[1])
|
||||
let den = tween_den(dur.code)
|
||||
let r = fx_div_code(timer.code, den)
|
||||
return val(emit_bind(`and i32 {r}, 65535`), "fixed") # nonneg fractional part
|
||||
}
|
||||
if (meth == "yoyo") { # triangle 0..1..0 over the duration -> fixed
|
||||
let timer = emit_expr(e.kids[0]); let dur = emit_expr(e.kids[1])
|
||||
let den = tween_den(dur.code)
|
||||
let r = fx_div_code(timer.code, den)
|
||||
let u = emit_bind(`srem i32 {r}, 131072`) # mod 2.0
|
||||
let back = emit_bind(`sub i32 131072, {u}`)
|
||||
let c = emit_bind(`icmp sle i32 {u}, 65536`)
|
||||
return val(emit_bind(`select i1 {c}, i32 {u}, i32 {back}`), "fixed")
|
||||
}
|
||||
if (meth == "done") { # timer >= duration -> bool
|
||||
let timer = emit_expr(e.kids[0]); let dur = emit_expr(e.kids[1])
|
||||
let c = emit_bind(`icmp sge i32 {timer.code}, {dur.code}`)
|
||||
return val(emit_bind(`zext i1 {c} to i32`), "bool")
|
||||
}
|
||||
if (meth == "ease") { # ease(t, mode) -> fixed; mode is a literal 0..6
|
||||
let t = emit_expr(e.kids[0])
|
||||
let m = e.kids[1]
|
||||
if (m.kind != E_INT) { perr("Tween.ease: the easing mode must be a literal int 0..6") }
|
||||
return val(ease_eval(m.ival, t.code), "fixed")
|
||||
}
|
||||
if (meth == "number") { # lerp two fixeds by t -> fixed
|
||||
let a = emit_expr(e.kids[0]); let b = emit_expr(e.kids[1]); let t = emit_expr(e.kids[2])
|
||||
return val(fx_lerp_code(a.code, b.code, t.code), "fixed")
|
||||
}
|
||||
if (meth == "round") { # lerp two ints by t, rounded -> int
|
||||
let a = emit_expr(e.kids[0]); let b = emit_expr(e.kids[1]); let t = emit_expr(e.kids[2])
|
||||
let d = emit_bind(`sub i32 {b.code}, {a.code}`)
|
||||
let d64 = emit_bind(`sext i32 {d} to i64`)
|
||||
let t64 = emit_bind(`sext i32 {t.code} to i64`)
|
||||
let p = emit_bind(`mul i64 {d64}, {t64}`) # Q16.16
|
||||
let p2 = emit_bind(`add i64 {p}, 32768`) # + 0.5
|
||||
let sh = emit_bind(`ashr i64 {p2}, 16`)
|
||||
let dt = emit_bind(`trunc i64 {sh} to i32`)
|
||||
return val(emit_bind(`add i32 {a.code}, {dt}`), "int")
|
||||
}
|
||||
if (meth == "point") { # lerp two Vectors by t -> Vector
|
||||
let a = emit_expr(e.kids[0]); let b = emit_expr(e.kids[1]); let t = emit_expr(e.kids[2])
|
||||
let ax = vec_x(a.code); let ay = vec_y(a.code); let bx = vec_x(b.code); let by = vec_y(b.code)
|
||||
let lx = fx_lerp_code(ax, bx, t.code)
|
||||
let ly = fx_lerp_code(ay, by, t.code)
|
||||
return val(vec_pack(lx, ly), "Vector")
|
||||
}
|
||||
# tint — blend two colors (0x00RRGGBB) by t, per channel -> int
|
||||
let a = emit_expr(e.kids[0]); let b = emit_expr(e.kids[1]); let t = emit_expr(e.kids[2])
|
||||
let r = color_lerp_ch(color_ch(a.code, "16"), color_ch(b.code, "16"), t.code)
|
||||
let g = color_lerp_ch(color_ch(a.code, "8"), color_ch(b.code, "8"), t.code)
|
||||
let bl = color_lerp_ch(color_ch(a.code, "0"), color_ch(b.code, "0"), t.code)
|
||||
return val(color_pack(r, g, bl), "int")
|
||||
}
|
||||
|
|
@ -1,6 +1,11 @@
|
|||
# emit_ease.ludic — the Ease.* namespace: tween curves over a normalized amount
|
||||
# t in 0.0..1.0, returning an eased fixed. All pure Q16.16, deterministic. The
|
||||
# "juice" layer that makes motion feel good (Robert Penner's easings).
|
||||
#
|
||||
# The curve math is factored into ease_eval(mode, t) so the Tween.* namespace
|
||||
# (emit_anim.ludic) can pick a curve by a small integer mode and reuse the exact
|
||||
# same formulas — one source of truth for every easing in the engine.
|
||||
# 0 linear 1 in 2 out 3 in_out 4 back 5 elastic 6 bounce
|
||||
|
||||
function is_ease_ns(meth: pointer) -> bool {
|
||||
if (meth == "in") or (meth == "out") or (meth == "in_out") { return true }
|
||||
|
|
@ -14,50 +19,69 @@ function ease_bounce_seg(u: pointer) -> pointer {
|
|||
return fx_mul_code(uu, "495616") # 7.5625 * u*u
|
||||
}
|
||||
|
||||
function emit_ease_ns(meth: pointer, e: Node) -> Val {
|
||||
let t = emit_expr(e.kids[0])
|
||||
if (meth == "in") { # ease-in quad: t*t
|
||||
return val(fx_mul_code(t.code, t.code), "fixed")
|
||||
# ease-out bounce: four parabolic segments, selected by t (all computed, then
|
||||
# picked branch-free). Shifts/offsets are the standard 2.75-denominator set.
|
||||
function ease_bounce_code(t: pointer) -> pointer {
|
||||
let sA = ease_bounce_seg(t)
|
||||
let uB = emit_bind(`sub i32 {t}, 35747`); let sB0 = ease_bounce_seg(uB); let sB = emit_bind(`add i32 {sB0}, 49152`)
|
||||
let uC = emit_bind(`sub i32 {t}, 53620`); let sC0 = ease_bounce_seg(uC); let sC = emit_bind(`add i32 {sC0}, 61440`)
|
||||
let uD = emit_bind(`sub i32 {t}, 62557`); let sD0 = ease_bounce_seg(uD); let sD = emit_bind(`add i32 {sD0}, 64512`)
|
||||
let cCD = emit_bind(`icmp slt i32 {t}, 59578`)
|
||||
let rCD = emit_bind(`select i1 {cCD}, i32 {sC}, i32 {sD}`)
|
||||
let cB = emit_bind(`icmp slt i32 {t}, 47663`)
|
||||
let rB = emit_bind(`select i1 {cB}, i32 {sB}, i32 {rCD}`)
|
||||
let cA = emit_bind(`icmp slt i32 {t}, 23831`)
|
||||
return emit_bind(`select i1 {cA}, i32 {sA}, i32 {rB}`)
|
||||
}
|
||||
|
||||
# evaluate easing `mode` at normalized amount `t` (a fixed code) -> fixed code.
|
||||
# The single source of truth for the engine's easing curves.
|
||||
function ease_eval(mode: int, t: pointer) -> pointer {
|
||||
if (mode == 0) { # linear: t
|
||||
return t
|
||||
}
|
||||
if (meth == "out") { # ease-out quad: t*(2 - t)
|
||||
let inv = emit_bind(`sub i32 131072, {t.code}`)
|
||||
return val(fx_mul_code(t.code, inv), "fixed")
|
||||
if (mode == 1) { # ease-in quad: t*t
|
||||
return fx_mul_code(t, t)
|
||||
}
|
||||
if (meth == "in_out") { # smooth ease-in-out: 3t^2 - 2t^3
|
||||
let t2 = fx_mul_code(t.code, t.code)
|
||||
let t3 = fx_mul_code(t2, t.code)
|
||||
if (mode == 2) { # ease-out quad: t*(2 - t)
|
||||
let inv = emit_bind(`sub i32 131072, {t}`)
|
||||
return fx_mul_code(t, inv)
|
||||
}
|
||||
if (mode == 3) { # smooth ease-in-out: 3t^2 - 2t^3
|
||||
let t2 = fx_mul_code(t, t)
|
||||
let t3 = fx_mul_code(t2, t)
|
||||
let three = emit_bind(`mul i32 {t2}, 3`)
|
||||
let two = emit_bind(`mul i32 {t3}, 2`)
|
||||
return val(emit_bind(`sub i32 {three}, {two}`), "fixed")
|
||||
return emit_bind(`sub i32 {three}, {two}`)
|
||||
}
|
||||
if (meth == "back") { # ease-in-back (overshoots below 0)
|
||||
let t2 = fx_mul_code(t.code, t.code)
|
||||
let t3 = fx_mul_code(t2, t.code)
|
||||
if (mode == 4) { # ease-in-back (overshoots below 0)
|
||||
let t2 = fx_mul_code(t, t)
|
||||
let t3 = fx_mul_code(t2, t)
|
||||
let a = fx_mul_code(t3, "177051") # 2.70158 * t^3
|
||||
let b = fx_mul_code(t2, "111515") # 1.70158 * t^2
|
||||
return val(emit_bind(`sub i32 {a}, {b}`), "fixed")
|
||||
return emit_bind(`sub i32 {a}, {b}`)
|
||||
}
|
||||
if (meth == "elastic") { # ease-out elastic: springy overshoot that settles
|
||||
if (mode == 5) { # ease-out elastic: springy overshoot that settles
|
||||
g_uses_mathrt = true # 2^(-10t) * sin((10t - 0.75) * 2pi/3) + 1
|
||||
let tt = emit_bind(`mul i32 {t.code}, 10`) # 10t
|
||||
let tt = emit_bind(`mul i32 {t}, 10`) # 10t
|
||||
let ntt = emit_bind(`sub i32 0, {tt}`) # -10t (exp2 exponent, Q16.16)
|
||||
let decay = emit_bind(`call i32 @fn_fx_exp2(i32 {ntt})`)
|
||||
let ph = emit_bind(`sub i32 {tt}, 49152`) # 10t - 0.75
|
||||
let ang = fx_mul_code(ph, "137258") # * (2pi/3), 2pi/3 = 137258 fixed
|
||||
let s = emit_bind(`call i32 @fn_fx_sin(i32 {ang})`)
|
||||
let osc = fx_mul_code(decay, s)
|
||||
return val(emit_bind(`add i32 {osc}, 65536`), "fixed")
|
||||
return emit_bind(`add i32 {osc}, 65536`)
|
||||
}
|
||||
# ease-out bounce: four parabolic segments, selected by t (all computed, then
|
||||
# picked branch-free). Shifts/offsets are the standard 2.75-denominator set.
|
||||
let sA = ease_bounce_seg(t.code)
|
||||
let uB = emit_bind(`sub i32 {t.code}, 35747`); let sB0 = ease_bounce_seg(uB); let sB = emit_bind(`add i32 {sB0}, 49152`)
|
||||
let uC = emit_bind(`sub i32 {t.code}, 53620`); let sC0 = ease_bounce_seg(uC); let sC = emit_bind(`add i32 {sC0}, 61440`)
|
||||
let uD = emit_bind(`sub i32 {t.code}, 62557`); let sD0 = ease_bounce_seg(uD); let sD = emit_bind(`add i32 {sD0}, 64512`)
|
||||
let cCD = emit_bind(`icmp slt i32 {t.code}, 59578`)
|
||||
let rCD = emit_bind(`select i1 {cCD}, i32 {sC}, i32 {sD}`)
|
||||
let cB = emit_bind(`icmp slt i32 {t.code}, 47663`)
|
||||
let rB = emit_bind(`select i1 {cB}, i32 {sB}, i32 {rCD}`)
|
||||
let cA = emit_bind(`icmp slt i32 {t.code}, 23831`)
|
||||
return val(emit_bind(`select i1 {cA}, i32 {sA}, i32 {rB}`), "fixed")
|
||||
# mode == 6 — ease-out bounce
|
||||
return ease_bounce_code(t)
|
||||
}
|
||||
|
||||
function emit_ease_ns(meth: pointer, e: Node) -> Val {
|
||||
let t = emit_expr(e.kids[0])
|
||||
if (meth == "in") { return val(ease_eval(1, t.code), "fixed") }
|
||||
if (meth == "out") { return val(ease_eval(2, t.code), "fixed") }
|
||||
if (meth == "in_out") { return val(ease_eval(3, t.code), "fixed") }
|
||||
if (meth == "back") { return val(ease_eval(4, t.code), "fixed") }
|
||||
if (meth == "elastic"){ return val(ease_eval(5, t.code), "fixed") }
|
||||
return val(ease_eval(6, t.code), "fixed") # bounce
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue