@algorisys/tinyfly 0.91.0 → 0.93.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.
Files changed (63) hide show
  1. package/README.md +7 -6
  2. package/bin/tinyfly.mjs +34 -1
  3. package/docs/2d-animation-roadmap.md +191 -0
  4. package/docs/3d-rotations.md +164 -0
  5. package/docs/3d-support-plan.md +628 -0
  6. package/docs/DEPLOYMENT.md +414 -0
  7. package/docs/acting.md +466 -0
  8. package/docs/api-reference.md +2353 -0
  9. package/docs/camera.md +94 -0
  10. package/docs/cartoon-hands.md +96 -0
  11. package/docs/character-system-m1.md +218 -0
  12. package/docs/character-system-plan.md +384 -0
  13. package/docs/dance.md +315 -0
  14. package/docs/editor-guide.md +1249 -0
  15. package/docs/examples.md +765 -0
  16. package/docs/extending.md +168 -0
  17. package/docs/file-format.md +690 -0
  18. package/docs/getting-started.md +314 -0
  19. package/docs/grid-and-snapping.md +64 -0
  20. package/docs/gsap-compat.md +1241 -0
  21. package/docs/llm-guide.md +123 -0
  22. package/docs/maps.md +116 -0
  23. package/docs/onion-skinning.md +41 -0
  24. package/docs/pen-tool.md +65 -0
  25. package/docs/polygon-star.md +44 -0
  26. package/docs/scene-3d.md +299 -0
  27. package/docs/scroll-animation.md +314 -0
  28. package/docs/shape-morph.md +61 -0
  29. package/docs/sprite-sheet-export.md +54 -0
  30. package/docs/symbols-and-library.md +137 -0
  31. package/docs/teaching.md +348 -0
  32. package/docs/video-rendering.md +728 -0
  33. package/lib/addons/adapters.js +22 -18
  34. package/lib/addons/characters.js +2785 -1794
  35. package/lib/addons/target-properties-BtN9skb-.js +142 -0
  36. package/lib/browser/tinyfly.iife.js +9 -4
  37. package/lib/browser/tinyfly.js +6575 -5454
  38. package/lib/browser/tinyfly.umd.js +9 -4
  39. package/lib/engine/tinyfly-engine.js +286 -258
  40. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  41. package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
  42. package/lib/types/adapters/canvas/index.d.ts +1 -0
  43. package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
  44. package/lib/types/characters/acting/beat-check.d.ts +95 -0
  45. package/lib/types/characters/acting/hand-path.d.ts +32 -0
  46. package/lib/types/characters/acting/index.d.ts +2 -0
  47. package/lib/types/characters/acting/script.d.ts +66 -7
  48. package/lib/types/characters/capabilities.d.ts +50 -0
  49. package/lib/types/characters/code-panel.d.ts +201 -0
  50. package/lib/types/characters/figure-actions.d.ts +11 -0
  51. package/lib/types/characters/figure-props.d.ts +87 -0
  52. package/lib/types/characters/gaits.d.ts +8 -0
  53. package/lib/types/characters/index.d.ts +4 -0
  54. package/lib/types/characters/species/human-motion.d.ts +45 -0
  55. package/lib/types/characters/species/human.d.ts +2 -0
  56. package/lib/types/characters/stick-figure.d.ts +2 -0
  57. package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
  58. package/lib/types/engine/authoring/index.d.ts +1 -0
  59. package/llms-full.txt +12548 -0
  60. package/llms.txt +57 -0
  61. package/package.json +6 -2
  62. package/skills/tinyfly/SKILL.md +64 -0
  63. package/lib/addons/camera-C7bZOWMB.js +0 -33
