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
31
docs/language/anim/anim-frame.md
Normal file
31
docs/language/anim/anim-frame.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
---
|
||||
id: anim-frame
|
||||
name: Anim.frame
|
||||
category: anim
|
||||
kind: namespace-method
|
||||
tokens: Anim.frame
|
||||
sig: Anim.frame(timer, fps, count) -> int
|
||||
tip: The looping frame index for an elapsed timer at a given fps.
|
||||
order: 1
|
||||
ns: Anim
|
||||
member: frame
|
||||
---
|
||||
|
||||
Returns the current frame of a looping clip: <code>floor(timer * fps)</code> reduced modulo <code>count</code>. <code>timer</code> is elapsed seconds as a <code>fixed</code>, <code>fps</code> the clip's frames per second, and <code>count</code> the number of frames. The clip wraps forever — frame <code>count-1</code> is followed by frame <code>0</code>.
|
||||
|
||||
Parameters:
|
||||
- `timer` — elapsed seconds (a `fixed`)
|
||||
- `fps` — frames per second
|
||||
- `count` — number of frames in the clip
|
||||
|
||||
```ludic
|
||||
program Demo {
|
||||
property Sprite { timer: fixed = 0.0 }
|
||||
model Hero { Sprite }
|
||||
handler Run phase Update {
|
||||
Sprite.timer = Sprite.timer + Time.delta()
|
||||
let cell = Anim.frame(Sprite.timer, 12, 4) # 4-frame run at 12 fps
|
||||
print(cell)
|
||||
}
|
||||
}
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue