@algorisys/tinyfly 0.99.0 → 0.101.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 (77) hide show
  1. package/README.md +9 -9
  2. package/bin/tinyfly.mjs +7 -3
  3. package/docs/acting.md +10 -6
  4. package/docs/character-appearance.md +71 -7
  5. package/docs/editor-guide.md +38 -3
  6. package/docs/examples.md +1 -1
  7. package/docs/getting-started.md +1 -1
  8. package/docs/gsap-compat.md +1 -1
  9. package/docs/llm-guide.md +34 -9
  10. package/docs/maps.md +2 -2
  11. package/docs/props.md +61 -1
  12. package/docs/scene-3d.md +23 -4
  13. package/docs/teaching.md +1 -1
  14. package/docs/video-rendering.md +154 -0
  15. package/lib/addons/adapters.js +387 -333
  16. package/lib/addons/characters.js +4795 -3752
  17. package/lib/addons/load-scene-oWNsYYC1.js +372 -0
  18. package/lib/addons/scene-3d-webgl.js +1 -1
  19. package/lib/addons/scene-3d.js +323 -277
  20. package/lib/addons/shading-0lPgnXmD.js +96 -0
  21. package/lib/browser/tinyfly-scene-3d.iife.js +2 -2
  22. package/lib/browser/tinyfly.iife.js +14 -14
  23. package/lib/browser/tinyfly.js +7294 -5893
  24. package/lib/browser/tinyfly.umd.js +14 -14
  25. package/lib/engine/tinyfly-engine.js +1389 -1031
  26. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  27. package/lib/headless/headless.js +39 -0
  28. package/lib/types/adapters/canvas/impossible.d.ts +15 -0
  29. package/lib/types/adapters/canvas/index.d.ts +3 -0
  30. package/lib/types/adapters/canvas/nested-zoom.d.ts +40 -0
  31. package/lib/types/adapters/canvas/zoom-blur.d.ts +49 -0
  32. package/lib/types/characters/acting/character-script.d.ts +14 -2
  33. package/lib/types/characters/acting/script.d.ts +9 -0
  34. package/lib/types/characters/capabilities.d.ts +2 -0
  35. package/lib/types/characters/character.d.ts +28 -1
  36. package/lib/types/characters/hair-follow.d.ts +12 -6
  37. package/lib/types/characters/hands/held-items.d.ts +6 -2
  38. package/lib/types/characters/head/face.d.ts +23 -1
  39. package/lib/types/characters/index.d.ts +3 -2
  40. package/lib/types/characters/interactions.d.ts +60 -0
  41. package/lib/types/characters/props/families/animals.d.ts +6 -0
  42. package/lib/types/characters/props/families/birds.d.ts +16 -0
  43. package/lib/types/characters/props/families/furniture.d.ts +102 -0
  44. package/lib/types/characters/props/index.d.ts +1 -0
  45. package/lib/types/characters/props/presets.d.ts +15 -2
  46. package/lib/types/characters/props/ride-3d.d.ts +4 -1
  47. package/lib/types/characters/scenery.d.ts +126 -0
  48. package/lib/types/characters/species/human-motion.d.ts +17 -0
  49. package/lib/types/characters/species/human.d.ts +6 -0
  50. package/lib/types/characters/wardrobe/basic-outfit.d.ts +16 -5
  51. package/lib/types/engine/authoring/beat-loop.d.ts +46 -0
  52. package/lib/types/engine/authoring/curve.d.ts +26 -0
  53. package/lib/types/engine/authoring/index.d.ts +3 -0
  54. package/lib/types/engine/authoring/periodic.d.ts +89 -0
  55. package/lib/types/engine/path/goo.d.ts +103 -0
  56. package/lib/types/engine/path/impossible.d.ts +92 -0
  57. package/lib/types/engine/path/index.d.ts +6 -0
  58. package/lib/types/engine/path/similarity.d.ts +48 -0
  59. package/lib/types/headless/index.d.ts +1 -0
  60. package/lib/types/headless/loop-audio.d.ts +21 -0
  61. package/lib/types/headless/node-audio.d.ts +20 -0
  62. package/lib/types/headless/video-scene.d.ts +9 -0
  63. package/lib/types/scene-3d/camera.d.ts +11 -2
  64. package/lib/types/scene-3d/geometry/mesh.d.ts +2 -0
  65. package/lib/types/scene-3d/geometry/primitives.d.ts +7 -0
  66. package/lib/types/scene-3d/impossible-3d.d.ts +29 -0
  67. package/lib/types/scene-3d/index.d.ts +4 -3
  68. package/lib/types/scene-3d/resolve-scene.d.ts +13 -1
  69. package/lib/types/scene-3d/scene-3d-adapter.d.ts +2 -0
  70. package/lib/types/scene-3d/scene-types.d.ts +29 -4
  71. package/lib/types/scene-3d/shading.d.ts +2 -0
  72. package/llms-full.txt +423 -47
  73. package/llms.txt +29 -29
  74. package/package.json +2 -2
  75. package/skills/tinyfly/SKILL.md +20 -6
  76. package/lib/addons/load-scene-CQvcFWGJ.js +0 -331
  77. package/lib/addons/shading-o5T_v9DT.js +0 -89