@@ -0,0 +1,384 @@
1
+ # Character System Plan — fluid figures, heads, hair and animals
2
+
3
+ **Status:** Planning (no implementation yet)
4
+ **Date:** 2026-10-03
5
+
6
+ This plan covers the work needed to draw everything in six reference model
7
+ sheets with tinyfly, from code, deterministically, in a clean or a
8
+ Pencilmation (pencil) look. It is a living plan: each milestone below ships
9
+ on its own, with a model sheet in `docs/model-sheet/` that proves it.
10
+
11
+ ---
12
+
13
+ ## The reference sheets
14
+
15
+ | Sheet | What it asks for |
16
+ |---|---|
17
+ | **Character model sheet** | Turnaround (bare, clothed), walk and run cycles, action poses, archetypes, clothing, body types, face features |
18
+ | **Animation model sheet, movie ready** | Adds emotion body language, lip-sync mouth shapes, hand gestures, props, everyday acting, two-character interactions, ground poses, scale and age, silhouettes |
19
+ | **Hair and head sheet** | Hair turnaround with head guides (crown, hairline, ear line, neck line); ~30 male, female and kid styles; hair in motion; facial hair, glasses, hats; hair-plus-expression combos; style tokens |
20
+ | **Animal and bird actions sheet** | Quadruped and bird turnarounds, 8 mammals, 8 birds, walk/run cycles, action poses, flight cycle, expressions, beaks, props, scale and age, tokens |
21
+ | **Fluid animals and birds sheet** | A bendable spine (curled sleep, pounce, leap), separate dog and cat gaits, trotting, 14 mammals, 11 birds, ear and tail types, aquatic animals (fish, penguin, turtle, frog, duck), richer tokens |
22
+ | **Fluid human figures sheet** | Construction with chest and waist, character types (adult, kid, teen, elderly), body types, walk/run, actions, emotions, face expressions, lip-sync, hands, hair and identity, everyday acting, props, interactions, ground poses, scale and age, silhouettes, tokens |
23
+
24
+ Plus: **every one of these in a Pencilmation look** (graphite strokes that boil,
25
+ on paper).
26
+
27
+ ### What all six sheets have in common
28
+
29
+ 1. **Turnarounds.** Every character (people, a dog, a bird) is shown front,
30
+ 3/4, side, 3/4 back and back, and hair, faces, clothes and tails have to be
31
+ right from every side.
32
+ 2. **Cycles.** Walk, run, trot, gallop, flap, swim: each 8 frames, looping.
33
+ 3. **Poses as data.** Named poses and expressions that blend.
34
+ 4. **Contact.** Feet on the ground, but also knees, hands, hips, a belly, a
35
+ perch, a water line, a held prop, another character's hand.
36
+ 5. **Variation by tokens.** "API-friendly style tokens": a character is a small
37
+ description (gender, age, build, hair, species, ears, tail, accessories…).
38
+ 6. **Silhouette readability.** Every pose must read as a solid black shape.
39
+
40
+ ---
41
+
42
+ ## Where tinyfly is today (0.76)
43
+
44
+ `@algorisys/tinyfly/characters` has one rig: the stick figure.
45
+
46
+ | Has | Lacks |
47
+ |---|---|
48
+ | Pose as numbers (blend, tracks, `poseTracks`) | Any rig other than the human stick figure |
49
+ | `walkPose`, `talk`, expressions, squash/stretch, rubber limbs | Run, trot, gallop, flap, swim; gaits as data |
50
+ | `turn` 0..1 (front → profile), `facing` mirror | True back views (the face always shows) |
51
+ | `sit`, feet planted on the ground | Contact with anything but the feet; whole-body rotation |
52
+ | `stickFigureJoints()`, `layers` hooks, `shoulderWidth`, `headSize` | Bendable spine/neck/tail chains; limbs reaching a point (IK) |
53
+ | Organic and classic looks, `sketch` (pencil) style | Eye/brow/nose styles, lip-sync shapes, hand shapes, hair, bodies |
54
+
55
+ Its limb angles live in one plane (the figure's front), and depth is a
56
+ hand-written rule (the back arm goes behind the body past `turn` 0.25). That is
57
+ the limit the new sheets hit: a front-plane angle cannot be both "arm out to the
58
+ side" in the front view and "arm hanging straight" in profile, which is why the
59
+ current model sheet has to close the arms up by hand as the figure turns.
60
+
61
+ ---
62
+
63
+ ## Decisions
64
+
65
+ ### 1. A new character system beside the stick figure (v2), not a rewrite of it
66
+
67
+ `stickFigureTarget`, `drawStickFigure`, `StickPose` and friends stay exactly as
68
+ they are (the API the story channel uses, pinned by the golden frames). The new
69
+ system is new API in the same `characters` entry point. Once v2's human matches
70
+ v1's organic look, v1 can become a thin adapter over it (milestone 8), checked
71
+ by the same goldens. No one is forced to migrate.
72
+
73
+ *Why:* v1's angle conventions (one plane, "outward" angles, a sideways walk
74
+ scissor) are baked into existing scenes. Changing what those numbers mean would
75
+ silently break them.
76
+
77
+ ### 2. Skeletons are 2.5D: joints in 3D, drawn as 2D lines
78
+
79
+ Each joint has a position in 3D (x across, y up, z toward the viewer). A
80
+ character turns by rotating about its vertical axis, then is projected flat
81
+ (orthographic). This one choice solves most of the turnaround problems at once:
82
+
83
+ | Problem today | With 2.5D |
84
+ |---|---|
85
+ | Arms spread sideways read as forward/back in profile | Spread is sideways (x); profile sees it edge-on, so it disappears |
86
+ | Back arm needs a hand-written depth rule | Parts are drawn far-to-near by their depth |
87
+ | Feet direction depends on `turn` by a hand-written blend | Feet point forward (+z); the projection turns them |
88
+ | No back view | `turn` 2 is just a 180° rotation; the face is on the far side |
89
+ | A quadruped's front view is a separate drawing | The same skeleton, seen from the front |
90
+
91
+ Lines stay 2D (tapered strokes, pencil strokes); there is no 3D rendering, no
92
+ lighting, no perspective. It is still a stick figure.
93
+
94
+ ### 3. Everything a character is, is data
95
+
96
+ - **Body plan** (one per species): chains of bones, their lengths and widths,
97
+ where they attach, contact points, head shape. A dog, a heron and a person are
98
+ three body plans and no special code.
99
+ - **Pose**: a flat record of numbers (`Record<string, number>`), so any two
100
+ poses blend and every value can be a track, exactly like `StickPose` today.
101
+ - **Gait**: a table of when each foot lands and lifts, plus how the body bobs,
102
+ leans and flexes. Walk, trot, gallop, run, hop and waddle are rows of data.
103
+ - **Character description (tokens)**: plain JSON (`{ species: 'dog', size: 'm',
104
+ ears: 'floppy', tail: 'curled' }`, `{ gender: 'female', age: 'child', hair: {
105
+ tie: 'pigtails' } }`) that resolves to a body plan, proportions, a look and
106
+ layers. Easy to store, sync and have AI generate.
107
+
108
+ ### 4. One pen for everything
109
+
110
+ Every stroke (bodies, hair, clothes, props, animals) goes through one `Pen`
111
+ interface with three looks:
112
+
113
+ - **clean**: tapered filled strokes (today's organic look);
114
+ - **pencil**: Pencilmation; graphite strokes that boil (`sketchPen`), pressure
115
+ taper, overshooting ellipses, optional construction lines and paper;
116
+ - **silhouette**: everything filled in one colour (the readability check).
117
+
118
+ Costume, hair and prop code draws with the pen it is handed, so it matches the
119
+ look automatically. (Today hooks get a pen only when sketched.)
120
+
121
+ ### 5. Deterministic secondary motion
122
+
123
+ Hair, ears and tails that swing are computed, not simulated. A cycle knows its
124
+ own phase, so its follow-through is a function of phase. For timeline motion
125
+ (an `x` track), a helper reads the keyframes (plain JSON) and writes
126
+ follow-through tracks: more JSON, no state between frames. Same time, same
127
+ frame, always.
128
+
129
+ ---
130
+
131
+ ## Architecture
132
+
133
+ All under `src/characters/` (file names hyphenated), exported from
134
+ `@algorisys/tinyfly/characters`. Nothing here touches the DOM or a framework;
135
+ drawing needs only a Canvas 2D context, as today.
136
+
137
+ ```
138
+ src/characters/
139
+ rig/
140
+ body-plan.ts types: BodyPlan, Chain, Bone, Attachment, ContactPoint
141
+ skeleton.ts pose → 3D joint positions (forward kinematics)
142
+ view.ts turn/facing → projection, depth order
143
+ contact.ts rest the lowest contact point on a surface; root rotation
144
+ reach.ts IK: two-bone (analytic) and long chains (fixed-iteration FABRIK)
145
+ joints.ts public joints API (2D points, angles, depth) for any character
146
+ look/
147
+ pen.ts Pen interface; clean, pencil and silhouette pens
148
+ draw-character.ts draw parts far-to-near, run layer hooks per part
149
+ head/
150
+ head.ts head as an ellipsoid; points on it by (around, up)
151
+ face.ts eye, brow, nose, mouth styles; expressions
152
+ visemes.ts lip-sync mouth shapes as numbers that blend
153
+ hair.ts hair built from parts: cap, fringe, length, tie, texture
154
+ accessories.ts glasses, hats, facial hair
155
+ motion/
156
+ gaits.ts gait tables + gaitPose(plan, gait, phase)
157
+ cycles.ts non-leg cycles: flap, glide, swim wave, waddle
158
+ follow-through.ts secondary motion for hair, ears, tails
159
+ species/
160
+ human.ts body plan + poses + gaits for people
161
+ quadrupeds.ts dog, cat, rabbit, horse, cow, goat, deer, fox, bear,
162
+ monkey, elephant, giraffe, pig, sheep
163
+ birds.ts sparrow, pigeon, crow, parrot, owl, duck, eagle, hen,
164
+ flamingo, peacock
165
+ aquatic.ts fish, penguin, turtle, frog
166
+ wardrobe/ ready-made outfits as layer factories
167
+ props/ phone, cup, umbrella, box, rope, sword, backpack, …
168
+ tokens.ts character descriptions → plan, proportions, look, layers
169
+ character.ts public entry: character(), characterTarget(), drawCharacter()
170
+ stick-figure.ts v1, unchanged
171
+ ```
172
+
173
+ ### The data model
174
+
175
+ ```ts
176
+ /** A bone chain: a spine, a neck, a leg, a wing, a tail, a trunk. */
177
+ interface Chain {
178
+ id: string // 'spine', 'neck', 'leg.front.left', 'tail'
179
+ attach: { chain: string; at: number } | 'root' // parent chain and joint index
180
+ bones: { length: number; width: [number, number] }[] // fractions of body size
181
+ side?: 'left' | 'right' // mirrored pairs share one definition
182
+ kind: 'spine' | 'neck' | 'arm' | 'leg' | 'tail' | 'wing' | 'trunk' | 'fin'
183
+ contact?: ('end' | 'joint')[] // which joints can touch a surface
184
+ }
185
+
186
+ interface BodyPlan {
187
+ id: string // 'human', 'dog', 'sparrow'
188
+ chains: Chain[]
189
+ head: HeadSpec // ellipsoid size, muzzle or beak, ears
190
+ rest: Pose // the standing pose
191
+ gaits: Record<string, Gait> // 'walk', 'trot', 'gallop', 'run', 'hop'
192
+ }
193
+
194
+ /** Every value is a number, so poses blend and tracks animate them. */
195
+ type Pose = Record<string, number>
196
+ // e.g. 'spine.bend': 12, 'leg.hind.left.0.swing': -20, 'tail.curl': 0.6,
197
+ // 'turn': 1, 'root.rotate': 0, 'mouth.open': 0.4, 'viseme.O': 1
198
+ ```
199
+
200
+ Angles on a bone are **swing** (forward/back), **spread** (sideways) and, for
201
+ spines, necks, tails and trunks, **bend** spread along the chain, so a cat's
202
+ back curls with one number and a tail curls with another.
203
+
204
+ ### Turnaround
205
+
206
+ `turn` runs 0 → 4: 0 front, 1 profile, 2 back, 3 the other profile, 4 front
207
+ again. `facing` stays for compatibility (it picks the profile side). Animals
208
+ default to `turn: 1` (profile), people to `turn: 0`. The head is an ellipsoid:
209
+ eyes, brows, nose and mouth sit at positions on its surface and are hidden when
210
+ they turn away, so the face slides round and disappears at the back without a
211
+ special back view. Hair parts and the head guides (crown, hairline, ear line,
212
+ neck line) are positions on the same surface.
213
+
214
+ ### Contact and rotation
215
+
216
+ Each body plan lists contact points (feet, knees, hands, hips, elbows, belly,
217
+ head, a bird's feet). After the pose (and any whole-body `root.rotate`) is
218
+ applied, the lowest contact point rests on the **surface**:
219
+
220
+ - `ground`: a line (today's behaviour, generalised);
221
+ - `water`: a line the body floats in, by buoyancy depth per plan (a duck sits
222
+ on it, a fish moves under it);
223
+ - `perch`: a point the feet grip (a branch);
224
+ - `air`: no contact (flying, a jump in mid-air).
225
+
226
+ Lying down, crawling, kneeling, rolling and tripping are then just poses.
227
+
228
+ ### Reaching
229
+
230
+ `reach(plan, pose, chain, target)` solves a limb to touch a point: the two-bone
231
+ case analytically (arms, legs), long chains (trunk, neck, tail) with a fixed
232
+ number of FABRIK iterations, so results never vary. A handshake is one
233
+ character's hand reaching the other's; holding a cup is the hand reaching the
234
+ cup's handle; helping someone up is two reaches.
235
+
236
+ ### Gaits
237
+
238
+ ```ts
239
+ interface Gait {
240
+ feet: { chain: string; offset: number; duty: number }[] // phase offset, fraction on the ground
241
+ stride: number // ground per cycle, fraction of body length
242
+ lift: number // foot height in swing
243
+ bob: number; lean: number; spineFlex: number; headBob: number; tailSwing: number
244
+ flight?: number // fraction with every foot off the ground (run, gallop)
245
+ }
246
+ ```
247
+
248
+ A foot on the ground stays planted (it moves back at exactly the body's speed)
249
+ and a swinging foot arcs forward; the leg reaches its foot by IK. So feet never
250
+ slide, for any body plan and any speed: walk the phase by distance / stride.
251
+ Human walk, run, sneak and tired shuffle; quadruped walk, trot, gallop and
252
+ bound; bird walk and hop; penguin waddle: all rows of data. Flap, glide and swim
253
+ are cycles over wing and spine chains instead of feet.
254
+
255
+ ### Public API (sketch)
256
+
257
+ ```js
258
+ import { character, characterTarget, poseTracks, gaitPose } from '@algorisys/tinyfly/characters'
259
+
260
+ // From tokens: plain JSON, so it can be stored or generated.
261
+ const didi = characterTarget({
262
+ x: 400, y: 900,
263
+ character: {
264
+ gender: 'female', age: 'adult', build: 'average',
265
+ hair: { length: 'long', tie: 'bun', texture: 'straight' },
266
+ outfit: { top: 'sari', colors: { sari: '#1f9d55', pallu: '#f4c430' } },
267
+ accessories: ['bindi', 'bangles'],
268
+ },
269
+ look: 'pencil',
270
+ })
271
+
272
+ const bruno = characterTarget({
273
+ x: 900, y: 900,
274
+ character: { species: 'dog', size: 'm', ears: 'floppy', tail: 'curled', accessories: ['collar'] },
275
+ })
276
+
277
+ // Poses, gaits and visemes are numbers, so the timeline drives them.
278
+ tracks: [
279
+ ...poseTracks('bruno', [{ time: 0, pose: 'sit' }, { time: 800, pose: 'stand' }]),
280
+ { id: 'trot', target: 'bruno', property: 'gait.trot', keyframes: [/* phase */] },
281
+ { id: 'say', target: 'didi', property: 'viseme', keyframes: [/* from narration */] },
282
+ ]
283
+ ```
284
+
285
+ Joints, layers and `…At(target, frame, id)` work for every character, as
286
+ `stickFigureJoints`, `layers` and `stickFigureAt` do for v1.
287
+
288
+ ---
289
+
290
+ ## Coverage: every section of the six sheets
291
+
292
+ | Area | Sections | Milestone |
293
+ |---|---|---|
294
+ | Turnaround (people, animals, birds), construction points | all six sheets, §1 | 1 (people), 5–6 (animals) |
295
+ | Pencilmation look, silhouettes | all sheets | 1 |
296
+ | Walk, run, sneak, tired (people) | char §2–3, fluid human §4–5 | 2 |
297
+ | Action, emotion, everyday acting, ground poses | movie §4, §9, §13, §15; fluid human §6–7, §12, §15 | 2 |
298
+ | Props, two-character interactions | movie §12, §14; fluid human §13–14 | 2 |
299
+ | Face expressions, eye/brow/nose/mouth styles | char §8; movie §8; fluid human §8 | 3 |
300
+ | Lip-sync mouth shapes | movie §10; fluid human §9 | 3 |
301
+ | Hair styles (male, female, kids), hair turnaround and motion | hair §1–5, §8; fluid human §11 | 3 |
302
+ | Facial hair, glasses, hats | hair §6 | 3 |
303
+ | Hand gestures | movie §11; fluid human §10 | 4 |
304
+ | Archetypes, body types, character types, scale and age | char §5, §7; movie §16; fluid human §2–3, §16 | 4 |
305
+ | Clothing | char §6; fluid human §1 (clothed) | 4 |
306
+ | Style tokens (people) | hair §9; fluid human §18 | 4 |
307
+ | Mammals, gaits (walk, trot, gallop; dog vs cat), poses, ears, tails, expressions | animal §1–4, §9, §12; fluid animal §1–5, §10, §13 | 5 |
308
+ | Birds, flight cycle, beaks, perching | animal §5–8, §10; fluid animal §6–9, §11 | 6 |
309
+ | Aquatic (fish, penguin, turtle, frog, duck) | fluid animal §15 | 6 |
310
+ | Animal props, scale and age, tokens, silhouettes | animal §11–14; fluid animal §12, §14, §16–17 | 5–6 |
311
+
312
+ ---
313
+
314
+ ## Milestones
315
+
316
+ Each is one minor release, and each ends with its model sheet(s) drawn by code
317
+ in `examples/headless-video/` and kept in `docs/model-sheet/`, in both the clean
318
+ and the pencil look.
319
+
320
+ | # | Release | Contents | Model sheet |
321
+ |---|---|---|---|
322
+ | 1 | **Rig core** | Body plans and chains; 2.5D skeleton and view (`turn` 0–4, depth order); contact with surfaces and `root.rotate`; IK (`reach`); the `Pen` and the clean, pencil and silhouette looks; joints and layers per part; the human body plan matching v1's organic look | Human construction and turnaround, bare and clothed, clean and pencil |
323
+ | 2 | **People in motion** | Gait engine; human walk, run, sneak, tired; action, emotion, everyday and ground poses; interactions via IK; first props (phone, cup, umbrella, box, rope, laptop, backpack, sword) | Walk and run cycles, actions, emotions, everyday acting, props, interactions, ground poses, silhouettes |
324
+ | 3 | **Heads, faces and hair** | Head ellipsoid with guides; eye, brow and nose styles; mouth shapes and lip-sync (`viseme`, narration-driven); hair from parts, ~30 styles for men, women and kids; facial hair, glasses, hats; hair follow-through | The hair and head sheet; face and lip-sync sections |
325
+ | 4 | **Hands, bodies and wardrobe** | Hand shapes (built early: [cartoon-hands.md](cartoon-hands.md)); proportions and builds (slim, athletic, broad, stocky, tall); ages (toddler to elderly, with a stoop and cane); wardrobe (t-shirt, hoodie, dress, skirt, jacket, shorts, cap, office wear, kurta, sari); people tokens | Character types, body types, clothing, scale and age, tokens |
326
+ | 5 | **Four-legged animals** | Quadruped plans; 14 mammals; walk, trot, gallop, bound with spine flex (dog and cat tuned differently); poses (sit, lie, curl, pounce, leap, sniff, look back, wag); ear and tail types; mammal head expressions; animal props and tokens | Quadruped construction, types, cycles, poses, expressions, ears and tails |
327
+ | 6 | **Birds and water** | Bird plan; 10 birds; flap, glide, hop, takeoff, landing, perching; beaks and crests; water surface; fish, penguin, turtle, frog, duck | Bird sheet; aquatic section; animal silhouettes |
328
+ | 7 | **Editor support** (optional) | Character picker from tokens, pose and gait tracks in the timeline | — |
329
+ | 8 | **v1 on v2** (optional) | `drawStickFigure` as an adapter over the human plan, still matching every golden frame | — |
330
+
331
+ Milestones 1 and 2 are the foundation; 3–6 can then go in any order (for
332
+ dialogue-heavy story channels, 3 first).
333
+
334
+ ---
335
+
336
+ ## Testing
337
+
338
+ - **Joints match drawing**, for every body plan and look, as today's joints
339
+ tests do for the stick figure.
340
+ - **Turnaround invariants**: `turn` 2 is `turn` 0 seen from behind (mirrored,
341
+ face hidden); `turn` 1 and 3 are mirror images.
342
+ - **Planted feet**: during a gait's stance phase a foot's ground position is
343
+ constant (within 0.5 px) at every phase, for every gait and plan.
344
+ - **Contact**: the lowest contact point is on the surface for every pose in
345
+ every pose library.
346
+ - **IK**: `reach` lands within 0.5 px when the target is in reach, and points
347
+ straight at it when it is not.
348
+ - **Determinism**: every frame of every model sheet renders identically twice,
349
+ and the sheets are golden PNGs.
350
+ - **v1 untouched**: the existing golden frames and tests keep passing.
351
+
352
+ ---
353
+
354
+ ## Review answers (2026-10-03)
355
+
356
+ | # | Question | Answer |
357
+ |---|---|---|
358
+ | 1 | v2 beside v1, or replace? | **A new API beside v1** (option A): `character()`, `characterTarget()`, `drawCharacter()` in `@algorisys/tinyfly/characters`; v1 frozen (bug fixes only) until milestone 8 rebuilds it on v2; each milestone is a minor release (milestone 1 is 0.77) |
359
+ | 2 | Skeletons with depth? | **Yes**, and the same skeletons must also draw traditional Pencilmation stick figures and bare figures, not only fluid dressed ones |
360
+ | 3 | Default line weight | **The bold viral look** (about 4–5% of the height, a bigger head), for now |
361
+ | 4 | Pencilmation scope | **All of it**: boiling strokes, construction lines, pressure variation and rubbed-out lines |
362
+ | 5 | Order after milestone 2 | **Heads and lip-sync first** |
363
+ | 6 | Editor support | **Wanted** |
364
+
365
+ What changes in the plan:
366
+
367
+ - **Figure styles (milestone 1).** Besides the look (clean, pencil, silhouette),
368
+ a character has a figure style, all from the same skeleton:
369
+ - **stick**: the traditional Pencilmation figure, single lines and a circle head;
370
+ - **bare**: the fluid body, tapered limbs, hands and feet, no clothes;
371
+ - **dressed**: bare plus wardrobe, hair and accessories.
372
+ - **Bold by default.** The default proportions and line weight are the bold
373
+ look; a thin preset matches the reference sheets.
374
+ - **Pencil look (milestone 1)** adds construction lines (the skeleton's guide
375
+ shapes under the final line), pressure variation along each stroke, and
376
+ rubbed-out lines (faint erased strokes, using the existing erase helpers),
377
+ all deterministic.
378
+ - **Order:** 1 rig core, 2 people in motion, 3 heads, faces, lip-sync and hair,
379
+ then 4 hands, bodies and wardrobe, 5 four-legged animals, 6 birds and water.
380
+ - **Editor support is in scope.** Rather than one milestone at the end, each
381
+ milestone adds its part to the editor (a character element from tokens in 1,
382
+ pose and gait tracks in 2, expression and viseme tracks in 3, and so on).
383
+ Milestone 7 becomes the polish pass: a character library panel and pose
384
+ presets.