castle-web-cli 0.4.151 → 0.4.153

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 (98) hide show
  1. package/dist/castle-host/host.js +11 -3
  2. package/dist/castleJson.d.ts +1 -0
  3. package/dist/castleJson.js +14 -0
  4. package/dist/ide.js +4 -0
  5. package/dist/imports.js +18 -12
  6. package/dist/init.js +28 -12
  7. package/dist/platformDoc.js +68 -0
  8. package/dist/save-deck.js +14 -9
  9. package/dist/serve.js +91 -18
  10. package/dist/serveSecurity.d.ts +6 -0
  11. package/dist/serveSecurity.js +38 -4
  12. package/dist/shell/assets/{index-Dlhc3eZW.js → index-DsDkYFvP.js} +2 -2
  13. package/dist/shell/index.html +1 -1
  14. package/kits/blank/castle.json +1 -1
  15. package/kits/blank/node_modules/.package-lock.json +13 -0
  16. package/kits/blank/node_modules/castle-web-fonts/README.md +114 -0
  17. package/kits/blank/node_modules/castle-web-fonts/dist/catalog.d.ts +18 -0
  18. package/kits/blank/node_modules/castle-web-fonts/dist/catalog.js +142 -0
  19. package/kits/blank/node_modules/castle-web-fonts/dist/face.d.ts +1 -0
  20. package/kits/blank/node_modules/castle-web-fonts/dist/face.js +52 -0
  21. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Bore.d.ts +3 -0
  22. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Bore.js +10 -0
  23. package/kits/blank/node_modules/castle-web-fonts/dist/faces/CourierPrime.d.ts +3 -0
  24. package/kits/blank/node_modules/castle-web-fonts/dist/faces/CourierPrime.js +10 -0
  25. package/kits/blank/node_modules/castle-web-fonts/dist/faces/DMSans.d.ts +3 -0
  26. package/kits/blank/node_modules/castle-web-fonts/dist/faces/DMSans.js +10 -0
  27. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Glacier.d.ts +3 -0
  28. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Glacier.js +10 -0
  29. package/kits/blank/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.d.ts +3 -0
  30. package/kits/blank/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.js +10 -0
  31. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Piazzolla.d.ts +3 -0
  32. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Piazzolla.js +10 -0
  33. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Synco.d.ts +3 -0
  34. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Synco.js +10 -0
  35. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Tektur.d.ts +3 -0
  36. package/kits/blank/node_modules/castle-web-fonts/dist/faces/Tektur.js +10 -0
  37. package/kits/blank/node_modules/castle-web-fonts/dist/faces/YatraOne.d.ts +3 -0
  38. package/kits/blank/node_modules/castle-web-fonts/dist/faces/YatraOne.js +10 -0
  39. package/kits/blank/node_modules/castle-web-fonts/dist/index.d.ts +16 -0
  40. package/kits/blank/node_modules/castle-web-fonts/dist/index.js +15 -0
  41. package/kits/blank/node_modules/castle-web-fonts/licenses/CC-BY-ND-4.0.txt +393 -0
  42. package/kits/blank/node_modules/castle-web-fonts/licenses/FONTS.md +64 -0
  43. package/kits/blank/node_modules/castle-web-fonts/licenses/OFL-1.1.txt +95 -0
  44. package/kits/blank/node_modules/castle-web-fonts/package.json +47 -0
  45. package/kits/blank/node_modules/castle-web-fonts/woff2/Bore.woff2 +0 -0
  46. package/kits/blank/node_modules/castle-web-fonts/woff2/CourierPrime.woff2 +0 -0
  47. package/kits/blank/node_modules/castle-web-fonts/woff2/DMSans.woff2 +0 -0
  48. package/kits/blank/node_modules/castle-web-fonts/woff2/Glacier.woff2 +0 -0
  49. package/kits/blank/node_modules/castle-web-fonts/woff2/HelicoCentrica.woff2 +0 -0
  50. package/kits/blank/node_modules/castle-web-fonts/woff2/Piazzolla.woff2 +0 -0
  51. package/kits/blank/node_modules/castle-web-fonts/woff2/SOURCE.txt +2 -0
  52. package/kits/blank/node_modules/castle-web-fonts/woff2/Synco.woff2 +0 -0
  53. package/kits/blank/node_modules/castle-web-fonts/woff2/Tektur.woff2 +0 -0
  54. package/kits/blank/node_modules/castle-web-fonts/woff2/YatraOne.woff2 +0 -0
  55. package/kits/blank/package-lock.json +10 -1
  56. package/kits/blank/package.json +3 -1
  57. package/kits/physics-2d/CLAUDE.md +158 -40
  58. package/kits/physics-2d/castle.json +3 -2
  59. package/kits/physics-2d/editors/SingleEditor.jsx +52 -19
  60. package/kits/physics-2d/editors/StyleEditor.jsx +139 -40
  61. package/kits/physics-2d/editors/deckFont.js +88 -0
  62. package/kits/physics-2d/editors/fontPreview.js +66 -0
  63. package/kits/physics-2d/editors/styleEditor.module.css +30 -3
  64. package/kits/physics-2d/editors/styleTheme.js +13 -2
  65. package/kits/physics-2d/engine/ScenePlayer.jsx +17 -2
  66. package/kits/physics-2d/engine/SceneUI.jsx +8 -0
  67. package/kits/physics-2d/engine/files.js +20 -9
  68. package/kits/physics-2d/engine/fonts.js +79 -0
  69. package/kits/physics-2d/engine/scene.js +6 -0
  70. package/kits/physics-2d/fonts.generated.js +9 -0
  71. package/kits/physics-2d/main.jsx +11 -0
  72. package/kits/physics-2d/package-lock.json +8 -1
  73. package/kits/physics-2d/package.json +1 -0
  74. package/kits/physics-2d/theme.style +2 -1
  75. package/kits/physics-3d/castle.json +1 -1
  76. package/kits/physics-3d/engine3d/PxModelEditor.jsx +3 -4
  77. package/kits/physics-3d/engine3d/Scene3DEditor.jsx +12 -8
  78. package/kits/physics-3d/engine3d/editorChrome.jsx +11 -6
  79. package/kits/physics-3d/engine3d/modelFiles.js +4 -5
  80. package/kits/physics-3d/package-lock.json +8 -1
  81. package/kits/physics-3d/package.json +1 -0
  82. package/kits/tabletop/.prettierrc +8 -0
  83. package/kits/tabletop/CLAUDE.md +309 -0
  84. package/kits/tabletop/castle.json +34 -0
  85. package/kits/tabletop/index.html +20 -0
  86. package/kits/tabletop/main.jsx +8 -0
  87. package/kits/tabletop/package-lock.json +341 -0
  88. package/kits/tabletop/package.json +29 -0
  89. package/kits/tabletop/room.js +269 -0
  90. package/kits/tabletop/testing.js +569 -0
  91. package/package.json +1 -1
  92. package/kits/blank/.castle/agent/children.json +0 -1
  93. package/kits/blank/.castle/agent/messages.json +0 -9
  94. package/kits/blank/.castle/agent/pending-sends.json +0 -1
  95. package/kits/blank/.castle/agent/tasks/index.md +0 -2
  96. package/kits/blank/.castle/docs/platform.md +0 -36
  97. package/kits/blank/node_modules/.vite/deps/_metadata.json +0 -8
  98. package/kits/blank/node_modules/.vite/deps/package.json +0 -3
@@ -22,6 +22,7 @@ Do you already know what you want to make, or do you want to figure it out toget
22
22
  - Every actor is an instance of a **blueprint** (`blueprints/*.scene`) — see `## Blueprints` below. Always author the blueprint file yourself and reference it via `"blueprint"`. Don't write inline actors (full `components`, no `blueprint` field): the editor auto-migrates each one into its own new blueprint file on open, one per actor with no dedup, which litters the deck with junk blueprints.
23
23
  - Real game objects and scenery should usually be editable sprites: generate `.sprite` with `npm run draw -- name`, then place it via a `Sprite` component pointing at `drawings/name.sprite`. Dynamic UI/effects stay procedural.
24
24
  - A deck can also hold uploaded media (the Files panel's Upload button): `Sprite` draws image files as well as `.sprite`, and `Video` plays video files. Point their `file` at the deck path (`assets/logo.png`). For audio see `## Sound` below -- sound effects need no component at all.
25
+ - The deck's body/UI font is picked in the Style editor (`theme.style`): HUD text inherits it, canvas text reads `scene.font`. A second display face is imported in the behavior that uses it. See `## Deck font` below.
25
26
  - This kit is plain JavaScript. Use `.jsx` for files with JSX, `.js` otherwise; do not add TypeScript files or a new build step.
26
27
  - Space is reserved by the editor for play/stop; do not bind Space to gameplay.
27
28
  - Do not read `engine/`, `editors/`, or built-in behaviors (`Layout.jsx`, `Sprite.jsx`, `Collider.jsx`, `Camera.jsx`, and the physics ones — `RigidBody.jsx`, `Joints.jsx`, `Draggable.jsx`, `Slingshot.jsx`, `AnalogStick.jsx`) to build a game. Their public API is documented below. Forking is the exception: when you're deliberately copying a kit file into the deck to change it — an editor (see `## Editors`) or a behavior you're shadowing — read the original. `engine/` stays off-limits either way.
@@ -52,25 +53,26 @@ where editing raw JSON in the code editor is the bottleneck.
52
53
  }