package/docs/scene-3d.md CHANGED
@@ -57,7 +57,7 @@ number or three), `parent` (an earlier object it moves with), `visible`, and
57
57
  |---|---|
58
58
  | `group` | (just a transform: move several objects together, or carry a camera) |
59
59
  | `mesh` | `geometry`, `material` (a key of `materials`) |
60
- | `camera` | `projection: 'perspective'` with `fov` (vertical, degrees), or `'orthographic'` with `height` (metres); `near`, `far`; optional `lookAt: [x, y, z]` |
60
+ | `camera` | `projection: 'perspective'` with `fov` (vertical, degrees), or `'orthographic'` with `height` (metres); `near`, `far`; optional `lookAt: [x, y, z]`, `up` (which way is up for it, default +y) and `roll` (degrees about the view axis, clockwise on screen) |
61
61
  | `light` | `light: 'ambient' \| 'directional' \| 'point' \| 'spot'`, `color`, `intensity` (1 is full light); directional and spot shine from their position toward `target` (default the origin); point and spot fade to nothing at `range`; spot's cone is `angle` (half-angle, default 30°) |
62
62
 
63
63
  **Geometry**: `box` (`size: [w, h, d]`), `sphere` (`radius`, `segments`),
@@ -67,7 +67,11 @@ facing up, `segments` per side), and `extrude`: any SVG `path` made solid,
67
67
  `depth` metres thick and scaled to `width` metres wide (default 1), with
68
68
  `curveSegments` points per curve (default 12). Subpaths inside others are
69
69
  holes (an "o", a ring); outlines inside holes are solid again. The path's y
70
- (down) is flipped to 3D's y (up). All centred on the origin.
70
+ (down) is flipped to 3D's y (up). All centred on the origin. A raw `mesh`
71
+ takes `positions` (flat x, y, z runs), `indices` (triples, counter-clockwise
72
+ from outside), optional `normals` per vertex (flat ones are computed) and
73
+ `colors`, one per face or one per vertex (blended per face), over the
74
+ material's colour: warped beams, terrain, anything exported from a tool.
71
75
 
