castle-web-cli 0.4.152 → 0.4.154
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/dist/castle-host/host.js +11 -3
- package/dist/castleJson.d.ts +1 -0
- package/dist/castleJson.js +14 -0
- package/dist/ide.js +4 -0
- package/dist/imports.js +18 -12
- package/dist/init.js +28 -12
- package/dist/platformDoc.js +68 -0
- package/dist/save-deck.js +14 -9
- package/dist/serve.js +24 -6
- package/dist/serveSecurity.d.ts +2 -0
- package/dist/serveSecurity.js +7 -4
- package/dist/shell/assets/{index-Dlhc3eZW.js → index-DsDkYFvP.js} +2 -2
- package/dist/shell/index.html +1 -1
- package/kits/blank/castle.json +1 -1
- package/kits/blank/node_modules/.package-lock.json +27 -0
- package/kits/blank/node_modules/castle-web-fonts/README.md +114 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/catalog.d.ts +18 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/catalog.js +142 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/face.d.ts +1 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/face.js +52 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Bore.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Bore.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/CourierPrime.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/CourierPrime.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/DMSans.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/DMSans.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Glacier.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Glacier.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Piazzolla.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Piazzolla.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Synco.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Synco.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Tektur.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/Tektur.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/YatraOne.d.ts +3 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/faces/YatraOne.js +10 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/index.d.ts +16 -0
- package/kits/blank/node_modules/castle-web-fonts/dist/index.js +15 -0
- package/kits/blank/node_modules/castle-web-fonts/licenses/CC-BY-ND-4.0.txt +393 -0
- package/kits/blank/node_modules/castle-web-fonts/licenses/FONTS.md +64 -0
- package/kits/blank/node_modules/castle-web-fonts/licenses/OFL-1.1.txt +95 -0
- package/kits/blank/node_modules/castle-web-fonts/package.json +47 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/Bore.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/CourierPrime.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/DMSans.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/Glacier.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/HelicoCentrica.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/Piazzolla.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/SOURCE.txt +2 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/Synco.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/Tektur.woff2 +0 -0
- package/kits/blank/node_modules/castle-web-fonts/woff2/YatraOne.woff2 +0 -0
- package/kits/blank/package-lock.json +25 -1
- package/kits/blank/package.json +4 -1
- package/kits/physics-2d/CLAUDE.md +158 -40
- package/kits/physics-2d/castle.json +3 -2
- package/kits/physics-2d/editors/SingleEditor.jsx +52 -19
- package/kits/physics-2d/editors/StyleEditor.jsx +139 -40
- package/kits/physics-2d/editors/deckFont.js +88 -0
- package/kits/physics-2d/editors/fontPreview.js +66 -0
- package/kits/physics-2d/editors/styleEditor.module.css +30 -3
- package/kits/physics-2d/editors/styleTheme.js +13 -2
- package/kits/physics-2d/engine/ScenePlayer.jsx +17 -2
- package/kits/physics-2d/engine/SceneUI.jsx +8 -0
- package/kits/physics-2d/engine/files.js +20 -9
- package/kits/physics-2d/engine/fonts.js +79 -0
- package/kits/physics-2d/engine/scene.js +6 -0
- package/kits/physics-2d/fonts.generated.js +9 -0
- package/kits/physics-2d/main.jsx +11 -0
- package/kits/physics-2d/package-lock.json +8 -1
- package/kits/physics-2d/package.json +1 -0
- package/kits/physics-2d/theme.style +2 -1
- package/kits/physics-3d/castle.json +1 -1
- package/kits/physics-3d/engine3d/PxModelEditor.jsx +3 -4
- package/kits/physics-3d/engine3d/Scene3DEditor.jsx +12 -8
- package/kits/physics-3d/engine3d/editorChrome.jsx +11 -6
- package/kits/physics-3d/engine3d/modelFiles.js +4 -5
- package/kits/physics-3d/package-lock.json +8 -1
- package/kits/physics-3d/package.json +1 -0
- package/kits/tabletop/.prettierrc +8 -0
- package/kits/tabletop/CLAUDE.md +309 -0
- package/kits/tabletop/castle.json +34 -0
- package/kits/tabletop/index.html +20 -0
- package/kits/tabletop/main.jsx +8 -0
- package/kits/tabletop/package-lock.json +341 -0
- package/kits/tabletop/package.json +29 -0
- package/kits/tabletop/room.js +269 -0
- package/kits/tabletop/testing.js +569 -0
- package/package.json +1 -1
- package/kits/blank/.castle/agent/children.json +0 -1
- package/kits/blank/.castle/agent/messages.json +0 -9
- package/kits/blank/.castle/agent/pending-sends.json +0 -1
- package/kits/blank/.castle/agent/tasks/index.md +0 -2
- package/kits/blank/.castle/docs/platform.md +0 -36
- package/kits/blank/node_modules/.vite/deps/_metadata.json +0 -8
- 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
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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 {
|
|
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
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
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
|
-
{
|
|
264
|
-
|
|
265
|
-
|
|
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();
|
|
353
|
-
actor.runtime.soundPlayer.stop();
|
|
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');
|
|
369
|
-
scene.sound.play('assets/sounds/hit.wav');
|
|
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();
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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-
|
|
135
|
+
"publishedVersion": "2026-08-30T21:21:40.235Z"
|
|
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
|
-
|
|
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({
|
|
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 =
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
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 =
|
|
310
|
+
body = (
|
|
311
|
+
<PxArtEditor path={path} text={text} onChange={onChange} files={files} readOnly={readOnly} />
|
|
312
|
+
);
|
|
289
313
|
} else if (kind === 'style') {
|
|
290
|
-
body =
|
|
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.
|