53
54
  ```
54
55
 
55
- These are ALL the fields that exist — do not invent others:
56
- - `ext` — the extension, with the dot. One entry per extension.
57
- - `label` — display name in the tab and pickers.
58
- - `new` — the entry in the Files panel's New menu; omit it and the type
59
- can't be created there.
60
- - `icon` — for that entry and the file's tree row. Use one the kit types
61
- already use: `globe`, `layer-group`, `code`, `file`, `image`, `music`,
62
- `film`. An unknown name falls back to a generic icon.
63
- - `editor` — the module that edits this type, as a path from the deck
64
- root, and it MUST live under `editors/` (that directory is the only
65
- place the loader looks). Omit it to leave the type to the builtin code
66
- editor. (The value `"kit"` is legacy — always name the module.)
67
- - `data` — how the file behaves when a module imports it: `"json"` (a
68
- module import yields the parsed object) or `"text"` (the raw string).
69
- Omit for an ordinary JS module. Data files are the normal case for
70
- editor-owned content.
71
- - `unsupported` — a refusal: why this deck must NOT be built on this
72
- format, shown when someone tries to upload one. Only for formats you
73
- recognize and reject.
56
+ These are ALL the fields that exist — do not invent others:
57
+
58
+ - `ext` — the extension, with the dot. One entry per extension.
59
+ - `label` — display name in the tab and pickers.
60
+ - `new` — the entry in the Files panel's New menu; omit it and the type
61
+ can't be created there.
62
+ - `icon` — for that entry and the file's tree row. Use one the kit types
63
+ already use: `globe`, `layer-group`, `code`, `file`, `image`, `music`,
64
+ `film`. An unknown name falls back to a generic icon.
65
+ - `editor` — the module that edits this type, as a path from the deck
66
+ root, and it MUST live under `editors/` (that directory is the only
67
+ place the loader looks). Omit it to leave the type to the builtin code
68
+ editor. (The value `"kit"` is legacy — always name the module.)
69
+ - `data` — how the file behaves when a module imports it: `"json"` (a
70
+ module import yields the parsed object) or `"text"` (the raw string).
71
+ Omit for an ordinary JS module. Data files are the normal case for
72
+ editor-owned content.
73
+ - `unsupported` — a refusal: why this deck must NOT be built on this
74
+ format, shown when someone tries to upload one. Only for formats you
75
+ recognize and reject.
74
76
 
75
77
  2. **Write the module** at the declared path, default-exporting a component:
76
78
 
@@ -80,18 +82,54 @@ const EMPTY = { lines: [] };
80
82
 
81
83
  export default function DialogueEditor({ path, text, onChange }) {
82
84
  let doc;
83
- try { doc = text.trim() ? JSON.parse(text) : EMPTY; } catch { doc = EMPTY; }
85
+ try {
86
+ doc = text.trim() ? JSON.parse(text) : EMPTY;
87
+ } catch {
88
+ doc = EMPTY;
89
+ }
84
90
  const save = (next) => onChange(JSON.stringify(next, null, 2));
85
91
  // ...render doc, call save(next) on every edit...
86
92
  }
87
93
  ```
88
94
 
