castle-web-cli 0.4.157 → 0.4.159
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-failures.d.ts +1 -0
- package/dist/agent-failures.js +6 -4
- package/dist/agent-prompts.js +4 -0
- package/dist/agent.d.ts +11 -0
- package/dist/agent.js +175 -15
- package/dist/bundle.js +8 -2
- package/dist/castle-host/host.js +4 -2
- package/dist/castleJson.js +6 -1
- package/dist/check.d.ts +1 -0
- package/dist/check.js +25 -0
- package/dist/devSessionServer.js +31 -7
- package/dist/imports.js +1 -19
- package/dist/index.js +15 -1
- package/dist/init.d.ts +2 -2
- package/dist/init.js +78 -42
- package/dist/mcpPlaytest.d.ts +1 -0
- package/dist/mcpPlaytest.js +182 -0
- package/dist/metering.d.ts +24 -0
- package/dist/metering.js +87 -0
- package/dist/sdkResolve.d.ts +3 -0
- package/dist/sdkResolve.js +55 -0
- package/dist/serve.js +50 -4
- package/dist/serverBundle.js +8 -3
- package/dist/shell/assets/{index-DsDkYFvP.js → index-DMSoTyXh.js} +64 -64
- package/dist/shell/assets/{index-DwezawBs.css → index-DfZmu3XC.css} +1 -1
- package/dist/shell/index.html +2 -2
- package/dist/vitePlugins.d.ts +1 -0
- package/dist/vitePlugins.js +20 -0
- package/kits/base/CLAUDE.md +196 -0
- package/kits/{blank → base}/castle.json +5 -2
- package/kits/base/editorHost.js +172 -0
- package/kits/{blank → base}/node_modules/.package-lock.json +3 -2
- package/kits/{blank → base}/package-lock.json +7 -4
- package/kits/{blank → base}/package.json +4 -2
- package/kits/base/sdk/README.md +569 -0
- package/kits/base/sdk/castle.d.ts +27 -0
- package/kits/base/sdk/castle.js +16 -0
- package/kits/base/sdk/commands.d.ts +181 -0
- package/kits/base/sdk/commands.js +16 -0
- package/kits/base/sdk/context.d.ts +17 -0
- package/kits/base/sdk/context.js +15 -0
- package/kits/base/sdk/errors.d.ts +22 -0
- package/kits/base/sdk/errors.js +16 -0
- package/kits/base/sdk/files.d.ts +15 -0
- package/kits/base/sdk/files.js +52 -0
- package/kits/base/sdk/haptics.d.ts +6 -0
- package/kits/base/sdk/haptics.js +36 -0
- package/kits/base/sdk/leaderboard.d.ts +26 -0
- package/kits/base/sdk/leaderboard.js +296 -0
- package/kits/base/sdk/lifecycle.d.ts +4 -0
- package/kits/base/sdk/lifecycle.js +13 -0
- package/kits/base/sdk/multiplayer.d.ts +43 -0
- package/kits/base/sdk/multiplayer.js +464 -0
- package/kits/base/sdk/multiplayerProtocol.d.ts +51 -0
- package/kits/base/sdk/multiplayerProtocol.js +5 -0
- package/kits/base/sdk/passes.d.ts +7 -0
- package/kits/base/sdk/passes.js +84 -0
- package/kits/base/sdk/portal.d.ts +7 -0
- package/kits/base/sdk/portal.js +35 -0
- package/kits/base/sdk/runtime.d.ts +62 -0
- package/kits/base/sdk/runtime.js +970 -0
- package/kits/base/sdk/saveQueue.d.ts +27 -0
- package/kits/base/sdk/saveQueue.js +205 -0
- package/kits/base/sdk/server/platformHandle.d.ts +25 -0
- package/kits/base/sdk/server/platformHandle.js +1 -0
- package/kits/base/sdk/server/wrapper.d.ts +28 -0
- package/kits/base/sdk/server/wrapper.js +109 -0
- package/kits/base/sdk/storage.d.ts +16 -0
- package/kits/base/sdk/storage.js +323 -0
- package/kits/base/sdk/time.d.ts +17 -0
- package/kits/base/sdk/time.js +120 -0
- package/kits/base/sdk/transport.d.ts +17 -0
- package/kits/base/sdk/transport.js +141 -0
- package/kits/base/sdk/types.d.ts +3 -0
- package/kits/base/sdk/types.js +1 -0
- package/kits/base/sdk/user.d.ts +10 -0
- package/kits/base/sdk/user.js +45 -0
- package/kits/multiplayer-2d/.prettierrc +5 -0
- package/kits/multiplayer-2d/CLAUDE.md +129 -0
- package/kits/multiplayer-2d/behaviors/Box.jsx +92 -0
- package/kits/multiplayer-2d/behaviors/Player.jsx +86 -0
- package/kits/multiplayer-2d/blueprints/crate.scene +13 -0
- package/kits/multiplayer-2d/blueprints/other-player.scene +13 -0
- package/kits/multiplayer-2d/blueprints/player.scene +15 -0
- package/kits/multiplayer-2d/blueprints/wall.scene +12 -0
- package/kits/multiplayer-2d/castle.json +39 -0
- package/kits/multiplayer-2d/code/client/avatars.js +93 -0
- package/kits/multiplayer-2d/code/client/poses.js +168 -0
- package/kits/multiplayer-2d/code/server/index.js +26 -0
- package/kits/multiplayer-2d/code/server/limits.js +99 -0
- package/kits/multiplayer-2d/code/server/ownership.js +177 -0
- package/kits/multiplayer-2d/code/server/players.js +127 -0
- package/kits/multiplayer-2d/code/server/sceneBodies.js +98 -0
- package/kits/multiplayer-2d/code/server/world.js +337 -0
- package/kits/multiplayer-2d/code/systems/multiplayer.js +424 -0
- package/kits/multiplayer-2d/eslint.config.js +21 -0
- package/kits/multiplayer-2d/fonts.generated.js +9 -0
- package/kits/multiplayer-2d/index.html +25 -0
- package/kits/multiplayer-2d/main.jsx +10 -0
- package/kits/multiplayer-2d/package-lock.json +351 -0
- package/kits/multiplayer-2d/package.json +30 -0
- package/kits/multiplayer-2d/scenes/main.scene +20 -0
- package/kits/multiplayer-2d/test/two-client-test.mjs +341 -0
- package/kits/multiplayer-2d/theme.style +4 -0
- package/kits/multiplayer-3d/.prettierrc +5 -0
- package/kits/multiplayer-3d/CLAUDE.md +215 -0
- package/kits/multiplayer-3d/blueprints/ball.scene +21 -0
- package/kits/multiplayer-3d/blueprints/other-player.scene +21 -0
- package/kits/multiplayer-3d/castle.json +43 -0
- package/kits/multiplayer-3d/code/client/avatars.js +136 -0
- package/kits/multiplayer-3d/code/client/nameTags.js +101 -0
- package/kits/multiplayer-3d/code/client/poses.js +220 -0
- package/kits/multiplayer-3d/code/server/index.js +23 -0
- package/kits/multiplayer-3d/code/server/limits.js +107 -0
- package/kits/multiplayer-3d/code/server/ownership.js +157 -0
- package/kits/multiplayer-3d/code/server/players.js +114 -0
- package/kits/multiplayer-3d/code/server/sceneBodies.js +88 -0
- package/kits/multiplayer-3d/code/server/world.js +306 -0
- package/kits/multiplayer-3d/code/systems/multiplayer.js +427 -0
- package/kits/multiplayer-3d/eslint.config.js +20 -0
- package/kits/multiplayer-3d/fonts.generated.js +9 -0
- package/kits/multiplayer-3d/index.html +22 -0
- package/kits/multiplayer-3d/main.jsx +9 -0
- package/kits/multiplayer-3d/package-lock.json +368 -0
- package/kits/multiplayer-3d/package.json +32 -0
- package/kits/multiplayer-3d/scenes/main.scene +409 -0
- package/kits/multiplayer-3d/theme.style +3 -0
- package/kits/physics-2d/CLAUDE.md +6 -0
- package/kits/physics-2d/castle.json +7 -1
- package/kits/physics-2d/editors/behaviorRegistry.js +5 -0
- package/kits/physics-2d/editors/editorRegistry.jsx +3 -1
- package/kits/physics-2d/engine/files.js +9 -5
- package/kits/physics-2d/engine/systemRegistry.js +2 -0
- package/kits/physics-2d/engine/ui.module.css +11 -0
- package/kits/physics-2d/package-lock.json +8 -2
- package/kits/physics-2d/package.json +2 -2
- package/kits/physics-3d/CLAUDE.md +4 -4
- package/kits/physics-3d/behaviors/Shape.jsx +1 -1
- package/kits/physics-3d/blueprints/crate.scene +1 -1
- package/kits/physics-3d/blueprints/door.scene +4 -4
- package/kits/physics-3d/blueprints/pillar.scene +1 -1
- package/kits/physics-3d/blueprints/platform.scene +1 -1
- package/kits/physics-3d/blueprints/statue.scene +1 -1
- package/kits/physics-3d/blueprints/wall.scene +1 -1
- package/kits/physics-3d/castle.json +8 -11
- package/kits/physics-3d/docs/pxmodel-format.md +1 -1
- package/kits/physics-3d/engine3d/materials.js +3 -3
- package/kits/physics-3d/engine3d/modelFiles.js +4 -2
- package/kits/physics-3d/engine3d/world3d.js +1 -1
- package/kits/physics-3d/fonts.generated.js +9 -0
- package/kits/physics-3d/main.jsx +1 -1
- package/kits/physics-3d/package-lock.json +85 -2
- package/kits/physics-3d/package.json +6 -2
- package/kits/physics-3d/scenes/main.scene +1 -1
- package/kits/physics-3d/scenes/model-lab.scene +1 -1
- package/kits/real-time/.prettierrc +5 -0
- package/kits/real-time/CLAUDE.md +60 -0
- package/kits/real-time/castle.json +19 -0
- package/kits/real-time/code/client/clock.js +68 -0
- package/kits/real-time/code/client/connection.js +134 -0
- package/kits/real-time/code/client/gameHooks.js +50 -0
- package/kits/real-time/code/client/interpolate.js +82 -0
- package/kits/real-time/code/client/messages.js +55 -0
- package/kits/real-time/code/client/ownership.js +94 -0
- package/kits/real-time/code/client/smooth.js +54 -0
- package/kits/real-time/code/server/blockDelta.js +48 -0
- package/kits/real-time/code/server/gameHooks.js +47 -0
- package/kits/real-time/code/server/limits.js +35 -0
- package/kits/real-time/code/server/session.js +251 -0
- package/kits/real-time/eslint.config.js +22 -0
- package/kits/real-time/index.html +45 -0
- package/kits/real-time/package.json +14 -0
- package/kits/{tabletop → turn-based}/CLAUDE.md +42 -49
- package/kits/turn-based/blueprints/board.scene +15 -0
- package/kits/turn-based/blueprints/square.scene +25 -0
- package/kits/turn-based/castle.json +37 -0
- package/kits/turn-based/code/behaviors/Board.jsx +169 -0
- package/kits/turn-based/code/behaviors/Square.jsx +26 -0
- package/kits/turn-based/code/server/index.js +152 -0
- package/kits/turn-based/drawings/square.sprite +25 -0
- package/kits/turn-based/eslint.config.js +12 -0
- package/kits/turn-based/fonts.generated.js +9 -0
- package/kits/{tabletop → turn-based}/index.html +5 -3
- package/kits/{tabletop → turn-based}/main.jsx +2 -2
- package/kits/{tabletop → turn-based}/package-lock.json +17 -4
- package/kits/{tabletop → turn-based}/package.json +5 -2
- package/kits/turn-based/room.js +289 -0
- package/kits/turn-based/scenes/main.scene +227 -0
- package/kits/{tabletop → turn-based}/testing.js +131 -99
- package/kits/turn-based/theme.style +3 -0
- package/package.json +1 -1
- package/kits/blank/CLAUDE.md +0 -198
- package/kits/tabletop/castle.json +0 -34
- package/kits/tabletop/room.js +0 -269
- /package/kits/{blank → base}/index.html +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/README.md +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/catalog.d.ts +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/catalog.js +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/face.d.ts +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/face.js +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Bore.d.ts +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Bore.js +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/CourierPrime.d.ts +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/CourierPrime.js +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/DMSans.d.ts +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/DMSans.js +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Glacier.d.ts +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Glacier.js +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.d.ts +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/HelicoCentrica.js +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Piazzolla.d.ts +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Piazzolla.js +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Synco.d.ts +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Synco.js +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Tektur.d.ts +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/Tektur.js +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/YatraOne.d.ts +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/faces/YatraOne.js +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/index.d.ts +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/dist/index.js +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/licenses/CC-BY-ND-4.0.txt +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/licenses/FONTS.md +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/licenses/OFL-1.1.txt +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/package.json +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Bore.woff2 +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/CourierPrime.woff2 +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/DMSans.woff2 +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Glacier.woff2 +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/HelicoCentrica.woff2 +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Piazzolla.woff2 +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/SOURCE.txt +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Synco.woff2 +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/Tektur.woff2 +0 -0
- /package/kits/{blank → base}/node_modules/castle-web-fonts/woff2/YatraOne.woff2 +0 -0
- /package/kits/physics-3d/drawings/{crate.pxart → crate.sprite} +0 -0
- /package/kits/physics-3d/drawings/{door-edge.pxart → door-edge.sprite} +0 -0
- /package/kits/physics-3d/drawings/{door.pxart → door.sprite} +0 -0
- /package/kits/physics-3d/drawings/{face.pxart → face.sprite} +0 -0
- /package/kits/physics-3d/drawings/{floor.pxart → floor.sprite} +0 -0
- /package/kits/physics-3d/drawings/{platform.pxart → platform.sprite} +0 -0
- /package/kits/physics-3d/drawings/{statue.pxart → statue.sprite} +0 -0
- /package/kits/physics-3d/drawings/{wall.pxart → wall.sprite} +0 -0
- /package/kits/{tabletop → turn-based}/.prettierrc +0 -0
package/dist/vitePlugins.js
CHANGED
|
@@ -3,6 +3,7 @@ import * as fs from 'fs';
|
|
|
3
3
|
import { IMPORTS_DIR } from './imports.js';
|
|
4
4
|
import { importedPathForFork, resolveForkedFile } from './forks.js';
|
|
5
5
|
import { dataModeOf, resolveFileTypes } from './editorConfig.js';
|
|
6
|
+
import { resolveSdkSpecifier } from './sdkResolve.js';
|
|
6
7
|
// Mirrors castle-web-sdk's IMPORTS_PREFIX, which is the definition deck code
|
|
7
8
|
// uses. Duplicated rather than imported: the CLI compiles under node16 module
|
|
8
9
|
// resolution and the SDK's published types don't, and one short string is not
|
|
@@ -69,6 +70,25 @@ export function importsAliasPlugin() {
|
|
|
69
70
|
},
|
|
70
71
|
};
|
|
71
72
|
}
|
|
73
|
+
// `castle-web-sdk` is a file of the deck's `base` import now, not a package in
|
|
74
|
+
// node_modules. Resolving the bare specifier here rather than rewriting every
|
|
75
|
+
// deck means the move costs nothing already written: the same import line keeps
|
|
76
|
+
// working, and a deck with no provider still resolves it the old way (return
|
|
77
|
+
// null and vite goes on to node resolution).
|
|
78
|
+
//
|
|
79
|
+
// Registered for the dev server, the deck bundler AND the server bundler, for
|
|
80
|
+
// the reason importsAliasPlugin is: a specifier that resolves in one and not
|
|
81
|
+
// the others is a deck that plays in the editor and breaks when it ships.
|
|
82
|
+
export function sdkAliasPlugin() {
|
|
83
|
+
return {
|
|
84
|
+
name: 'castle-sdk-alias',
|
|
85
|
+
enforce: 'pre',
|
|
86
|
+
resolveId(source) {
|
|
87
|
+
const root = this.environment?.config?.root ?? process.cwd();
|
|
88
|
+
return resolveSdkSpecifier(root, source);
|
|
89
|
+
},
|
|
90
|
+
};
|
|
91
|
+
}
|
|
72
92
|
// `<path>?raw` -> ['<path>', '?raw']; no query -> ['<path>', ''].
|
|
73
93
|
function splitQuery(id) {
|
|
74
94
|
const at = id.indexOf('?');
|
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
# base kit
|
|
2
|
+
|
|
3
|
+
The Castle SDK and the authoring guide every deck is written against. Every
|
|
4
|
+
deck imports this one -- a deck built on no framework, and a deck built on a
|
|
5
|
+
framework kit, which imports it in turn. It ships the SDK (`sdk/`), the editor
|
|
6
|
+
host a deck with no kit mounts its editors through (`editorHost.js`), and this
|
|
7
|
+
document.
|
|
8
|
+
|
|
9
|
+
Nothing here describes what a particular deck is made of. A deck's own
|
|
10
|
+
`CLAUDE.md` says whether it has a framework; a framework kit's guide says what
|
|
11
|
+
that framework provides. This one is true either way.
|
|
12
|
+
|
|
13
|
+
## Quick reference
|
|
14
|
+
|
|
15
|
+
<!-- Injected into Castle's create assistant every turn; keep this compact and factual. -->
|
|
16
|
+
|
|
17
|
+
- `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`, `Multiplayer`, `Lifecycle` — come from the same package; the full reference is `imports/castle.base/sdk/README.md`.
|
|
18
|
+
- The SDK is a file of this import, not an npm package: `castle-web-sdk` resolves here. Nothing needs installing, and nothing in a deck's `package.json` names it.
|
|
19
|
+
- 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.
|
|
20
|
+
- Details: `## Files`, `## Editors` and `## The SDK` in this file (`imports/castle.base/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.
|
|
21
|
+
|
|
22
|
+
## The SDK
|
|
23
|
+
|
|
24
|
+
`castle-web-sdk` is how a deck reaches Castle: saved data, leaderboards, the
|
|
25
|
+
signed-in player, server time, haptics, passes, portals, multiplayer, and the
|
|
26
|
+
card the deck draws into. It resolves to `imports/castle.base/sdk/`, so the
|
|
27
|
+
import line is the same wherever the deck runs and there is nothing to install.
|
|
28
|
+
|
|
29
|
+
The API reference is `imports/castle.base/sdk/README.md` -- read it when you
|
|
30
|
+
need a service; it is too long to keep in context, and every entry point is
|
|
31
|
+
named in the bullet above.
|
|
32
|
+
|
|
33
|
+
The three calls almost every deck makes:
|
|
34
|
+
|
|
35
|
+
- `setup()` — once, before anything else. Mounts the 5:7 Castle card and, while
|
|
36
|
+
serving locally, forwards `console` output to the CLI.
|
|
37
|
+
- `initCard()` — the element to draw into, when the deck renders into a
|
|
38
|
+
`<canvas>` or raw DOM rather than a React tree at `#root`.
|
|
39
|
+
- `Lifecycle.ready()` — after the first real frame paints, so the feed reveals
|
|
40
|
+
the deck immediately instead of waiting out a timeout. A framework kit already
|
|
41
|
+
fires this; a deck rendering for itself has to.
|
|
42
|
+
|
|
43
|
+
## Files
|
|
44
|
+
|
|
45
|
+
```text
|
|
46
|
+
index.html entry page
|
|
47
|
+
package.json scripts + any npm package the deck adds
|
|
48
|
+
castle.json editor config + import pins; gets a deckId on first save-deck
|
|
49
|
+
imports/ other decks this one imports, read-only. `castle.base` (this
|
|
50
|
+
one) is always here; `castle-web add-import` adds more
|
|
51
|
+
.castle/ runtime state: serve.json (the live serve), logs.txt (forwarded
|
|
52
|
+
console output), screenshots/
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`castle.json` → `editor`:
|
|
56
|
+
|
|
57
|
+
- `initialPanels` — what the workspace opens with (`files`, `playtest`,
|
|
58
|
+
`editor`).
|
|
59
|
+
- `visiblePaths` / `hiddenPaths` — the Files panel filter. `[]` shows every
|
|
60
|
+
file; a deck that lists paths has to add new content directories to it or
|
|
61
|
+
they never appear.
|
|
62
|
+
- `fileTypes` — the deck's own file types; see `## Editors`.
|
|
63
|
+
- `defaultPlayFile` — what the play panel opens with. A deck that declares none
|
|
64
|
+
just loads `index.html`.
|
|
65
|
+
|
|
66
|
+
Scripts: `npm run check` bundles the deck (the same build `save-deck` runs);
|
|
67
|
+
`npm run screenshot` captures the open page; `npm run save-deck` publishes (the
|
|
68
|
+
deck is then at `https://castle.xyz/d/<deckId>`) and also photographs the
|
|
69
|
+
running deck for its cover; `npm run restart` reloads every panel
|
|
70
|
+
(`.castle/docs/platform.md` says when not to).
|
|
71
|
+
|
|
72
|
+
## Editors
|
|
73
|
+
|
|
74
|
+
An editor is a visual authoring surface for a file type. A deck can add one for
|
|
75
|
+
a type it defines: declare the type in `castle.json`, write one module under
|
|
76
|
+
`editors/`. The Files panel then opens that type in your editor with a
|
|
77
|
+
code/visual toggle. Reach for one when the deck accumulates content someone
|
|
78
|
+
will keep iterating on by hand — level layouts, dialogue, item or word
|
|
79
|
+
catalogs, tuning values — where editing raw JSON in the code editor is the
|
|
80
|
+
bottleneck.
|
|
81
|
+
|
|
82
|
+
### The two steps
|
|
83
|
+
|
|
84
|
+
1. **Declare the type** in the deck's own `castle.json` under
|
|
85
|
+
`editor.fileTypes`:
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
"editor": {
|
|
89
|
+
"fileTypes": [
|
|
90
|
+
{ "ext": ".dialogue", "label": "Dialogue", "new": "New dialogue",
|
|
91
|
+
"icon": "file", "editor": "editors/DialogueEditor.js", "data": "json" }
|
|
92
|
+
]
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
These are ALL the fields that exist — do not invent others:
|
|
97
|
+
- `ext` — the extension, with the dot. One entry per extension. Pick one
|
|
98
|
+
that is the deck's own (`.dialogue`, `.levels`), not `.json`: a type
|
|
99
|
+
claims every file with that extension.
|
|
100
|
+
- `label` — display name in the tab and pickers.
|
|
101
|
+
- `new` — the entry in the Files panel's New menu; omit it and the type
|
|
102
|
+
can't be created there.
|
|
103
|
+
- `icon` — for that entry and the file's tree row, from the shell's set:
|
|
104
|
+
`globe`, `layer-group`, `code`, `file`, `image`, `music`, `film`. An
|
|
105
|
+
unknown name falls back to a generic icon.
|
|
106
|
+
- `editor` — the module that edits this type, as a path from the deck
|
|
107
|
+
root, and it MUST live under `editors/` (that directory is the only place
|
|
108
|
+
the registry glob looks). Omit it to leave the type to the code editor.
|
|
109
|
+
(The value `"kit"` is legacy — always name the module.)
|
|
110
|
+
- `data` — how the file behaves when a module imports it: `"json"` (the
|
|
111
|
+
import yields the parsed object) or `"text"` (the raw string). Omit for
|
|
112
|
+
an ordinary JS module. See the gotchas before relying on it.
|
|
113
|
+
- `unsupported` — a refusal: why this deck must NOT be built on this
|
|
114
|
+
format, shown when someone tries to upload one. Only for formats you
|
|
115
|
+
recognize and reject.
|
|
116
|
+
|
|
117
|
+
2. **Write the module** at the declared path. It is handed the file and a way
|
|
118
|
+
to save it; how it renders is yours.
|
|
119
|
+
|
|
120
|
+
```js
|
|
121
|
+
// editors/DialogueEditor.js
|
|
122
|
+
const EMPTY = { lines: [] };
|
|
123
|
+
|
|
124
|
+
export default function mount(el, { path, text, onChange }) {
|
|
125
|
+
let doc;
|
|
126
|
+
try { doc = text.trim() ? JSON.parse(text) : EMPTY; } catch { doc = EMPTY; }
|
|
127
|
+
const save = (next) => onChange(JSON.stringify(next, null, 2));
|
|
128
|
+
// ...render doc into el, call save(next) on every edit...
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Props: `path` (deck-relative file path), `text` (current file text),
|
|
133
|
+
`onChange(nextText)` (replaces the whole file — the host debounces the write,
|
|
134
|
+
retries it, and flushes before a reload, so call it on every edit and don't
|
|
135
|
+
build your own save button), `onChangeFile(path, nextText)` (the same for
|
|
136
|
+
another file, e.g. a sub-document), and `readOnly` (true for an imported
|
|
137
|
+
file this deck hasn't forked — lock the UI rather than collecting edits that
|
|
138
|
+
can't be saved).
|
|
139
|
+
|
|
140
|
+
That's the whole integration: no entry-point changes and no registration call.
|
|
141
|
+
A deck scaffolded by `init` already routes the editor request to the host
|
|
142
|
+
(`mountEditorRoute` in `game.js`), and a deck on a framework kit is routed by
|
|
143
|
+
its kit. A **framework kit may hand your module a different shape** — physics-2d
|
|
144
|
+
renders it as a React component with the same props — so check that kit's
|
|
145
|
+
`## Editors` when the deck has one.
|
|
146
|
+
|
|
147
|
+
### Gotchas
|
|
148
|
+
|
|
149
|
+
- **A `new:`-created file starts EMPTY.** Your editor must render a sensible
|
|
150
|
+
default on empty text (as `EMPTY` above) and write the real document back
|
|
151
|
+
on first edit — a module that throws on `""` is a blank panel.
|
|
152
|
+
- **`data:` takes effect at serve start.** The serve reads the declared data
|
|
153
|
+
types once, when it starts — and `init` started it before your type
|
|
154
|
+
existed — so play code that `import`s a `.dialogue` file gets a parse error
|
|
155
|
+
until the serve process restarts. Either import the content as text and
|
|
156
|
+
parse it yourself (`import raw from './dialogue/main.dialogue?raw'`, or
|
|
157
|
+
`import.meta.glob('./dialogue/*.dialogue', { query: '?raw', import: 'default', eager: true })`
|
|
158
|
+
— no declaration needed, and it bundles), or declare `data` and accept that
|
|
159
|
+
the module import works after the next serve start. The editor route is
|
|
160
|
+
unaffected: it reads the file over the serve.
|
|
161
|
+
- **Play code reads your file by importing it** —
|
|
162
|
+
`import lines from './dialogue/main.dialogue'`, which yields the parsed object
|
|
163
|
+
for `"data": "json"` and the raw string for `"text"`. That import is what
|
|
164
|
+
carries the file into a published deck, so it is the right thing to write; it
|
|
165
|
+
is also frozen at page load, so a run picks up an edit when Play starts a
|
|
166
|
+
fresh run, not while one is going.
|
|
167
|
+
- **Editors are edit-time only.** They must never run in play, and play code
|
|
168
|
+
must never import from `editors/`. Keep logic both sides need (parsing,
|
|
169
|
+
defaults) in a plain module both import.
|
|
170
|
+
- **A brand-new editor module is not in the registry glob until the panel
|
|
171
|
+
reloads** — the person's next reload picks it up; do not force one.
|
|
172
|
+
- **Reading media/binary files:** point an `<img>`/`<audio>` at
|
|
173
|
+
`fileUrl(path)` from `castle-web-sdk`; the `text` prop 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.
|
|
178
|
+
- **The code view stays reachable** (the tab's view toggle), so don't build
|
|
179
|
+
a raw-JSON fallback mode into the editor itself.
|
|
180
|
+
- **Imported editors.** A type declared by a deck this one imports resolves to
|
|
181
|
+
that deck's module, and the registry reaches it — nothing to wire. `imports/`
|
|
182
|
+
is read-only: to change an imported editor, `castle-web fork-import-file` it
|
|
183
|
+
or declare the same `ext` yourself pointing at your own module. The deck's own
|
|
184
|
+
declaration wins.
|
|
185
|
+
|
|
186
|
+
### When to build one
|
|
187
|
+
|
|
188
|
+
Content the creator (or you) keeps returning to edit by hand — a catalog of
|
|
189
|
+
entities, level data, sequences, dialogue — earns an editor once it's clear
|
|
190
|
+
iteration will continue. Data that is written once, or generated by code,
|
|
191
|
+
stays code. A value that is tuned while playing belongs in the game's own UI
|
|
192
|
+
or a debug overlay, not in a file editor. Content a framework kit already opens
|
|
193
|
+
(its scenes, its art) does not need another editor around it, and a per-instance
|
|
194
|
+
setting belongs on the thing it configures, not in a file. Never let building
|
|
195
|
+
one delay a playable change the user asked for — it rides alongside, and it
|
|
196
|
+
needs the user's yes first.
|
|
@@ -4,8 +4,11 @@
|
|
|
4
4
|
"visiblePaths": []
|
|
5
5
|
},
|
|
6
6
|
"autoUpdateWhenImported": true,
|
|
7
|
-
"title": "
|
|
7
|
+
"title": "base",
|
|
8
8
|
"deckId": "yRcmH4_aYllE",
|
|
9
9
|
"cardId": "zkFdingmIm3m",
|
|
10
|
-
"publishedVersion": "2026-
|
|
10
|
+
"publishedVersion": "2026-09-02T03:33:34.585Z",
|
|
11
|
+
"provides": [
|
|
12
|
+
"castle-web-sdk"
|
|
13
|
+
]
|
|
11
14
|
}
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
// The editor route, for a deck that has no kit to answer it.
|
|
2
|
+
//
|
|
3
|
+
// The shell opens a declared file type as an iframe of the deck's own page at
|
|
4
|
+
// `/index.html?file=<path>&editorModule=<module>`, so something in the deck has
|
|
5
|
+
// to notice that and mount an editor instead of the game. That used to be ~25
|
|
6
|
+
// lines every bare deck wrote by hand -- a glob, a fetch, a debounce, a save --
|
|
7
|
+
// each copy a chance to get the ordering or the read-only rule wrong. It lives
|
|
8
|
+
// here instead, so a deck's entry is one line and an editor module is the same
|
|
9
|
+
// shape it is in a kit deck.
|
|
10
|
+
//
|
|
11
|
+
// Deliberately framework-free: a deck built on nothing should not acquire React
|
|
12
|
+
// to open a file. An editor module mounts into an element; the props it gets are
|
|
13
|
+
// named as a kit's are, so what you learn writing one carries over.
|
|
14
|
+
|
|
15
|
+
import {
|
|
16
|
+
fileUrl,
|
|
17
|
+
flushSaves,
|
|
18
|
+
isEdit,
|
|
19
|
+
isImportedFile,
|
|
20
|
+
onBeforeRestart,
|
|
21
|
+
onSaveState,
|
|
22
|
+
writeFile,
|
|
23
|
+
} from 'castle-web-sdk';
|
|
24
|
+
|
|
25
|
+
// Absolute patterns, so they resolve from the DECK root even though this file
|
|
26
|
+
// lives under `imports/`. That is what lets one registry reach the deck's own
|
|
27
|
+
// editors and every import's. A static glob rather than `import(modulePath)`:
|
|
28
|
+
// the specifier has to be static to survive bundling into a published deck.
|
|
29
|
+
const modules = {
|
|
30
|
+
...import.meta.glob('/imports/*/editors/**/*.{js,jsx}'),
|
|
31
|
+
...import.meta.glob('/imports/*/code/editors/**/*.{js,jsx}'),
|
|
32
|
+
...import.meta.glob('/editors/**/*.{js,jsx}'),
|
|
33
|
+
...import.meta.glob('/code/editors/**/*.{js,jsx}'),
|
|
34
|
+
};
|
|
35
|
+
|
|
36
|
+
const SAVE_DEBOUNCE_MS = 800;
|
|
37
|
+
|
|
38
|
+
async function loadEditorModule(modulePath) {
|
|
39
|
+
const load = modules[`/${modulePath}`];
|
|
40
|
+
if (!load) {
|
|
41
|
+
throw new Error(
|
|
42
|
+
`No editor module at "${modulePath}". Editors must live under editors/ so the registry glob can reach them.`,
|
|
43
|
+
);
|
|
44
|
+
}
|
|
45
|
+
const mod = await load();
|
|
46
|
+
const mount = mod.default ?? mod.mount;
|
|
47
|
+
if (typeof mount !== 'function') {
|
|
48
|
+
throw new Error(`"${modulePath}" has no default export to mount as an editor.`);
|
|
49
|
+
}
|
|
50
|
+
return mount;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
// Which paths this deck may write. An import's file is someone else's unless
|
|
54
|
+
// this deck forked it, and a published deck being read in the app has nowhere
|
|
55
|
+
// to write at all -- the host page says so before this module runs.
|
|
56
|
+
async function makeIsWritable() {
|
|
57
|
+
if (typeof window !== 'undefined' && window.__castleReadOnly === true) return () => false;
|
|
58
|
+
let forked = new Set();
|
|
59
|
+
try {
|
|
60
|
+
const res = await fetch('/__castle/files/forks');
|
|
61
|
+
if (res.ok) {
|
|
62
|
+
const data = await res.json();
|
|
63
|
+
forked = new Set((data.forks ?? []).filter((f) => f.ownFork).map((f) => f.path));
|
|
64
|
+
}
|
|
65
|
+
} catch {
|
|
66
|
+
// No serve (a published deck): nothing is forkable there anyway.
|
|
67
|
+
}
|
|
68
|
+
return (p) => !isImportedFile(p) || forked.has(p);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
// Debounce on top of the SDK's save queue: this decides WHEN an edit is worth
|
|
72
|
+
// writing (a drag shouldn't write every frame), the queue decides that it lands
|
|
73
|
+
// at all -- it holds the newest text per path and retries until the dev server
|
|
74
|
+
// takes it. Leaving the tab is the case the debounce was never written for, so
|
|
75
|
+
// flush there too, while there is still a socket.
|
|
76
|
+
function makeSaver(isWritable) {
|
|
77
|
+
const timers = new Map();
|
|
78
|
+
const pending = new Map();
|
|
79
|
+
|
|
80
|
+
const commit = (p) => {
|
|
81
|
+
const text = pending.get(p);
|
|
82
|
+
if (text === undefined) return Promise.resolve();
|
|
83
|
+
pending.delete(p);
|
|
84
|
+
clearTimeout(timers.get(p));
|
|
85
|
+
timers.delete(p);
|
|
86
|
+
return writeFile(p, text).catch(() => undefined);
|
|
87
|
+
};
|
|
88
|
+
const flushAll = () => Promise.all([...pending.keys()].map(commit)).then(() => flushSaves());
|
|
89
|
+
|
|
90
|
+
const onHidden = () => {
|
|
91
|
+
if (document.visibilityState === 'hidden') void flushAll();
|
|
92
|
+
};
|
|
93
|
+
document.addEventListener('visibilitychange', onHidden);
|
|
94
|
+
window.addEventListener('pagehide', () => void flushAll());
|
|
95
|
+
onBeforeRestart(flushAll);
|
|
96
|
+
|
|
97
|
+
return function schedule(p, text) {
|
|
98
|
+
if (!isWritable(p)) return;
|
|
99
|
+
pending.set(p, text);
|
|
100
|
+
clearTimeout(timers.get(p));
|
|
101
|
+
timers.set(
|
|
102
|
+
p,
|
|
103
|
+
setTimeout(() => void commit(p), SAVE_DEBOUNCE_MS),
|
|
104
|
+
);
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
// Shown only once a save has actually FAILED and is being retried. A "saving"
|
|
109
|
+
// flicker on every edit would be noise; work shown as saved that never landed is
|
|
110
|
+
// the bug the save queue exists to prevent, so that case gets the banner.
|
|
111
|
+
function mountSaveNotice(container) {
|
|
112
|
+
const el = document.createElement('div');
|
|
113
|
+
el.style.cssText =
|
|
114
|
+
'position:fixed;left:0;right:0;bottom:0;padding:8px 12px;font:13px system-ui,sans-serif;' +
|
|
115
|
+
'background:#7a2b2b;color:#fff;display:none;z-index:10';
|
|
116
|
+
container.appendChild(el);
|
|
117
|
+
onSaveState(({ pending, error }) => {
|
|
118
|
+
const show = Boolean(error) && pending.length > 0;
|
|
119
|
+
el.style.display = show ? 'block' : 'none';
|
|
120
|
+
if (show) {
|
|
121
|
+
el.textContent = `${pending.length} unsaved change${pending.length === 1 ? '' : 's'} — retrying…`;
|
|
122
|
+
}
|
|
123
|
+
});
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
function message(container, text) {
|
|
127
|
+
container.textContent = text;
|
|
128
|
+
container.style.cssText +=
|
|
129
|
+
';display:flex;align-items:center;justify-content:center;font:14px system-ui,sans-serif';
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
// Mount the editor for `?file=` if the shell asked for one.
|
|
133
|
+
//
|
|
134
|
+
// Returns true when it did, so an entry point reads:
|
|
135
|
+
// if (!(await mountEditorRoute())) startGame(initCard());
|
|
136
|
+
// A play load, and a published deck nobody is editing, take the false branch on
|
|
137
|
+
// the first line and never load any of the above.
|
|
138
|
+
export async function mountEditorRoute(options = {}) {
|
|
139
|
+
const params = new URLSearchParams(window.location.search);
|
|
140
|
+
const file = params.get('file');
|
|
141
|
+
if (!file || !isEdit()) return false;
|
|
142
|
+
|
|
143
|
+
const container = options.element ?? document.body;
|
|
144
|
+
if (container === document.body) document.body.style.margin = '0';
|
|
145
|
+
// The shell is dark and none of its theme reaches this iframe. Set a floor so
|
|
146
|
+
// an editor that styles nothing is still legible; anything it sets wins.
|
|
147
|
+
container.style.cssText += ';background:#161616;color:#eee;width:100%;min-height:100vh';
|
|
148
|
+
message(container, 'loading…');
|
|
149
|
+
|
|
150
|
+
const modulePath = params.get('editorModule');
|
|
151
|
+
try {
|
|
152
|
+
const [mount, isWritable, text] = await Promise.all([
|
|
153
|
+
loadEditorModule(modulePath),
|
|
154
|
+
makeIsWritable(),
|
|
155
|
+
fetch(fileUrl(file)).then((r) => r.text()),
|
|
156
|
+
]);
|
|
157
|
+
const schedule = makeSaver(isWritable);
|
|
158
|
+
container.textContent = '';
|
|
159
|
+
container.style.display = 'block';
|
|
160
|
+
mountSaveNotice(container);
|
|
161
|
+
mount(container, {
|
|
162
|
+
path: file,
|
|
163
|
+
text,
|
|
164
|
+
readOnly: !isWritable(file),
|
|
165
|
+
onChange: (next) => schedule(file, next),
|
|
166
|
+
onChangeFile: (target, next) => schedule(target, next),
|
|
167
|
+
});
|
|
168
|
+
} catch (e) {
|
|
169
|
+
message(container, e instanceof Error ? e.message : String(e));
|
|
170
|
+
}
|
|
171
|
+
return true;
|
|
172
|
+
}
|
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
{
|
|
2
|
-
"name": "
|
|
2
|
+
"name": "base",
|
|
3
3
|
"lockfileVersion": 3,
|
|
4
4
|
"requires": true,
|
|
5
5
|
"packages": {
|
|
6
6
|
"../../sdk": {
|
|
7
7
|
"name": "castle-web-sdk",
|
|
8
|
-
"version": "0.4.
|
|
8
|
+
"version": "0.4.24",
|
|
9
|
+
"dev": true,
|
|
9
10
|
"devDependencies": {
|
|
10
11
|
"eslint": "^9.0.0",
|
|
11
12
|
"jscpd": "^4.0.5",
|
|
@@ -1,18 +1,21 @@
|
|
|
1
1
|
{
|
|
2
|
-
"name": "
|
|
2
|
+
"name": "base",
|
|
3
3
|
"lockfileVersion": 3,
|
|
4
4
|
"requires": true,
|
|
5
5
|
"packages": {
|
|
6
6
|
"": {
|
|
7
|
-
"name": "
|
|
7
|
+
"name": "base",
|
|
8
8
|
"dependencies": {
|
|
9
|
-
"castle-web-fonts": "^1.0.0"
|
|
9
|
+
"castle-web-fonts": "^1.0.0"
|
|
10
|
+
},
|
|
11
|
+
"devDependencies": {
|
|
10
12
|
"castle-web-sdk": "file:../../sdk"
|
|
11
13
|
}
|
|
12
14
|
},
|
|
13
15
|
"../../sdk": {
|
|
14
16
|
"name": "castle-web-sdk",
|
|
15
|
-
"version": "0.4.
|
|
17
|
+
"version": "0.4.24",
|
|
18
|
+
"dev": true,
|
|
16
19
|
"devDependencies": {
|
|
17
20
|
"eslint": "^9.0.0",
|
|
18
21
|
"jscpd": "^4.0.5",
|
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
{
|
|
2
|
-
"name": "
|
|
2
|
+
"name": "base",
|
|
3
3
|
"private": true,
|
|
4
4
|
"type": "module",
|
|
5
5
|
"scripts": {
|
|
6
6
|
"check": "node --input-type=module -e \"const { bundleProject } = await import('../../cli/dist/bundle.js'); await bundleProject('.');\""
|
|
7
7
|
},
|
|
8
8
|
"dependencies": {
|
|
9
|
-
"castle-web-fonts": "^1.0.0"
|
|
9
|
+
"castle-web-fonts": "^1.0.0"
|
|
10
|
+
},
|
|
11
|
+
"devDependencies": {
|
|
10
12
|
"castle-web-sdk": "file:../../sdk"
|
|
11
13
|
}
|
|
12
14
|
}
|