castle-web-cli 0.4.142 → 0.4.145
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/agent-prompts.d.ts +1 -0
- package/dist/agent-prompts.js +7 -2
- package/dist/agent.js +11 -9
- package/dist/imports.js +44 -4
- package/dist/init.d.ts +4 -0
- package/dist/init.js +63 -26
- package/dist/install.js +4 -0
- package/dist/platformDoc.d.ts +12 -0
- package/dist/platformDoc.js +236 -0
- package/dist/serve.d.ts +3 -0
- package/dist/serve.js +157 -13
- package/dist/serveSecurity.d.ts +5 -1
- package/dist/serveSecurity.js +27 -8
- package/dist/shell/assets/index-BaiRLZ8p.css +1 -0
- package/dist/shell/assets/{index-qbygvQIx.js → index-CbRAepsq.js} +68 -68
- package/dist/shell/index.html +2 -2
- package/kits/blank/CLAUDE.md +198 -0
- package/kits/blank/castle.json +8 -0
- package/kits/blank/index.html +42 -0
- package/kits/blank/package-lock.json +10 -0
- package/kits/blank/package.json +9 -0
- package/kits/physics-2d/CLAUDE.md +44 -4
- package/kits/physics-2d/behaviors/Collider.jsx +21 -0
- package/kits/physics-2d/behaviors/Draggable.jsx +9 -0
- package/kits/physics-2d/behaviors/Layout.jsx +7 -0
- package/kits/physics-2d/behaviors/RigidBody.jsx +6 -0
- package/kits/physics-2d/behaviors/Sprite.jsx +9 -4
- package/kits/physics-2d/editors/BlueprintLibrary.jsx +64 -32
- package/kits/physics-2d/editors/NewBlueprintModal.jsx +69 -0
- package/kits/physics-2d/editors/PlayOnly.jsx +1 -1
- package/kits/physics-2d/editors/SceneEditor.jsx +333 -108
- package/kits/physics-2d/editors/SelectionOverlay.jsx +6 -2
- package/kits/physics-2d/editors/behaviorRegistry.js +78 -5
- package/kits/physics-2d/engine/SceneUI.jsx +2 -2
- package/kits/physics-2d/engine/blueprint.js +212 -15
- package/kits/physics-2d/engine/editorFlags.js +50 -0
- package/kits/physics-2d/engine/files.js +9 -0
- package/kits/physics-2d/engine/liveReload.js +16 -4
- package/kits/physics-2d/engine/panelPrefs.js +78 -0
- package/kits/physics-2d/engine/panelSorting.jsx +84 -0
- package/kits/physics-2d/engine/physics/PhysicsSystem.js +5 -2
- package/kits/physics-2d/engine/physics/matterBridge.js +12 -2
- package/kits/physics-2d/engine/scene.js +94 -3
- package/kits/physics-2d/engine/ui.jsx +157 -4
- package/kits/physics-2d/engine/ui.module.css +615 -1
- package/kits/physics-2d/package-lock.json +78 -1
- package/kits/physics-2d/package.json +4 -0
- package/kits/physics-3d/CLAUDE.md +2 -3
- package/package.json +1 -1
- package/dist/commonInstructions.d.ts +0 -1
- package/dist/commonInstructions.js +0 -26
- package/dist/shell/assets/index-CcVJjnL3.css +0 -1
package/dist/shell/index.html
CHANGED
|
@@ -10,8 +10,8 @@
|
|
|
10
10
|
<link rel="icon" type="image/png" sizes="32x32" href="/__castle/ide/favicon-32x32.png" />
|
|
11
11
|
<link rel="icon" type="image/png" sizes="16x16" href="/__castle/ide/favicon-16x16.png" />
|
|
12
12
|
<link rel="icon" href="/__castle/ide/favicon.ico" sizes="any" />
|
|
13
|
-
<script type="module" crossorigin src="/__castle/ide/assets/index-
|
|
14
|
-
<link rel="stylesheet" crossorigin href="/__castle/ide/assets/index-
|
|
13
|
+
<script type="module" crossorigin src="/__castle/ide/assets/index-CbRAepsq.js"></script>
|
|
14
|
+
<link rel="stylesheet" crossorigin href="/__castle/ide/assets/index-BaiRLZ8p.css">
|
|
15
15
|
</head>
|
|
16
16
|
<body>
|
|
17
17
|
<div id="root"></div>
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# blank kit
|
|
2
|
+
|
|
3
|
+
The authoring guide for a deck built on no framework -- a plain browser
|
|
4
|
+
project. This kit ships no code, only this document: `## Files` covers what the
|
|
5
|
+
deck holds, `## Editors` covers building a visual editor for a file type the
|
|
6
|
+
deck defines. The rules that hold for every Castle deck are the platform's, in
|
|
7
|
+
`.castle/docs/platform.md` (written by the serve at every start).
|
|
8
|
+
|
|
9
|
+
## Quick reference
|
|
10
|
+
|
|
11
|
+
<!-- Injected into Castle's create assistant every turn; keep this compact and factual. -->
|
|
12
|
+
|
|
13
|
+
- A plain browser project: `index.html` + `game.js` (an ES module) + `package.json` + `castle.json` (editor config). No kit: nothing in this deck comes from a framework, and there is no scene, behavior, sprite, or level format unless the deck defines one. Build directly with DOM, canvas, WebGL, React, Pixi, Three, or any installed package.
|
|
14
|
+
- `import { setup, initCard } from 'castle-web-sdk'`. Call `setup()` first, once; `initCard()` returns the element to render into (a React tree mounted at `#root` needs no `initCard`). Castle services — `Storage`, `SharedStorage`, `Leaderboard`, `Time`, `User`, `Haptics`, `Pass`, `Portal`, `Lifecycle` — come from the same package; the full reference is `node_modules/castle-web-sdk/README.md`.
|
|
15
|
+
- Vite serves and bundles the deck: ES modules, JSX, JSON, CSS and npm packages all work with no build step of your own — don't add one.
|
|
16
|
+
- Call `Lifecycle.ready()` once the first real frame is painted, so the Castle feed reveals the deck right away instead of after a timeout.
|
|
17
|
+
- There is no `check` script: verifying a change means the Play panel, the forwarded console in `.castle/logs.txt`, and `npm run screenshot` (needs a live panel; a canvas needs `preserveDrawingBuffer: true` or the capture is blank).
|
|
18
|
+
- Details: `## Files` and `## Editors` in this file (`imports/castle.blank/CLAUDE.md`). The rules every deck plays by -- the card, touch, assets and formats, imports, reloading -- are the platform's: `.castle/docs/platform.md`, written by the serve.
|
|
19
|
+
|
|
20
|
+
## Files
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
index.html entry page; loads game.js as a module
|
|
24
|
+
game.js the game (any layout of modules under it is fine)
|
|
25
|
+
package.json scripts + dependencies
|
|
26
|
+
castle.json editor config + import pins; gets a deckId on first save-deck
|
|
27
|
+
imports/ other decks this one imports, read-only. `castle.blank` (this
|
|
28
|
+
guide) is always here; `castle-web add-import` adds more
|
|
29
|
+
.castle/ runtime state: serve.json (the live serve), logs.txt (forwarded
|
|
30
|
+
console output), screenshots/
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`castle.json` → `editor`:
|
|
34
|
+
|
|
35
|
+
- `initialPanels` — what the workspace opens with (`files`, `playtest`).
|
|
36
|
+
- `visiblePaths` / `hiddenPaths` — the Files panel filter. `[]` shows every
|
|
37
|
+
file, which is a bare deck's default; nothing needs adding for new files to
|
|
38
|
+
appear.
|
|
39
|
+
- `fileTypes` — the deck's own file types; see `## Editors`.
|
|
40
|
+
- `defaultPlayFile` — what the play panel opens with. A bare deck has none: it
|
|
41
|
+
plays `index.html`.
|
|
42
|
+
|
|
43
|
+
Scripts: `npm run screenshot` captures the open page; `npm run save-deck`
|
|
44
|
+
publishes (the deck is then at `https://castle.xyz/d/<deckId>`) and also
|
|
45
|
+
photographs the running deck for its cover; `npm run restart` reloads every
|
|
46
|
+
panel (`.castle/docs/platform.md` says when not to).
|
|
47
|
+
|
|
48
|
+
## Editors
|
|
49
|
+
|
|
50
|
+
An editor is a visual authoring surface for a file type. This deck has none
|
|
51
|
+
built in — the code editor opens everything — but it can add its own: declare
|
|
52
|
+
a file type in `castle.json`, write one module, and have the entry answer the
|
|
53
|
+
editor route. The Files panel then opens that type in your editor with a
|
|
54
|
+
code/visual toggle. Reach for one when the deck accumulates content someone
|
|
55
|
+
will keep iterating on by hand — level layouts, dialogue, item or word
|
|
56
|
+
catalogs, tuning values — where editing raw JSON in the code editor is the
|
|
57
|
+
bottleneck.
|
|
58
|
+
|
|
59
|
+
### The three steps
|
|
60
|
+
|
|
61
|
+
1. **Declare the type** in `castle.json` under `editor.fileTypes`:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
"editor": {
|
|
65
|
+
"fileTypes": [
|
|
66
|
+
{ "ext": ".dialogue", "label": "Dialogue", "new": "New dialogue",
|
|
67
|
+
"icon": "file", "editor": "editors/DialogueEditor.js", "data": "json" }
|
|
68
|
+
]
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
These are ALL the fields that exist — do not invent others:
|
|
73
|
+
- `ext` — the extension, with the dot. One entry per extension. Pick one
|
|
74
|
+
that is the deck's own (`.dialogue`, `.levels`), not `.json`: a type
|
|
75
|
+
claims every file with that extension.
|
|
76
|
+
- `label` — display name in the tab and pickers.
|
|
77
|
+
- `new` — the entry in the Files panel's New menu; omit it and the type
|
|
78
|
+
can't be created there.
|
|
79
|
+
- `icon` — for that entry and the file's tree row, from the shell's set:
|
|
80
|
+
`globe`, `layer-group`, `code`, `file`, `image`, `music`, `film`. An
|
|
81
|
+
unknown name falls back to a generic icon.
|
|
82
|
+
- `editor` — the module that edits this type, as a path from the deck
|
|
83
|
+
root, under `editors/`. Omit it to leave the type to the code editor.
|
|
84
|
+
- `data` — how the file behaves when a module imports it: `"json"` (the
|
|
85
|
+
import yields the parsed object) or `"text"` (the raw string). Omit for
|
|
86
|
+
an ordinary JS module. See the gotcha below before relying on it.
|
|
87
|
+
- `unsupported` — a refusal: why this deck must NOT be built on this
|
|
88
|
+
format, shown when someone tries to upload one. Only for formats you
|
|
89
|
+
recognize and reject.
|
|
90
|
+
|
|
91
|
+
2. **Write the module** at the declared path. There is no host component
|
|
92
|
+
here, so the shape is yours; a default export that mounts into an element
|
|
93
|
+
is the simplest:
|
|
94
|
+
|
|
95
|
+
```js
|
|
96
|
+
// editors/DialogueEditor.js
|
|
97
|
+
const EMPTY = { lines: [] };
|
|
98
|
+
|
|
99
|
+
export default function mount(el, { path, text, onChange }) {
|
|
100
|
+
let doc;
|
|
101
|
+
try { doc = text.trim() ? JSON.parse(text) : EMPTY; } catch { doc = EMPTY; }
|
|
102
|
+
const save = (next) => onChange(JSON.stringify(next, null, 2));
|
|
103
|
+
// ...render doc into el, call save(next) on every edit...
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
3. **Answer the editor route in the entry.** The shell opens a declared type
|
|
108
|
+
as an iframe of the deck's own page at
|
|
109
|
+
`/index.html?file=<path>&editorModule=<module>`, so `game.js` has to branch
|
|
110
|
+
on `file` before it starts the game:
|
|
111
|
+
|
|
112
|
+
```js
|
|
113
|
+
import { setup, initCard, isEdit, writeFile, fileUrl } from 'castle-web-sdk';
|
|
114
|
+
|
|
115
|
+
const editors = import.meta.glob('./editors/*.js');
|
|
116
|
+
|
|
117
|
+
async function mountEditor(file, editorModule) {
|
|
118
|
+
const load = editors[`./${editorModule}`];
|
|
119
|
+
if (!load) throw new Error(`no editor module ${editorModule}`);
|
|
120
|
+
const [mod, text] = await Promise.all([load(), fetch(fileUrl(file)).then((r) => r.text())]);
|
|
121
|
+
let pending;
|
|
122
|
+
const onChange = (next) => {
|
|
123
|
+
clearTimeout(pending);
|
|
124
|
+
pending = setTimeout(() => writeFile(file, next), 300);
|
|
125
|
+
};
|
|
126
|
+
document.body.style.margin = '0';
|
|
127
|
+
mod.default(document.body, { path: file, text, onChange });
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
setup();
|
|
131
|
+
const params = new URLSearchParams(location.search);
|
|
132
|
+
const file = params.get('file');
|
|
133
|
+
if (isEdit() && file) {
|
|
134
|
+
mountEditor(file, params.get('editorModule'));
|
|
135
|
+
} else {
|
|
136
|
+
startGame(initCard());
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Read the file with `fetch(fileUrl(path))` and save it with
|
|
141
|
+
`writeFile(path, text)`, debounced — both are SDK calls that only work
|
|
142
|
+
while editing on the serve, which is the only place an editor runs. Load
|
|
143
|
+
the module through `import.meta.glob` so the bundler knows about it; a
|
|
144
|
+
dynamic `import(editorModule)` of a runtime string does not bundle. The
|
|
145
|
+
editor branch skips `initCard()`: it fills the panel, not a 5:7 card.
|
|
146
|
+
|
|
147
|
+
That's the whole integration. Nothing auto-reloads: the person opens the file
|
|
148
|
+
(or reloads its panel) when they are ready.
|
|
149
|
+
|
|
150
|
+
### Gotchas
|
|
151
|
+
|
|
152
|
+
- **Declare the glob and the mount function ABOVE the branch that calls them.**
|
|
153
|
+
A `const` is in its temporal dead zone until its own line runs, so a
|
|
154
|
+
`mountEditor(...)` called from higher up throws `Cannot access 'editors'
|
|
155
|
+
before initialization` the moment it reads the map -- the function hoists, the
|
|
156
|
+
`const` does not. Keep the dispatch last, as above.
|
|
157
|
+
- **A `new:`-created file starts EMPTY.** Your editor must render a sensible
|
|
158
|
+
default on empty text (as `EMPTY` above) and write the real document back
|
|
159
|
+
on first edit — a module that throws on `""` is a blank panel.
|
|
160
|
+
- **`data:` takes effect at serve start.** The serve reads the declared data
|
|
161
|
+
types once, when it starts — and `init` started it before your type
|
|
162
|
+
existed — so play code that `import`s a `.dialogue` file gets a parse error
|
|
163
|
+
until the serve process restarts. Either import the content as text and
|
|
164
|
+
parse it yourself (`import raw from './dialogue/main.dialogue?raw'`, or
|
|
165
|
+
`import.meta.glob('./dialogue/*.dialogue', { query: '?raw', import: 'default', eager: true })`
|
|
166
|
+
— no declaration needed, and it bundles), or declare `data` and accept that
|
|
167
|
+
the module import works after the next serve start. The editor route is
|
|
168
|
+
unaffected: it reads through `fileUrl`.
|
|
169
|
+
- **Editors are edit-time only.** They must never run in play, and play code
|
|
170
|
+
must never import from `editors/`. Keep logic both sides need (parsing,
|
|
171
|
+
defaults) in a plain module both import.
|
|
172
|
+
- **Reading media/binary files:** point an `<img>`/`<audio>` at
|
|
173
|
+
`fileUrl(path)`; `fetch(fileUrl(path))` is for text.
|
|
174
|
+
- **Design for a phone.** The editor renders in a panel that is often
|
|
175
|
+
phone-width. Touch first: direct tap/drag on the content, big hit targets,
|
|
176
|
+
no hover-only or keyboard-only affordances, no fixed-wide toolbars. Scroll
|
|
177
|
+
vertically inside the panel rather than overflowing it. The shell is dark;
|
|
178
|
+
nothing of its theme reaches the iframe, so set your own background and
|
|
179
|
+
text colors rather than inheriting the page default.
|
|
180
|
+
- **The code view stays reachable** (the tab's view toggle), so don't build
|
|
181
|
+
a raw-JSON fallback mode into the editor itself.
|
|
182
|
+
- **Imported editors.** If this deck imports another deck that declares a
|
|
183
|
+
type, the shell hands the entry that deck's module as
|
|
184
|
+
`editorModule=imports/<alias>/editors/...`. A second
|
|
185
|
+
`import.meta.glob('./imports/*/editors/*.{js,jsx}')` alongside the deck's
|
|
186
|
+
own lets the same dispatcher load it. `imports/` is read-only: to change an
|
|
187
|
+
imported editor, copy it into your own `editors/` and declare the same
|
|
188
|
+
`ext` yourself — the deck's own declaration wins.
|
|
189
|
+
|
|
190
|
+
### When to build one
|
|
191
|
+
|
|
192
|
+
Content the creator (or you) keeps returning to edit by hand — a catalog of
|
|
193
|
+
entities, level data, sequences, dialogue — earns an editor once it's clear
|
|
194
|
+
iteration will continue. Data that is written once, or generated by code,
|
|
195
|
+
stays code. A value that is tuned while playing belongs in the game's own UI
|
|
196
|
+
or a debug overlay, not in a file editor. Never let building one delay a
|
|
197
|
+
playable change the user asked for — it rides alongside, and it needs the
|
|
198
|
+
user's yes first.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html>
|
|
3
|
+
<head>
|
|
4
|
+
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
|
|
5
|
+
<meta name="color-scheme" content="dark" />
|
|
6
|
+
<title>blank kit</title>
|
|
7
|
+
<style>
|
|
8
|
+
html {
|
|
9
|
+
color-scheme: dark;
|
|
10
|
+
background: #0a0a0a;
|
|
11
|
+
}
|
|
12
|
+
body {
|
|
13
|
+
margin: 0;
|
|
14
|
+
height: 100vh;
|
|
15
|
+
display: flex;
|
|
16
|
+
flex-direction: column;
|
|
17
|
+
align-items: center;
|
|
18
|
+
justify-content: center;
|
|
19
|
+
gap: 12px;
|
|
20
|
+
font-family: system-ui, sans-serif;
|
|
21
|
+
color: #fff;
|
|
22
|
+
text-align: center;
|
|
23
|
+
padding: 24px;
|
|
24
|
+
box-sizing: border-box;
|
|
25
|
+
}
|
|
26
|
+
p {
|
|
27
|
+
margin: 0;
|
|
28
|
+
max-width: 22em;
|
|
29
|
+
color: #999;
|
|
30
|
+
font-size: 15px;
|
|
31
|
+
line-height: 1.5;
|
|
32
|
+
}
|
|
33
|
+
</style>
|
|
34
|
+
</head>
|
|
35
|
+
<body>
|
|
36
|
+
<h1>blank</h1>
|
|
37
|
+
<p>
|
|
38
|
+
The authoring guide for a Castle deck built on no framework. Decks import this for
|
|
39
|
+
<code>CLAUDE.md</code>; there is no code here to run.
|
|
40
|
+
</p>
|
|
41
|
+
</body>
|
|
42
|
+
</html>
|
|
@@ -22,14 +22,10 @@ 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
|
-
- **Supported media formats are exactly**: `.png` `.jpg` `.jpeg` `.gif` `.webp` `.svg` images, `.mp3` `.wav` `.m4a` audio, `.mp4` (H.264) video. Nothing else — a published deck inlines every asset as a `data:` URI, where the browser trusts the declared type instead of sniffing the bytes, so a format that merely works while serving (`.mov` is the classic case) can be dead once published. Convert, don't improvise.
|
|
26
25
|
- This kit is plain JavaScript. Use `.jsx` for files with JSX, `.js` otherwise; do not add TypeScript files or a new build step.
|
|
27
|
-
- Do not reload the deck after an edit. Nothing auto-reloads any more: the person applies your changes when they are ready, from the Play panel's restart button or a panel's own reload control.
|
|
28
26
|
- Space is reserved by the editor for play/stop; do not bind Space to gameplay.
|
|
29
27
|
- 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.
|
|
30
|
-
- The deck can define its own editors: declare a file type in `castle.json` (`editor.fileTypes`: ext, label, icon, and an `editors/` module) and the Files panel opens that type in it — whole recipe in `## Editors` below. Kit editors under `imports/` are read-only; add or fork, don't edit.
|
|
31
28
|
- An editor is for content FILES the creator keeps coming back to (catalogs, dialogue, level tables) that nothing already opens. Scenes, sprites and styles have editors; per-actor settings belong on behavior props in the inspector — not in a new editor.
|
|
32
|
-
- Unprompted, an editor is an offer, never a build: when the same data keeps getting edited by hand, propose one and build on the user's yes. Never during a first build.
|
|
33
29
|
- Details below: `## Behavior shape`, `## Scene file`, `## Blueprints`, `## Built-in behaviors`, `## Creating pixel art`, `## SceneRuntime API`, and `## Input shortcuts`.
|
|
34
30
|
|
|
35
31
|
## Editors
|
|
@@ -240,6 +236,17 @@ export class MyThing {
|
|
|
240
236
|
ui(actor, scene) {
|
|
241
237
|
return null;
|
|
242
238
|
}
|
|
239
|
+
|
|
240
|
+
// Optional. A one-line summary of this behavior's state, shown beside the
|
|
241
|
+
// title when its inspector panel is collapsed. Keep it short.
|
|
242
|
+
static summary(props) {
|
|
243
|
+
return `${props.speed}`;
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
// Optional. Fired when `$enabled` flips (see "Switching a behavior off").
|
|
247
|
+
// For letting go of anything held outside your own props.
|
|
248
|
+
onDisable(actor, scene) {}
|
|
249
|
+
onEnable(actor, scene) {}
|
|
243
250
|
}
|
|
244
251
|
```
|
|
245
252
|
|
|
@@ -260,6 +267,37 @@ A scene is a background plus a list of actors. Every actor is an **instance of a
|
|
|
260
267
|
}
|
|
261
268
|
```
|
|
262
269
|
|
|
270
|
+
### Switching a behavior off without losing its settings
|
|
271
|
+
|
|
272
|
+
Any component may carry `"$enabled": false` to stop the behavior running while
|
|
273
|
+
keeping every prop it has. Absent means on — never write `"$enabled": true`.
|
|
274
|
+
|
|
275
|
+
```json
|
|
276
|
+
"Slingshot": { "speed": 0.1, "maxDrag": 200, "$enabled": false }
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
Use this instead of deleting the component when the behavior should come back:
|
|
280
|
+
deleting it throws the configuration away, and re-adding it starts from
|
|
281
|
+
`defaultProps`. It merges per-property like any other prop, so a blueprint can
|
|
282
|
+
ship a behavior switched off and one instance turn it on.
|
|
283
|
+
|
|
284
|
+
**`$` marks a RESERVED property — one the engine owns, not a behavior.** Do not
|
|
285
|
+
name a behavior prop with a leading `$`, and do not expect one to appear in
|
|
286
|
+
`defaultProps` or the inspector's field list. The prefix exists because
|
|
287
|
+
behaviors come from decks and from imports, so any bare name the engine reserved
|
|
288
|
+
could already be in use somewhere — and a silent collision on a name like
|
|
289
|
+
`enabled` would switch somebody's behavior off rather than error. `$enabled` is
|
|
290
|
+
the only one today; the namespace is what makes adding another safe.
|
|
291
|
+
|
|
292
|
+
Disabling `Collider` is the big hammer: a body only exists for an actor with
|
|
293
|
+
one, so its `RigidBody`, `Joints` and controls all go inert with it. Disabling
|
|
294
|
+
`RigidBody` alone leaves the Collider as a static obstacle, which is what a lone
|
|
295
|
+
Collider already means.
|
|
296
|
+
|
|
297
|
+
A behavior can react to the transition with `onDisable(actor, scene)` /
|
|
298
|
+
`onEnable(actor, scene)` — for releasing something it was holding. `Draggable`
|
|
299
|
+
uses it to let go of a grab.
|
|
300
|
+
|
|
263
301
|
Rules: every actor needs a unique `id` (any string). An instance's `components` holds ONLY props that differ from its blueprint (merged per-property on top of the template); anything unspecified falls back to the blueprint, then to the behavior's `defaultProps`. Position (`Layout.x`/`y`/`rotation`) always lives on the instance. Omit optional fields (`z`, `rotation`, actor `name`, `tint: '#ffffffff'`, scene `name`) to keep scenes compact, especially when generating many actors.
|
|
264
302
|
|
|
265
303
|
## Blueprints
|
|
@@ -669,6 +707,8 @@ For HUD text use a behavior's `ui` hook (returns React); for in-world text or sh
|
|
|
669
707
|
|
|
670
708
|
## Don't
|
|
671
709
|
|
|
710
|
+
- Don't name a behavior prop with a leading `$` — the engine reserves that prefix (see `$enabled`).
|
|
711
|
+
|
|
672
712
|
- Don't `console.log` in tight loops — flood the serve log.
|
|
673
713
|
- Don't keep per-actor state on the behavior class instance; it's recreated each frame. Use `actor.runtime` or component props.
|
|
674
714
|
- Don't try to import from `editors/`; behaviors run in the play runtime too.
|
|
@@ -47,6 +47,12 @@ const SHAPE_DEFAULTS = {
|
|
|
47
47
|
},
|
|
48
48
|
};
|
|
49
49
|
|
|
50
|
+
// The pre-list spelling of the shape, still on decks authored before shapes
|
|
51
|
+
// became a list. Only consulted when there is no `shapes[0]` to ask.
|
|
52
|
+
function legacyShape(props) {
|
|
53
|
+
return typeof props.shape === 'string' && props.shape ? props.shape : 'box';
|
|
54
|
+
}
|
|
55
|
+
|
|
50
56
|
// The collider's shapes, materialized (default = one full box).
|
|
51
57
|
function currentShapes(component) {
|
|
52
58
|
return Array.isArray(component.shapes) && component.shapes.length > 0 ? component.shapes : [FULL_BOX];
|
|
@@ -100,6 +106,21 @@ export class Collider {
|
|
|
100
106
|
density: 0.001,
|
|
101
107
|
};
|
|
102
108
|
|
|
109
|
+
// Shape, and how many of them -- a compound collider's shape count is the
|
|
110
|
+
// thing you cannot see from the canvas without turning debug on.
|
|
111
|
+
static summary(props) {
|
|
112
|
+
const list = Array.isArray(props.shapes) ? props.shapes : [];
|
|
113
|
+
// A compound collider's shape COUNT is the thing you cannot see from the
|
|
114
|
+
// canvas without turning debug on, so it wins over naming one of them.
|
|
115
|
+
const shape =
|
|
116
|
+
list.length > 1
|
|
117
|
+
? `${list.length} shapes`
|
|
118
|
+
// `shapes[0].type` is where the shape lives now; `props.shape` is the
|
|
119
|
+
// pre-list spelling, still on decks authored before the change.
|
|
120
|
+
: list[0]?.type ?? legacyShape(props);
|
|
121
|
+
return props.isTrigger ? `${shape} · trigger` : shape;
|
|
122
|
+
}
|
|
123
|
+
|
|
103
124
|
// Inspector ranges. No `max` on any of these: matter treats them as open-ended
|
|
104
125
|
// (bounciness "can exceed 1" per the docs, and stiction above 1 is meaningful),
|
|
105
126
|
// and a max is a hard authoring ceiling here -- typed entry is clamped to it,
|
|
@@ -41,6 +41,15 @@ export class Draggable {
|
|
|
41
41
|
this.props = props;
|
|
42
42
|
}
|
|
43
43
|
|
|
44
|
+
// Switched off mid-drag, this is the only thing that can let go: `update` is
|
|
45
|
+
// the sole caller of `release`, and it stops running the moment the behavior
|
|
46
|
+
// is disabled. Without this the actor stays welded to the pointer.
|
|
47
|
+
onDisable(actor, scene) {
|
|
48
|
+
if (actor.runtime._dragPointerId == null) return;
|
|
49
|
+
scene.physics.release(actor);
|
|
50
|
+
actor.runtime._dragPointerId = null;
|
|
51
|
+
}
|
|
52
|
+
|
|
44
53
|
update(actor, scene) {
|
|
45
54
|
const rt = actor.runtime;
|
|
46
55
|
const held = rt._dragPointerId == null ? null : scene.pointers.get(rt._dragPointerId);
|
|
@@ -13,6 +13,13 @@ export class Layout {
|
|
|
13
13
|
debug: false,
|
|
14
14
|
};
|
|
15
15
|
|
|
16
|
+
// Position first: it is what tells two instances of the same blueprint apart,
|
|
17
|
+
// and the first thing you look for when the panel is shut.
|
|
18
|
+
static summary(props) {
|
|
19
|
+
const round = (n) => Math.round(Number(n) || 0);
|
|
20
|
+
return `${round(props.x)}, ${round(props.y)} · ${round(props.width)}×${round(props.height)}`;
|
|
21
|
+
}
|
|
22
|
+
|
|
16
23
|
// Position/rotation/z never inherit from a blueprint: they're always written
|
|
17
24
|
// as instance values at placement time (z gets an explicit top-of-stack value
|
|
18
25
|
// on spawn), and a blueprint edit to its own template x/y/z/rotation only
|
|
@@ -35,6 +35,12 @@ export class RigidBody {
|
|
|
35
35
|
angularVelocity: 0,
|
|
36
36
|
};
|
|
37
37
|
|
|
38
|
+
// Body type is the whole question about a rigid body: does this thing fall,
|
|
39
|
+
// sit still, or get pushed around by hand.
|
|
40
|
+
static summary(props) {
|
|
41
|
+
return typeof props.bodyType === 'string' ? props.bodyType : '';
|
|
42
|
+
}
|
|
43
|
+
|
|
38
44
|
// `drag`/`angularDrag` are matter's air friction, where values above 1 flip
|
|
39
45
|
// the velocity sign and destabilize the body -- so 1 is a real ceiling, not a
|
|
40
46
|
// convenience. `gravityScale` deliberately has none: negative is legitimate
|
|
@@ -38,6 +38,13 @@ export class Sprite {
|
|
|
38
38
|
tileSize: 50,
|
|
39
39
|
};
|
|
40
40
|
|
|
41
|
+
// The art's filename, without the folder -- `drawings/` is the same for
|
|
42
|
+
// nearly every sprite and the header has no room to spend on it.
|
|
43
|
+
static summary(props) {
|
|
44
|
+
const file = typeof props.file === 'string' ? props.file : '';
|
|
45
|
+
return file.split('/').pop() ?? '';
|
|
46
|
+
}
|
|
47
|
+
|
|
41
48
|
// Tile cell size in card units -- a floor of 1 (0 would divide by zero when
|
|
42
49
|
// laying out the repeat), no ceiling since a deck may tile larger than a card.
|
|
43
50
|
static propertyMeta = {
|
|
@@ -64,8 +71,7 @@ export class Sprite {
|
|
|
64
71
|
const sequence = frameSequence(sprite, tag);
|
|
65
72
|
const state = ensureAnimState(actor, sprite, this.props, sequence);
|
|
66
73
|
if (!this.props.playing) {
|
|
67
|
-
resetAnimState(state
|
|
68
|
-
state.frameIndex = 0;
|
|
74
|
+
if (state.done) resetAnimState(state);
|
|
69
75
|
return;
|
|
70
76
|
}
|
|
71
77
|
advanceAnim(state, sprite, sequence, tag, dt);
|
|
@@ -389,12 +395,11 @@ function ensureAnimState(actor, sprite, props, sequence) {
|
|
|
389
395
|
return state;
|
|
390
396
|
}
|
|
391
397
|
|
|
392
|
-
function resetAnimState(state
|
|
398
|
+
function resetAnimState(state) {
|
|
393
399
|
state.pos = 0;
|
|
394
400
|
state.elapsedMs = 0;
|
|
395
401
|
state.loops = 0;
|
|
396
402
|
state.done = false;
|
|
397
|
-
state.frameIndex = sequence[0];
|
|
398
403
|
}
|
|
399
404
|
|
|
400
405
|
// Advance the playhead by `dt` seconds, stepping frames by their durationMs and
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import React, { useEffect, useRef, useState } from 'react';
|
|
2
|
-
import { onArtLoaded, renderArtFrame } from '../engine/art';
|
|
2
|
+
import { isImageArt, onArtLoaded, renderArtFrame } from '../engine/art';
|
|
3
3
|
import { screenToCard } from '../engine/scene';
|
|
4
4
|
import { countBlueprintInstances, listBlueprints } from '../engine/blueprint';
|
|
5
|
-
import { ConfirmDialog, ContextMenu, cx, Icon, styles } from '../engine/ui';
|
|
5
|
+
import { ConfirmDialog, ContextMenu, cx, Icon, styles, useWheelToHorizontal } from '../engine/ui';
|
|
6
6
|
|
|
7
7
|
const DRAG_THRESHOLD = 4;
|
|
8
8
|
|
|
@@ -31,21 +31,8 @@ export function BlueprintLibrary({
|
|
|
31
31
|
const [contextMenu, setContextMenu] = useState(null);
|
|
32
32
|
const [confirmDelete, setConfirmDelete] = useState(null);
|
|
33
33
|
|
|
34
|
-
//
|
|
35
|
-
|
|
36
|
-
// React's onWheel so the listener is non-passive and can preventDefault.
|
|
37
|
-
useEffect(() => {
|
|
38
|
-
const bar = hotbarRef.current;
|
|
39
|
-
if (!bar) return undefined;
|
|
40
|
-
const onWheel = (event) => {
|
|
41
|
-
if (event.deltaY !== 0 && Math.abs(event.deltaY) > Math.abs(event.deltaX)) {
|
|
42
|
-
bar.scrollLeft += event.deltaY;
|
|
43
|
-
event.preventDefault();
|
|
44
|
-
}
|
|
45
|
-
};
|
|
46
|
-
bar.addEventListener('wheel', onWheel, { passive: false });
|
|
47
|
-
return () => bar.removeEventListener('wheel', onWheel);
|
|
48
|
-
}, []);
|
|
34
|
+
// Vertical wheel/trackpad pans the hotbar (see the hook for the direction).
|
|
35
|
+
useWheelToHorizontal(hotbarRef);
|
|
49
36
|
|
|
50
37
|
const onSlotContextMenu = (event, blueprint) => {
|
|
51
38
|
if (isPlaying) return;
|
|
@@ -121,7 +108,7 @@ export function BlueprintLibrary({
|
|
|
121
108
|
type="button"
|
|
122
109
|
className={styles.bpActionSlot}
|
|
123
110
|
aria-label="Add actor"
|
|
124
|
-
title="New blueprint"
|
|
111
|
+
title="New blueprint (hold Alt for a blank one)"
|
|
125
112
|
onClick={onAddActor}
|
|
126
113
|
disabled={isPlaying}>
|
|
127
114
|
<Icon name="plus" />
|
|
@@ -218,32 +205,77 @@ function BlueprintDragPreview({ preview, sprites }) {
|
|
|
218
205
|
);
|
|
219
206
|
}
|
|
220
207
|
|
|
221
|
-
|
|
208
|
+
// Asked of the CANVAS, not the source art: counting non-transparent grid chars
|
|
209
|
+
// would call a path-drawn sprite blank. Skipped for image art, whose native
|
|
210
|
+
// resolution is whatever was uploaded.
|
|
211
|
+
function rendersNothing(sprite, canvas) {
|
|
212
|
+
if (isImageArt(sprite)) return false;
|
|
213
|
+
try {
|
|
214
|
+
const ctx = canvas.getContext('2d', { willReadFrequently: true });
|
|
215
|
+
const { data } = ctx.getImageData(0, 0, canvas.width, canvas.height);
|
|
216
|
+
for (let i = 3; i < data.length; i += 4) if (data[i] !== 0) return false;
|
|
217
|
+
return true;
|
|
218
|
+
} catch {
|
|
219
|
+
// Tainted or zero-sized canvas: assume it draws something rather than
|
|
220
|
+
// mislabeling real art as blank.
|
|
221
|
+
return false;
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
// A blueprint's slot art, falling back to its NAME when there is nothing to
|
|
226
|
+
// show -- no Sprite, a file that doesn't resolve, or art that is entirely
|
|
227
|
+
// transparent (a "Draw new" sprite nobody has drawn in yet). Without it a belt
|
|
228
|
+
// of not-yet-drawn actors is a row of identical placeholders.
|
|
229
|
+
// `showName={false}` for callers that already print the name right beside the
|
|
230
|
+
// thumbnail (the creation modal's tiles) -- otherwise a sprite-less blueprint
|
|
231
|
+
// renders its name inside the tile AND under it, reading as "GoalGoal".
|
|
232
|
+
export function BlueprintThumbnail({ blueprint, sprites, preview = false, showName = true }) {
|
|
222
233
|
const canvasRef = useRef(null);
|
|
223
234
|
const spritePath = blueprint.components?.Sprite?.file;
|
|
224
235
|
const sprite = spritePath ? sprites?.[spritePath] : null;
|
|
225
236
|
// Thumbnails draw on change, not on a frame loop, so an image that finishes
|
|
226
237
|
// decoding after this rendered has to say so or the slot stays blank.
|
|
227
238
|
const [loadTick, setLoadTick] = useState(0);
|
|
239
|
+
const [blank, setBlank] = useState(false);
|
|
228
240
|
useEffect(() => onArtLoaded(() => setLoadTick((tick) => tick + 1)), []);
|
|
229
241
|
useEffect(() => {
|
|
230
242
|
const canvas = canvasRef.current;
|
|
231
243
|
if (!canvas || !sprite) return;
|
|
232
|
-
renderArtFrame(sprite, 0, canvas);
|
|
244
|
+
const drew = renderArtFrame(sprite, 0, canvas);
|
|
245
|
+
// `false` means "not here yet" (an image still loading), not blank.
|
|
246
|
+
if (drew !== false) setBlank(rendersNothing(sprite, canvas));
|
|
233
247
|
}, [sprite, loadTick]);
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
248
|
+
const name = showName && typeof blueprint.name === 'string' ? blueprint.name.trim() : '';
|
|
249
|
+
// The canvas stays mounted underneath, so art arriving later clears this.
|
|
250
|
+
// The inner span is load-bearing, not decoration: bare text inside a flex
|
|
251
|
+
// container becomes an anonymous item sized to max-content, so it never
|
|
252
|
+
// "overflows a line" and `overflow-wrap` never fires -- a long single-word
|
|
253
|
+
// name silently clipped at both edges instead of wrapping. A real child can
|
|
254
|
+
// be held to the box's width, which is what gives the wrap something to
|
|
255
|
+
// break against.
|
|
256
|
+
const label = name ? (
|
|
257
|
+
<span className={cx(styles.bpSlotName, preview && styles.bpSlotNamePreview)} title={name}>
|
|
258
|
+
<span className={styles.bpSlotNameText}>{name}</span>
|
|
259
|
+
</span>
|
|
260
|
+
) : (
|
|
261
|
+
<span className={styles.bpSlotFallback}>
|
|
262
|
+
<Icon name="clone" />
|
|
263
|
+
</span>
|
|
264
|
+
);
|
|
265
|
+
if (!sprite) return label;
|
|
241
266
|
return (
|
|
242
|
-
<
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
267
|
+
<span className={styles.bpSlotArt}>
|
|
268
|
+
<canvas
|
|
269
|
+
ref={canvasRef}
|
|
270
|
+
className={cx(
|
|
271
|
+
styles.bpSlotThumb,
|
|
272
|
+
preview && styles.bpPreviewThumb,
|
|
273
|
+
blank && styles.bpSlotThumbHidden
|
|
274
|
+
)}
|
|
275
|
+
aria-hidden="true"
|
|
276
|
+
/>
|
|
277
|
+
{blank ? label : null}
|
|
278
|
+
</span>
|
|
247
279
|
);
|
|
248
280
|
}
|
|
249
281
|
|