89
- Props: `path` (deck-relative file path), `text` (current file text),
90
- `onChange(nextText)` (replaces the whole file; the host debounces the
91
- write and flushes before a restart — call it on every edit, don't build
92
- your own save button), `files` (live map of every deck text file,
93
- path → text), and `onChangeFile(path, nextText)` (edit another file, e.g.
94
- a sub-document — same debounced save).
95
+ Props: `path` (deck-relative file path), `text` (current file text),
96
+ `onChange(nextText)` (replaces the whole file; the host debounces the
97
+ write and flushes before a restart — call it on every edit, don't build
98
+ your own save button), `files` (live map of every deck text file,
99
+ path → text), `onChangeFile(path, nextText)` (edit another file, e.g.
100
+ a sub-document — same debounced save), and `readOnly` (below).
101
+
102
+ ### Read-only
103
+
104
+ A file is read-only when it belongs to an import this deck has not forked, or
105
+ when the whole deck is being viewed rather than edited (view source). Your
106
+ editor is told which through one prop:
107
+
108
+ ```jsx
109
+ export default function DialogueEditor({ text, onChange, readOnly }) {
110
+ return (
111
+ <input value={line} disabled={readOnly} onChange={(e) => onChange(next(e.target.value))} />
112
+ );
113
+ }
114
+ ```
115
+
116
+ Honoring it is about the UI, not safety: writes from a read-only file are
117
+ dropped before they reach disk, so an editor that ignores `readOnly` loses the
118
+ edit instead of corrupting anything. But the shell shows a "Read Only" banner
119
+ above your editor, so controls that still look live are the confusing part —
120
+ disable them.
121
+
122
+ Editors a kit routes to directly, rather than through the declared-editor host,
123
+ get no props and must ask:
124
+
125
+ ```jsx
126
+ import { useReadOnlyFile } from '@imports/castle.physics-2d/editors/SingleEditor';
127
+ const readOnly = useReadOnlyFile(path);
128
+ ```
129
+
130
+ That hook is the single definition of the rule. Do not re-derive it from
131
+ `isImportedFile` or `window.__castleReadOnly` — a fork IS writable, and getting
132
+ that wrong locks an editor the deck is entitled to use.
95
133
 
96
134
  3. **Make it visible.** If the deck's `castle.json` has
97
135
  `editor.visiblePaths`, add your content directory (e.g. `"dialogue/**"`)
@@ -260,9 +298,21 @@ A scene is a background plus a list of actors. Every actor is an **instance of a
260
298
  {
261
299
  "background": "#1b2030",
262
300
  "actors": [
263
- { "id": "paddle", "blueprint": "blueprints/paddle.scene", "components": { "Layout": { "x": 200, "y": 650 } } },
264
- { "id": "brick-1", "blueprint": "blueprints/brick.scene", "components": { "Layout": { "x": 50, "y": 75 } } },
265
- { "id": "brick-2", "blueprint": "blueprints/brick.scene", "components": { "Layout": { "x": 100, "y": 75 } } }
301
+ {
302
+ "id": "paddle",
303
+ "blueprint": "blueprints/paddle.scene",
304
+ "components": { "Layout": { "x": 200, "y": 650 } }
305
+ },
306
+ {
307
+ "id": "brick-1",
308
+ "blueprint": "blueprints/brick.scene",
309
+ "components": { "Layout": { "x": 50, "y": 75 } }
310
+ },
311
+ {
312
+ "id": "brick-2",
313
+ "blueprint": "blueprints/brick.scene",
314
+ "components": { "Layout": { "x": 100, "y": 75 } }
315
+ }
266
316
  ]
267
317
  }
268
318
  ```
@@ -349,13 +399,14 @@ Template `components` keys are behavior names (the `static behaviorName`); add a
349
399
 
350
400
  ```jsx
351
401
  scene.getActor('music').runtime.soundPlayer.play();
352
- await actor.runtime.soundPlayer.play(); // ...and wait for it to finish
353
- actor.runtime.soundPlayer.stop(); // stream also: pause(), resume(), .playing
402
+ await actor.runtime.soundPlayer.play(); // ...and wait for it to finish
403
+ actor.runtime.soundPlayer.stop(); // stream also: pause(), resume(), .playing
354
404
  ```
355
405
 
356
406
  **For a one-off sound effect, don't place one of these** — `scene.sound.play('hit')` needs no actor and no component. See `## Sound` below.
357
407
 
358
408
  Sound only plays during play, never in the editor, and everything stops on Stop / a scene change. Browsers refuse audio until the player has touched the page; a sound that starts before that is queued and begins on the first tap or key, so don't work around it.
409
+
359
410
  - **Video** — `{ file: "assets/clip.mp4", mode?: 'cover'|'fit'|'stretch', playing?: true, loop?: true, muted?: true, volume?: 1 }`. Plays an `.mp4` (H.264) video inside the Layout box, drawn into the scene like a sprite: it moves with Layout, draws in `z` order, and can carry a Collider. `mode` frames it exactly as Sprite's does. In the editor it holds its first frame so you can place it. Leave `muted: true` unless the player has already interacted — an unmuted autoplaying video is blocked by browsers, a muted one isn't.
360
411
 
361
412
  ## Sound
@@ -365,10 +416,10 @@ Two ways to make a noise. The choice is about LENGTH, not importance.
365
416
  **Sound effects — `scene.sound.play(name)`.** No actor, no component, no import:
