mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-16 06:19:21 +00:00
feat(registry): add a Lottie character walk-in and document the character route
This commit is contained in:
@@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user