72
76
  ```js
73
77
  { id: 'star', kind: 'mesh', material: 'gold',
@@ -93,7 +97,9 @@ milestone); the stylized renderers ignore them, so one material serves both.
93
97
 
94
98
  The scene can have `background` and `fog: { color, near, far }` (metres from
95
99
  the camera). A scene with no lights gets a soft default (ambient plus a key
96
- light from upper right).
100
+ light from upper right). Outlines fade into the fog too. `nearFade: { from, to }` fades geometry
101
+ nearer the camera than `to` metres, gone at `from`, so a dive passes through
102
+ things as if they were glass (also an option of `resolveScene3D`).
97
103
 
98
104
  ## Animating it
99
105
 
@@ -108,8 +114,9 @@ live in the same timeline as everything else.
108
114
  | `visible` | any object | 0 or 1 (children hide with their parent) |
109
115
  | `opacity` | meshes | 0..1, times the material's |
110
116
  | `color` | meshes, lights | a colour, over the material's or light's |
117
+ | `outlineWidth`, `outlineColor` | meshes | px and a colour, over the material's outline (0 switches it off) |
111
118
  | `intensity`, `target` | lights | |
112
- | `fov` / `height`, `lookAt` | cameras | |
119
+ | `fov` / `height`, `lookAt`, `roll` | cameras | |
113
120
  | `color`, `width`, `opacity` | lines, trails | |
114
121
  | `length` | trails | ms |
115
122
  | `activeCamera` | the scene, target `<sceneId>` | a camera's id: **a cut is one keyframe** |
@@ -394,6 +401,18 @@ objects, prepares them once, and each frame returns meshes (shaded and sorted
394
401
  with the scene's) and drawables (drawn whole at their depth). Pass it in
395
402
  `loadScene3D(scene, { kinds })`.
396
403
 
404
+ ## Impossible objects
405
+
406
+ `penroseTriangle3D({ length, thickness, material, id, position, distance })`
407
+ returns three box objects (beams along x, up y and along z, each starting
408
+ where the last ends) and an orthographic camera on the (1, 1, 1) diagonal
409
+ from which the third beam's end meets the first's start on screen. Add the
410
+ objects with a material of that name and the camera, or place your own camera
411
+ along the diagonal; from anywhere else the loop is open. The third corner
412
+ shows the beams' ends as a real sculpture's does. For a clean drawing see the
413
+ 2D `penroseTriangle` and `penroseStairs` in
414
+ [Video from code](video-rendering.md#dives-and-impossible-objects).
415
+
397
416
  ## The WebGL2 renderer
398
417
 
399
418
  `@algorisys/tinyfly/scene-3d/webgl` (`tinyfly-scene-3d-webgl.iife.js` for
package/docs/teaching.md CHANGED
@@ -25,7 +25,7 @@ path for all of that:
25
25
  </figure>
26
26
 
27
27
  <!-- once, anywhere on the page (a site-wide footer is fine) -->
28
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.99.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
28
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
29
29
  ```
30
30
 
31
31
  Every `[data-tinyfly-embed]` mounts when the page is ready, with no per-post
@@ -557,6 +557,141 @@ The numbers are PSNR (higher is more alike; fast or trembling motion makes
557
557
  every step lower). From code: `checkLoop(scene)` returns the same report, and
558
558
  `psnr(a, b)` / `loopReport(frames)` work on any RGBA frames.
559
559
 
