Guides

Templates that move

How every template's values take keys, how each part arrives, leaves and loops, and the background, placement and cursor every template has.

Every template is built on one framework, so every template moves the same way and takes the same choices in the same words. A template draws its parts at rest — a card, the bubbles, the bars, a name — and the framework moves them. This page is how: values with keys, the motion of each part, and the surface, placement, theme and cursor every template has. Templates has placing and changing one.

Values that change over time: keys

Any number, colour, point, word, choice, switch or table a template takes can be given as keys instead of one value — a bar's value rising and falling, a name that changes, an accent that warms. The catalogue marks each value that takes them with "or keys". A value that can't, because it decides the layout (a type size that decides where words wrap), says so and why.

ymotion_edit {"ops":[{"verb":"placeTemplate","args":{"template":"social/post","at":0,"params":{"name":{"keys":[{"t":0,"value":"Priya Shah"},{"t":2.5,"value":"Dr Priya Shah"}]},"accent":{"keys":[{"t":0,"value":"#0A84FF","ease":"cubicInOut"},{"t":2,"value":"#FF9F0A"}]}}}}]}

t is seconds of the template's own clock: 0 is its first frame, wherever on the film it's placed. The reply says where that clock starts on the film. A key past the template's length is refused.
A key's ease shapes the move from that key to the next one, as in the graph editor. Absent is linear; "hold" holds. Any ease from ymotion_help {"topic":"eases"}, or four numbers. So the ease goes on the first key of a move, not the last.
Before the first key the value is the first key's; after the last, the last's — its rest, which is also what a still view of the template shows.
Text, choices and switches hold, like After Effects' Source Text: they change at their keys and never part way. An ease on one of them is refused.
A table's keys all have the same columns, row names and colours; only the numbers move, cell by cell.
Keys that all hold one value are that value. The template is built exactly as if it had been given still.

Whatever a value drives moves with it from one curve: a bar's value moves its length and its count together, a colour keys a fill, a name's words change at their keys and its card eases to fit. Where what's drawn is an exact function of the value, the keys are carried as keyframes with the same eases at the same moments; where it isn't (a length over an axis that follows the data), the value is sampled while it moves, at most 30 times a second.

To change one value to keys on a placed template:

ymotion_edit {"ops":[{"verb":"setTemplateParams","args":{"id":"<its composition or layer id>","params":{"name":{"keys":[{"t":0,"value":"Q1"},{"t":3,"value":"Q2"}]}}}}]}

How each part moves: motion

A template declares the parts that move together — a post's card, header, words and actions; a chat's bubbles and typing dots — and every part takes the same motion values. The catalogue lists each template's parts with their in, out, timing and ease. Give only what differs:

ymotion_edit {"ops":[{"verb":"placeTemplate","args":{"template":"social/post","at":0,"params":{"motion":{"card":{"in":"wipeRight","duration":0.6},"header":{"in":"typewriter","duration":0.9},"actions":{"in":"rise","stagger":0.1}}}}}]}

in and out are a move: none, fade, pop, scale, grow, rise, drop, slideUp, slideDown, slideLeft, slideRight, wipeUp, wipeDown, wipeLeft, wipeRight, drawOn, typewriter, words, count. A move named by a direction names the way it travels, in and out alike — slideUp arrives moving up from below the frame and leaves moving up past its top. typewriter and words act on a part's type, drawOn on its strokes and count on its numbers, and a part offers only the ones it has something for — the catalogue lists each part's own. A template may add moves of its own for a part — a chat's send, a gauge's swing — and the catalogue lists them.
duration and outDuration are how long each takes; delay comes before the in, and outBefore ends the out that long before the part must be gone.
stagger spaces the items of a list part (each message, each bar), in order: forward, backward, centre or random (by seed).
ease is the in's ease, played mirrored for the out, or "spring", which settles by itself; bounce (0 to 1) is how far a spring overshoots, and 0 settles without any. Opacity and trims never overshoot, whatever the ease.
distance is how far rise and drop travel, in short edges.
loop is what a part does while it's on screen: none, pulse, float, wiggle, jitter — with loopAmount and loopPeriod. A loop starts from rest at the end of the in, runs through the out, and repeats exactly; wiggle and jitter are seeded, so every render is the same.

