npm i flipbook-foundry

// Svelte
import { Stage, Figure, TextFlow, FlipbookConfig } from 'flipbook-foundry/svelte';
// React
import { Stage, Figure, TextFlow, FlipbookConfig, useAnimate } from 'flipbook-foundry/react';
// Anything else
import { createStage, animate, stagger } from 'flipbook-foundry';

// Fonts load from jsDelivr, pinned to your installed version, and only the
// chunks your figures use. To self-host, copy node_modules/flipbook-foundry/fonts/
// to your public folder and call setFontBase('/fonts/') once at startup.
// Preload with getLibrary().load(['regular', 'bold']).

<Page
  text={'Bob {walk} left the house. Sue {wave} waved. The dog {run} gave chase.'}
  font="400 20px Georgia"   // any CSS font for the words
  figureScale={1.3}         // figure size relative to the text (default 1.3)
  align="center"            // or left
  phase={({ x, width }) => x / width}   // loops start by position: a wave
  bind:page                 // page.figures[i] are Characters you can direct
/>

{trip>get-up>dust-off}   a sequence, looped
{idle|sneak|run}         a figure that may switch between these
                         (room is reserved for the widest, so the line never moves)
a newline                starts a new paragraph

<Figure
  animate="walk"            // action or variant to play; change it to play another
  initial="sit-idle"        // shown first; routes from here into animate
  exit="bow"                // played before removal from a Stage
  transition={{ onTwos: true }}
  whileHover="wave"         // inline only (Stage figures: use stage.hitTest)
  whileTap="jump"
  x={120} y={300}           // Stage px; y is the ground line under the feet
  size={64}                 // font size in px; the figure is ~0.7 of it
  facing={-1}               // 1 faces right, -1 mirrors
  layer="bold"              // regular | bold | limbs | limbs-bold
  body={{ char: 'A', font: '700 10px Georgia' }}   // a letter for a body
  onAnimationComplete={(action) => …}
  onEvent={(event, action) => …}                    // 'hit', 'land', 'release'…
/>

const moods = {
  calm: 'idle',
  happy: { action: 'cheer', transition: { repeat: 2 }, then: 'calm' },
  leave: { action: 'walk', x: 900, then: 'wave' },   // travel to x, then wave
};

<Figure variants={moods} animate={mood} />

<Stage
  background={null}         // or a colour; null leaves the canvas transparent
  layers={['regular']}      // fonts to load before first draw
  onUpdate={(frame, stage) => …}      // game logic, every frame
  onBeforeDraw={(frame, stage) => …}  // draw terrain under the figures
  onAfterDraw={(frame, stage) => …}
>
  …figures, text flows…
</Stage>

// The Stage instance (bind:stage in Svelte, onReady / useStage in React):
stage.add({ x, y, size, facing })         // → Character
stage.remove(character, 'bow')           // exit action, then gone
stage.addProp({ text: 'A', font: '700 40px Georgia', attach: { to: c, anchor: 'handR' } })
stage.hitTest(x, y)                      // topmost Character or null
stage.toStage(clientX, clientY)          // pointer → stage space
stage.camera = { x, y, zoom }            // scroll and zoom big maps
stage.stats                               // { fps, characters, drawn, updateMs, drawMs }

// Things are glyphs too: props and set pieces in the Flipbook Stick Things font.
// shovel · broom · sack (12 fullnesses) · hole (12 depths) · pile (12 sizes) · wall · clod
await getLibrary().load(['regular', 'things']);

const sack   = stage.addThing({ name: 'sack', x: 600, y: ground, size: 120 });
const wall   = stage.addThing({ name: 'wall', x: 900, y: ground, layer: 'front' }); // hides who's behind
const shovel = stage.addThing({ name: 'shovel', size: 120 });

stage.hold(shovel, digger, 'R');      // tools turn with the forearm, every frame
stage.hold(sack, thief, 'L', true);   // sacks hang; true draws it behind the figure
stage.drop(sack);                     // lands under the hand
sack.frame++;                         // a drawing fuller

// Throw anything along an arc: a stolen letter, a clod of earth.
const letter = stage.addProp({ text: 'A', font: '700 54px Georgia', x, y });
await stage.fly(letter, { to: [sack.x, sack.y - 40], height: 90, spin: 1.5 });

// Real letters as objects: where each one is, so you can take it.
flow.glyphs();   // [{ index, char, x, y, width }, …]  then flow.setText(without it)

