Skip to content

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 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.
  • target is 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.
  • component is the component’s key in the scene file, and field one of its number fields, or a field that holds a file’s url: texture’s source, 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 color widget 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.

import { Animator } from '@shell/engine-2d';
entity.addComponent(Animator, { clip: '/assets/animations/jump.anim.json' });
FieldWhat it does
clipThe clip file’s url.
autoplayStarts playing when the game does. On by default.
speed2 plays twice as fast, and below 0 plays backwards.
loopclip (as the clip says), once (stops at the end), or forever.
playingWhether it plays now. Set it to start or stop.
timeWhere 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.

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 with create_animation, and changes one track’s keys with set_keys. A change is saved at once and is not an undo step.
  • The Agent animates on screen too: create_bone draws a bone (from another’s tip, a chain), attach_to_bone puts pictures under it without moving them, and pose keys a rig’s parts at a time, a turn in degrees for each, as one undo step. create_path makes a Path for something to follow with followPath. open_animate opens 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 light backdrop or the scene open in the Scene tab behind it, and screenshot then shows it. set_keys takes 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.

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.