feat(registry): add a Lottie character walk-in and document the character route

This commit is contained in:
Miguel Angel Simon Sierra
2026-09-23 01:20:33 -04:00
parent 859d5c7aee
commit 348e67626a
8 changed files with 222 additions and 11 deletions
+9
View File
@@ -71,6 +71,15 @@ The Lottie adapter seeks the existing animation frame by frame, so the
designer's work renders exactly as authored. Asking the agent to recreate it in
GSAP throws away the source and lands somewhere approximate.
Characters work the same way. A mascot that walks in, stops and points is a
Lottie file with the acting in it; the agent builds the scene around it in GSAP:
> Use this character Lottie (`assets/mascot.json`): it walks in and points right at 5.2s. Bring the title card in on the point.
A short walk cycle with `loop: true` keeps cycling for the whole scene. The
[`lottie-character-walk`](/catalog/blocks/lottie-character-walk) block is a
working starting point.
## Simple UI and text motion → the default
Fades, slides, staggers, counters, kinetic type, hover-style reveals — the
File diff suppressed because one or more lines are too long
@@ -0,0 +1,137 @@
<!doctype html>
<html
lang="en"
data-composition-variables='[{"id":"title","type":"string","label":"Card title","default":"Meet your guide","maxLength":28},{"id":"body","type":"string","label":"Card text","default":"Walks in on planted feet, then points the way.","maxLength":90}]'
>
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=1920, height=1080" />
<title>lottie-character-walk</title>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/lottie-web@5.12.2/build/player/lottie_light.min.js"></script>
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin="" />
<link
href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap"
rel="stylesheet"
/>
<style>
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
#lcw-root {
position: relative;
width: 1920px;
height: 1080px;
overflow: hidden;
background: #fcfcfd;
font-family: Inter, sans-serif;
color: #111827;
}
#lcw-ground {
position: absolute;
left: 0;
right: 0;
top: 906px;
height: 1px;
background: rgba(17, 24, 39, 0.14);
}
#lcw-mascot {
position: absolute;
inset: 0;
}
#lcw-card {
position: absolute;
left: 1100px;
top: 300px;
width: 660px;
padding: 56px 60px 60px;
border-radius: 28px;
background: rgba(17, 24, 39, 0.08);
border: 1px solid rgba(17, 24, 39, 0.14);
opacity: 0;
}
#lcw-title {
font-size: 64px;
font-weight: 600;
line-height: 1.05;
letter-spacing: -0.02em;
}
#lcw-rule {
width: 120px;
height: 8px;
margin: 28px 0 30px;
border-radius: 4px;
background: #ff5a36;
transform-origin: left center;
}
#lcw-body {
font-size: 34px;
line-height: 1.35;
color: rgba(17, 24, 39, 0.72);
}
</style>
</head>
<body>
<div
id="lcw-root"
data-composition-id="lottie-character-walk"
data-start="0"
data-duration="7.5"
data-width="1920"
data-height="1080"
>
<div id="lcw-ground"></div>
<div id="lcw-card">
<div id="lcw-title">Meet your guide</div>
<div id="lcw-rule"></div>
<div id="lcw-body">Walks in on planted feet, then points the way.</div>
</div>
<div id="lcw-mascot"></div>
</div>
<script>
(function () {
var vars =
window.__hyperframes && typeof window.__hyperframes.getVariables === "function"
? window.__hyperframes.getVariables()
: {};
if (vars.title) document.getElementById("lcw-title").textContent = vars.title;
if (vars.body) document.getElementById("lcw-body").textContent = vars.body;
// The character's body acting (walk, stop, point, idle) lives in the Lottie file.
// The runtime seeks every player on window.__hfLottie to composition time.
var mascot = lottie.loadAnimation({
container: document.getElementById("lcw-mascot"),
renderer: "svg",
loop: false,
autoplay: false,
path: "assets/mascot.json",
});
window.__hfLottie = window.__hfLottie || [];
window.__hfLottie.push(mascot);
// The stage around the character is GSAP, timed to the Lottie's point at 5.2 s.
var tl = gsap.timeline({ paused: true });
tl.fromTo(
"#lcw-card",
{ opacity: 0, x: 40, scale: 0.96 },
{ opacity: 1, x: 0, scale: 1, duration: 0.6, ease: "power3.out" },
5.2,
);
tl.fromTo(
["#lcw-title", "#lcw-body"],
{ opacity: 0, y: 18 },
{ opacity: 1, y: 0, duration: 0.5, ease: "power2.out", stagger: 0.1 },
5.3,
);
tl.fromTo("#lcw-rule", { scaleX: 0 }, { scaleX: 1, duration: 0.5, ease: "expo.out" }, 5.5);
tl.to({}, { duration: 0 }, 7.5);
window.__timelines = window.__timelines || {};
window.__timelines["lottie-character-walk"] = tl;
})();
</script>
</body>
</html>
@@ -0,0 +1,52 @@
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "lottie-character-walk",
"type": "hyperframes:block",
"title": "Lottie Character Walk",
"description": "A jointed flat character walks in on planted feet, stops and points at a card; the body acting is a Lottie file and the stage is GSAP.",
"tags": [
"character",
"character-animation",
"mascot",
"walk-cycle",
"gesture",
"pointing",
"puppet",
"lottie",
"explainer"
],
"license": "Apache-2.0",
"dimensions": {
"width": 1920,
"height": 1080
},
"duration": 7.5,
"variables": [
{
"id": "title",
"type": "string",
"label": "Card title",
"default": "Meet your guide",
"maxLength": 28
},
{
"id": "body",
"type": "string",
"label": "Card text",
"default": "Walks in on planted feet, then points the way.",
"maxLength": 90
}
],
"files": [
{
"path": "lottie-character-walk.html",
"target": "compositions/lottie-character-walk/lottie-character-walk.html",
"type": "hyperframes:composition"
},
{
"path": "assets/mascot.json",
"target": "compositions/lottie-character-walk/assets/mascot.json",
"type": "hyperframes:asset"
}
]
}
+2 -1
View File
@@ -38,6 +38,7 @@ Blueprints live in `blueprints-index.md`. Each entry points to `blueprints/<id>.
| GSAP — eases / stagger | `adapters/gsap-easing-and-stagger.md` |
| GSAP — timeline / labels | `adapters/gsap-timeline-and-labels.md` |
| Lottie / dotLottie (After Effects exports, `window.__hfLottie`) | `adapters/lottie.md` |
| Character animation (walk cycle, mascot, jointed puppet, gestures) | `adapters/lottie.md` → Characters |
| Three.js / WebGL (3D scenes, `AnimationMixer`, `hf-seek`) | `adapters/three.md` |
| Anime.js (`window.__hfAnime`) | `adapters/animejs.md` |
| CSS keyframes (`animation-delay` / `play-state` / `fill-mode`) | `adapters/css-animations.md` |
@@ -49,7 +50,7 @@ Blueprints live in `blueprints-index.md`. Each entry points to `blueprints/<id>.
## Picking a runtime
- **GSAP** is the default for 95% of motion work — covers timeline orchestration, transforms, easing, stagger. All atomic rules in this skill are GSAP-based.
- **Lottie** when an asset has its own pre-baked timeline (typically After Effects exports).
- **Lottie** when an asset has its own pre-baked timeline (typically After Effects exports), including characters that walk, gesture or react.
- **Three.js** for 3D scenes, camera motion, shader-driven visuals.
- **Anime.js** for lightweight tweening when GSAP is overkill.
- **CSS** for simple repeated motifs, decoration, shimmer — no JavaScript animation cost.
@@ -11,7 +11,7 @@ HyperFrames can seek both `lottie-web` and dotLottie players through its `lottie
- Load assets from local project files, usually under `assets/`.
- Set `autoplay: false`.
- Prefer `loop: false` unless the user explicitly wants a loop.
- Use `loop: false` for a one-shot and `loop: true` for a cycle (walk, idle, spinner). A looping animation is seeked to composition time modulo its own length, so it keeps cycling for the whole scene; a one-shot holds its last frame.
- Register every returned animation or player on `window.__hfLottie`.
- Keep the Lottie container dimensions stable with CSS.
@@ -84,12 +84,25 @@ HyperFrames seeks them all to the same composition time.
## Composition Duration
The render engine needs the composition's total length. GSAP timelines report duration automatically; a Lottie-only composition has no timeline object, so the runtime reads the registered animation's native length directly — `totalFrames / frameRate` for `lottie-web`, or the player's own `duration` for dotLottie. `data-duration` on the root element is optional for Lottie compositions: as long as every animation is registered on `window.__hfLottie` (per the contract above), the runtime has a finite duration to work with even when you set `loop: true`.
The render engine needs the composition's total length. GSAP timelines report duration automatically; a Lottie-only composition has no timeline object, so the runtime reads the registered animation's native length directly — `totalFrames / frameRate` for `lottie-web`, or the player's own `duration` for dotLottie. `data-duration` on the root element is optional for Lottie compositions: as long as every animation is registered on `window.__hfLottie` (per the contract above), the runtime has a finite duration to work with. With `loop: true` that length is one cycle, so a looping Lottie in a longer scene needs `data-duration` or a GSAP timeline to set the scene length.
## Characters
For a character that walks, gestures or reacts (a mascot, a walk cycle, a jointed puppet), put the acting in one Lottie and the stage in GSAP:
- **The Lottie owns the body.** Walk, stop, point and idle live in the file's own timeline, so limbs stay jointed and feet stay planted exactly as the animator made them.
- **GSAP owns everything around it.** Cards, captions and camera moves go on the paused timeline, timed to the Lottie's beats. Read the beat times from the file's `markers` array (`tm` is in frames, divide by `fr`) or from the animator's notes.
- **Every registered animation plays against composition time.** There is no per-animation start offset, so a gesture that should begin at 4 s must begin at 4 s inside its file. Author the whole performance as one Lottie, or offset the action inside the file, rather than stacking separate action files.
- **A short cycle is fine.** A 1 s walk cycle with `loop: true` cycles for the whole scene. Move the character across the stage with GSAP `x` only if the cycle walks in place, and match the travel speed to the stride or the feet slide.
- **License the character.** Use a file the user or their designer made, or one whose license allows redistribution, and say where it came from. Never ship a character ripped from a site.
The `lottie-character-walk` registry block is a working example: a jointed flat character walks in on planted feet, stops, and points at a card that GSAP brings in on the point (`npx hyperframes add lottie-character-walk`).
## Good Uses
- After Effects exports that are already known to render correctly in lottie-web.
- Logo reveals, icon loops, decorative accents, and product UI motion.
- Characters: walk cycles, mascots, gestures (see Characters above).
- Translating Remotion Lottie usage into plain HyperFrames HTML.
## Avoid
+1 -1
View File
@@ -197,7 +197,7 @@ Vector animations that play inside a composition. Use for logos, character anima
</script>
```
`autoplay: false` + `loop: false` + `window.__hfLottie.push()` are mandatory — HyperFrames seeks each registered player to composition time, so anything left on `autoplay`/`loop` runs in wall-clock and renders non-deterministically. The adapter seeks absolute time (no modulo loop, no playback-rate scaling): bake repeating cycles or non-default speed into the Lottie asset or an explicit timeline, then verify the render. Full contract + `.lottie`/dotLottie variant: `adapters/lottie.md`.
`autoplay: false` + `window.__hfLottie.push()` are mandatory — HyperFrames seeks each registered player to composition time, so a player left on `autoplay` runs in wall-clock and renders non-deterministically. `loop: true` is seek-safe: the adapter wraps composition time into the animation's own length, so a short cycle repeats for the whole scene. There is no playback-rate scaling: bake non-default speed into the Lottie asset. Characters (walk cycles, mascots, gestures) and the full `.lottie`/dotLottie contract: `adapters/lottie.md`.
---
@@ -104,13 +104,11 @@ for the full supported feature list.
## Loop behavior
Remotion's `loop={true}` plays the animation continuously. Translate to
the player option only after checking the generated frames. The HF
adapter seeks absolute composition time; it does not add modulo looping
or playback-rate scaling on top of the player. For exact repeating
cycles or non-default playback rates, bake the timing into the Lottie
asset or author an explicit timeline around the Lottie layer and verify
the rendered output.
Remotion's `loop={true}` plays the animation continuously. Translate it
to `loop: true` on the player: the HF adapter wraps composition time into
the animation's own length, so the cycle repeats for the whole scene. It
does not add playback-rate scaling; bake a non-default rate into the
Lottie asset and verify the rendered output.
## Performance note