366
417
 
367
418
  ```jsx
368
- scene.sound.play('jump'); // by filename, without the extension
369
- scene.sound.play('assets/sounds/hit.wav'); // ...or by full path
419
+ scene.sound.play('jump'); // by filename, without the extension
420
+ scene.sound.play('assets/sounds/hit.wav'); // ...or by full path
370
421
  scene.sound.play('hit', { volume: 0.5, pan: -0.8, playbackRate: 1.2 });
371
- scene.sound.stopAll(); // everything the scene is playing, off
422
+ scene.sound.stopAll(); // everything the scene is playing, off
372
423
  ```
373
424
 
374
425
  Effects are decoded into memory before the deck starts, so they fire instantly and overlap. **Put them in `assets/sounds/`** — that directory, and only that one, is preloaded. A sound kept elsewhere still plays, but its FIRST play is silent while it loads.
@@ -381,6 +432,69 @@ Name a sound by its filename without the extension, or by its full deck path. Tw
381
432
 
382
433
  128 effects can sound at once; past that the oldest is cut off to make room.
383
434
 
435
+ ## Deck font
436
+
437
+ A physics-2d deck picks its **deck font** in the Style editor — open
438
+ `theme.style` and choose one of the nine Castle faces, or None. That is the
439
+ deck's body and UI face: HUD text inherits it, and `scene.font` returns it.
440
+
441
+ Picking writes two files, and both belong in the deck:
442
+
443
+ - `theme.style` — `{ "palette": "...", "font": "Piazzolla" }`. The record.
444
+ Hand-editable; the editor repairs the module on the next panel load if you do.
445
+ - `fonts.generated.js` — one static re-export, and the only thing that carries
446
+ that face's bytes into the published deck. Generated; don't edit it.
447
+
448
+ Use it in the two places this kit renders text:
449
+
450
+ - **HUD text** (a behavior's `ui` hook) inherits it already — plain React, no
451
+ extra work. `--castle-deck-font` is on the UI layer if you want to name it in
452
+ CSS.
453
+ - **In-world text** (a behavior's `draw` hook) reads `scene.font`, which is
454
+ always a usable CSS family — the deck's face, or a sans stack when it has
455
+ none:
456
+
457
+ ```jsx
458
+ draw(actor, scene, ctx) {
459
+ ctx.font = `24px ${scene.font}`;
460
+ ctx.fillText(`${this.props.score}`, 20, 40);
461
+ }
462
+ ```
463
+
464
+ Don't hardcode the deck font's family name there: a `draw` hook naming
465
+ `'Piazzolla'` outright keeps drawing in it after someone picks a different
466
+ font, and draws in nothing at all once they pick None.
467
+
468
+ ### A second face
469
+
470
+ The picker sets one font because a deck has one default, not because a deck may
471
+ only have one. A display face for titles beside the body face is an ordinary
472
+ thing to want — import it in the behavior that uses it, and name it there:
473
+
474
+ ```jsx
475
+ import { installBore } from 'castle-web-fonts';
476
+
477
+ installBore(); // font-family: 'Bore' from here on
478
+
479
+ export class Title {
480
+ static behaviorName = 'Title';
481
+ draw(actor, scene, ctx) {
482
+ ctx.font = `20px ${scene.font}`; // the deck font: read it
483
+ ctx.fillText('level 3', 40, 200);
484
+ ctx.font = '64px Bore'; // a face this behavior chose: name it
485
+ ctx.fillText('GAME OVER', 40, 300);
486
+ }
487
+ }
488
+ ```
489
+
490
+ The kit waits for every face the deck registered — the picked one and any a
491
+ behavior imported for itself — before the first frame, so `ctx.font` is safe to
492
+ set from the very first `draw`. Each face costs its own 12–90 KB in the bundle,
493
+ so two or three in total is the shape to aim for.
494
+
495
+ There is no Text behavior — text is drawn by the deck's own code, through the
496
+ two hooks above.
497
+
384
498
  ## Physics
385
499
 
386
500
  This kit simulates 2D physics with matter-js. You get gravity, collisions,
@@ -445,7 +559,7 @@ A behavior can implement these; the physics system calls them on both actors of
445
559
  a contact — every pair, including static-vs-static and moving kinematic bodies
446
560
  (and sensor overlaps). For a quick one-off "are these two touching right now?"
447
561
  without callbacks, use `scene.physics.isColliding(a, b)`. (`scene.overlaps(a, b)`
448
- also exists but is a cheaper *bounding-box* test — not shape-accurate; prefer
562
+ also exists but is a cheaper _bounding-box_ test — not shape-accurate; prefer
449
563
  the physics calls for physics actors.)
450
564
 
451
565
  ```jsx
@@ -466,7 +580,7 @@ still collides with the world. Each needs a `RigidBody` (dynamic) + `Collider` -
466
580
  silently inert. The editor adds them for you (`expectedSiblings`), but a
467
581
  blueprint you write by hand must include them itself.
468
582
  Controls are **touch/pointer-first** (Castle games are played on mobile first;
469
- touch degrades to mouse). Keyboard, if added, should only *duplicate* an
583
+ touch degrades to mouse). Keyboard, if added, should only _duplicate_ an
470
584
  on-screen control -- never be the only way to play.
471
585
 
472
586
  - **`Draggable`** — grab the actor with the pointer and fling it (collides).
@@ -492,6 +606,7 @@ lands on a control's own collider outranks one that merely takes any press, so a
492
606
  `Slingshot` set to `grabAnywhere` never steals a finger that grabbed a
493
607
  `Draggable`. Custom controls get the same treatment via `scene.claimPointer` —
494
608
  see the SceneRuntime API below.
609
+
495
610
  - **`Slingshot`** — press the actor, pull back, release to launch it the
496
611
  opposite way (angry-birds), with an aim arrow. `speed`, `maxDrag`.
497
612
  - **`AnalogStick`** — on-screen virtual joystick (press anywhere) that drives
@@ -500,7 +615,7 @@ see the SceneRuntime API below.
500
615
  ### Recipe: a launch-and-bounce game
501
616
 
502
617
  - Ball blueprint: `Layout` (square), `Sprite`, `Collider {shape:'circle',
503
- bounciness:0.6}`, `RigidBody {bodyType:'dynamic'}`, `Slingshot {}`.
618
+ bounciness:0.6}`, `RigidBody {bodyType:'dynamic'}`, `Slingshot {}`.
504
619
  - Walls/floor blueprint: `Layout`, `Collider {bounciness:0.4}` (no RigidBody →
505
620
  static).
506
621
  - Goal blueprint: `Collider {isTrigger:true}` + a `Goal` behavior with
@@ -532,7 +647,7 @@ target either dynamic or a static anchor (a lone `Collider`). Each list entry:
532
647
  inspector, turn **Auto length** on to lock it to the actors' distance when play
533
648
  starts (stored as `-1`). Not used by `pin`/`weld`.
534
649
  - `springiness` (0..1) — for `spring`, how bouncy the tether is; for `rope`, how
535
- it behaves *when taut*: `0` = a dead rope (holds firm at max length), `1` = a
650
+ it behaves _when taut_: `0` = a dead rope (holds firm at max length), `1` = a
536
651
  bungee (stretches well past and springs back).
537
652
  - `damping` (0..1, spring only) — how fast the spring's oscillation settles.
538
653
  - `anchorX/anchorY` (+ `targetAnchorX/targetAnchorY` for spring/rod/rope) —
@@ -562,7 +677,7 @@ anchors.
562
677
  - `line` (default) — the schematic overlay (coil/dashed/etc.). Good for
563
678
  prototyping; you see your joints working.
564
679
  - `hidden` — nothing drawn in play (the joint is pure mechanics). It still shows
565
- as a faint line in the *editor* so you don't lose track of it.
680
+ as a faint line in the _editor_ so you don't lose track of it.
566
681
  - `sprite` — draw art along the joint. Set `sprite` to a `.sprite`
567
682
  (defaults to a built-in rope), `thickness` (px), and `fit`: `tile` (repeat a
568
683
  segment — rope, chain) or `stretch` (one image end-to-end — stick, beam). The
@@ -641,6 +756,7 @@ Don't hand-write pixel grids. Generate sprites with the `draw` command: **emit a
641
756
  `#e69c69` `#bf6f4a` `#8a4836` `#391f21` `#891e2b` `#ea323c` `#ffa214` `#ffeb57` `#5ac54f` `#1e6f50` `#134c4c` `#657392` `#c7cfdd` `#ffffff` `#0cf1ff` `#0098dc`
642
757
 
643
758
  If the deck defines a palette in `theme.style`, that governs instead. `npm run palette` prints the active generation palette. Off-palette fills snap to the nearest of these, so stay on-palette to keep what you intend. People editing in the app paint from the deck palette (and the sprite's own colors); only this generation path is quantized.
759
+
644
760
  - **Run it** (sprite name as the arg; stdin is the svg):
645
761
 
646
762
  ```bash
@@ -648,6 +764,7 @@ Don't hand-write pixel grids. Generate sprites with the `draw` command: **emit a
648
764
  ```
649
765
 
650
766
  writes `drawings/ship.sprite`. You can also pass `--from file.svg` instead of stdin. An undecodable svg (no usable rects) errors with a nonzero exit and writes nothing.
767
+
651
768
  - **A newly created file is not in the kit's static glob until the panel reloads**, so until then the missing-sprite fallback renders the placeholder -- an actor pointing at a not-yet-drawn `.sprite` is still playable. Do not force a reload to fix it.
652
769
 
653
770
  Point a `Sprite` component's `file` at the generated `drawings/<name>.sprite` to put the art on an actor.
@@ -680,6 +797,7 @@ To generate path art, emit an svg of **shapes** rather than per-pixel rects and
680
797
  - `scene.spawnFromBlueprint('blueprints/enemy.scene', { components: { Layout: { x, y } } })` — spawn an instance of a blueprint, same merge semantics as a placed instance. Prefer this over `spawnActor` when you're spawning copies of something that has (or should have) a blueprint, e.g. `scene.spawnFromBlueprint(actor.blueprint, { components: { Layout: { x: actor.components.Layout.x, y: actor.components.Layout.y } } })` to spawn another of the same kind as an existing actor.
681
798
  - `scene.despawnActor(id)` — remove an actor at runtime. Use this; don't `splice` + `delete` by hand.
682
799
  - `scene.sound` — the deck's sound library: `play(name, opts)`, `stopAll()`, `isLoaded`, `whenLoaded`, `has(name)`, `voiceCount`. See `## Sound`.
800
+ - `scene.font` — the deck's font as a CSS family, for `ctx.font` in `draw`. Always usable: the face picked in the Style editor, or a sans stack. See `## Deck font`.
683
801
  - `scene.status` — string you can set/read for game-state ('playing', 'gameover', ...).
684
802
  - `scene.load(sceneData)` — replace the running scene with the given scene data object.
685
803
  - `scene.readFromFile(name)` — read and parse a scene file (`'gameover.scene'`, `'levels/2.scene'`), returning its scene data. Use this instead of importing a `.scene` file.
@@ -696,7 +814,7 @@ if (scene.keys.has('KeyX')) /* launch ball */ ;
696
814
 
697
815
  **Space is reserved** — the editor binds it to the play/stop toggle, so don't bind Space to a gameplay action (jump / shoot / launch / ...). Use arrows, WASD, letter keys, or on-screen buttons instead.
698
816
 
699
- For HUD text use a behavior's `ui` hook (returns React); for in-world text or shapes, draw with `ctx` from `draw`.
817
+ For HUD text use a behavior's `ui` hook (returns React); for in-world text or shapes, draw with `ctx` from `draw`. Both render in the deck's font — see `## Deck font`.
700
818
 
701
819
  ## Common breakout-shaped recipe (sketch)
702
820
 
@@ -24,7 +24,8 @@
24
24
  "blueprints/**",
25
25
  "behaviors/**",
26
26
  "assets/**",
27
- "theme.style"
27
+ "theme.style",
28
+ "fonts.generated.js"
28
29
  ],
29
30
  "fileTypes": [
30
31
  {
@@ -131,5 +132,5 @@
131
132
  "main": "main.jsx",
132
133
  "autoUpdateWhenImported": true,
133
134
  "title": "physics-2d",
134
- "publishedVersion": "2026-08-27T22:04:36.510Z"
135
+ "publishedVersion": "2026-08-30T20:44:19.653Z"
135
136
  }
@@ -149,7 +149,7 @@ function UnsavedNotice({ saveState }) {
149
149
  // `isImportedFile` alone would refuse edits the deck is entitled to make.
150
150
  // Asked of the serve rather than derived here: forks live outside the file map
151
151
  // this kit sees, and only the serve knows the whole chain.
152
- function useForkedPaths() {
152
+ export function useForkedPaths() {
153
153
  const [forked, setForked] = useState(() => new Set());
154
154
  useEffect(() => {
155
155
  let alive = true;
@@ -169,7 +169,25 @@ function useForkedPaths() {
169
169
  return forked;
170
170
  }
171
171
 
172
- function DeclaredEditor({ path, module: modulePath, text, onChange, files, onChangeFile, readOnly }) {
172
+ // The one read-only rule. A file is read-only when the host says the whole deck
173
+ // is (view source) or when it belongs to an import this deck has not forked.
174
+ // Declared editors get this as the `readOnly` prop and need not call it; an
175
+ // editor a kit routes to directly has to ask.
176
+ export function useReadOnlyFile(path) {
177
+ const forkedPaths = useForkedPaths();
178
+ const viewerOnly = typeof window !== 'undefined' && window.__castleReadOnly === true;
179
+ return viewerOnly || (isImportedFile(path) && !forkedPaths.has(path));
180
+ }
181
+
182
+ function DeclaredEditor({
183
+ path,
184
+ module: modulePath,
185
+ text,
186
+ onChange,
187
+ files,
188
+ onChangeFile,
189
+ readOnly,
190
+ }) {
173
191
  const [Editor, setEditor] = useState(null);
174
192
  const [error, setError] = useState(null);
175
193
  useEffect(() => {
@@ -178,7 +196,7 @@ function DeclaredEditor({ path, module: modulePath, text, onChange, files, onCha
178
196
  setError(null);
179
197
  loadEditorModule(modulePath).then(
180
198
  (loaded) => alive && setEditor(() => loaded),
181
- (e) => alive && setError(e instanceof Error ? e.message : String(e)),
199
+ (e) => alive && setError(e instanceof Error ? e.message : String(e))
182
200
  );
183
201
  return () => {
184
202
  alive = false;
@@ -217,7 +235,10 @@ export function SingleEditor({ path, editor, editorModule }) {
217
235
  const { schedule, hasPending, saveState } = useFileSaver(isWritable);
218
236
  // Live deck files; our own in-flight (debounced, unsaved) edits win over the
219
237
  // fs echo of a stale write, so a drag in progress isn't clobbered.
220
- const { files, setFiles, hydrated } = useLiveDeckFiles({ shouldSkipPath: hasPending, ensurePath: path });
238
+ const { files, setFiles, hydrated } = useLiveDeckFiles({
239
+ shouldSkipPath: hasPending,
240
+ ensurePath: path,
241
+ });
221
242
  const [selectedActorIds, setSelectedActorIds] = useState(stash?.selectedActorIds ?? []);
222
243
  const [multiSelectMode, setMultiSelectMode] = useState(stash?.multiSelectMode ?? false);
223
244
  useEffect(
@@ -250,19 +271,20 @@ export function SingleEditor({ path, editor, editorModule }) {
250
271
  // the serve a moment after mount. Wait for it: an editor handed '' for a
251
272
  // file that exists renders its empty state, and one edit there overwrites
252
273
  // the real document.
253
- body = !hydrated && files[path] === undefined ? (
254
- <div className={styles.editorBody}>loading…</div>
255
- ) : (
256
- <DeclaredEditor
257
- path={path}
258
- module={editorModule}
259
- text={text}
260
- onChange={onChange}
261
- files={files}
262
- onChangeFile={onChangeFile}
263
- readOnly={readOnly}
264
- />
265
- );
274
+ body =
275
+ !hydrated && files[path] === undefined ? (
276
+ <div className={styles.editorBody}>loading…</div>
277
+ ) : (
278
+ <DeclaredEditor
279
+ path={path}
280
+ module={editorModule}
281
+ text={text}
282
+ onChange={onChange}
283
+ files={files}
284
+ onChangeFile={onChangeFile}
285
+ readOnly={readOnly}
286
+ />
287
+ );
266
288
  } else if (kind === 'scene') {
267
289
  body = (
268
290
  <SceneEditor
@@ -285,9 +307,20 @@ export function SingleEditor({ path, editor, editorModule }) {
285
307
  />
286
308
  );
287
309
  } else if (kind === 'pxart') {
288
- body = <PxArtEditor path={path} text={text} onChange={onChange} files={files} readOnly={readOnly} />;
310
+ body = (
311
+ <PxArtEditor path={path} text={text} onChange={onChange} files={files} readOnly={readOnly} />
312
+ );
289
313
  } else if (kind === 'style') {
290
- body = <StyleEditor path={path} text={text} onChange={onChange} readOnly={readOnly} />;
314
+ body = (
315
+ <StyleEditor
316
+ path={path}
317
+ text={text}
318
+ onChange={onChange}
319
+ // Picking a font writes `fonts.generated.js` beside `theme.style`.
320
+ onChangeFile={onChangeFile}
321
+ readOnly={readOnly}
322
+ />
323
+ );
291
324
  } else if (kind === 'image') {
292
325
  // Viewers read their file's BYTES over the serve, not the text file map --
293
326
  // `files` holds source, and an image decoded as utf-8 is nothing.