@algorisys/tinyfly 0.92.0 → 0.94.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -6
- package/bin/tinyfly.mjs +34 -1
- package/docs/2d-animation-roadmap.md +191 -0
- package/docs/3d-rotations.md +164 -0
- package/docs/3d-support-plan.md +628 -0
- package/docs/DEPLOYMENT.md +414 -0
- package/docs/acting.md +529 -0
- package/docs/api-reference.md +2353 -0
- package/docs/camera.md +94 -0
- package/docs/cartoon-hands.md +96 -0
- package/docs/character-system-m1.md +218 -0
- package/docs/character-system-plan.md +384 -0
- package/docs/dance.md +315 -0
- package/docs/editor-guide.md +1249 -0
- package/docs/examples.md +765 -0
- package/docs/extending.md +168 -0
- package/docs/file-format.md +690 -0
- package/docs/getting-started.md +314 -0
- package/docs/grid-and-snapping.md +64 -0
- package/docs/gsap-compat.md +1241 -0
- package/docs/llm-guide.md +131 -0
- package/docs/maps.md +116 -0
- package/docs/onion-skinning.md +41 -0
- package/docs/pen-tool.md +65 -0
- package/docs/polygon-star.md +44 -0
- package/docs/scene-3d.md +299 -0
- package/docs/scroll-animation.md +314 -0
- package/docs/shape-morph.md +61 -0
- package/docs/sprite-sheet-export.md +54 -0
- package/docs/symbols-and-library.md +137 -0
- package/docs/teaching.md +348 -0
- package/docs/video-rendering.md +728 -0
- package/lib/addons/adapters.js +22 -18
- package/lib/addons/characters.js +3045 -2024
- package/lib/addons/target-properties-BtN9skb-.js +142 -0
- package/lib/browser/tinyfly.iife.js +9 -4
- package/lib/browser/tinyfly.js +6968 -5817
- package/lib/browser/tinyfly.umd.js +9 -4
- package/lib/engine/tinyfly-engine.js +286 -258
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
- package/lib/types/adapters/canvas/index.d.ts +1 -0
- package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
- package/lib/types/characters/acting/beat-check.d.ts +102 -0
- package/lib/types/characters/acting/custom.d.ts +66 -0
- package/lib/types/characters/acting/gags.d.ts +10 -0
- package/lib/types/characters/acting/hand-path.d.ts +35 -0
- package/lib/types/characters/acting/index.d.ts +4 -0
- package/lib/types/characters/acting/persona.d.ts +93 -0
- package/lib/types/characters/acting/script.d.ts +75 -11
- package/lib/types/characters/capabilities.d.ts +61 -0
- package/lib/types/characters/code-panel.d.ts +201 -0
- package/lib/types/characters/figure-actions.d.ts +12 -0
- package/lib/types/characters/figure-props.d.ts +87 -0
- package/lib/types/characters/gaits.d.ts +8 -0
- package/lib/types/characters/index.d.ts +3 -0
- package/lib/types/characters/stick-figure.d.ts +9 -2
- package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
- package/lib/types/engine/authoring/index.d.ts +1 -0
- package/llms-full.txt +12631 -0
- package/llms.txt +57 -0
- package/package.json +6 -2
- package/skills/tinyfly/SKILL.md +67 -0
- package/lib/addons/camera-C7bZOWMB.js +0 -33
package/docs/camera.md
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# Camera — Phase B design
|
|
2
|
+
|
|
3
|
+
**Status:** In progress (foundation landed)
|
|
4
|
+
**Date:** 2026-07-22
|
|
5
|
+
**Roadmap:** [2d-animation-roadmap.md](2d-animation-roadmap.md) → Phase B
|
|
6
|
+
|
|
7
|
+
A **camera** animates a pan / zoom / rotate over the whole stage — cinematic
|
|
8
|
+
moves without touching your elements. True to tinyfly's "animation = a transform"
|
|
9
|
+
ethos, the camera is **just an animated element**: a reserved layer named
|
|
10
|
+
`Camera` that wraps the stage, driven by ordinary keyframe tracks.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## Model
|
|
15
|
+
|
|
16
|
+
No new data model. The camera is a set of tracks targeting the reserved name
|
|
17
|
+
**`Camera`** with the existing animatable properties:
|
|
18
|
+
|
|
19
|
+
| Track property | Effect on the stage |
|
|
20
|
+
|----------------|---------------------|
|
|
21
|
+
| `x`, `y` | Pan (translate the whole stage) |
|
|
22
|
+
| `scale` | Zoom (around the stage centre) |
|
|
23
|
+
| `rotate` | Rotate (around the stage centre) |
|
|
24
|
+
|
|
25
|
+
The preview wraps all elements in a `Camera` layer
|
|
26
|
+
(`<div data-tinyfly="Camera">`) registered with the DOM adapter, so those tracks
|
|
27
|
+
transform everything at once. With no `Camera` tracks the layer is identity —
|
|
28
|
+
completely inert — so nothing changes until you add a camera.
|
|
29
|
+
|
|
30
|
+
Because it's ordinary tracks + a named layer, the camera **serializes for free**
|
|
31
|
+
(it's in the timeline JSON), keyframes like any track, and — once the layer is
|
|
32
|
+
emitted — flows through export and embeds via the same adapters.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Store API
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
addCamera() // add x/y/scale/rotate tracks on "Camera", seeded at identity
|
|
40
|
+
removeCamera() // drop all Camera tracks
|
|
41
|
+
hasCamera() // is a camera present?
|
|
42
|
+
getCameraValue(prop) // current pan/zoom/rotate at the playhead
|
|
43
|
+
setCameraValue(prop, value) // keyframe a camera prop at the playhead (upsert)
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
`addCamera` seeds each track with a keyframe at `0` and at the timeline's end, so
|
|
47
|
+
it's ready to keyframe. Keyframe the camera like any track (select a Camera
|
|
48
|
+
track, add/drag keyframes, edit values in the Property Panel).
|
|
49
|
+
|
|
50
|
+
**Camera inspector.** With a camera present and nothing selected, the Property
|
|
51
|
+
Panel shows a 🎥 **Camera** section with Pan X / Pan Y / Zoom / Rotation inputs.
|
|
52
|
+
Editing a field calls `setCameraValue`, which upserts a keyframe **at the
|
|
53
|
+
playhead** — so you scrub to a time, dial in the framing, and the pan/zoom is
|
|
54
|
+
recorded. "Reset to identity" and "Remove camera" live there too.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Implementation slices
|
|
59
|
+
|
|
60
|
+
1. **Foundation (this slice):** `Camera` layer in the **DOM preview** + store
|
|
61
|
+
`addCamera` / `removeCamera` / `hasCamera` + a **🎥 Camera** toggle in the
|
|
62
|
+
preview header. Camera animation plays in the DOM preview. Unit-tested.
|
|
63
|
+
2. **Everywhere else (done):** the camera applies in the **Canvas** and **SVG**
|
|
64
|
+
previews, **raster export** (GIF/WebP/MP4), and **embeds** (single-scene via a
|
|
65
|
+
`Camera` wrapper the player animates; multi-scene via a per-scene camera layer
|
|
66
|
+
in the sequencer). `src/editor/utils/camera.ts` holds the shared transform math.
|
|
67
|
+
3. **Camera inspector (done):** a 🎥 **Camera** section in the Property Panel
|
|
68
|
+
(shown when a camera exists and nothing is selected) with Pan X/Y, Zoom, and
|
|
69
|
+
Rotation inputs that keyframe at the playhead via `setCameraValue`, plus
|
|
70
|
+
"Reset to identity" / "Remove camera". Unit-tested.
|
|
71
|
+
3b. **On-stage pan + timeline camera lane (done):** a **✋ Pan** toggle in the DOM
|
|
72
|
+
preview drops a drag overlay on the stage — dragging pans the camera 1:1 (its
|
|
73
|
+
pan is added in stage space after scale/rotate, so no inverse transform is
|
|
74
|
+
needed), writing x/y keyframes at the playhead via `setCameraValue`. The
|
|
75
|
+
timeline floats the Camera tracks to the top as a distinct 🎥 lane. Corner-zoom
|
|
76
|
+
and a rotate handle stay numeric in the inspector (they need the inverse
|
|
77
|
+
transform); a full draggable frame with those is a later refinement.
|
|
78
|
+
4. **Edit-in-camera correctness:** element drag/resize math accounts for the
|
|
79
|
+
current camera transform (today, edit at the camera's start/identity frame).
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## Known limitations (foundation)
|
|
84
|
+
|
|
85
|
+
- Editing elements while the playhead sits on a **camera-transformed** frame is
|
|
86
|
+
approximate — the drag math assumes identity. Set up your scene first, then
|
|
87
|
+
keyframe the camera (slice 4 fixes this).
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## Non-goals
|
|
92
|
+
|
|
93
|
+
- Multiple cameras / camera switching (one camera per scene).
|
|
94
|
+
- Depth / parallax layers (possible later via per-layer camera influence).
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Cartoon hands
|
|
2
|
+
|
|
3
|
+
A hand you can pose: a palm and five fingers built in the hand's own 3D space,
|
|
4
|
+
posed by a flat record of numbers, turned and drawn flat in any look (clean,
|
|
5
|
+
pencil, silhouette). Because the hand is 3D, turning the wrist needs no extra
|
|
6
|
+
drawing code: fingers behind the palm are drawn behind it, and nails show only
|
|
7
|
+
where they face you.
|
|
8
|
+
|
|
9
|
+

|
|
10
|
+
|
|
11
|
+
The sheet is `examples/headless-video/hand-shapes.mjs`.
|
|
12
|
+
|
|
13
|
+
```js
|
|
14
|
+
import { drawCartoonHand, HAND_SHAPES, mixHandPoses } from '@algorisys/tinyfly/characters'
|
|
15
|
+
|
|
16
|
+
// The wrist at (200, 300), fingers pointing up, 120 px from wrist to fingertip.
|
|
17
|
+
drawCartoonHand(ctx, { x: 200, y: 300 }, HAND_SHAPES.point, { size: 120 })
|
|
18
|
+
|
|
19
|
+
// A left hand in pencil, palm toward us, pointing up and to the right.
|
|
20
|
+
drawCartoonHand(ctx, { x: 400, y: 300 }, { ...HAND_SHAPES.wave, turn: 2 }, { side: 'left', look: 'pencil', angle: 30 }, time)
|
|
21
|
+
|
|
22
|
+
// Halfway from a fist to an open hand.
|
|
23
|
+
drawCartoonHand(ctx, at, mixHandPoses(HAND_SHAPES.fist, HAND_SHAPES.open, 0.5))
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## The pose
|
|
27
|
+
|
|
28
|
+
Every field is a number, so two poses blend and any field can be a timeline track.
|
|
29
|
+
|
|
30
|
+
| Field | Meaning |
|
|
31
|
+
|---|---|
|
|
32
|
+
| `index.curl`, `middle.curl`, `ring.curl`, `pinky.curl` | 0 straight, 1 curled into the palm |
|
|
33
|
+
| `thumb.curl` | 0 straight, 1 bent at both knuckles |
|
|
34
|
+
| `thumb.across` | 0 out to the side, 1 across the palm |
|
|
35
|
+
| `spread` | 0 fingers together, 1 fanned wide |
|
|
36
|
+
| `turn` | Wrist turn: 0 back of the hand toward you, 1 thumb side, 2 palm, -1 little-finger side |
|
|
37
|
+
| `bend` | Wrist bend, degrees: + toward the palm |
|
|
38
|
+
| `tilt` | Wrist tilt, degrees: + toward the little finger |
|
|
39
|
+
| `roll` | The whole hand turned in the picture, degrees clockwise (a left hand turns the mirror way) |
|
|
40
|
+
|
|
41
|
+
`handPose(changes)` gives a full pose from the fields that differ from rest
|
|
42
|
+
(`HAND_REST`, a relaxed hand).
|
|
43
|
+
|
|
44
|
+
### Shapes
|
|
45
|
+
|
|
46
|
+
`HAND_SHAPES`: `relaxed`, `open`, `spread`, `flat`, `fist`, `point`,
|
|
47
|
+
`thumbsUp`, `peace`, `ok`, `pinch`, `cupped`, `wave`, `pencilGrip` (thumb and
|
|
48
|
+
middle finger pinch, index on top) and `hold` (every finger wrapped round a
|
|
49
|
+
handle). Change single fields on top: `{ ...HAND_SHAPES.point, turn: 2 }`.
|
|
50
|
+
|
|
51
|
+
## The style
|
|
52
|
+
|
|
53
|
+
| Option | Meaning |
|
|
54
|
+
|---|---|
|
|
55
|
+
| `size` | Wrist to the tip of the middle finger, px (default 100) |
|
|
56
|
+
| `side` | `'right'` (default) or `'left'`: the left hand is the right mirrored |
|
|
57
|
+
| `angle` | Which way the fingers point, degrees clockwise from straight up |
|
|
58
|
+
| `fingers` | `5` (default) or `4`: a thumb and three, the classic cartoon glove |
|
|
59
|
+
| `plump` | 1 a natural hand (default); 1.5 a fat cartoon glove |
|
|
60
|
+
| `skin`, `ink`, `lineWidth` | Fill, outline colour and outline width; a glove is just another skin |
|
|
61
|
+
| `look`, `seed`, `pencil` | The look, when no `pen` is given |
|
|
62
|
+
| `pen` | Draw with a character's pen, so the hand matches and boils with it |
|
|
63
|
+
| `nails` | Nails on fingertips that face you (default true) |
|
|
64
|
+
| `prop` | `{ depth, draw(pen) }`: something held, drawn among the fingers at its depth |
|
|
65
|
+
|
|
66
|
+
## Joints, for props and attachments
|
|
67
|
+
|
|
68
|
+
`handJoints(pose, style)` returns where everything is with the wrist at (0, 0)
|
|
69
|
+
(`handJointsAt` moves it): each finger's joints, depths and widths, the palm
|
|
70
|
+
outline, which way the palm faces, and the hand's own axes on screen.
|
|
71
|
+
`drawCartoonHand` returns the same, as drawn. Use the fingertips to place a
|
|
72
|
+
prop, or the depths to slot it between fingers.
|
|
73
|
+
|
|
74
|
+
## Where hands are used
|
|
75
|
+
|
|
76
|
+
- **The animator's hand.** `drawHand(ctx, tip, { tool, lift })` is this hand
|
|
77
|
+
in its `pencilGrip`, holding a pencil or an eraser between the thumb and
|
|
78
|
+
fingers, with a forearm whose sleeve fades out. `handAt(strokes, time)` moves
|
|
79
|
+
one hand through a whole scene: it follows each stroke, lifts and glides to
|
|
80
|
+
the next, and comes in and leaves the page.
|
|
81
|
+
- **Characters.** `character({ hands: 'cartoon' })` puts gloved hands on the
|
|
82
|
+
fluid figure (four fingers, plump, `handSize` 0.17 of the height). Each hand
|
|
83
|
+
takes its pose from `hand.left.*` / `hand.right.*` fields in the character's
|
|
84
|
+
pose (`'hand.right.index.curl': 0`), so hands are tracks like everything
|
|
85
|
+
else. `hand.<side>.turn` is relative to how a hand hangs at the side (thumb
|
|
86
|
+
forward); `characterHandPose(pose, side)` shows what a hand will get.
|
|
87
|
+
`handStyle: 'natural'` draws five slimmer fingers instead of the glove
|
|
88
|
+
(`handSize` 0.14), so shapes like mudras read finger by finger.
|
|
89
|
+
|
|
90
|
+
## Not yet
|
|
91
|
+
|
|
92
|
+
- The editor's Character element takes hand shapes from dances (Hands: Cartoon
|
|
93
|
+
gloves or Natural); there is no hand-shape picker for single poses yet.
|
|
94
|
+
- A forearm pointing straight at the viewer does not foreshorten the hand.
|
|
95
|
+
- The v1 stick figure draws these hands with `style.hands`; see
|
|
96
|
+
[Dance and Flips](dance.md).
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
# Character System — Milestone 1: rig core (design)
|
|
2
|
+
|
|
3
|
+
**Status:** Built on `feat/character-v2`, for review (core and the editor's character element)
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
## Built so far
|
|
8
|
+
|
|
9
|
+
| Piece | Where |
|
|
10
|
+
|---|---|
|
|
11
|
+
| Body plans, chains, bone angles | `src/characters/rig/body-plan.ts` |
|
|
12
|
+
| Skeleton: 3D bones, turn, roll, contact, lift | `src/characters/rig/skeleton.ts` |
|
|
13
|
+
| Reaching (two-bone, exact) | `src/characters/rig/reach.ts` |
|
|
14
|
+
| The human plan, rest pose, 10 named poses | `src/characters/species/human.ts` |
|
|
15
|
+
| Pen: clean, pencil (boil, pressure, construction lines, rubbed-out attempts), silhouette | `src/characters/look/pen.ts` |
|
|
16
|
+
| Face on the head, sliding round with the turn | `src/characters/head/face.ts` |
|
|
17
|
+
| `character()`, `drawCharacter()`, `characterJoints()`, `characterTarget()`, `characterAt()`, `reachCharacter()`, `mixPoses()` | `src/characters/character.ts` |
|
|
18
|
+
| Tests (joints vs drawing, turn invariants, depth order, contact, reach, determinism, looks) | `src/characters/character.test.ts` |
|
|
19
|
+
| Model sheet | `examples/headless-video/human-turnaround.mjs` → `docs/model-sheet/human-turnaround.png` |
|
|
20
|
+
|
|
21
|
+
`taperedLine` and `rubberLimb` moved to `src/characters/look/` (re-exported
|
|
22
|
+
from the v1 module unchanged) so v2 does not depend on v1. v1's tests and
|
|
23
|
+
golden frames pass unchanged.
|
|
24
|
+
|
|
25
|
+
### The editor's character element
|
|
26
|
+
|
|
27
|
+
| Piece | Where |
|
|
28
|
+
|---|---|
|
|
29
|
+
| `character` element type (figure, look, colours, outfit, pose) | `src/editor/stores/scene-store.ts` |
|
|
30
|
+
| Element → character, pose at a time, canvas target, DOM canvas | `src/editor/utils/character-element.ts` |
|
|
31
|
+
| 🧍 Character in the Elements panel (centred, sized to the canvas) | `src/editor/components/element-panel.tsx` |
|
|
32
|
+
| DOM preview canvas, repainted with the animated pose | `src/editor/components/preview-panel.tsx` |
|
|
33
|
+
| Canvas preview and GIF / MP4 export | `src/editor/utils/scene-to-canvas.ts` |
|
|
34
|
+
| Character section: figure, look, colours, clothes, view, body, face, ◆ keyframe | `src/editor/components/property-panel.tsx` |
|
|
35
|
+
| Key a pose at the playhead in one undo step | `keyValuesAtPlayhead` in `src/editor/stores/editor-store.ts` |
|
|
36
|
+
| Plain-language track names | `trackPropertyLabel` (timeline, track list, curves) |
|
|
37
|
+
|
|
38
|
+
The library gained `characterPoseTracks()` (timed poses to tracks),
|
|
39
|
+
`humanFieldLabel()`, `HUMAN_EXPRESSIONS` and `basicOutfit()` (a T-shirt and
|
|
40
|
+
trousers whose sleeves grow out of the shoulders), and the whole-figure roll
|
|
41
|
+
field is `roll` (not `rotate`, which turns an element's box).
|
|
42
|
+
|
|
43
|
+
Not yet: characters in exported HTML / embeds and in the SVG preview.
|
|
44
|
+
|
|
45
|
+
### Not done yet in milestone 1
|
|
46
|
+
|
|
47
|
+
- **Faces in profile** use a cartoon mapping (the face shifts toward the side
|
|
48
|
+
it faces) rather than the true sphere, so a profile keeps an eye and a mouth;
|
|
49
|
+
noses and profile mouths come with milestone 3.
|
|
50
|
+
- **Reaching** is exact for two-bone limbs; long chains come with the animals.
|
|
51
|
+
**Plan:** [character-system-plan.md](character-system-plan.md)
|
|
52
|
+
|
|
53
|
+
Milestone 1 builds the skeleton every later character uses, and a human on it,
|
|
54
|
+
drawn in three looks (clean, pencil, silhouette) and two figure styles (stick,
|
|
55
|
+
fluid). It ends with a turnaround model sheet.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Space and turning
|
|
60
|
+
|
|
61
|
+
A character is built in its own 3D space, measured from the ground under its
|
|
62
|
+
hips:
|
|
63
|
+
|
|
64
|
+
- **+x** is the character's **left**, **+y** is up, **+z** is the way it faces.
|
|
65
|
+
- `turn` spins it about the vertical axis by `turn × 90°`: **0** faces the
|
|
66
|
+
viewer, **1** faces screen-right (profile), **2** shows its back, **3** faces
|
|
67
|
+
screen-left. Any value works (0.5 is a 3/4 view; -1 is the same as 3).
|
|
68
|
+
- The view is orthographic: screen x = x·cos θ + z·sin θ, screen y = −y, and
|
|
69
|
+
**depth** (toward the viewer) = −x·sin θ + z·cos θ.
|
|
70
|
+
|
|
71
|
+
With +x as the character's left, its left arm is on screen-right in the front
|
|
72
|
+
view (as a real person facing you) and is the far arm when it faces right.
|
|
73
|
+
|
|
74
|
+
## Body plans, chains and bones
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
interface BoneSpec { length: number; width: [number, number] } // fractions of height
|
|
78
|
+
interface ChainSpec {
|
|
79
|
+
id: string // 'spine', 'neck', 'arm.left', 'leg.right'
|
|
80
|
+
parent: string | null // chain it hangs from (null: the hips)
|
|
81
|
+
at?: number // parent joint index (default: its end)
|
|
82
|
+
offset?: [number, number, number] // from that joint, fractions of height
|
|
83
|
+
rest: [number, number, number] // direction of the first bone at rest
|
|
84
|
+
bones: BoneSpec[]
|
|
85
|
+
side?: -1 | 1 // right (-1) or left (+1): sets which way "spread" goes
|
|
86
|
+
}
|
|
87
|
+
interface BodyPlan { id: string; chains: ChainSpec[]; head: HeadSpec; contacts: ContactSpec[] }
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Bone angles
|
|
91
|
+
|
|
92
|
+
Each bone's direction comes from its chain's rest direction, turned by two
|
|
93
|
+
angles in degrees:
|
|
94
|
+
|
|
95
|
+
- **swing**: forward (+) and back (−), about the character's x axis;
|
|
96
|
+
- **spread**: away from the body (+) and across it (−), about its z axis.
|
|
97
|
+
|
|
98
|
+
A bone's angles add to its parent bone's, as v1's elbow adds to its shoulder.
|
|
99
|
+
Direction = Rz(spread · side) · Rx(swing) · rest. Seen from the front only the
|
|
100
|
+
spread shows; seen from the side only the swing. This is what fixes the
|
|
101
|
+
"arms forward and back in profile" problem.
|
|
102
|
+
|
|
103
|
+
## Pose
|
|
104
|
+
|
|
105
|
+
A pose is a flat record of numbers, so poses blend and every field can be a
|
|
106
|
+
timeline track. The human's fields:
|
|
107
|
+
|
|
108
|
+
| Field | Meaning |
|
|
109
|
+
|---|---|
|
|
110
|
+
| `turn` | View, as above |
|
|
111
|
+
| `lean`, `side` | Upper body: forward/back and sideways bend, degrees |
|
|
112
|
+
| `head.turn`, `head.nod`, `head.tilt` | Head yaw on the body, pitch, roll |
|
|
113
|
+
| `arm.left.swing`, `arm.left.spread`, `arm.left.elbow` | Upper arm, and the elbow (forearm swings forward) |
|
|
114
|
+
| `leg.left.swing`, `leg.left.spread`, `leg.left.knee` | Thigh, and the knee (shin swings back) |
|
|
115
|
+
| `leg.left.ankle`, `leg.left.toeOut` | Foot tilt (toes up +), and the foot turned out (+) or in (−) from its natural angle |
|
|
116
|
+
| `leg.left.rotate` | The whole leg turned out at the hip, degrees: at 90 a bent knee points sideways (a turned-out plié) |
|
|
117
|
+
| `stretch` | Squash and stretch, as v1 |
|
|
118
|
+
| `lift` | Height above the surface, fraction of height (a jump) |
|
|
119
|
+
| `roll` | Whole-figure roll in the picture plane, degrees (falling, lying). Not `rotate`, which turns an element's box |
|
|
120
|
+
| `mouth`, `smile`, `mouthWidth`, `blink`, `eye.left`, `eye.right`, `brow.left`, `brow.right`, `browTilt`, `lookX`, `lookY` | Face, as v1 |
|
|
121
|
+
|
|
122
|
+
(`.right` fields as `.left`.)
|
|
123
|
+
|
|
124
|
+
## Placing on a surface
|
|
125
|
+
|
|
126
|
+
After the pose is projected and rolled by `roll` (about the hips), the
|
|
127
|
+
lowest **contact point** rests on the ground (y = 0): toes and heels, knees,
|
|
128
|
+
hands, elbows, hips, the head. Lying down, kneeling and crawling are then just
|
|
129
|
+
poses. `lift` raises the figure above that. `contact: 'none'` turns placement
|
|
130
|
+
off (a figure in the air keeps its hips at standing height).
|
|
131
|
+
|
|
132
|
+
## Reaching
|
|
133
|
+
|
|
134
|
+
`reachPose(character, pose, 'arm.left', target)` returns the pose with that
|
|
135
|
+
limb's angles solved so its end touches `target` (a point in character space,
|
|
136
|
+
or a screen point given a depth). Two-bone limbs are solved exactly, bending
|
|
137
|
+
the elbow down and back and the knee forward; out of reach, the limb points
|
|
138
|
+
straight at the target. Long chains (tails, trunks) come with the animals.
|
|
139
|
+
|
|
140
|
+
## Drawing
|
|
141
|
+
|
|
142
|
+
1. Solve the bones (forward kinematics), project, roll, place.
|
|
143
|
+
2. Build **parts**: each chain is one part with a depth (its average); the head
|
|
144
|
+
is a part. Sort far to near; ties keep the plan's order (legs, torso, arms,
|
|
145
|
+
head), so arms in front of the chest stay in front.
|
|
146
|
+
3. Draw each part with the figure style and the pen, calling layer hooks:
|
|
147
|
+
`layers: { [partId]: { under?, over? } }`, plus `behind` and `front` for
|
|
148
|
+
the whole figure. A sleeve on the far arm is behind the body because the
|
|
149
|
+
arm is.
|
|
150
|
+
|
|
151
|
+
### Figure styles
|
|
152
|
+
|
|
153
|
+
- **`stick`**: the traditional (Pencilmation) stick figure: even lines, a
|
|
154
|
+
circle head, one point for the shoulders and hips, no hands or feet.
|
|
155
|
+
- **`fluid`**: tapered limbs, small hands, feet, rounded shoulders. Clothes
|
|
156
|
+
and hair are layers on top (wardrobe is milestone 4).
|
|
157
|
+
|
|
158
|
+
### Looks: the Pen
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
interface Pen {
|
|
162
|
+
readonly look: 'clean' | 'pencil' | 'silhouette'
|
|
163
|
+
limb(points: Point[], from: number, to: number): void // tapered stroke
|
|
164
|
+
line(points: Point[], width?: number): void // even stroke
|
|
165
|
+
shape(points: Point[], fill: string): void // closed, filled, outlined
|
|
166
|
+
ellipse(cx: number, cy: number, rx: number, ry: number, angle: number, fill?: string): void
|
|
167
|
+
dot(x: number, y: number, r: number): void
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Every part, and every layer hook, draws through the pen it is handed:
|
|
172
|
+
|
|
173
|
+
- **clean**: filled tapered shapes and canvas strokes.
|
|
174
|
+
- **pencil**: graphite strokes in passes that boil (the existing `sketchPen`
|
|
175
|
+
wobble), **pressure variation** along each stroke (seeded, so a stroke is the
|
|
176
|
+
same every frame of its boil), **construction lines** (the skeleton's guide
|
|
177
|
+
shapes, faint, under the final line: the head circle with its centre lines, a
|
|
178
|
+
torso line, joint circles), and **rubbed-out lines** (a few earlier attempts,
|
|
179
|
+
faint and smudged, offset from the final line). All seeded by the
|
|
180
|
+
character's seed, the boil frame and the stroke's order.
|
|
181
|
+
- **silhouette**: everything filled in the ink colour, for the readability
|
|
182
|
+
check.
|
|
183
|
+
|
|
184
|
+
### Head
|
|
185
|
+
|
|
186
|
+
The head is an ellipsoid (a sphere stretched by `stretch`). Face features
|
|
187
|
+
(eyes, brows, mouth) have a position on its surface, an angle around from the
|
|
188
|
+
front and an angle up. They are drawn where the head's yaw (`turn` plus
|
|
189
|
+
`head.turn`) puts them, narrowed as they turn away, and hidden on the far side,
|
|
190
|
+
so the face slides round in 3/4, shows one eye in profile and disappears at the
|
|
191
|
+
back. Eye, brow and nose styles, ears and lip-sync shapes are milestone 3.
|
|
192
|
+
|
|
193
|
+
## Public API (milestone 1)
|
|
194
|
+
|
|
195
|
+
```ts
|
|
196
|
+
const hero = character({ figure: 'fluid', look: 'clean', height: 400, ink: '#2b1d16', skin: '#f2c49b', layers })
|
|
197
|
+
drawCharacter(ctx, hero, pose, time) // feet at (0, 0)
|
|
198
|
+
characterJoints(hero, pose) // every point, part and depth, as drawn
|
|
199
|
+
characterTarget({ x, y, character: hero, pose }) // a canvas custom target; pose fields are props
|
|
200
|
+
characterAt(target, frame, id) // its joints in a frame, for draw()
|
|
201
|
+
humanPose(changes) // a full pose from the fields that differ from rest
|
|
202
|
+
mixPoses(a, b, t) // blend
|
|
203
|
+
reachPose(hero, pose, chain, target) // IK
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Defaults are the bold look: head 30% of the height, line 4.5% of the height.
|
|
207
|
+
`proportions: 'thin'` gives the reference sheets' lighter line and 24% head.
|
|
208
|
+
|
|
209
|
+
## Tests
|
|
210
|
+
|
|
211
|
+
- Joints match drawing (recorded canvas calls vs `characterJoints`).
|
|
212
|
+
- Turn invariants: `turn` 2 is `turn` 0 mirrored with the face hidden; `turn`
|
|
213
|
+
1 and 3 mirror each other; arms spread sideways vanish edge-on in profile.
|
|
214
|
+
- Contact: the lowest contact point is at y = 0 for every pose.
|
|
215
|
+
- Reach: within 0.5 px when in reach.
|
|
216
|
+
- Determinism: the pencil look draws identically twice for the same time, and
|
|
217
|
+
changes between boil frames.
|
|
218
|
+
- v1's golden frames and tests are untouched.
|