560
+ ### A scene that loops
561
+
562
+ Say so with `loop: true`: the duration is the period. `tinyfly video` then
563
+ runs the loop check before it encodes anything and stops (exit 1) if the loop
564
+ does not close; every frame carries `period`, which the periodic helpers and
565
+ 3D trails without a `period` of their own use.
566
+
567
+ ```js
568
+ import { wobble, loopNoise, loopEase } from '@algorisys/tinyfly'
569
+
570
+ export default {
571
+ width: 1280, height: 720, duration: 4000, loop: true,
572
+ draw(ctx, frame) {
573
+ const sway = wobble(frame.time, { period: frame.period, cycles: 2, amplitude: 12 }) // a sine, two whole cycles
574
+ const drift = loopNoise(frame.time, { period: frame.period, seed: 'tree' }) * 30 // smooth noise round a circle
575
+ const breathe = loopEase(frame.time, { period: frame.period, easing: 'ease-in-out' }) // 0 → 1 → 0, eased
576
+ },
577
+ }
578
+ ```
579
+
580
+ | Helper | Repeats exactly every `period` |
581
+ |---|---|
582
+ | `wobble(t, { period, cycles, amplitude, phase, shape })` | A sine (or `triangle`, `square`) with a whole number of cycles |
583
+ | `loopEase(t, { period, cycles, easing, phase })` | 0 → 1 → 0, the easing on the way up and mirrored down |
584
+ | `loopNoise(t, { period, seed, cycles, octaves, phase })` | Seeded value noise read round a circle, about −1..1: the end meets the start |
585
+ | `torusNoise(t, along, { period, periodAlong, seed, … })` | Noise periodic in time and along a length (ripples, grass, a flag) |
586
+ | `phaseOf(t, period, cycles)`, `pingPong(u)` | The building blocks: where in the cycle, and there-and-back |
587
+
588
+ Each is a pure function of time, so frames render in any order and the loop
589
+ check reports "closes", not "seamless".
590
+
591
+ ### Sound for a loop
592
+
593
+ A loop's sound must come round with its picture. `cutAudioToLoop(file, {
594
+ output, period, crossfade, fadeIn, fadeOut })` (Node) decodes a drone, a
595
+ riser or a beat, trims it to the period with its end blended into its start
596
+ (tiling it first if it is shorter) and writes the WAV to pass as the scene's
597
+ `audio`; `loopSamples` is the pure step on samples. For motion on the beat,
598
+ `loopBeats(period, grid)` cuts a tempo to the loop (the nearest whole number
599
+ of beats, the bpm nudged to fit exactly), `beatPulse(time, grid, { attack,
600
+ decay, barAccent })` spikes to 1 on every beat and decays, and
601
+ `beatPeriod(grid, beats)` is the length of so many beats. For motion that
602
+ follows the sound itself, `audioEnvelope(samples, sampleRate, { fps,
603
+ smoothing })` gives a level per frame (rising at once, letting go slowly,
604
+ loudest 1) and `envelopeAt(levels, time, fps, period)` reads it at any time,
605
+ wrapped for the loop:
606
+
607
+ ```js
608
+ import { decodeAudio, cutAudioToLoop } from '@algorisys/tinyfly/headless'
609
+ import { audioEnvelope, envelopeAt, loopBeats, beatPulse, detectTempo } from '@algorisys/tinyfly'
610
+
611
+ const PERIOD = 4000
612
+ const audio = await cutAudioToLoop('drone.wav', { output: 'build/drone-loop.wav', period: PERIOD, baseDir: here })
613
+ const samples = await decodeAudio(audio, { sampleRate: 48000 })
614
+ const levels = audioEnvelope(samples, 48000, { fps: 30 })
615
+ const { grid } = loopBeats(PERIOD, detectTempo(samples, 48000))
616
+ export default {
617
+ width: 1280, height: 720, duration: PERIOD, loop: true, audio,
618
+ draw(ctx, frame) {
619
+ const level = envelopeAt(levels, frame.time, 30, frame.period) // 0..1 with the sound
620
+ const pulse = beatPulse(frame.time, grid) // 1 on each beat, decaying
621
+ },
622
+ }
623
+ ```
624
+
625
+ ### Nested zooms (Droste)
626
+
627
+ A picture inside itself, the camera diving in: after one step every level is
628
+ where the next one was, so a video one step long loops. `similarityAbout(
629
+ scale, turn, centre)` is the step (a scale, a turn and a move as one value;
630
+ `powSimilarity(step, k)` is a fraction of it, `composeSimilarity` chains
631
+ them, `similarityFixedPoint` is the centre everything converges on), and
632
+ `nestedZoom` draws the levels:
633
+
634
+ ```js
635
+ import { similarityAbout } from '@algorisys/tinyfly'
636
+ import { nestedZoom } from '@algorisys/tinyfly/adapters'
637
+
638
+ const step = similarityAbout(0.5, 12, { x: 640, y: 360 })
639
+ export default {
640
+ width: 1280, height: 720, duration: 3000, loop: true, background: '#05030c',
641
+ draw(ctx, frame) {
642
+ nestedZoom(ctx, {
643
+ step,
644
+ phase: frame.time / frame.period, // 0..1: how far into one step
645
+ extent: 1600, // how far a level's drawing reaches at level 0, px
646
+ coversAbove: 1.1, // a level this big fills the frame: nothing behind it is drawn
647
+ draw(ctx, level, scale) { drawFrame(ctx, level) }, // in level-0 coordinates
648
+ })
649
+ },
650
+ }
651
+ ```
652
+
653
+ Levels smaller than `minSize` px (default 1) are skipped, and so is
654
+ everything behind a level at or above `coversAbove`, so a zoom of twenty
655
+ levels draws the five or six that show. `draw` gets the level number (0 is
656
+ the one at natural size at phase 0, 1 the one inside it) and its screen
657
+ scale, to keep line widths readable; colour or detail that should travel with
658
+ the zoom is a function of `level - phase`. `examples/headless-video/nested-zoom.mjs`
659
+ is a looping neon zoom built this way; `nestedZoomTransform(step, level,
660
+ phase)` gives a level's similarity for drawing it some other way.
661
+
662
+ A Droste *face*: `drawCharacterHead` draws a character's head big, and its
663
+ `face.inPupil` hook draws inside each pupil, clipped to it, so the head can
664
+ hold itself (see [Close-ups](character-appearance.md#close-ups)). Anything
665
+ that should change with a level's size on screen rather than with time (the
666
+ eyes opening as a head grows, a colour cooling with depth) is a `curve`:
667
+ `curve([{ at: 20, value: 0 }, { at: 300, value: 1, easing: 'ease-out' }])(radius)`
668
+ reads keyframes and easings at any input, holding beyond its ends.
669
+
670
+ ### Dives and impossible objects
671
+
672
+ Two post-effects for a dive, both deterministic. `applyZoomBlur(ctx, { centre,
673
+ strength, samples, blend })` streaks the finished frame out from a point (a
674
+ fixed set of scaled copies, averaged, or added with `blend: 'add'` for neon);
675
+ `drawDiveLines(ctx, { centre, count, inner, outer, length, phase, seed, color,
676
+ blend })` streams seeded lines past the camera, and `phase: phaseOf(time,
677
+ period)` moves them one line along per loop so they repeat exactly.
678
+
679
+ The impossible objects are built the way the sculptures are: real boxes that
680
+ line up from one viewpoint. `penroseTriangle({ size, thickness, centre, scale })`
681
+ and `penroseStairs({ steps, tread, rise, width, base, centre, scale })` give
682
+ boxes and their visible faces in drawing order for the isometric view (along
683
+ the (1, 1, 1) diagonal, z up); `drawIsometricFaces(ctx, faces, { top, left,
684
+ right, fill, outline })` fills them. The triangle's third beam ends one
685
+ diagonal from where the first began, so on screen the loop closes (the first
686
+ beam is drawn again over the third's end); the stairs climb all the way round
687
+ and the last step meets the first. `projectIsometric`, `isometricBoxFaces`
688
+ and `isometricFaces` are the building blocks for your own. In a 3D scene,
689
+ `penroseTriangle3D({ length, thickness, material })` returns the three beams
690
+ and an orthographic camera down the diagonal: from it the loop closes, from
691
+ anywhere else it is three beams (its third corner shows the beams' ends,
692
+ as a real sculpture's does; a `rotateY` track on a group round it breaks and
693
+ remakes the illusion).
694
+
560
695
  ## Bloom
561
696
 
562
697
  `bloom: true` (or options) adds a glow around everything bright, after each
@@ -633,6 +768,25 @@ beads where segments overlap and no seams between them. `ribbon(points)` and
633
768
  `line` and `trail` objects, sorted by depth among the meshes (see
634
769
  [3D Scenes](scene-3d.md#lines-and-trails)).
635
770
 
771
+ ## Satisfying matter
772
+
773
+ Goo as geometry, every shape a pure function of its inputs:
774
+
775
+ | Helper | Gives |
776
+ |---|---|
777
+ | `metaballContours(balls, { threshold, cell, smooth })` | The outlines of balls (`{ x, y, r }`) that merge through necks as they near and split as they part, as closed polygons; `metaballField` is the field itself |
778
+ | `dripPath({ x, y, length, width, progress })` | A drip under a surface: a neck thinning to a thread and a head swelling as `progress` runs 0 → 1 |
779
+ | `bubblePath({ x, y, r, grow, time, period, wobble })` | A bubble growing from nothing (with a little swell on the way) whose surface quivers with the time; with `period` the quiver repeats exactly |
780
+ | `bubblePop({ x, y, r, progress, pieces })` | The pop: arcs of the rim flying out and shrinking, gone at 1 |
781
+ | `squashStretch(amount, { keep })`, `scalePoints(points, scale, about)` | Stretch taller (or squash, negative) with the width giving way so the area (or the `volume`) stays; apply it about the point a blob lands on |
782
+
783
+ ```js
784
+ draw(ctx, frame) {
785
+ const balls = [{ x: 400, y: 300, r: 60 }, { x: 400 + wobble(frame.time, { period: frame.period, amplitude: 90 }), y: 300, r: 40 }]
786
+ for (const loop of metaballContours(balls, { cell: 3 })) fillPolygon(ctx, loop, '#b6ff3b')
787
+ }
788
+ ```
789
+
636
790
  ## Camera, overlay and drawing on twos
637
791
 
638
792
  - `camera: true` sees the scene through the tracks of the `Camera` target: