@algorisys/tinyfly 0.92.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.
- 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 +466 -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 +123 -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 +2694 -1809
- package/lib/addons/target-properties-BtN9skb-.js +142 -0
- package/lib/browser/tinyfly.iife.js +9 -4
- package/lib/browser/tinyfly.js +6498 -5483
- 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 +95 -0
- package/lib/types/characters/acting/hand-path.d.ts +32 -0
- package/lib/types/characters/acting/index.d.ts +2 -0
- package/lib/types/characters/acting/script.d.ts +66 -7
- package/lib/types/characters/capabilities.d.ts +50 -0
- package/lib/types/characters/code-panel.d.ts +201 -0
- package/lib/types/characters/figure-actions.d.ts +11 -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 +2 -0
- 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 +12548 -0
- package/llms.txt +57 -0
- package/package.json +6 -2
- package/skills/tinyfly/SKILL.md +64 -0
- package/lib/addons/camera-C7bZOWMB.js +0 -33
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Building Animations with an LLM
|
|
2
|
+
|
|
3
|
+
tinyfly is built to be written by code, and that includes code a language
|
|
4
|
+
model writes. This page is for you, setting up an assistant (Claude Code,
|
|
5
|
+
Cursor, Copilot, a chat window), and for the assistant itself.
|
|
6
|
+
|
|
7
|
+
The short version: **read the catalog, write, check, look.**
|
|
8
|
+
|
|
9
|
+
## 1. Read the catalog first
|
|
10
|
+
|
|
11
|
+
Everything tinyfly can do, read from the library itself:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npx @algorisys/tinyfly capabilities # markdown
|
|
15
|
+
npx @algorisys/tinyfly capabilities --json # the same as data
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
It lists the easings, track kinds, every property each canvas shape can
|
|
19
|
+
animate (with units and ranges), the stick figure's joints, poses,
|
|
20
|
+
expressions, gags, gaits, beat actions, dances, flips and hand shapes, the v2
|
|
21
|
+
character's poses, the code panel's languages, anchors and edits, camera
|
|
22
|
+
shots and the teaching helpers. It is generated from the code, so it can't
|
|
23
|
+
fall behind: **a name in it is accepted, and a name not in it is rejected.**
|
|
24
|
+
It is also the last part of `llms-full.txt`.
|
|
25
|
+
|
|
26
|
+
From code, the same catalog is `capabilities()` (and `capabilitiesMarkdown()`)
|
|
27
|
+
in `@algorisys/tinyfly/characters`.
|
|
28
|
+
|
|
29
|
+
## 2. Ask a target what it can do
|
|
30
|
+
|
|
31
|
+
```js
|
|
32
|
+
import { stickFigureTarget, codePanel, describeTarget } from '@algorisys/tinyfly/characters'
|
|
33
|
+
|
|
34
|
+
describeTarget({ type: 'rect', x: 0, y: 0, width: 80, height: 40 })
|
|
35
|
+
// { type: 'rect', properties: [{ name: 'opacity', unit: '0..1', min: 0, max: 1, value: … }, …] }
|
|
36
|
+
|
|
37
|
+
describeTarget(stickFigureTarget({ x: 200, y: 300 }))
|
|
38
|
+
// { kind: 'stick figure', properties: [{ name: 'rightShoulder', unit: 'degrees', description: '…', value: 18 }, …],
|
|
39
|
+
// actions: { walk: '…', grab: 'Steps to where its arm reaches the target …', … } }
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Custom targets can describe themselves with `about` (`kind`, `summary`,
|
|
43
|
+
`props`, `actions`); the stick figure and the code panel do.
|
|
44
|
+
`animatableProperties(target)` is just the names.
|
|
45
|
+
|
|
46
|
+
## 3. Check before you play
|
|
47
|
+
|
|
48
|
+
Wrong names fail loudly, with the name that was probably meant:
|
|
49
|
+
|
|
50
|
+
```text
|
|
51
|
+
scriptTracks: 2 problem(s) in the beats:
|
|
52
|
+
beat 0: Unknown action "jumpp": did you mean "jump"? Known: walk, bouncy, …
|
|
53
|
+
beat 1: Unknown beat field "expression": did you mean "mood"? Known: do, at, for, …
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
- **Beat scripts**: `scriptTracks()` throws on errors. `checkBeats(beats)`
|
|
57
|
+
returns errors and warnings without throwing, and from the command line:
|
|
58
|
+
`npx @algorisys/tinyfly check beats.json`.
|
|
59
|
+
- **Tracks**: `checkTracks(tracks, targets)` finds tracks aimed at targets
|
|
60
|
+
that aren't there, properties a target can't animate (`rotation` → `rotate`),
|
|
61
|
+
keys out of time order, values of the wrong kind and values out of range.
|
|
62
|
+
- **Code panels** reject unknown languages and remove styles. `token()` throws
|
|
63
|
+
when a line doesn't have the word.
|
|
64
|
+
- **Teaching timelines**: `npx @algorisys/tinyfly validate timeline.json --markup figure.svg`.
|
|
65
|
+
|
|
66
|
+
## 4. Look at it
|
|
67
|
+
|
|
68
|
+
An animation that compiles can still look wrong. Render frames and look at
|
|
69
|
+
them before calling it done:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
npx @algorisys/tinyfly video scene.mjs --stills frames --times 0,800,1600,2400
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
A model that can read images should look at the PNGs: is the hand on the
|
|
76
|
+
word, does the figure stand on the line, does the text land where it should?
|
|
77
|
+
Fix, render again.
|
|
78
|
+
|
|
79
|
+
## The rules that trip models up
|
|
80
|
+
|
|
81
|
+
- **Milliseconds in JSON, seconds in the GSAP-style API.** Timeline keyframes
|
|
82
|
+
and beats are ms; `live.to(el, { duration: 1 })` is seconds.
|
|
83
|
+
- **Canvas `x`/`y` tracks are offsets** from where the target was placed, not
|
|
84
|
+
positions. A beat script's `to` is a scene x, and its tracks are offsets
|
|
85
|
+
from `from` (and `ground` for y).
|
|
86
|
+
- **Scene y grows downward.** A floor higher up the screen has a smaller y.
|
|
87
|
+
- **Angles are degrees.** Stick-figure arms: 0 hangs down, 90 straight out,
|
|
88
|
+
180 straight up; in profile the left arm's forward is negative.
|
|
89
|
+
- **Aim beats at anchors, not guessed numbers**: `code.line(7)`,
|
|
90
|
+
`code.token(3, 'var')`, `code.spot(2, 8, 4)`, `piece.home`.
|
|
91
|
+
- **Key reactions to contact times.** Beats that touch something report
|
|
92
|
+
`result.beats[i].contact` (and `release`): wipe the line, fling the word or
|
|
93
|
+
type the text at those times.
|
|
94
|
+
- **Record panel edits before `code.ride()`**, which reads the moves they make.
|
|
95
|
+
|
|
96
|
+
## Set up your assistant
|
|
97
|
+
|
|
98
|
+
The npm package ships everything an agent needs, at the version installed:
|
|
99
|
+
|
|
100
|
+
```text
|
|
101
|
+
node_modules/@algorisys/tinyfly/
|
|
102
|
+
llms.txt the index
|
|
103
|
+
llms-full.txt every doc, the course and the capability catalog
|
|
104
|
+
docs/*.md the docs
|
|
105
|
+
skills/tinyfly/SKILL.md
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
**Claude Code**: copy the skill into your project and it loads when you ask
|
|
109
|
+
for an animation:
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
mkdir -p .claude/skills && cp -r node_modules/@algorisys/tinyfly/skills/tinyfly .claude/skills/
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
**Other agents** (Cursor, Copilot, Codex, Aider): point them at the skill
|
|
116
|
+
from your `AGENTS.md` or rules file:
|
|
117
|
+
|
|
118
|
+
```markdown
|
|
119
|
+
When writing tinyfly animations, follow node_modules/@algorisys/tinyfly/skills/tinyfly/SKILL.md.
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
**A chat window**: paste the output of `npx @algorisys/tinyfly capabilities`,
|
|
123
|
+
or link `llms-full.txt`.
|
package/docs/maps.md
ADDED
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# Animated Maps
|
|
2
|
+
|
|
3
|
+
`@algorisys/tinyfly/maps` draws animated maps on a canvas: a camera that flies
|
|
4
|
+
from the whole world in to a city, pins that drop in, and routes that draw
|
|
5
|
+
themselves while a marker travels them. Everything that moves is a number, so
|
|
6
|
+
it is a timeline track like any other, and it renders the same in a browser and
|
|
7
|
+
in headless video.
|
|
8
|
+
|
|
9
|
+
```js
|
|
10
|
+
import { mapTarget, mapFlyTracks, routeStops, fitView } from '@algorisys/tinyfly/maps'
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
On a page with no build step, load the maps add-on after the browser bundle; it
|
|
14
|
+
adds to the same `tinyfly` global:
|
|
15
|
+
|
|
16
|
+
```html
|
|
17
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly.iife.js"></script>
|
|
18
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly-maps.iife.js"></script>
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
It is a separate script because the offline world map it carries adds about
|
|
22
|
+
33 KB (gzipped), which pages without maps should not pay for.
|
|
23
|
+
|
|
24
|
+
In the editor, the **🗺 Map** element does all of this without code (see the
|
|
25
|
+
[editor guide](editor-guide.md#maps)).
|
|
26
|
+
|
|
27
|
+
## Two base maps
|
|
28
|
+
|
|
29
|
+
| Base | What | Use it for |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| `tiles` | Raster map tiles: OpenStreetMap by default, or any server with the standard `{z}/{x}/{y}` scheme | Real street maps in a browser |
|
|
32
|
+
| `outline` (default) | Country outlines from Natural Earth (public domain), bundled | Headless video, offline use, and the pencil look |
|
|
33
|
+
|
|
34
|
+
**Tiles come from a server.** OpenStreetMap's tile servers allow light use with
|
|
35
|
+
attribution ("© OpenStreetMap contributors", which the map draws for you) and
|
|
36
|
+
do not allow heavy use. For anything busy, set `url` to your own tile server or
|
|
37
|
+
a commercial provider:
|
|
38
|
+
|
|
39
|
+
```js
|
|
40
|
+
const tiles = { url: 'https://tiles.example.com/{z}/{x}/{y}.png', attribution: '© My Maps', maxZoom: 18 }
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Tiles load in the background. Until a tile arrives, the matching corner of an
|
|
44
|
+
already-loaded zoomed-out tile stands in, so flying in never shows blank
|
|
45
|
+
squares. For frames that must be complete (exports, stills), call
|
|
46
|
+
`preloadTiles(cache, source, views)` first.
|
|
47
|
+
|
|
48
|
+
**The outline needs nothing.** It is drawn from vector shapes, so it renders
|
|
49
|
+
the same everywhere, colours countries the way you ask
|
|
50
|
+
(`style.highlight: { IND: '#f7d9a8' }`), and can be drawn in hand-drawn
|
|
51
|
+
pencil strokes that boil (`style.sketch`).
|
|
52
|
+
|
|
53
|
+
## A map target
|
|
54
|
+
|
|
55
|
+
```js
|
|
56
|
+
const trip = mapTarget({
|
|
57
|
+
x: 0, y: 0, width: 1280, height: 720,
|
|
58
|
+
view: { lon: 30, lat: 25, zoom: 2.2 }, // where it starts
|
|
59
|
+
base: 'outline',
|
|
60
|
+
style: { highlight: { IND: '#f7d9a8', NPL: '#f3c9a0' } },
|
|
61
|
+
places: [
|
|
62
|
+
{ id: 'mumbai', lon: 72.88, lat: 19.08, label: 'Mumbai' },
|
|
63
|
+
{ id: 'delhi', lon: 77.10, lat: 28.70, label: 'Delhi' },
|
|
64
|
+
{ id: 'kathmandu', lon: 85.32, lat: 27.72, label: 'Kathmandu' },
|
|
65
|
+
],
|
|
66
|
+
routes: [{ id: 'trip', through: ['mumbai', 'delhi', 'kathmandu'] }],
|
|
67
|
+
})
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Its props are the values tracks animate:
|
|
71
|
+
|
|
72
|
+
| Prop | Meaning |
|
|
73
|
+
|---|---|
|
|
74
|
+
| `view.lon`, `view.lat`, `view.zoom` | The camera: what is at the centre, and the zoom (0 is the whole world, each step doubles) |
|
|
75
|
+
| `<place>.show` | 0..1: the pin drops in and its label fades up (default 1) |
|
|
76
|
+
| `<route>.draw` | 0..1: how much of the route is drawn (default 1) |
|
|
77
|
+
| `<route>.marker` | 0..1: where a marker travelling the route is; below 0 hides it (default -1) |
|
|
78
|
+
|
|
79
|
+
The view's props are named with a dot so they never clash with a CSS property
|
|
80
|
+
(`zoom` is one).
|
|
81
|
+
|
|
82
|
+
Routes are `arc` (a flight-path bow, the default), `great-circle` (the shortest
|
|
83
|
+
way over the globe) or `straight`, in a colour and width, optionally dashed,
|
|
84
|
+
with an `arrow` or `dot` marker.
|
|
85
|
+
|
|
86
|
+
## Helpers
|
|
87
|
+
|
|
88
|
+
| | |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `fitView(places, width, height, padding)` | The centre and zoom that show every place |
|
|
91
|
+
| `flyView(from, to, t)` | A view part way along a flight, pulling out in the middle when the ends are far apart |
|
|
92
|
+
| `mapFlyTracks(target, from, to, start, end)` | That flight as `view.*` keyframe tracks |
|
|
93
|
+
| `routeStops(options, routeId)` | How far along a route each stop is (0..1), so a pin can drop as the line arrives |
|
|
94
|
+
| `mapAt(target, frame, id)` | The view in a frame, and `point(lon, lat)` in the scene, for drawing that stays on the map |
|
|
95
|
+
| `project(view, lon, lat)`, `unproject(view, x, y)` | Web Mercator, the projection web maps use |
|
|
96
|
+
| `greatCircle(from, to)` | Points along the shortest route over the globe |
|
|
97
|
+
| `WORLD_CITIES`, `findCity(name)` | About 80 major cities, so you need not look up coordinates |
|
|
98
|
+
| `worldCountries()`, `findCountry(code)` | The outline map's countries, by ISO code or name |
|
|
99
|
+
|
|
100
|
+
## A trip in a timeline
|
|
101
|
+
|
|
102
|
+
```js
|
|
103
|
+
const stops = routeStops(trip.map, 'trip')
|
|
104
|
+
tracks: [
|
|
105
|
+
...mapFlyTracks('map', world, india, 800, 3200), // fly in
|
|
106
|
+
{ id: 'd', target: 'map', property: 'trip.draw', keyframes: [{ time: 3600, value: 0 }, { time: 8200, value: 1 }] },
|
|
107
|
+
{ id: 'm', target: 'map', property: 'trip.marker', keyframes: [{ time: 3599, value: -1 }, { time: 3600, value: 0 }, { time: 8200, value: 1 }] },
|
|
108
|
+
// Delhi's pin drops as the line reaches it:
|
|
109
|
+
{ id: 'p', target: 'map', property: 'delhi.show', keyframes: [{ time: 0, value: 0 }, { time: 3600 + 4600 * stops[1], value: 1 }] },
|
|
110
|
+
]
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The full scene is
|
|
114
|
+
[`examples/headless-video/map-route.mjs`](../examples/headless-video/map-route.mjs);
|
|
115
|
+
the **Map Route** card in the Examples gallery plays the same trip on
|
|
116
|
+
OpenStreetMap tiles.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Onion skinning
|
|
2
|
+
|
|
3
|
+
Onion skinning shows faint **ghost frames** of the animation just before and
|
|
4
|
+
after the playhead, so you can see the arc of a move (a bounce, a swing, an
|
|
5
|
+
ease) while editing a single frame.
|
|
6
|
+
|
|
7
|
+
## Using it
|
|
8
|
+
|
|
9
|
+
1. Switch the preview to the **Canvas** renderer.
|
|
10
|
+
2. Click **🧅 Onion** in the preview header.
|
|
11
|
+
3. Scrub the playhead — dim copies of the moving elements appear at nearby times,
|
|
12
|
+
brightest closest to the playhead.
|
|
13
|
+
|
|
14
|
+
Onion skin only draws while **paused** (it would just blur during playback) and
|
|
15
|
+
is an **editor-only visualization** — it is never part of the exported animation
|
|
16
|
+
or the saved JSON.
|
|
17
|
+
|
|
18
|
+
## Why Canvas only
|
|
19
|
+
|
|
20
|
+
The Canvas renderer can cheaply redraw the whole stage several times per frame at
|
|
21
|
+
different opacities. The DOM/SVG renderers would need cloned element trees per
|
|
22
|
+
ghost, which is heavier and easy to get wrong — so onion skin is Canvas-only for
|
|
23
|
+
now. The camera is honoured per ghost, so ghosts land where they actually appear.
|
|
24
|
+
|
|
25
|
+
## How it works
|
|
26
|
+
|
|
27
|
+
`src/editor/utils/onion.ts` is a pure helper:
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
onionGhostTimes(now, duration, { frames = 3, step = 120, maxAlpha = 0.35 })
|
|
31
|
+
// → [{ time, alpha }, …] nearer ghosts brighter; out-of-range times dropped
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The preview (`preview-panel.tsx`, `renderCanvas`) samples each ghost time with
|
|
35
|
+
`timeline.getStateAtTime`, applies it to the Canvas adapter, and renders at the
|
|
36
|
+
ghost's alpha before drawing the current frame at full opacity.
|
|
37
|
+
|
|
38
|
+
## Config
|
|
39
|
+
|
|
40
|
+
The defaults (3 frames each side, 120 ms apart, 0.35 max opacity) are baked in for
|
|
41
|
+
now. Exposing them in the UI is a possible later refinement.
|
package/docs/pen-tool.md
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# Pen tool
|
|
2
|
+
|
|
3
|
+
Draw custom paths point by point — straight segments and smooth bezier curves —
|
|
4
|
+
in the DOM preview.
|
|
5
|
+
|
|
6
|
+
## Using it
|
|
7
|
+
|
|
8
|
+
1. In the DOM preview header, click **✒️ Pen**.
|
|
9
|
+
2. **Click** on the stage to drop anchor points (straight segments between them).
|
|
10
|
+
3. **Click-drag** to pull out a curve handle as you place a point (a smooth
|
|
11
|
+
bezier, with symmetric handles).
|
|
12
|
+
4. **Finish**:
|
|
13
|
+
- **Click the first point** to close the path (filled). It grows and turns cyan
|
|
14
|
+
when the cursor is close enough to close.
|
|
15
|
+
- **Enter** or **double-click** to finish an open path (stroked).
|
|
16
|
+
- **Backspace / Delete** removes the last point you placed.
|
|
17
|
+
- **Esc** to cancel.
|
|
18
|
+
|
|
19
|
+
The result is a normal `PathElement`, so it animates, morphs, and exports like any
|
|
20
|
+
other path. Open paths default to a 2px stroke with no fill; closed paths get a
|
|
21
|
+
solid fill.
|
|
22
|
+
|
|
23
|
+
## How it works
|
|
24
|
+
|
|
25
|
+
The geometry is a pure, unit-tested helper:
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
// src/editor/utils/pen-path.ts
|
|
29
|
+
buildPenPath(nodes, closed) // nodes → "M … L/C … [Z]"
|
|
30
|
+
penNodesBounds(nodes) // bbox incl. handles
|
|
31
|
+
localizePenPath(nodes, closed) // → { x, y, width, height, d } in local coords
|
|
32
|
+
mirrorHandle(ax, ay, h) // symmetric drag handle
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The preview tracks pen nodes in stage coordinates (mapped from the pointer via the
|
|
36
|
+
canvas rect, so it's correct at any zoom), draws the in-progress path, anchors,
|
|
37
|
+
and handles live, and on finish localises the nodes into an element box via
|
|
38
|
+
`localizePenPath` and adds a `PathElement`.
|
|
39
|
+
|
|
40
|
+
## Adjusting as you draw
|
|
41
|
+
|
|
42
|
+
Before finishing, you can grab what you've already placed:
|
|
43
|
+
|
|
44
|
+
- **Drag an anchor** to move that point (its handles move with it).
|
|
45
|
+
- **Drag a handle** to reshape the curve; the opposite handle mirrors it, keeping
|
|
46
|
+
the anchor smooth.
|
|
47
|
+
- **Hold Alt while dragging a handle** to break symmetry — the opposite handle
|
|
48
|
+
stays put, giving a corner (cusp) instead of a smooth point.
|
|
49
|
+
|
|
50
|
+
Handles take priority over anchors when they overlap, so you can always grab a
|
|
51
|
+
handle sitting on its point.
|
|
52
|
+
|
|
53
|
+
## Snapping
|
|
54
|
+
|
|
55
|
+
When **🧲 Snap** is on, pen **points** snap to the grid (**▦ Grid**), your guides
|
|
56
|
+
(**📏 Rulers**), other elements' edges/centres, and the artboard — with the same
|
|
57
|
+
pink alignment guides as element editing. Bezier **handles** stay free so curves
|
|
58
|
+
aren't constrained.
|
|
59
|
+
|
|
60
|
+
## Limitations / later
|
|
61
|
+
|
|
62
|
+
- After finishing, edit the path with the existing path control points, or the
|
|
63
|
+
raw SVG field in Properties.
|
|
64
|
+
- Backspace removes points from the end; the first anchor is reserved for closing,
|
|
65
|
+
so it can't be repositioned mid-draw (its handle still can).
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Polygon & star shapes
|
|
2
|
+
|
|
3
|
+
Add regular polygons and stars from the **Elements** panel. They are ordinary
|
|
4
|
+
closed paths under the hood, so they render, animate, and export exactly like any
|
|
5
|
+
other path — while staying parametric (editable sides/points, resizable).
|
|
6
|
+
|
|
7
|
+
## Using them
|
|
8
|
+
|
|
9
|
+
- In the **Elements** panel, click **⬡ Polygon** or **★ Star**.
|
|
10
|
+
- Select the shape and open **Properties**:
|
|
11
|
+
- **Sides** (polygon) or **Points** (star)
|
|
12
|
+
- **Inner %** (star) — the inner radius as a percentage of the outer radius
|
|
13
|
+
- **Resize** the shape on the stage like any box; the geometry regenerates to fill
|
|
14
|
+
the new width/height, so sides/points stay crisp at any size.
|
|
15
|
+
|
|
16
|
+
## How it works
|
|
17
|
+
|
|
18
|
+
`src/editor/utils/poly-star.ts` is a pure, unit-tested geometry helper:
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
polygonVertices(width, height, sides) // inscribed in the box, first vertex up
|
|
22
|
+
starVertices(width, height, points, innerRatio)
|
|
23
|
+
verticesToPath(verts) // → "M … L … Z"
|
|
24
|
+
polyStarPath(spec, width, height) // → path `d`
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
A polygon/star is a `PathElement` with an extra `shape: { kind, points, innerRatio }`
|
|
28
|
+
spec. The scene store keeps the path `d` in sync:
|
|
29
|
+
|
|
30
|
+
- `addPolyStar(spec, overrides)` creates it (solid fill, closed).
|
|
31
|
+
- `updateShape(id, patch)` changes sides/points/inner ratio and regenerates `d`.
|
|
32
|
+
- `updateElement` regenerates `d` whenever the width/height (or spec) changes, so
|
|
33
|
+
resizing rescales the shape.
|
|
34
|
+
|
|
35
|
+
Because it's a plain path with a generated `d`, every renderer (DOM/Canvas/SVG),
|
|
36
|
+
raster export, and embed handles it with no special cases. In the editor, a
|
|
37
|
+
parametric shape shows the box + resize handles (not per-vertex control points) so
|
|
38
|
+
it resizes as a unit.
|
|
39
|
+
|
|
40
|
+
## Limitations / later
|
|
41
|
+
|
|
42
|
+
- Corner rounding and per-vertex editing aren't offered for parametric shapes
|
|
43
|
+
(convert intent is a plain path if you need free vertices).
|
|
44
|
+
- Grid size / rotation snapping apply as they do for any element.
|