| name | basementuniverse-animation |
| description | Use and troubleshoot the @basementuniverse/animation TypeScript library for value animation in HTML5 games. Use when implementing, debugging, or documenting animation behaviour driven by this package.
|
Basement Universe Animation
Use this skill when working with @basementuniverse/animation.
This package animates values over time (numbers, vectors, colors). It does not
render anything. Consumers use animated values for position, rotation, scale,
colors, and other gameplay/UI state.
When to use
Use this skill for:
- Creating or updating
Animation, MultiAnimation, or AnimationTimeline
usage.
- Choosing interpolation/easing functions and parameters.
- Designing markers, keyframe stops, repeat behaviour, and manual scrubbing.
- Troubleshooting issues like callbacks not firing, values not changing, or
timeline tracks not activating.
Do not use this skill for:
- Rendering concerns (Canvas/WebGL draw loops, shaders, sprite systems).
- Physics or collision logic unrelated to animation value generation.
Workflow
- Identify which abstraction the user needs:
- single value stream:
Animation
- grouped named values:
MultiAnimation
- scheduled orchestration:
AnimationTimeline
- Confirm control model:
- automatic (
Auto/Trigger) update via update(dt)
- hold-driven (
Hold)
- externally controlled (
Manual via progress/globalTime)
- Pick interpolation strategy:
- named easing for scalar/vector/color interpolation
- custom interpolation function
- spline interpolation via
bezierPath / catmullRomPath for vec2/vec3
- Apply timing features only if needed:
delay, repeat, repeats, keyframe stops, markers
- Validate with a frame loop assumption:
update(dt) where dt is seconds- verify
progress, current, callbacks, and repeat counts
Troubleshooting checklist
- Nothing moves:
- verify
.update(dt) is called
- verify animation is running (
Auto or explicit .start())
- verify
dt is in seconds
- Unexpected stop:
- check
repeat/repeats
- check
finished, running, direction
- Marker not firing:
- check
time vs progress precedence
- check marker
direction, once, and global
- check if animation crossed marker in current update span
- Timeline track never activates:
- validate track start/end against timeline
durationMode
- for relative mode, ensure timeline
duration is provided
- Spline errors:
- ensure values are vec2/vec3 (not numbers)
- ensure point counts match bezier order or Catmull-Rom minimums
References
