Clips
@shell/clip plays keyframed animations written as files. A clip keys fields of one entity and its
descendants, and an Animator on that entity plays it on the game’s clock. Its runtime does not use
tweens: a pure sampleClip(clip, t) gives every value at a time, so a pose at a time is always the
same.
Engine2D and BrowserPlugin already install ClipPlugin, and the engine packages re-export it. A
world of its own plugins adds it:
import { ClipPlugin } from '@shell/clip';
world.addPlugin(ClipPlugin);A clip file
Section titled “A clip file”A clip is public/assets/animations/<name>.anim.json. Times are in milliseconds.
{ "version": 1, "duration": 1200, "loop": true, "tracks": [ { "target": "", "component": "position", "field": "y", "keys": [ [0, 0], [400, -120, "outQuad"], [800, 0, "inQuad"] ] }, { "target": "Body", "component": "position", "field": "x", "step": true, "keys": [ [0, 0], [400, 10] ] }, { "target": "Shadow", "component": "tint", "field": "color", "keys": [ [0, 4869975], [400, 2763059] ] } ], "events": [{ "t": 800, "name": "landed" }]}labels, optional, names times of the clip, as{ "landing": 800 }. The Timeline shows them on its ruler; the Animator does not use them.rig, optional, is the prefab file the clip is made on, by its path in the asset folder, as"prefabs/knight.prefab.json". The editor sets it when a clip is made on a prefab instance, and changes it when the prefab is moved or renamed. A clip that names none opens in its Animate tab on the one prefab that has every part its tracks name, with nothing written. Otherwise the tab asks which prefab it is made on: two that fit, none, or a clip that moves only the root, which every prefab has. Those that fit come first, then those that play it (an Animator of the prefab, or of an instance of it in a scene), then the others, each with the parts it lacks (“does not fit: no Head”). An entity that plays the clip and is no prefab, in any scene, is named with its scene, and Make a prefab of it opens that scene and makes its rig; where no prefab fits or plays the clip, that comes in place of the prefabs. One that does not fit can be chosen all the same, as a rig may get its parts later; until then the tab and the rig’s Clips on this rig say which parts it lacks, as those tracks move nothing. Clips on this rig lists the clips that name the rig, and of those that name none, the ones whose tracks name its parts and the ones its prefab plays. The tab’s Rig choice changes the rig, marking the prefabs that do not fit, and its None takes it off again, one undo step. The game does not read it: any entity with the children the tracks name plays the clip.targetis a path of child names from the entity that plays the clip:""is that entity,"Body/Eyes"a grandchild. Each name takes the first child of that name.componentis the component’s key in the scene file, andfieldone of its number fields, or a field that holds a file’s url:texture’ssource, a sprite’s picture.- A key is
[ms, value, ease?]. The ease is one of the 31 names and shapes the time from the key before; without one it is linear. - Before the first key a track holds that key’s value, and after the last key the last.
- A field with the
colorwidget goes channel by channel and stays in range. An integer or boolean field, or a track with"step": true, jumps at each key. Any other field goes as a number. - A picture is keyed in a clip of
"version": 2: each key holds the picture’s url, as[100, "/assets/textures/blink.png"], and it jumps at each key. A file of version 1 holds only numbers, and is read as it is. The pictures a clip keys load before its Scene shows, and in the editor before the first frame of Play, so a swap shows the new picture on the frame it is keyed.
validateClip(clip, world?, entity?) lists what is wrong with a clip, each as a sentence. Given the
world, it also checks the components and fields; given the entity that plays it, the targets.
The Animator
Section titled “The Animator”import { Animator } from '@shell/engine-2d';
entity.addComponent(Animator, { clip: '/assets/animations/jump.anim.json' });| Field | What it does |
|---|---|
clip | The clip file’s url. |
autoplay | Starts playing when the game does. On by default. |
speed | 2 plays twice as fast, and below 0 plays backwards. |
loop | clip (as the clip says), once (stops at the end), or forever. |
playing | Whether it plays now. Set it to start or stop. |
time | Where in the clip it is, in ms. A playing Animator goes on from it. |
AnimatorSystem runs at PostUpdate and not in edit mode. It finds each track’s target once, and
again only when a name or a parent changes on the way, and keeps its place in each track’s keys
from frame to frame. A field is written only when its value is another: a held key wakes nothing
that waits for a change, and a field the game moved is set back to the clip’s value.
Clip files are read by url, as PrefabFiles reads prefab files, by the clipFiles resource
(ClipFiles) that ClipPlugin binds, and an Animator holds until its file is there.
resources.get('clipFiles').get(url) is undefined until the file is read, which the first ask
starts, and settled() resolves once every read asked for is done. A file that cannot be read, or
is not a clip of this world, is said once in the console and plays nothing. The file is asked for
as soon as the Animator is in the world, and in the editor play waits for it, and the pictures it
keys, before its first frame (ten seconds at most), so play_step of N frames from the start
leaves time at N frames.
In the editor
Section titled “In the editor”A clip file is an asset of kind animation:
- The assets panel makes one with New Animation (in
animations/), and renames and moves it; an Animator that plays a moved clip follows it. Selected there, a clip shows as its timeline, not its text: the ruler, its tracks and their keys, drawn from the file and following it as it changes, with nothing edited there. Animate opens the clip’s Animate tab, on its rig, and the Timeline with it; while a game plays it is disabled, and says so. - An Animator with no clip has New animation under it in the Inspector: a clip named after the entity, with its prefab as the rig, opened in its Animate tab.
- A broken file says what is wrong in the assets panel and in
list_assets: its shape, or a component or field that is not there. A child name that an entity has not is said under that entity’s Animator in the Inspector, and in the console when it plays. - The Agent reads one with
get_animation(given an entity, it also says what of it that entity cannot play), writes one withcreate_animation, and changes one track’s keys withset_keys. A change is saved at once and is not an undo step. - The Agent animates on screen too:
create_bonedraws a bone (from another’s tip, a chain),attach_to_boneputs pictures under it without moving them, andposekeys a rig’s parts at a time, a turn in degrees for each, as one undo step.create_pathmakes a Path for something to follow withfollowPath.open_animateopens a clip in its Animate tab at a time, on its rig (the prefab the clip names, alone), with its onion skin, on a dark or lightbackdropor thesceneopen in the Scene tab behind it, andscreenshotthen shows it.set_keystakes a picture key’s url as its value, in a clip of version 2.
The Timeline panel, at the bottom, comes to the front with an Animate tab and goes with it: on
the Scene there is none, and the bottom shows what it showed before. It shows the tab’s clip on its
rig: its tracks by entity and component, keys and the eases between them, labels and events. Play
goes round the clip; the playhead is dragged, or moved with the arrow keys, a frame of 1/60 s at a
time unless Snap says otherwise, and each time is drawn on the rig in the tab. On the Scene, the
Agent shows the pose of the selected entity’s clip with set_playhead and a time, drawn on a copy
of the scene, so nothing is written: not the file, its undo history, or what other Members see;
a screenshot then has it.
Keys are edited on the Timeline, each edit one step of the editor’s Undo and Redo. Drag a key
to move it, Alt-drag to copy it, and double-click a lane to add a key with the value the track has
there. A chosen key is deleted with Delete, moved a step of the snap with the arrow keys (Alt
copies), and opened with Enter or a double-click: its popover sets its time, its value and the
ease into it (any of the 31 of @shell/animate), or that ease on every key of the track. A time
typed outside the clip is refused, and the popover says so. A key moved, copied or given the
time of another key takes its place; one added where a key is chooses that key. Each edit writes
the clip file at once. When another program changed the file meanwhile, its change is kept: the
edit, or the undo, is not made, and the console says so. An undo or redo that fails otherwise,
such as a write that did not get through, stays to be tried again. The list at the start of the
bar chooses the rig’s Animator clip, or makes one with “New animation…”, as an undo step of the
prefab. A track on a child that the entity does not have says so in its row, in the Inspector’s
words.
Keys from the Inspector. In an Animate tab, in Animate, a row of the Inspector that can be keyed (of the Animator’s entity or its children) ends with a diamond: filled where each value of the row has a key at the playhead, half filled where some have, an outline where one has a track, faint where none has. A press keys every value of the row that has no key there, with the value shown, or takes the row’s keys away. A value’s own box says which: filled with the key colour where it has a key at the playhead, edged where it has a track. A right-click on a box keys or unkeys that value alone, keys its row, or shows its track in the Timeline. A strip over the Inspector says which clip is animated and where the playhead is, and whether a change is a key at once (Auto key) or waits for K. In Animate, what you change in the Inspector, or drag in the scene view, becomes a key at the playhead, and a field with no track gets one, from the value it had at the start. The Inspector shows the pose, and the scene is not changed. Each change is one undo step. In Setup and on the Scene the Inspector shows no keys.
Events
Section titled “Events”Each time the playhead passes an event, wraps included, the system triggers ClipEvent. A frame
that goes round a short clip more than once hears it once for each pass, in the order passed:
import { ClipEvent, Define } from '@shell/engine-2d';
export const Landed = Define.system() .observes(ClipEvent) .update(({ events }) => { const { entity, name } = events.get(ClipEvent)!.data; if (name === 'landed') console.log('landed', entity.uid); });An event at 0 is heard at each wrap, not when the clip first starts.