<Stage style="height: 420px">
  <TextFlow
    text={copy}
    font="400 22px Georgia"   // any CSS font; measured once by pretext
    x={0} y={0} width={720} lineHeight={32}
    padding={10}               // breathing room around figures
    avoid                      // re-wrap around every figure, every frame
  />
  <Figure animate="run" x={0} y={160} size={64} />
</Stage>

// Without components:
const flow = createTextFlow({ text, font, x, y, width, lineHeight });
flow.layout(obstacles);  // Rect[] → fragments, pure arithmetic
flow.draw(ctx);
flow.ledges();           // word tops: places to stand, sit or hang

import { animate, stagger } from 'flipbook-foundry';

animate(bob, 'jump');                                // → controls (thenable)
await animate(bob, 'walk', { x: 400, then: 'wave' }); // travel, then settle
animate(crowd, 'cheer', { delay: stagger(0.04, { from: 'center' }) });

// Sequences, with framer-motion's `at`:
animate([
  [bob, 'walk', { x: 260 }],
  [sue, 'walk', { x: 340, at: '<' }],     // same time as previous
  [[bob, sue], 'high-five'],              // after both arrive
  [bob, 'cheer', { at: '+0.3' }],         // 0.3s after
]);

const c = animate(bob, 'dance');
c.stop();  await c.finished;

const c = createCharacter({ x: 0, y: 300, size: 64, animate: 'idle' });
c.animate('trip');                 // interrupts, routes hubs, resolves when done
c.pose('jump', 14);                // freeze on a drawing
c.on('hit', () => shake());        // baked events: hit, land, release, grab…
c.on('frame', ({ action, frame }) => …);
c.anchor('handR');                 // [x, y] stage px — where to put the letter
c.bounds();                        // ink box, for hit-tests and text flow
c.glyph;                           // the current character to draw
c.use(wander(), greet());          // behaviours

// Compose: actions play in order; rest-pose routes (get-up, stand-up…)
// are inserted for you. Loops play one cycle each.
c.sequence(['sneak', 'trip', 'dust-off', 'wave'], { loop: true });

import { wander, greet } from 'flipbook-foundry';

stage.add({ x, y }).use(
  wander({
    area: [0, 1200],
    gaits: ['walk', 'walk', 'jog', 'skip'],
    idles: ['idle', 'look-around', 'yawn', 'dance'],
    pause: [1, 4],
    clumsiness: 0.1,            // chance of a trip on the way
  }),
  greet({ radius: 70, actions: ['wave', 'high-five', 'bow'] }),
);

// A behaviour is just (character, stage, now) => void. Write your own:
const flee = (c, stage) => { if (near(c, cat)) c.animate({ action: 'sprint', x: 0 }); };

const animate = useAnimate();       // animate() that stops on unmount
const stage = useStage();           // enclosing Stage (null until fonts load)
useStageFrame((frame, stage) => …); // per-frame logic
const reduced = useReducedMotion(); // honours prefers-reduced-motion

<Figure ref={setBob} animate="idle" />   // ref → Character

<FlipbookConfig
  family={stick}            // figure family (default: stick)
  transition={{ onTwos: true }}
  layer="bold"
  size={48}
  reducedMotion="user"      // 'user' | 'always' | 'never' — freezes figures on frame 0
>
  …
</FlipbookConfig>

import stick from '@flipbook-foundry/stick';
import { getLibrary, setDefaultFamily, setFontBase } from 'flipbook-foundry';

setDefaultFamily(stick);              // the family used when none is given
<Stage family={stick}>…</Stage>        // a Stage's Figures draw in its family
<Page family={stick} text={…} />
<Figure family={stick} animate="wave" />   // inline figures

getLibrary(stick).names();            // that family's actions
setFontBase('/fonts/', stick);        // self-host its fonts

// packages/rig/actions/emote.ts
export const shrug: ActionDef = {
  name: 'shrug', category: 'gesture', description: '…',
  frames: 30, fps: 24, loop: false, from: 'stand', to: 'stand',
  keys: [
    { at: 0, ...STAND },
    { at: 8, armL: [-20, 120], armR: [20, 120], head: -10, ease: 'snap' },
    { at: 20, head: 4, event: 'shrugged' },
    { at: 29, ...STAND },
  ],
};

// npm run build:font   → bakes every action into the fonts + manifest
// npm run sheet shrug  → contact sheet in .sheets/shrug.png
// /forge               → pose it by hand, copy the ActionDef