castle-web-cli 0.4.151 → 0.4.153
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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 +91 -18
- package/dist/serveSecurity.d.ts +6 -0
- package/dist/serveSecurity.js +38 -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 +13 -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 +10 -1
- package/kits/blank/package.json +3 -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
package/kits/physics-2d/main.jsx
CHANGED
|
@@ -4,10 +4,21 @@ import { isEdit, setup } from 'castle-web-sdk';
|
|
|
4
4
|
import { PlayOnly } from './editors/PlayOnly';
|
|
5
5
|
import { ErrorBoundary } from './editors/ErrorBoundary';
|
|
6
6
|
import { SingleEditor } from './editors/SingleEditor';
|
|
7
|
+
import { syncDeckFontModule } from './editors/deckFont';
|
|
7
8
|
document.body.dataset.castleScreenshotTarget = 'viewport';
|
|
8
9
|
setup();
|
|
9
10
|
const root = document.getElementById('root');
|
|
10
11
|
if (!root) throw new Error('Missing root element');
|
|
12
|
+
|
|
13
|
+
// `theme.style` records the deck's font and `fonts.generated.js` carries its
|
|
14
|
+
// bytes (see editors/deckFont.js). Editing the record by hand leaves the module
|
|
15
|
+
// stale, so edit mode repairs it on load -- the one place that sees both and
|
|
16
|
+
// can write. Silent unless it actually did something.
|
|
17
|
+
if (isEdit()) {
|
|
18
|
+
const repair = syncDeckFontModule();
|
|
19
|
+
if (repair) console.log(repair);
|
|
20
|
+
}
|
|
21
|
+
|
|
11
22
|
// Route on URL params so the shell can mount each piece in its own panel iframe.
|
|
12
23
|
// File browsing and the code/text editor are now builtin shell panels, so the
|
|
13
24
|
// kit only renders the deck (play) and its rich per-file editors (scene/pxart):
|
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
"@dnd-kit/utilities": "^3.2.2",
|
|
18
18
|
"@fortawesome/free-solid-svg-icons": "^5.15.4",
|
|
19
19
|
"@lezer/highlight": "^1.2.3",
|
|
20
|
+
"castle-web-fonts": "^1.0.0",
|
|
20
21
|
"castle-web-sdk": "file:../../sdk",
|
|
21
22
|
"codemirror": "^6.0.2",
|
|
22
23
|
"matter-js": "^0.20.0",
|
|
@@ -32,7 +33,7 @@
|
|
|
32
33
|
},
|
|
33
34
|
"../../sdk": {
|
|
34
35
|
"name": "castle-web-sdk",
|
|
35
|
-
"version": "0.4.
|
|
36
|
+
"version": "0.4.19",
|
|
36
37
|
"devDependencies": {
|
|
37
38
|
"eslint": "^9.0.0",
|
|
38
39
|
"jscpd": "^4.0.5",
|
|
@@ -864,6 +865,12 @@
|
|
|
864
865
|
"node": ">=6"
|
|
865
866
|
}
|
|
866
867
|
},
|
|
868
|
+
"node_modules/castle-web-fonts": {
|
|
869
|
+
"version": "1.0.0",
|
|
870
|
+
"resolved": "https://registry.npmjs.org/castle-web-fonts/-/castle-web-fonts-1.0.0.tgz",
|
|
871
|
+
"integrity": "sha512-amFts4vVJjaXKNQkh2DMMmxYHafCYczAOvme70n+0WX8fsTqJACh6r6MzND94l89Q6LFoIyrCm+cLh3S1Usy0w==",
|
|
872
|
+
"license": "SEE LICENSE IN licenses/FONTS.md"
|
|
873
|
+
},
|
|
867
874
|
"node_modules/castle-web-sdk": {
|
|
868
875
|
"resolved": "../../sdk",
|
|
869
876
|
"link": true
|
|
@@ -30,7 +30,7 @@ import {
|
|
|
30
30
|
HotbarButton,
|
|
31
31
|
StageCanvas,
|
|
32
32
|
StageControls,
|
|
33
|
-
|
|
33
|
+
useReadOnlyFile,
|
|
34
34
|
useEditorShortcuts,
|
|
35
35
|
useFileSaver3D,
|
|
36
36
|
} from './editorChrome';
|
|
@@ -235,7 +235,7 @@ export function PxModelEditor({ path }) {
|
|
|
235
235
|
});
|
|
236
236
|
};
|
|
237
237
|
|
|
238
|
-
const readOnly =
|
|
238
|
+
const readOnly = useReadOnlyFile(path);
|
|
239
239
|
useEditorShortcuts({
|
|
240
240
|
history,
|
|
241
241
|
setMode,
|
|
@@ -279,8 +279,7 @@ export function PxModelEditor({ path }) {
|
|
|
279
279
|
);
|
|
280
280
|
}
|
|
281
281
|
|
|
282
|
-
// Hoisted so the hotbar markup reads flat
|
|
283
|
-
// editors' identical scaffolding as one clone).
|
|
282
|
+
// Hoisted so the hotbar markup reads flat.
|
|
284
283
|
const addPartButtons = readOnly
|
|
285
284
|
? null
|
|
286
285
|
: KIND_OPTIONS.map((option) => (
|
|
@@ -62,7 +62,7 @@ import { THUMB_PREFIX, thumbArtFor, withThumbRef } from './thumbnails';
|
|
|
62
62
|
import {
|
|
63
63
|
StageCanvas,
|
|
64
64
|
StageControls,
|
|
65
|
-
|
|
65
|
+
useReadOnlyFile,
|
|
66
66
|
useEditorShortcuts,
|
|
67
67
|
useFileSaver3D,
|
|
68
68
|
} from './editorChrome';
|
|
@@ -70,9 +70,7 @@ import {
|
|
|
70
70
|
export function Scene3DEditor({ path }) {
|
|
71
71
|
const stashKey = `scene3d-editor:${path}`;
|
|
72
72
|
const [stash] = useState(() => takeReloadState(stashKey));
|
|
73
|
-
|
|
74
|
-
// editor doesn't LOOK writable while nothing saves.
|
|
75
|
-
const readOnly = isViewerOnly();
|
|
73
|
+
const readOnly = useReadOnlyFile(path);
|
|
76
74
|
const saver = useFileSaver3D();
|
|
77
75
|
const { files, setFiles, dataVersion, hydrated } = useLiveDeckFiles3D({
|
|
78
76
|
shouldSkipPath: saver.hasPending,
|
|
@@ -84,6 +82,7 @@ export function Scene3DEditor({ path }) {
|
|
|
84
82
|
saver.schedule(path, next);
|
|
85
83
|
};
|
|
86
84
|
const onChangeFile = (filePath, nextText) => {
|
|
85
|
+
if (readOnly) return;
|
|
87
86
|
setFiles((current) => ({ ...current, [filePath]: nextText }));
|
|
88
87
|
saver.schedule(filePath, nextText);
|
|
89
88
|
};
|
|
@@ -94,7 +93,8 @@ export function Scene3DEditor({ path }) {
|
|
|
94
93
|
const [selectedBlueprintPath, setSelectedBlueprintPath] = useState(
|
|
95
94
|
stash?.selectedBlueprintPath ?? null
|
|
96
95
|
);
|
|
97
|
-
|
|
96
|
+
// The gizmo attaches only in a transform mode, so read-only opens in select.
|
|
97
|
+
const [mode, setMode] = useState(readOnly ? 'select' : 'move');
|
|
98
98
|
const onSelectActorIds = (ids) => {
|
|
99
99
|
setSelectedBlueprintPath(null);
|
|
100
100
|
setSelectedActorIdsRaw(ids);
|
|
@@ -125,7 +125,11 @@ export function Scene3DEditor({ path }) {
|
|
|
125
125
|
? makeScene(sceneData, behaviorClasses, sprites, files, path).data
|
|
126
126
|
: null;
|
|
127
127
|
const serialize = (next) => formatJson(isBlueprintFile ? stripTemplateId(next) : next);
|
|
128
|
-
|
|
128
|
+
// One guard covers every mutation path: gizmo commit, inspector, blueprint
|
|
129
|
+
// actions all funnel through here.
|
|
130
|
+
const commitScene = readOnly
|
|
131
|
+
? () => {}
|
|
132
|
+
: (next, options) => history.commit(serialize(next), options);
|
|
129
133
|
|
|
130
134
|
const canvasRef = useRef(null);
|
|
131
135
|
const edRef = useRef(null);
|
|
@@ -182,8 +186,8 @@ export function Scene3DEditor({ path }) {
|
|
|
182
186
|
// eslint-disable-next-line react-hooks/exhaustive-deps
|
|
183
187
|
}, [text, dataVersion]);
|
|
184
188
|
useEffect(() => {
|
|
185
|
-
if (edRef.current) edRef.current.mode = mode;
|
|
186
|
-
}, [mode]);
|
|
189
|
+
if (edRef.current) edRef.current.mode = readOnly ? 'select' : mode;
|
|
190
|
+
}, [mode, readOnly]);
|
|
187
191
|
useEffect(() => {
|
|
188
192
|
if (edRef.current) edRef.current.selection = selectedActorIds;
|
|
189
193
|
}, [selectedActorIds]);
|
|
@@ -3,7 +3,8 @@
|
|
|
3
3
|
// the common keyboard shortcuts. One place so the editors stay in the same
|
|
4
4
|
// design system by construction.
|
|
5
5
|
import React, { forwardRef, useEffect, useRef } from 'react';
|
|
6
|
-
import { onBeforeRestart, writeFile } from 'castle-web-sdk';
|
|
6
|
+
import { isImportedFile, onBeforeRestart, writeFile } from 'castle-web-sdk';
|
|
7
|
+
import { useForkedPaths } from '@imports/castle.physics-2d/editors/SingleEditor';
|
|
7
8
|
import * as castleSdk from 'castle-web-sdk';
|
|
8
9
|
|
|
9
10
|
// See the note in physics-2d's SingleEditor: a deck can take a kit update while
|
|
@@ -86,7 +87,12 @@ const MODE_STYLE = {
|
|
|
86
87
|
// says the whole deck is read-only.
|
|
87
88
|
export const isViewerOnly = () => typeof window !== 'undefined' && window.__castleReadOnly === true;
|
|
88
89
|
|
|
90
|
+
export { useReadOnlyFile } from '@imports/castle.physics-2d/editors/SingleEditor';
|
|
91
|
+
|
|
89
92
|
export function useFileSaver3D() {
|
|
93
|
+
const forked = useForkedPaths();
|
|
94
|
+
const forkedRef = useRef(forked);
|
|
95
|
+
forkedRef.current = forked;
|
|
90
96
|
const pending = useRef({});
|
|
91
97
|
const timers = useRef({});
|
|
92
98
|
function commit(path) {
|
|
@@ -102,10 +108,9 @@ export function useFileSaver3D() {
|
|
|
102
108
|
return writeFile(path, value).catch(() => undefined);
|
|
103
109
|
}
|
|
104
110
|
function schedule(path, text) {
|
|
105
|
-
//
|
|
106
|
-
//
|
|
107
|
-
|
|
108
|
-
if (isViewerOnly()) return;
|
|
111
|
+
// The serve refuses these writes anyway; skipping here keeps a missed UI
|
|
112
|
+
// lock from looking like a save that failed.
|
|
113
|
+
if (isViewerOnly() || (isImportedFile(path) && !forkedRef.current.has(path))) return;
|
|
109
114
|
pending.current[path] = text;
|
|
110
115
|
if (timers.current[path]) window.clearTimeout(timers.current[path]);
|
|
111
116
|
timers.current[path] = window.setTimeout(() => void commit(path), 500);
|
|
@@ -220,7 +225,7 @@ export function StageControls({
|
|
|
220
225
|
onClick={() => setMode(value)}
|
|
221
226
|
/>
|
|
222
227
|
);
|
|
223
|
-
// Selection stays
|
|
228
|
+
// Selection stays; everything that mutates goes.
|
|
224
229
|
if (readOnly) {
|
|
225
230
|
return <div style={MODE_STYLE}>{modeButton('select', 'marquee', 'Select (1)')}</div>;
|
|
226
231
|
}
|
|
@@ -16,11 +16,10 @@ import { imageArt } from '@imports/castle.physics-2d/engine/art';
|
|
|
16
16
|
// engine's own file globs: when this kit is itself an import, its models live
|
|
17
17
|
// under imports/<alias>/models/ in the deck being served, and a map without
|
|
18
18
|
// them can't resolve a kit blueprint's Model ref.
|
|
19
|
-
const modelModules = import.meta.glob(
|
|
20
|
-
|
|
21
|
-
import: 'default',
|
|
22
|
-
|
|
23
|
-
});
|
|
19
|
+
const modelModules = import.meta.glob(
|
|
20
|
+
['/**/*.pxmodel', '!/node_modules/**', '!/dist/**', '!/.castle/**'],
|
|
21
|
+
{ query: '?raw', import: 'default', eager: true }
|
|
22
|
+
);
|
|
24
23
|
|
|
25
24
|
export const initialFiles3D = {
|
|
26
25
|
...initialFiles,
|
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
"@dimforge/rapier3d-compat": "^0.19.2",
|
|
15
15
|
"@fortawesome/free-solid-svg-icons": "^5.15.4",
|
|
16
16
|
"@lezer/highlight": "^1.2.3",
|
|
17
|
+
"castle-web-fonts": "^1.0.0",
|
|
17
18
|
"castle-web-sdk": "^0.4.13",
|
|
18
19
|
"codemirror": "^6.0.2",
|
|
19
20
|
"matter-js": "^0.20.0",
|
|
@@ -30,7 +31,7 @@
|
|
|
30
31
|
},
|
|
31
32
|
"../../sdk": {
|
|
32
33
|
"name": "castle-web-sdk",
|
|
33
|
-
"version": "0.4.
|
|
34
|
+
"version": "0.4.19",
|
|
34
35
|
"devDependencies": {
|
|
35
36
|
"eslint": "^9.0.0",
|
|
36
37
|
"jscpd": "^4.0.5",
|
|
@@ -801,6 +802,12 @@
|
|
|
801
802
|
"node": ">=6"
|
|
802
803
|
}
|
|
803
804
|
},
|
|
805
|
+
"node_modules/castle-web-fonts": {
|
|
806
|
+
"version": "1.0.0",
|
|
807
|
+
"resolved": "https://registry.npmjs.org/castle-web-fonts/-/castle-web-fonts-1.0.0.tgz",
|
|
808
|
+
"integrity": "sha512-amFts4vVJjaXKNQkh2DMMmxYHafCYczAOvme70n+0WX8fsTqJACh6r6MzND94l89Q6LFoIyrCm+cLh3S1Usy0w==",
|
|
809
|
+
"license": "SEE LICENSE IN licenses/FONTS.md"
|
|
810
|
+
},
|
|
804
811
|
"node_modules/castle-web-sdk": {
|
|
805
812
|
"resolved": "../../sdk",
|
|
806
813
|
"link": true
|
|
@@ -0,0 +1,309 @@
|
|
|
1
|
+
# tabletop kit
|
|
2
|
+
|
|
3
|
+
The **room** a board game is played in, for decks whose server is authoritative:
|
|
4
|
+
seats, spectators, reconnect, and when state left in a session stops belonging to
|
|
5
|
+
anybody. It knows no rule of any game.
|
|
6
|
+
|
|
7
|
+
Built ON TOP of the `physics-2d` kit as an import, the way `physics-3d` is: the
|
|
8
|
+
engine, scenes, blueprints, drawings, behaviors and editors all come from
|
|
9
|
+
`imports/castle.physics-2d/` and work exactly as that kit's CLAUDE.md describes.
|
|
10
|
+
This kit adds no engine, no editors and no assets -- two files of server-side
|
|
11
|
+
code:
|
|
12
|
+
|
|
13
|
+
- `room.js` -- the room, and the clock it reads.
|
|
14
|
+
- `testing.js` -- a `MultiplayerServerSession` double, a movable clock, the room
|
|
15
|
+
conformance suite, and the node resolver hook that lets a plain test script
|
|
16
|
+
import a deck module written with `@imports/`.
|
|
17
|
+
|
|
18
|
+
## Quick reference
|
|
19
|
+
|
|
20
|
+
<!-- Injected into Castle's create assistant every turn; keep this compact and factual. -->
|
|
21
|
+
|
|
22
|
+
- Server-side room bookkeeping for board games, over the physics-2d kit. The
|
|
23
|
+
deck's `server/index.js` builds one room and delegates arrivals and departures
|
|
24
|
+
to it: `createRoom({ seats, createState, idleMs, graceMs })` from
|
|
25
|
+
`@imports/castle.tabletop/room.js`.
|
|
26
|
+
- `room.join(session, player)` -> `{ table, seat, returning, cleared }`, and
|
|
27
|
+
`room.leave(session, player)` -> `{ table, seat, promoted }`. One table per
|
|
28
|
+
`session.sessionId`, made on demand.
|
|
29
|
+
- The table holds the deck's own game at `table.game` (whatever `createState`
|
|
30
|
+
returned) plus `seatOf(playerId)`, `holder(seat)`, `names()`, `occupied()`,
|
|
31
|
+
`watching(session)`, `touch()`, `newRound()`, `rotate()`.
|
|
32
|
+
- `table.touch()` stamps the idle clock and must be called ONLY past every
|
|
33
|
+
rejection -- a refused message is not a sign of life.
|
|
34
|
+
- **A leave never clears the game.** The kit releases the seat, remembers the
|
|
35
|
+
departure for `graceMs`, and promotes a watcher. Clearing only ever happens on
|
|
36
|
+
a join. There is no path from `leave` to `createState`.
|
|
37
|
+
- Clearing rules, all inside `room.join`: never in a `party` session; never for a
|
|
38
|
+
player returning inside the grace window; always for someone arriving alone;
|
|
39
|
+
never while `minPlayers` seats are held by people who are present; otherwise
|
|
40
|
+
only past `idleMs` since the last accepted move.
|
|
41
|
+
- **A seat is not a secret.** Promotion hands the new holder the seat and with it
|
|
42
|
+
whatever the deck attached to that seat. State only one person may see -- a
|
|
43
|
+
hand of cards, a hidden role -- must be keyed by the `playerId` it was dealt
|
|
44
|
+
to, never by the seat id.
|
|
45
|
+
- Test it with `checkRoom({...})` and `createSessionHarness(server)` from
|
|
46
|
+
`@imports/castle.tabletop/testing.js`, run from the deck dir as
|
|
47
|
+
`node --import ./imports/castle.tabletop/testing.js tools/check.mjs` -- that
|
|
48
|
+
`--import` is what makes `@imports/` resolve under plain node.
|
|
49
|
+
- Deliberately NOT here: the solo fallback, the message envelope, any HUD, fonts
|
|
50
|
+
and other assets, and every game rule.
|
|
51
|
+
|
|
52
|
+
## Using it
|
|
53
|
+
|
|
54
|
+
The kit is imported with `autoUpdateWhenImported`, so a decision it makes today
|
|
55
|
+
changes every shipped deck's behaviour tomorrow without the author asking. It
|
|
56
|
+
therefore decides only bookkeeping -- seats, spectators, departures, session
|
|
57
|
+
freshness. Every number, every rule and every message is the deck's.
|
|
58
|
+
|
|
59
|
+
```js
|
|
60
|
+
import { createRoom } from '@imports/castle.tabletop/room.js';
|
|
61
|
+
|
|
62
|
+
const room = createRoom({
|
|
63
|
+
seats: ['X', 'O'],
|
|
64
|
+
createState: () => ({ board: Array(9).fill(null), turn: 'X', winner: null }),
|
|
65
|
+
idleMs: 3 * 60 * 1000,
|
|
66
|
+
graceMs: 45 * 1000,
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
export default {
|
|
70
|
+
onPlayerJoin(session, player) {
|
|
71
|
+
push(session, room.join(session, player).table);
|
|
72
|
+
},
|
|
73
|
+
onPlayerLeave(session, player) {
|
|
74
|
+
push(session, room.leave(session, player).table);
|
|
75
|
+
},
|
|
76
|
+
onMessage(session, player, data) {
|
|
77
|
+
const table = room.table(session);
|
|
78
|
+
// ... validate against table.seatOf(player.playerId) and table.game,
|
|
79
|
+
// then table.touch() only once the move is accepted.
|
|
80
|
+
},
|
|
81
|
+
};
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
`onStart` is optional -- every entry point makes the table it works on.
|
|
85
|
+
|
|
86
|
+
### `createRoom(config)`
|
|
87
|
+
|
|
88
|
+
- `seats` -- seat ids, in the order they are handed out. Required.
|
|
89
|
+
- `createState` -- `() => any`, a fresh game. Required. The kit stores what it
|
|
90
|
+
returns at `table.game` and otherwise never reads or writes it.
|
|
91
|
+
- `idleMs` -- how long an untended table may sit before an arriving player is
|
|
92
|
+
handed a clean one instead. Required. The three decks this came from chose
|
|
93
|
+
3, 3 and 10 minutes: configuration, not disagreement.
|
|
94
|
+
- `graceMs` -- how long a dropped player's seat is held for them. Required. See
|
|
95
|
+
"What a reconnect is" for what it can and cannot buy.
|
|
96
|
+
- `minPlayers` -- how many seats held by PRESENT players protect the table from a
|
|
97
|
+
join-side clear. Default: every seat. A game that runs short-handed (a card
|
|
98
|
+
game with a minimum of 2 at a 6-seat table) sets it.
|
|
99
|
+
- `displayName` -- `(player) => string`. Default: `username`, else `'guest'` for
|
|
100
|
+
an anonymous player, else `'player'`.
|
|
101
|
+
- `now` -- `() => ms`, if the deck wants its own clock. Leave it alone unless you
|
|
102
|
+
have a reason; the kit's clock is the one `testing.js` can move.
|
|
103
|
+
|
|
104
|
+
### `room`
|
|
105
|
+
|
|
106
|
+
- `room.table(session)` -- the table for this session, made if new.
|
|
107
|
+
- `room.join(session, player)` -> `{ table, seat, returning, cleared }`. `seat`
|
|
108
|
+
is `null` for a spectator: everyone past the last seat watches.
|
|
109
|
+
- `room.leave(session, player)` -> `{ table, seat, promoted }` -- the seat freed
|
|
110
|
+
(null if the leaver was watching) and the playerIds moved up into seats.
|
|
111
|
+
- `room.forget(session)` -- drop a session's table. Only for a host that reuses a
|
|
112
|
+
`sessionId`.
|
|
113
|
+
|
|
114
|
+
### `table`
|
|
115
|
+
|
|
116
|
+
- `table.game` -- the deck's game. Mutate it freely; the kit replaces it
|
|
117
|
+
wholesale on a clear or a `newRound()`.
|
|
118
|
+
- `table.seatOf(playerId)` -- seat id, or `null`. The ONLY thing that should
|
|
119
|
+
decide whether a message may move anything. Identity comes from
|
|
120
|
+
`player.playerId` / `player.userId`, never from a message body.
|
|
121
|
+
- `table.holder(seat)` -> `{ playerId, userId, name } | null`. Null the moment
|
|
122
|
+
the holder drops. The departure record behind it is pruned at `graceMs`, so a
|
|
123
|
+
deck that has to keep showing a departed player's name for the length of a hand
|
|
124
|
+
copies the name into its own state when it deals.
|
|
125
|
+
- `table.names()` -> `{ [seat]: name | null }`, ready to send.
|
|
126
|
+
- `table.occupied()` -- seats with a holder.
|
|
127
|
+
- `table.watching(session)` -- people in the session holding no seat.
|
|
128
|
+
- `table.touch()` -- stamp the idle clock. **Past every rejection, never before
|
|
129
|
+
one.**
|
|
130
|
+
- `table.newRound()` -- fresh game, same seats, clock restarted.
|
|
131
|
+
- `table.rotate()` -- shift every holder one seat BACKWARDS along the declared
|
|
132
|
+
order, so a series alternates who plays what. Chess swaps colours with this; a
|
|
133
|
+
card game moves the dealer. It turns the whole ring rather than compacting it:
|
|
134
|
+
an empty seat rotates along with the held ones.
|
|
135
|
+
- `table.lastActivityAt`, `table.sessionId`, `table.seats`, `table.departed` are
|
|
136
|
+
readable for a status line or a test.
|
|
137
|
+
|
|
138
|
+
## The rules, stated
|
|
139
|
+
|
|
140
|
+
On **join**, in this order:
|
|
141
|
+
|
|
142
|
+
1. Expired departure records are pruned.
|
|
143
|
+
2. If this player already holds a seat, or has a departure record inside
|
|
144
|
+
`graceMs` whose seat is still free, they get it back and this join is a
|
|
145
|
+
**return**.
|
|
146
|
+
3. The table is cleared iff: the mode is not `party`, AND this is not a return,
|
|
147
|
+
AND either (a) they arrived alone, or (b) fewer than `minPlayers` seats are
|
|
148
|
+
held by present players and nothing has been accepted for `idleMs`. A clear
|
|
149
|
+
makes a new game, restarts the clock, drops departure records, and frees seats
|
|
150
|
+
whose holder is not present.
|
|
151
|
+
4. They take the first free seat in declared order, or watch.
|
|
152
|
+
|
|
153
|
+
On **leave**: their seat, if any, is recorded in `departed` and freed; every
|
|
154
|
+
other present player without a seat is moved into one, in roster order; and
|
|
155
|
+
nothing else -- `game` is not touched.
|
|
156
|
+
|
|
157
|
+
Promotion is why a present person outranks a seat held for a connection that may
|
|
158
|
+
never come back, and step 2 of join gives way once the seat is taken. It is also
|
|
159
|
+
why a seat is not a place to keep a secret: the promoted watcher inherits the
|
|
160
|
+
seat id, and with it anything the deck keyed by seat id.
|
|
161
|
+
|
|
162
|
+
`party` is tested rather than `public` on purpose: the host converts a `public`
|
|
163
|
+
request into `party` when the play came from one (`sdk/src/host.ts:332`), and
|
|
164
|
+
`castle-web serve` reports `named` for every session
|
|
165
|
+
(`cli/src/devSessionServer.ts`) -- so a `=== 'public'` test would be dead code
|
|
166
|
+
both in production and on a serve.
|
|
167
|
+
|
|
168
|
+
## What a reconnect is
|
|
169
|
+
|
|
170
|
+
Read from source, because three decks' comments disagreed about it.
|
|
171
|
+
|
|
172
|
+
**Verified.** `playerId` is a connection, not an account:
|
|
173
|
+
`sdk/src/server/wrapper.ts` keys its player map by the platform's `connId`, so
|
|
174
|
+
one account in two tabs is two players at the table. The joining player IS
|
|
175
|
+
already in `session.players` when `onPlayerJoin` runs, and the leaving player is
|
|
176
|
+
already OUT of it when `onPlayerLeave` runs -- never count off `players.length`
|
|
177
|
+
to answer "is anyone else here", filter by playerId, which is what the kit does.
|
|
178
|
+
On a local serve a socket close fires `playerLeft` immediately, but the player
|
|
179
|
+
record and its reconnect token survive unless the close code was 1000
|
|
180
|
+
(`cli/src/devSessionServer.ts`, `detachClient`), and a client presenting that
|
|
181
|
+
token is re-attached under the **same `playerId`** -- so a genuine blip is a
|
|
182
|
+
leave/join pair with one playerId, which is what `graceMs` is for. The client
|
|
183
|
+
gives up on the token after `RECONNECT_BUDGET_MS = 30_000`
|
|
184
|
+
(`sdk/src/multiplayer.ts`) and re-acquires the session from scratch, minting a
|
|
185
|
+
new playerId.
|
|
186
|
+
|
|
187
|
+
**So:** on a serve, a `graceMs` much past ~30s buys nothing, and a page reload or
|
|
188
|
+
a closed tab is an **arrival**, not a return -- don't design around it being one.
|
|
189
|
+
|
|
190
|
+
**Not verified.** How the production host mints and re-issues `playerId`, and
|
|
191
|
+
over what window, is not in this repo. Treat `graceMs` as a courtesy, never as
|
|
192
|
+
correctness: that is why a present player always outranks a held seat, and why
|
|
193
|
+
nothing but the seat itself depends on the record surviving.
|
|
194
|
+
|
|
195
|
+
## Testing
|
|
196
|
+
|
|
197
|
+
Ship a test script with any deck built on this. It is a plain node script; there
|
|
198
|
+
is no runner. Run it from the deck directory, with the kit's `testing.js` as the
|
|
199
|
+
`--import`, so `@imports/` means the same thing in a test as it does in the deck:
|
|
200
|
+
|
|
201
|
+
```sh
|
|
202
|
+
node --import ./imports/castle.tabletop/testing.js tools/check.mjs
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
Put that in the deck's `package.json` as a `check` script. Without it `node` has
|
|
206
|
+
never heard of `@imports/` and cannot import the very server module the tests
|
|
207
|
+
exist to check.
|
|
208
|
+
|
|
209
|
+
```js
|
|
210
|
+
import server from '../server/index.js';
|
|
211
|
+
import { checkRoom, printRoomChecks } from '@imports/castle.tabletop/testing.js';
|
|
212
|
+
|
|
213
|
+
process.exit(
|
|
214
|
+
printRoomChecks(
|
|
215
|
+
checkRoom({
|
|
216
|
+
server,
|
|
217
|
+
seats: 2,
|
|
218
|
+
idleMs: 3 * 60 * 1000,
|
|
219
|
+
graceMs: 45 * 1000,
|
|
220
|
+
play: (h, seated) => {
|
|
221
|
+
/* one move the server will ACCEPT, from whoever may make it */
|
|
222
|
+
},
|
|
223
|
+
junk: (h, player) => {
|
|
224
|
+
/* things the server must refuse, whichever seat sends them */
|
|
225
|
+
},
|
|
226
|
+
snapshot: (h, playerId) => {
|
|
227
|
+
/* the PUBLIC game, as that player last heard it */
|
|
228
|
+
},
|
|
229
|
+
seatOf: (h, playerId) => {
|
|
230
|
+
/* that player's seat, or null */
|
|
231
|
+
},
|
|
232
|
+
})
|
|
233
|
+
)
|
|
234
|
+
);
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
Two hooks are worth reading twice:
|
|
238
|
+
|
|
239
|
+
- `snapshot` is the **public projection of the game**, not the player's own view
|
|
240
|
+
of it. Five scenarios compare one player's snapshot against another's -- an
|
|
241
|
+
arrival's against a seated player's -- so a deck with hidden information can
|
|
242
|
+
never satisfy them by returning a hand. Return the board, the turn, the counts,
|
|
243
|
+
the result, and check the private part with the deck's own tests. Leave out the
|
|
244
|
+
seat names and the watcher count too: those change for reasons that are not the
|
|
245
|
+
game changing.
|
|
246
|
+
- `junk` is always called with `seated[0]`, who may not be the side to move. Put
|
|
247
|
+
only messages in it that BOTH seats would be refused -- an illegal move, a
|
|
248
|
+
malformed body, an unknown type. One that happens to be legal for the player it
|
|
249
|
+
is handed to refreshes the idle clock and fails the check that says refused
|
|
250
|
+
messages do not.
|
|
251
|
+
|
|
252
|
+
Twenty-three checks, covering seating and spectators, promotion, the grace
|
|
253
|
+
window, present-beats-ghost, lone arrivals, the idle window, the long think, the
|
|
254
|
+
`party` / `named` / `public` split, and that two sessions do not share a table.
|
|
255
|
+
Run against the tic-tac-toe deck as it shipped BEFORE this kit existed, it
|
|
256
|
+
reports six failures, all from one line that cleared the board when a seated
|
|
257
|
+
player dropped.
|
|
258
|
+
|
|
259
|
+
The rest of `testing.js` stands on its own:
|
|
260
|
+
|
|
261
|
+
- `createSessionHarness(server, { mode, sessionId, deckId })` ->
|
|
262
|
+
`{ session, start(), join(playerId, identity?), leave(player),
|
|
263
|
+
message(player, data), sent(playerId), last(playerId, match?), outbox }`. It
|
|
264
|
+
mirrors the real wrapper where it counts: roster timing around the callbacks,
|
|
265
|
+
keying by playerId, and JSON round-tripping every message so a payload holding
|
|
266
|
+
a live reference to server state arrives as a copy.
|
|
267
|
+
- `createTestClock(startAt?)` -> `{ now, advance(ms), set(at), install(),
|
|
268
|
+
uninstall() }`. `install()` points the kit's clock at it.
|
|
269
|
+
|
|
270
|
+
It is not a transport. A two-client game over a real `castle-web serve` is still
|
|
271
|
+
the thing that proves a deck -- `tic-tac-toe-tabletop/tools/live.mjs` is a
|
|
272
|
+
dependency-free one to copy. It needs the serve on **loopback** and to itself: a
|
|
273
|
+
socket with no browser Origin is admitted from nowhere else, and a browser tab
|
|
274
|
+
already on that serve holds a seat the suite expects to be free.
|
|
275
|
+
|
|
276
|
+
## What is deliberately not here
|
|
277
|
+
|
|
278
|
+
- **The solo fallback** (`conn.isSolo`). Three decks wrote three incompatible and
|
|
279
|
+
individually correct answers -- pass-and-play on one device, a bot, a waiting
|
|
280
|
+
screen. A kit choosing one would be choosing the game.
|
|
281
|
+
- **The message envelope.** `type` vs `t` vs `kind` is the deck's.
|
|
282
|
+
- **A HUD or status line.** Rendering is the deck's.
|
|
283
|
+
- **Fonts and other assets.** A typeface is a game's choice, not a room's; each
|
|
284
|
+
deck carries the faces it picked, copied from `castle-client/core/assets/`.
|
|
285
|
+
- **Any game rule.**
|
|
286
|
+
|
|
287
|
+
## Wiring a deck
|
|
288
|
+
|
|
289
|
+
```sh
|
|
290
|
+
castle-web init <dir> --kit physics-2d
|
|
291
|
+
castle-web add-import <tabletop deckId> <dir> --as castle.tabletop
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
`--as castle.tabletop` matters: the alias is the path every `@imports/...`
|
|
295
|
+
specifier is written against, and it is never re-derived from the upstream deck
|
|
296
|
+
name. `castle.physics-2d` comes along with it -- transitive imports are flattened
|
|
297
|
+
into one `imports/` at the deck root.
|
|
298
|
+
|
|
299
|
+
Then point `index.html` at `/imports/castle.tabletop/main.jsx` (physics-2d's
|
|
300
|
+
entry, re-exported so a deck imports one kit and not two), and set `server.main`
|
|
301
|
+
in `castle.json`.
|
|
302
|
+
|
|
303
|
+
## Platform
|
|
304
|
+
|
|
305
|
+
The rules every Castle deck plays by -- the card and touch, assets and formats,
|
|
306
|
+
imports, reloading, editors -- are the Castle CLI's, not this kit's. The serve
|
|
307
|
+
writes them fresh at every start to `.castle/docs/platform.md`, loaded here:
|
|
308
|
+
|
|
309
|
+
@.castle/docs/platform.md
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
{
|
|
2
|
+
"title": "tabletop",
|
|
3
|
+
"editor": {
|
|
4
|
+
"initialPanels": [
|
|
5
|
+
{
|
|
6
|
+
"width": 400,
|
|
7
|
+
"column": [
|
|
8
|
+
{
|
|
9
|
+
"type": "files"
|
|
10
|
+
}
|
|
11
|
+
]
|
|
12
|
+
},
|
|
13
|
+
{
|
|
14
|
+
"type": "editor",
|
|
15
|
+
"file": "room.js"
|
|
16
|
+
}
|
|
17
|
+
],
|
|
18
|
+
"hiddenPaths": [],
|
|
19
|
+
"visiblePaths": [
|
|
20
|
+
"room.js",
|
|
21
|
+
"testing.js"
|
|
22
|
+
]
|
|
23
|
+
},
|
|
24
|
+
"imports": {
|
|
25
|
+
"castle.physics-2d": {
|
|
26
|
+
"deckId": "ckRZGFW4iPrx",
|
|
27
|
+
"version": "2026-08-28T19:17:29.217Z"
|
|
28
|
+
}
|
|
29
|
+
},
|
|
30
|
+
"main": "main.jsx",
|
|
31
|
+
"autoUpdateWhenImported": true,
|
|
32
|
+
"deckId": "7rrXIMh-giTm",
|
|
33
|
+
"cardId": "rkhXyRo-pwhX"
|
|
34
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
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>Castle Tabletop Kit</title>
|
|
7
|
+
<!-- Dark scheme declared statically so the frame never paints light first
|
|
8
|
+
(see the physics-2d kit's index.html for the Safari repaint story). -->
|
|
9
|
+
<style>
|
|
10
|
+
html {
|
|
11
|
+
color-scheme: dark;
|
|
12
|
+
background: #0a0a0a;
|
|
13
|
+
}
|
|
14
|
+
</style>
|
|
15
|
+
</head>
|
|
16
|
+
<body>
|
|
17
|
+
<div id="root"></div>
|
|
18
|
+
<script type="module" src="./main.jsx"></script>
|
|
19
|
+
</body>
|
|
20
|
+
</html>
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
// The tabletop kit adds no engine and no editors -- it is server-side room
|
|
2
|
+
// bookkeeping and a test double. Playing and editing are the physics-2d kit's,
|
|
3
|
+
// unchanged, so this entry is that entry.
|
|
4
|
+
//
|
|
5
|
+
// It exists so a deck's `index.html` can point at ONE import
|
|
6
|
+
// (`/imports/castle.tabletop/main.jsx`) and not have to know that physics-2d is
|
|
7
|
+
// underneath, and so `castle.json`'s `main` has something to name.
|
|
8
|
+
import '@imports/castle.physics-2d/main.jsx';
|