Every move ends exactly at rest, so the frame after an in is the same picture whichever in was chosen, and nothing of a part is drawn before its in starts or after its out ends. When an instance is too short for an in and an out, both shrink together.

What it sits on: surface and theme

Every template takes a surface — what's behind it — and a theme:

ymotion_edit {"ops":[{"verb":"setTemplateParams","args":{"id":"<its composition or layer id>","params":{"surface":{"background":"linear","color":"#0F2A5F","color2":"#3B82F6","angle":135,"card":true,"shadow":"wide","radius":0.12}}}}]}

background is none (transparent, over footage), solid (its color), linear (from color to color2, travelling at angle degrees clockwise from left to right: 90 runs top to bottom, as a paint's grad: does), radial (from color at centre out to color2), or picture (an uploaded image, cover-fitted). The background is the frame's: it doesn't move with placement.
card puts a rounded card under the content, sized to it: its cardColor, radius (a share of half its shorter side), border and borderColor, shadow (none, soft or wide), padding (inside, in short edges) and opacity (0 to 100).
theme is light, dark or custom. Under light or dark, a template's own colours and its surface's are the theme's. Giving one of those colours switches the theme to custom, starting from the theme's other colours, and the reply says so.

Where it sits: placement

Every template takes a placement: align (topLeft, top, topRight, left, centre, right, bottomLeft, bottom or bottomRight), a margin from the frame's edges in short edges, a box width and height as fractions of the frame (a most, for a template sized by its words), and an offset, a scale and a rotation applied to the whole afterwards — which take keys, so the whole can drift or grow:

ymotion_edit {"ops":[{"verb":"setTemplateParams","args":{"id":"<its composition or layer id>","params":{"placement":{"align":"bottomRight","margin":0.06,"offset":{"keys":[{"t":0,"value":{"x":0,"y":0.02},"ease":"cubicOut"},{"t":1,"value":{"x":0,"y":0}}]}}}}}]}

Everything but the background hangs from one null named "Placement", so the whole moves as one. What a template cuts at an edge as a whole — a chat's thread, a prompt's conversation, a map — is a composition of its own, drawn as large as the placement's scale will show it, so a scale above 1 stays as sharp as everything beside it.

Pointing at things: the cursor

Every template can show a cursor — an arrow or a hand — that glides in, presses with a ring, and leaves. With "aim":"auto" it presses what the template presses (a button at the moment it's pressed); a template that presses nothing gives it nothing to aim at, and the reply says so. With "aim":"free", at is where it is (give it keys for a path) and clicks are the seconds it presses:

ymotion_edit {"ops":[{"verb":"setTemplateParams","args":{"id":"<its composition or layer id>","params":{"cursor":{"show":true,"aim":"free","at":{"keys":[{"t":0.5,"value":{"x":1.1,"y":0.9},"ease":"cubicInOut"},{"t":1.4,"value":{"x":0.5,"y":0.55}}]},"clicks":[1.6],"look":"hand"}}}}]}

Numbers that count

A count, a value on a bar, a timer — every number a template shows is a number text: a text layer whose words are a formatted number, keyed once rather than a key a frame, its digits set in tabular cells so its width holds while the count keeps the same number of digits. It's an ordinary text layer: setText with "number" makes one, and its value is keyable at content.text.number.value, as in After Effects' Numbers effect. A template's number format is a record — prefix, suffix, decimals, group (the thousands mark), point (the decimal mark), and form: number, compact (1.2K, 3.4M) or time, a clock (1:05). A negative amount reads with its sign first: −$48,250.

The count move counts a number up from nothing to its value as its part arrives. A value with keys of its own is counted only while it stands still — up to the moment its keys first move — and one moving the whole time its part arrives fades in instead, so a countdown keyed from its first frame counts down and never up first.

Good to know

Records merge. {"surface":{"radius":0.1}} changes the radius and keeps the rest; so do placement, cursor and each part of motion.
It's still ordinary layers. Every move is keys on a null named for its part, a layer's opacity, a mask, a trim or a text animator — open the composition and change any of it by hand, and a later change of values keeps that. See Templates.