castle-web-cli 0.4.230 → 0.4.231
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 +81 -0
- package/dist/devSaveStorage.d.ts +36 -0
- package/dist/devSaveStorage.js +469 -0
- package/dist/devSessionChild.js +22 -12
- package/dist/devSessionServer.js +8 -2
- package/dist/devSessionStorage.d.ts +9 -0
- package/dist/devSessionStorage.js +66 -1
- package/dist/init.js +1 -1
- package/dist/serve.js +5 -1
- package/kits/base/castle.json +1 -1
- package/kits/base/sdk/README.md +148 -1
- package/kits/base/sdk/castle.d.ts +4 -0
- package/kits/base/sdk/castle.js +2 -0
- package/kits/base/sdk/commands.d.ts +15 -0
- package/kits/base/sdk/multiplayer.js +52 -4
- package/kits/base/sdk/save.d.ts +197 -0
- package/kits/base/sdk/save.js +525 -0
- package/kits/base/sdk/saveCoordinator.d.ts +39 -0
- package/kits/base/sdk/saveCoordinator.js +252 -0
- package/kits/base/sdk/server/storage.d.ts +3 -2
- package/kits/base/sdk/server/storage.js +25 -5
- package/kits/base/sdk/server/wrapper.d.ts +4 -0
- package/kits/base/sdk/server/wrapper.js +2 -0
- package/kits/base/sdk/store.d.ts +3 -2
- package/kits/base/sdk/store.js +5 -0
- package/kits/hub-game/CLAUDE.md +4 -1
- package/kits/hub-game/code/client/chrome.js +43 -9
- package/kits/hub-game/code/client/grab.js +142 -7
- package/kits/hub-game/code/client/hookLayer.js +7 -1
- package/kits/hub-game/code/client/state.js +13 -1
- package/kits/hub-game/code/client/talk.js +10 -36
- package/kits/hub-game/code/client/tiers.js +480 -0
- package/kits/hub-game/code/client/together.js +78 -3
- package/kits/hub-game/code/server/grab.js +3 -2
- package/kits/hub-game/code/server/hub.js +99 -5
- package/kits/hub-game/code/server/manifest.js +34 -7
- package/kits/hub-game/code/server/npcs.js +21 -33
- package/kits/hub-game/code/server/party.js +64 -6
- package/kits/hub-game/code/systems/hub.js +133 -16
- package/kits/hub-game/docs/contract.md +84 -14
- package/kits/hub-game/package.json +1 -1
- package/kits/hub-game/scripts/test-grab-client.mjs +328 -0
- package/kits/hub-game/scripts/test-hub-trip.mjs +208 -0
- package/kits/hub-game/scripts/test-manifest.mjs +47 -1
- package/kits/hub-game/scripts/test-npcs.mjs +34 -24
- package/kits/hub-game/scripts/test-party.mjs +87 -4
- package/kits/hub-game/scripts/test-tiers.mjs +666 -0
- package/kits/hub-game/scripts/test-together.mjs +33 -1
- package/kits/physics-2d/CLAUDE.md +2 -0
- package/kits/physics-2d/castle.json +2 -2
- package/kits/physics-2d/engine/scene.js +92 -0
- package/kits/physics-2d/package.json +1 -1
- package/kits/physics-2d/scripts/test-skip-unchanged.mjs +254 -0
- package/kits/physics-3d/CLAUDE.md +279 -0
- package/kits/physics-3d/behaviors/Player.jsx +74 -1
- package/kits/physics-3d/castle.json +3 -3
- package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +1 -1
- package/kits/physics-3d/engine3d/actornode.js +253 -0
- package/kits/physics-3d/engine3d/nearshadows.js +600 -0
- package/kits/physics-3d/engine3d/unchanged.js +153 -0
- package/kits/physics-3d/engine3d/world3d.js +465 -7
- package/kits/physics-3d/package.json +1 -1
- package/kits/physics-3d/scripts/test-camera-follow.mjs +533 -0
- package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
- package/kits/physics-3d/scripts/test-static-actors.mjs +662 -0
- package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
- package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
- package/kits/physics-3d/systems/physics3d.js +182 -3
- package/package.json +1 -1
|
@@ -7,7 +7,8 @@
|
|
|
7
7
|
// ribbon, the avatar the player wears everywhere, grabbing and throwing
|
|
8
8
|
// the place's loose objects where it offers that (`client/grab.js`), and idle
|
|
9
9
|
// play -- emotes, seats and the place's sounds -- where it offers that
|
|
10
|
-
// (`client/idle.js`, `client/sound.js`)
|
|
10
|
+
// (`client/idle.js`, `client/sound.js`), and, in a deck that asks for it, a
|
|
11
|
+
// cheaper picture on a slow device (`client/tiers.js`).
|
|
11
12
|
//
|
|
12
13
|
// One engine, one iframe (HUB.md decision 2): going through a door unloads this
|
|
13
14
|
// place's scene, loads the next one's (`scene.requestedScene`), and moves the
|
|
@@ -35,6 +36,7 @@ import { makeIdle } from '../client/idle.js';
|
|
|
35
36
|
import { makeSay, REACTIONS } from '../client/say.js';
|
|
36
37
|
import { makeSound } from '../client/sound.js';
|
|
37
38
|
import { makeTalk } from '../client/talk.js';
|
|
39
|
+
import { makeTiers } from '../client/tiers.js';
|
|
38
40
|
import { makeTogether, pointerAt } from '../client/together.js';
|
|
39
41
|
import { makeWear } from '../client/wear.js';
|
|
40
42
|
|
|
@@ -79,6 +81,8 @@ const START_NEAR_STAY_M = 4;
|
|
|
79
81
|
const JUMP_GAP_MS = 1100;
|
|
80
82
|
// How long "Let's play <door>" from someone here is offered as a Go.
|
|
81
83
|
const PLAY_ASK_MS = 20000;
|
|
84
|
+
// How long "<friend> went into <door>" is offered as a Follow.
|
|
85
|
+
const WENT_ASK_MS = 45000;
|
|
82
86
|
// The same player naming the same door is not offered again inside this.
|
|
83
87
|
const PLAY_ASK_AGAIN_MS = 60000;
|
|
84
88
|
// A cabinet (v1.7): how long the cover waits for the host to say it is playing
|
|
@@ -187,6 +191,8 @@ class HubSystem {
|
|
|
187
191
|
// `${playerId}:${door}` -> when each was last offered.
|
|
188
192
|
this.playAsk = null;
|
|
189
193
|
this.playAsked = new Map();
|
|
194
|
+
// A friend who went through a door while the question could not be put.
|
|
195
|
+
this.wentAsk = null;
|
|
190
196
|
this.chat = makeChat();
|
|
191
197
|
this.namesTouched = new WeakMap();
|
|
192
198
|
}
|
|
@@ -256,13 +262,7 @@ class HubSystem {
|
|
|
256
262
|
// network pose each frame, which would lift a hidden one back up.
|
|
257
263
|
if (this.lateFor !== scene && typeof scene.registerSystem === 'function') {
|
|
258
264
|
this.lateFor = scene;
|
|
259
|
-
|
|
260
|
-
afterBehaviors: (s) => {
|
|
261
|
-
this.applyVisibility(s);
|
|
262
|
-
this.applyWear(s);
|
|
263
|
-
this.fadeNames(s);
|
|
264
|
-
},
|
|
265
|
-
});
|
|
265
|
+
this.registerLate(scene);
|
|
266
266
|
}
|
|
267
267
|
this.applyVisibility(scene);
|
|
268
268
|
this.applyWear(scene);
|
|
@@ -295,6 +295,46 @@ class HubSystem {
|
|
|
295
295
|
this.measure(scene, mp, now);
|
|
296
296
|
}
|
|
297
297
|
|
|
298
|
+
// Device tiers (`client/tiers.js`), only in a deck whose castle.json asks
|
|
299
|
+
// (`hub.tiers`): without it this is never called, nothing of theirs is made
|
|
300
|
+
// or run, and the place is drawn and behaves exactly as it did. A frame
|
|
301
|
+
// counts toward the judge only while the player is placed and no trip or
|
|
302
|
+
// ending is under way: a scene swap's frames say nothing about how this
|
|
303
|
+
// device draws the place.
|
|
304
|
+
deviceTier(scene, mp, now) {
|
|
305
|
+
if (!Hub.deck.tiers) {
|
|
306
|
+
return;
|
|
307
|
+
}
|
|
308
|
+
if (!this.tiers) {
|
|
309
|
+
this.tiers = makeTiers();
|
|
310
|
+
const pick = (mode) => {
|
|
311
|
+
this.tiers.set(mode);
|
|
312
|
+
this.chrome?.setGraphics?.(this.tiers.mode, pick);
|
|
313
|
+
};
|
|
314
|
+
this.chrome?.setGraphics?.(this.tiers.mode, pick);
|
|
315
|
+
}
|
|
316
|
+
const counts = !this.trip && this.pendingEnd === null && mp?.placed?.() === true;
|
|
317
|
+
this.tiers.frame(scene, counts, now);
|
|
318
|
+
globalThis.__hub.tier = this.tiers.handle;
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
// The systems that run after every other one, registered once per runtime.
|
|
322
|
+
registerLate(scene) {
|
|
323
|
+
scene.registerSystem({
|
|
324
|
+
afterBehaviors: (s) => {
|
|
325
|
+
this.applyVisibility(s);
|
|
326
|
+
this.applyWear(s);
|
|
327
|
+
this.fadeNames(s);
|
|
328
|
+
},
|
|
329
|
+
});
|
|
330
|
+
// Device tiers run as a system of their own, registered only in a deck
|
|
331
|
+
// that asks (`deck.tiers` is read once, as the page loads): a deck without
|
|
332
|
+
// it runs exactly the frame it always did.
|
|
333
|
+
if (Hub.deck.tiers) {
|
|
334
|
+
scene.registerSystem({ afterBehaviors: (s) => this.deviceTier(s, s.multiplayer, performance.now()) });
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
|
|
298
338
|
// The places this player will walk back into stay built while they are away
|
|
299
339
|
// (physics-3d's `residentScenes`): a return redraws the town from the nodes
|
|
300
340
|
// it left, rather than rebuilding every mesh behind the door.
|
|
@@ -347,6 +387,7 @@ class HubSystem {
|
|
|
347
387
|
this.say.clear();
|
|
348
388
|
this.together.clear();
|
|
349
389
|
this.playAsk = null;
|
|
390
|
+
this.wentAsk = null;
|
|
350
391
|
this.playAsked.clear();
|
|
351
392
|
}
|
|
352
393
|
|
|
@@ -440,6 +481,7 @@ class HubSystem {
|
|
|
440
481
|
this.say.clear();
|
|
441
482
|
this.together.clear();
|
|
442
483
|
this.playAsk = null;
|
|
484
|
+
this.wentAsk = null;
|
|
443
485
|
this.playAsked.clear();
|
|
444
486
|
this.chat.reset();
|
|
445
487
|
}
|
|
@@ -555,7 +597,18 @@ class HubSystem {
|
|
|
555
597
|
|
|
556
598
|
// The session under this player ended without a trip of ours: the game's
|
|
557
599
|
// server crashed or was replaced. A game is left through the door the player
|
|
558
|
-
// came in by (contract §5); anywhere else the multiplayer kit rejoins
|
|
600
|
+
// came in by (contract §5); anywhere else the multiplayer kit rejoins, but
|
|
601
|
+
// only a join it can make again. A player who came back to the town through
|
|
602
|
+
// a door is there by a hub join, whose handoff is spent: when the town's own
|
|
603
|
+
// server is replaced under them (a new version saved) nothing would join
|
|
604
|
+
// again and the town would stand there dead, so the join this runtime began
|
|
605
|
+
// with is made again, as a lost join at the root of the trail is. Deeper on
|
|
606
|
+
// the host's trail (a place behind a door) there is no join to make again
|
|
607
|
+
// from where the player stands -- the host's doors are this place's own, and
|
|
608
|
+
// only a new acquisition names the new version's content -- so the player is
|
|
609
|
+
// sent back the way they came, as from a game, and walks in again through
|
|
610
|
+
// the door. Once per close: `lastNet` is forgotten, the way back is a trip,
|
|
611
|
+
// and one that is refused leaves the host's Back to ask again.
|
|
559
612
|
watchSession(scene, mp) {
|
|
560
613
|
if (this.trip) {
|
|
561
614
|
// Our own switch closes the old connection; that is not an ending.
|
|
@@ -571,10 +624,24 @@ class HubSystem {
|
|
|
571
624
|
}
|
|
572
625
|
this.lastNet = null;
|
|
573
626
|
const inGame = Boolean(Hub.hub.place?.result);
|
|
627
|
+
const barred = last.closeError?.() === HUB_BANNED;
|
|
574
628
|
Hub.clear();
|
|
575
629
|
if (inGame && scene.persistent.hubTickets.length) {
|
|
576
630
|
this.toast = { text: 'The game ended', until: performance.now() + TOAST_MS };
|
|
577
631
|
this.back(scene);
|
|
632
|
+
} else if (!inGame && !barred && mp.target?.mode === 'hub' && !(scene.persistent.hubDepth > 0)) {
|
|
633
|
+
console.warn('[hub-door] this place ended under a hub join: joining it again');
|
|
634
|
+
mp.switchSession(scene, scene.persistent.hubRootJoin ?? { mode: 'public' });
|
|
635
|
+
this.helloNet = null;
|
|
636
|
+
this.toast = { text: 'Reconnecting…', until: performance.now() + TOAST_MS };
|
|
637
|
+
} else if (!inGame && !barred && mp.target?.mode === 'hub') {
|
|
638
|
+
console.warn('[hub-door] this place ended under a hub join behind a door: leaving by its way back');
|
|
639
|
+
const title = scene.persistent.hubTickets.at(-1)?.title;
|
|
640
|
+
this.toast = {
|
|
641
|
+
text: title ? `This place was updated. Back to ${title}…` : 'This place was updated. Going back…',
|
|
642
|
+
until: performance.now() + TOAST_MS,
|
|
643
|
+
};
|
|
644
|
+
this.back(scene);
|
|
578
645
|
}
|
|
579
646
|
}
|
|
580
647
|
|
|
@@ -1134,6 +1201,21 @@ class HubSystem {
|
|
|
1134
1201
|
}
|
|
1135
1202
|
}
|
|
1136
1203
|
|
|
1204
|
+
// Why chat reaches nobody when a friend exists but is not in this layer:
|
|
1205
|
+
// "amy is in Tile Fall · chat when they're back". Only the friends the
|
|
1206
|
+
// People list also names: one inside a game behind one of this town's
|
|
1207
|
+
// doors, or in another layer of it. Null when there is nobody to name.
|
|
1208
|
+
awayNote() {
|
|
1209
|
+
const title = (door) => Hub.hub.doors.find((d) => d.id === door)?.title ?? null;
|
|
1210
|
+
const rows = (this.friendsAll ?? []).filter((f) => f && !f.here && (typeof f.door !== 'string' || title(f.door)));
|
|
1211
|
+
const away = rows.find((f) => typeof f.door === 'string') ?? rows[0];
|
|
1212
|
+
if (!away) {
|
|
1213
|
+
return null;
|
|
1214
|
+
}
|
|
1215
|
+
const where = typeof away.door === 'string' ? `in ${title(away.door)}` : 'in another part of town';
|
|
1216
|
+
return `${away.username ?? 'Your friend'} is ${where} · chat when they're back`;
|
|
1217
|
+
}
|
|
1218
|
+
|
|
1137
1219
|
// A pick from the speech card: a reaction or a phrase goes to the place; a
|
|
1138
1220
|
// typed line goes to the host, which sends it to whoever ghost lets read it.
|
|
1139
1221
|
saying(what) {
|
|
@@ -1142,7 +1224,10 @@ class HubSystem {
|
|
|
1142
1224
|
return;
|
|
1143
1225
|
}
|
|
1144
1226
|
this.chat.send(what.text, (status) => {
|
|
1145
|
-
|
|
1227
|
+
// A sent line says whom it went to: there is no other sign it arrived.
|
|
1228
|
+
const to = this.chatReach ?? [];
|
|
1229
|
+
const sent = to.length ? `Sent to ${to.slice(0, 3).join(', ')}${to.length > 3 ? ` +${to.length - 3}` : ''}` : null;
|
|
1230
|
+
const text = status === 'none' ? 'Nobody here can read that. Follow each other to chat.' : status === 'limited' ? 'Slow down a little.' : status === 'sent' ? sent : "That didn't send.";
|
|
1146
1231
|
if (text) {
|
|
1147
1232
|
this.toast = { text, until: performance.now() + TOAST_MS };
|
|
1148
1233
|
}
|
|
@@ -1167,7 +1252,14 @@ class HubSystem {
|
|
|
1167
1252
|
const play = this.playAsk;
|
|
1168
1253
|
if (play && performance.now() < play.until && Hub.hub.doors.some((d) => d.id === play.door) && !invite) {
|
|
1169
1254
|
const title = Hub.hub.doors.find((d) => d.id === play.door)?.title ?? 'a game';
|
|
1170
|
-
|
|
1255
|
+
// A game that takes no late joiners cannot be followed into: the player
|
|
1256
|
+
// is told where their friend is, and that they will be back.
|
|
1257
|
+
const late = Hub.hub.doors.find((d) => d.id === play.door)?.late === true;
|
|
1258
|
+
if (play.went && !late) {
|
|
1259
|
+
return { key: `play:${play.from}:${play.door}:${play.until}`, kind: 'play', door: null, text: `${play.name} went into ${title} · back soon`, yes: 'OK', no: 'Go to the door' };
|
|
1260
|
+
}
|
|
1261
|
+
const text = play.went ? `${play.name} went into ${title}` : `${play.name}: let's play ${title}`;
|
|
1262
|
+
return { key: `play:${play.from}:${play.door}:${play.until}`, kind: 'play', door: play.door, text, yes: play.went ? 'Follow' : 'Go', no: 'Not now' };
|
|
1171
1263
|
}
|
|
1172
1264
|
if (invite) {
|
|
1173
1265
|
return { key: `invite:${invite.from}`, kind: 'invite', from: invite.from, text: `${invite.username ?? 'Someone'} invited you to their party`, yes: 'Join party', no: 'No thanks' };
|
|
@@ -1181,9 +1273,13 @@ class HubSystem {
|
|
|
1181
1273
|
return;
|
|
1182
1274
|
}
|
|
1183
1275
|
if (ask.kind === 'play') {
|
|
1276
|
+
// "Back soon" (no door on the question): OK stays, the other button
|
|
1277
|
+
// goes to wait at the door.
|
|
1278
|
+
const door = ask.door ?? (yes ? null : this.playAsk?.door ?? null);
|
|
1279
|
+
const go = ask.door ? yes : !yes;
|
|
1184
1280
|
this.playAsk = null;
|
|
1185
|
-
if (
|
|
1186
|
-
this.sendJump(net, { k: 'hub-door-jump', door
|
|
1281
|
+
if (go && door) {
|
|
1282
|
+
this.sendJump(net, { k: 'hub-door-jump', door });
|
|
1187
1283
|
}
|
|
1188
1284
|
return;
|
|
1189
1285
|
}
|
|
@@ -1863,6 +1959,21 @@ class HubSystem {
|
|
|
1863
1959
|
chrome.setPeople?.(free ? this.people(scene, inGame) : null, town ? this.together.partyLine() : null);
|
|
1864
1960
|
chrome.setAsk?.(town ? this.ask() : null);
|
|
1865
1961
|
this.startBeside(scene, local, town, now);
|
|
1962
|
+
// A friend or party member went through a door: say so, and offer to follow.
|
|
1963
|
+
// Kept until the question can be put (not while talking to an NPC): the
|
|
1964
|
+
// name is taken now, while the friend is still remembered.
|
|
1965
|
+
for (const went of Hub.hub.wentEvents.splice(0)) {
|
|
1966
|
+
const name = place && !inGame ? went.players.map((id) => this.together.lately(id)).find(Boolean) : null;
|
|
1967
|
+
if (name) {
|
|
1968
|
+
this.wentAsk = { from: went.players[0], name, door: went.door, until: now + WENT_ASK_MS, went: true };
|
|
1969
|
+
}
|
|
1970
|
+
}
|
|
1971
|
+
if (town && this.wentAsk) {
|
|
1972
|
+
if (now < this.wentAsk.until && Hub.hub.doors.some((d) => d.id === this.wentAsk.door)) {
|
|
1973
|
+
this.playAsk = this.wentAsk;
|
|
1974
|
+
}
|
|
1975
|
+
this.wentAsk = null;
|
|
1976
|
+
}
|
|
1866
1977
|
// A friend or party member who just came in: say so, and point to them.
|
|
1867
1978
|
for (const who of town ? this.together.arrivals() : []) {
|
|
1868
1979
|
this.toast = { text: `${who.username ?? 'A friend'} is here · People to join`, until: now + TOAST_MS };
|
|
@@ -1910,6 +2021,7 @@ class HubSystem {
|
|
|
1910
2021
|
this.say.chat(now, from?.playerId ?? null, from?.username ?? message.fromUsername ?? 'Someone', message, CHAT_BUBBLE_MS);
|
|
1911
2022
|
}
|
|
1912
2023
|
const reach = (this.chat.peers ?? []).map((userId) => byUser.get(userId)?.username).filter(Boolean);
|
|
2024
|
+
this.chatReach = reach;
|
|
1913
2025
|
// The field is always there where the host has chat, so it can be found;
|
|
1914
2026
|
// when it cannot be used the card says why, in terms of this player alone
|
|
1915
2027
|
// (never another player's age).
|
|
@@ -1917,7 +2029,7 @@ class HubSystem {
|
|
|
1917
2029
|
? "Chat isn't available on this account"
|
|
1918
2030
|
: reach.length
|
|
1919
2031
|
? `Chat reaches ${reach.slice(0, 3).join(', ')}${reach.length > 3 ? ` +${reach.length - 3}` : ''}`
|
|
1920
|
-
: '
|
|
2032
|
+
: this.awayNote() ?? 'Chat is for players who follow each other. None of yours are here now · the phrases above reach everyone.';
|
|
1921
2033
|
const chatPart = this.chat.available() && this.chat.peers !== null
|
|
1922
2034
|
? { input: this.chat.canChat && reach.length > 0, note: chatNote }
|
|
1923
2035
|
: null;
|
|
@@ -1926,8 +2038,13 @@ class HubSystem {
|
|
|
1926
2038
|
// Standing still beside someone: a small button invites them.
|
|
1927
2039
|
const beside = town && !Hub.hub.party.invite && local ? this.together.beside(scene, local) : null;
|
|
1928
2040
|
chrome.nearPrompt?.(
|
|
1929
|
-
beside ?
|
|
1930
|
-
() =>
|
|
2041
|
+
beside ? `${beside.sent ? 'Invited' : '+ Party'} · ${beside.username ?? 'this player'}` : null,
|
|
2042
|
+
() => {
|
|
2043
|
+
if (!beside.sent) {
|
|
2044
|
+
this.together.invited(beside.playerId);
|
|
2045
|
+
this.join(scene, beside, 'invite');
|
|
2046
|
+
}
|
|
2047
|
+
},
|
|
1931
2048
|
);
|
|
1932
2049
|
// Barred from the hub: the town's own join was refused, and is not asked again.
|
|
1933
2050
|
if (scene.multiplayer?.joinError === HUB_BANNED) {
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# The hub-game contract
|
|
2
2
|
|
|
3
|
-
**Version 1.
|
|
3
|
+
**Version 1.22** (2026-10-04; v1 plus the optional additions under "Changes in
|
|
4
4
|
v1", each marked with the minor version that added it). Kit: `castle.hub-game` (`kits/hub-game`). Design:
|
|
5
5
|
`cauldron-game-server` `docs/HUB.md` (decision 3: a hub game is a kit plus a
|
|
6
6
|
contract). Inputs: the M0 report's Tier 0 gaps 1-9 (card
|
|
@@ -61,6 +61,7 @@ curation where it cannot:
|
|
|
61
61
|
"grab": true, // optional (v1.3); players pick up loose objects and throw them (§6)
|
|
62
62
|
"idle": { "emotes": true, "seats": true, "sounds": ["sounds/jukebox.mp3"] }, // optional (v1.6); emotes, seats, the place's sounds (§6)
|
|
63
63
|
"nearestPlayers": 30, // optional; 1..100, how many other players each client is sent (§12)
|
|
64
|
+
"tiers": true, // optional (v1.21); a cheaper picture on a slow device, client only
|
|
64
65
|
"places": { } // optional; more places in the same deck (§3)
|
|
65
66
|
}
|
|
66
67
|
```
|
|
@@ -80,9 +81,10 @@ curation where it cannot:
|
|
|
80
81
|
| `places` | object | §3. |
|
|
81
82
|
| `npcs` | object | §13. |
|
|
82
83
|
| `fallY` | number | v1.1. -25 to 50 metres; below it a player has fallen (§5). Default: none, or -20 in a scene with no ground. |
|
|
83
|
-
| `grab` | boolean or object | v1.3. `true`, or `{ throwSpeed, holdDistance, holdHeight }`: 1-14 m/s (default 10), 0.8-3 m (default 1.4), 0-2.5 m (default 1.2); any left out takes its default. `false` or absent: no grabbing (§6). |
|
|
84
|
+
| `grab` | boolean or object | v1.3. `true`, or `{ throwSpeed, holdDistance, holdHeight }`: 1-14 m/s (default 10), 0.8-3 m (default 1.4), 0-2.5 m (default 1.2); any left out takes its default. v1.22 adds two, each optional: `reach`, 1.6-3 m, how far (flat, from the object's near side) an object is offered, and `steady`, true or false, an offer that holds through a moment at its edge (§6). Left out (or `steady: false`), neither is sent to the client nor changes anything: the place is offered, sent and drawn exactly what it was. `false` or absent: no grabbing (§6). |
|
|
84
85
|
| `idle` | boolean or object | v1.6. `true` (emotes and seats), or `{ emotes, seats, sounds }`: `emotes` and `seats` true or false (default false), `sounds` up to 16 different `.mp3`/`.wav`/`.m4a` paths (lower-case extensions, as the engine bundles them) of this deck that `hub.sound` may play (each at most 256 KB, 1 MB in all, checked at publish). `false`, absent or all off: none of it (§6). |
|
|
85
86
|
| `nearestPlayers` | integer | 1-100, default 30. Each client is sent the poses of only this many other players, the nearest (§12). |
|
|
87
|
+
| `tiers` | boolean | v1.21, the deck's (not a place's). `true`: each client draws a cheaper picture where the device is slow -- a weak phone GPU or 2 GB or less of memory, or frames slower than 40 ms (the median of the first 5 s after arrival, or of any 10 s after), remembered on the device for 7 days. Low has no sun shadow (the render resolution is unchanged), no decorative actors (only `Transform`/`Shape`/`Model`), and no scenery (those plus `Solid`/`Lookable`) past 30 m or NPC bodies past 20 m; doors, pads, players and anything else with gameplay are always drawn, and in a game reached through a door only the shadow changes. The Character card gains Graphics: Auto / Low / High, kept on the device; Low or High wins. Nothing changes on the wire or for other players. `false` or absent: none of it. |
|
|
86
88
|
|
|
87
89
|
Unknown keys are a check failure, not ignored: a typo in a contract field must
|
|
88
90
|
not publish as "no such rule".
|
|
@@ -274,8 +276,10 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
|
|
|
274
276
|
- A late joiner arrives the same way, alone.
|
|
275
277
|
- **Jumping to a door.** In a town (a place with no `result`) the chrome's Doors
|
|
276
278
|
button lists the place's doors; Go puts the player on that door's pad (the
|
|
277
|
-
`HubPad` actor naming it, v1.10:
|
|
278
|
-
|
|
279
|
+
`HubPad` actor naming it, v1.10: inside its radius, so the pad counts them;
|
|
280
|
+
v1.20: on a spot no one stands within 1.1 m of, a ring 1.2 m about its
|
|
281
|
+
middle first, then nearer its edge, then the middle, else the spot with the
|
|
282
|
+
most room), facing the door, or 7 m in front of a door with no pad, in the
|
|
279
283
|
door's own frame (at most once a second; never a held player). It is a walk, not a trip: the player stays in this session. A game
|
|
280
284
|
has no list.
|
|
281
285
|
- **Where a player came from** is ghost's arrival where the host has hub ops
|
|
@@ -299,6 +303,22 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
|
|
|
299
303
|
trail the runtime's first join is made again into the place already loading,
|
|
300
304
|
anywhere deeper the player leaves by that place's way back, twice at most.
|
|
301
305
|
Acquisitions and `Hub.cancel` run one at a time.
|
|
306
|
+
- **A place replaced under its players (v1.18).** When a place's session ends
|
|
307
|
+
under a player who is not on a trip (a new version of it was saved, or its
|
|
308
|
+
server stopped): a game is left as before ("The game ended", then its way
|
|
309
|
+
back); any other place reached through a door (the host's trail holds the
|
|
310
|
+
trip) is left by its way back at once, with a line saying it was updated
|
|
311
|
+
("This place was updated. Back to <the place left>…"), and is entered again
|
|
312
|
+
through its door, which acquires the new version and its content. A join
|
|
313
|
+
cannot be made again from inside such a place: its handoff is spent, and
|
|
314
|
+
only a door's acquisition names the release to mount. The way back is asked
|
|
315
|
+
once per ending; one that is refused leaves the player where they are with
|
|
316
|
+
the host's Back control, as any refused way back does. The town itself, at
|
|
317
|
+
the root of the host's trail, joins again where it stands with the join the
|
|
318
|
+
runtime began with ("Reconnecting…"; the kit did this before v1.18, and it
|
|
319
|
+
is written down here). A player barred from the hub is neither sent back nor
|
|
320
|
+
joined again. The place's server sees nothing new: the players of the old
|
|
321
|
+
session had `leave`, and those who walk back in `arrive` like anyone.
|
|
302
322
|
- **A cabinet's trip (v1.7).** A `hub-go` with `classic` is a hub trip with no
|
|
303
323
|
destination session and no content. The client asks `Hub.go(door)`, which a
|
|
304
324
|
host that can play classic decks answers `{ status: 'ok', kind: 'classic' }`
|
|
@@ -328,7 +348,9 @@ layer door. On the dev serve the door is a `deck:<name>` door like any other.
|
|
|
328
348
|
<door> pad" for a `HubPad` actor's circle, "near <door>" within 7 m of a
|
|
329
349
|
door, else the place's `where` hook (§4), else "in town". Join
|
|
330
350
|
(`hub-goto`) puts the player beside that friend, facing them, as a jump to a
|
|
331
|
-
door does
|
|
351
|
+
door does, but never on a door's pad nor at its edge, theirs included (v1.19:
|
|
352
|
+
beside a friend on a pad is just off its edge, so joining their game is a
|
|
353
|
+
step the player takes): a town only, at most once a second, never a held player, never
|
|
332
354
|
across a block; a sitter stands first. The server does not know who is whose
|
|
333
355
|
friend, so it moves a player beside any player of the session they may see;
|
|
334
356
|
only the chrome's list limits Join to friends. Find moves nobody: it puts
|
|
@@ -464,6 +486,32 @@ and at a game's end. `hub.drop(playerId?)` makes a player let go (a goal, a
|
|
|
464
486
|
whistle): the object falls where it is. A place without `grab` draws no button
|
|
465
487
|
and is sent exactly what it was.
|
|
466
488
|
|
|
489
|
+
**A steadier offer (v1.22).** The offer is tested afresh every frame: within
|
|
490
|
+
the reach, within 60 degrees of facing, and this client's to simulate (the
|
|
491
|
+
multiplayer kit hands an object to the nearest player). At any of those edges
|
|
492
|
+
-- a player turning, two players near one object -- the button comes and
|
|
493
|
+
goes, and on a phone a press lands on nothing. A place may set, in `grab`:
|
|
494
|
+
|
|
495
|
+
- `reach` (1.6-3 m): objects are offered this far from their near side instead
|
|
496
|
+
of 1.6 m.
|
|
497
|
+
- `steady: true`: once an object is offered, it stays the one offered while
|
|
498
|
+
its near side is within the reach and 0.4 m more and it is within 90
|
|
499
|
+
degrees of facing, even when another is nearer. When it fails that for a
|
|
500
|
+
moment -- briefly someone else's to simulate, a turn past the cone, a step
|
|
501
|
+
back -- the button stays up for 600 ms. A press in that time waits up to
|
|
502
|
+
500 ms for the object to pass the test again (this client's own included)
|
|
503
|
+
and grabs it then; if it does not, the press is dropped. Another object
|
|
504
|
+
that passes the ordinary test takes the offer over meanwhile.
|
|
505
|
+
|
|
506
|
+
With either set, an object is also never offered when its centre is more than
|
|
507
|
+
3 m from the player's, and less the faster the player is moving (their body's
|
|
508
|
+
speed, jumps included, or their tuned speed, over the 0.2 s the server's view of
|
|
509
|
+
them may trail), keeping inside the server's 4 m in ordinary play; a grab the
|
|
510
|
+
server still refuses is let go, as any refused grab is. Nothing changes on the server: it checks every grab
|
|
511
|
+
as it always has, and the client still sends a grab only for an object that
|
|
512
|
+
is its own at that moment. A place that sets neither runs the offer it always
|
|
513
|
+
did, and is sent and drawn exactly what it was.
|
|
514
|
+
|
|
467
515
|
A refusal and `hub.drop` bind the hub client, which is the only client a hub
|
|
468
516
|
place has; they do not take the object from its owner on the server. A
|
|
469
517
|
modified client can carry a loose object it owns whatever the place says,
|
|
@@ -856,7 +904,7 @@ place with `idle` (v1.6) only the parts it turns on: `hubEmotes` (player id →
|
|
|
856
904
|
`{ id, at, until }`, simulation ms), `hubSeated` (player id → seat actor id),
|
|
857
905
|
`hubSounds` (actor id → `{ file, volume, radius, since }`, the loops playing).
|
|
858
906
|
Server → every client: `{ k: 'hub-sound', actor, file, volume, radius }` (v1.6,
|
|
859
|
-
a one-shot); `{ k: 'hub-said', player, r }` or `{ k: 'hub-said', player, p, door? }` (v1.11, §6: to each client a block does not hide the speaker from). Server → one
|
|
907
|
+
a one-shot); `{ k: 'hub-went', players, door }` (v1.15, a town: to each player staying, who of the players they may see went through `door`); `{ k: 'hub-said', player, r }` or `{ k: 'hub-said', player, p, door? }` (v1.11, §6: to each client a block does not hide the speaker from). Server → one
|
|
860
908
|
client: `{ k: 'hub-go', door, key, place, scene, title, party }` (in production `key` is null and `pad` names the fired pad; a cabinet's, v1.7, has `classic: true`, no `key` and no `pad`, and `dev: true` on the dev serve),
|
|
861
909
|
`{ k: 'hub-cabinet', actor, door, card }` (v1.7: a cabinet's card for the door actor `actor`, `{ title, label, cover, top: [{ username, score, photo, frame }] }`, or `card: null` when it is gone),
|
|
862
910
|
`{ k: 'hub-arrived', facing }`, `{ k: 'hub-jumped', facing }` (after a jump to a door or, with `to` the player, to a player, §5),
|
|
@@ -865,7 +913,7 @@ client: `{ k: 'hub-go', door, key, place, scene, title, party }` (in production
|
|
|
865
913
|
override), `{ k: 'hub-tune', tune }` (v1.2, that player's `{ speed, jump }` or null), `{ k: 'hub-labels', labels }` (that player's own labels),
|
|
866
914
|
`{ k: 'hub-result', result }`, `{ k: 'hub-end', why }`,
|
|
867
915
|
`{ k: 'hub-grab-deny', actor }` (v1.3: a grab refused; let go), `{ k: 'hub-drop', actor }` (v1.3: `hub.drop`),
|
|
868
|
-
`{ k: 'hub-npc', npc, open, mind?, character?, name?, disclosure?, hearRange?, why? }
|
|
916
|
+
`{ k: 'hub-npc', npc, open, mind?, character?, name?, disclosure?, hearRange?, why? }` (since v1.17 `disclosure` is always `"participants"` and `hearRange` always 0: a client from before it named the players in that range as a turn's listeners),
|
|
869
917
|
`{ k: 'hub-npc-line', npc, text, why }` (`why` v1.8, as `npcLine`'s), `{ k: 'hub-npc-notes', npc, prefix }` (v1.8, §13), `{ k: 'hub-av', hubAv }` (avatars of players in a
|
|
870
918
|
hidden pair that this player may see, laid over the shared `hubAv`), `{ k: 'hub-wear', hubWear }`
|
|
871
919
|
(v1.4, their wearables, laid over the shared `hubWear` the same way).
|
|
@@ -988,18 +1036,32 @@ door that names its own session.
|
|
|
988
1036
|
| `route` | optional; a `server.destinations` route with `characters: "shared"`, joined only on SDKs without place characters. Without a route the minds are the place's alone: every layer addresses ghost's one place mind |
|
|
989
1037
|
| `slot` | 1-64 of `[A-Za-z0-9_.-]`; default `"main"`; the fallback route's world. A world keeps the character definitions it was created with: after changing the bundle's characters, name a new slot (ghost refuses turns in the old world with `CAULDRON_SHARED_CHARACTER_CONFLICT`) |
|
|
990
1038
|
| `turnsPerMinute` | 1-30, default 6: the conversation budget of each character's body, so per layer |
|
|
991
|
-
| `disclosure` | `"participants"`
|
|
1039
|
+
| `disclosure` | `"participants"` or `"world"`: read, and since v1.17 not acted on. A player's conversation with a character is theirs alone (below) |
|
|
992
1040
|
| `followSec` | 10-600, default 120: how long a body follows before it goes home |
|
|
993
1041
|
|
|
994
1042
|
Where a session has the place's characters, a player's words are a character turn. The kit admits it only
|
|
995
|
-
for the player the body is talking to, near it, with
|
|
996
|
-
|
|
1043
|
+
for the player the body is talking to, near it, with no listener of any kind,
|
|
1044
|
+
within the character's `turnsPerMinute`; anything else is refused
|
|
997
1045
|
before a model is called, and over budget the place's `budget` line answers
|
|
998
1046
|
instead, so a crowd degrades to authored lines rather than a queue. The reply
|
|
999
|
-
is ghost's text, shown in the speaker's panel and over the body for the
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
|
|
1047
|
+
is ghost's text, shown in the speaker's panel and over the body for the
|
|
1048
|
+
speaker alone.
|
|
1049
|
+
|
|
1050
|
+
**A player's conversation is theirs alone (v1.17).** What a player types to a
|
|
1051
|
+
character, and what the character answers, reaches no other player: not as a
|
|
1052
|
+
bubble, not through the character's memory, not in another layer or a later
|
|
1053
|
+
session. Ghost keeps a turn's words for everyone its audience names (a listener
|
|
1054
|
+
reads them back and the character may repeat them), so a turn names no player
|
|
1055
|
+
and no character as a listener and is never `world`-disclosed: the kit's
|
|
1056
|
+
client sends an empty audience, the kit's server refuses any other
|
|
1057
|
+
(`HUB_NPC_AUDIENCE`), and ghost keeps a place mind's conversations per player
|
|
1058
|
+
whatever a client sent. The character still remembers the same player
|
|
1059
|
+
tomorrow: its memory of them is that player's own. Only words with nothing of
|
|
1060
|
+
any player's typing in them are public: authored lines, ambient lines, and
|
|
1061
|
+
what a mind says from ghost's verified news. A place must keep it so: never
|
|
1062
|
+
put what a player typed (`npcHeard`'s and `npcLine`'s `text`) into a line, a
|
|
1063
|
+
label, a HUD, storage another player reads, or another player's notes.
|
|
1064
|
+
A body follows a player
|
|
1003
1065
|
only when its character chose its follow action (an action whose object effect
|
|
1004
1066
|
hands the `follow` object to `"player"`); clients cannot start or aim it. The
|
|
1005
1067
|
follow object is one per place, so only the body in the holder's layer follows.
|
|
@@ -1105,6 +1167,14 @@ Minor additions, each optional; a deck written before them reads the same.
|
|
|
1105
1167
|
|
|
1106
1168
|
| date | change |
|
|
1107
1169
|
| --- | --- |
|
|
1170
|
+
| 2026-10-04 (v1.22) | §1 and §6 `grab.reach` (1.6-3 m) and `grab.steady`: a place may offer objects from farther away and keep an offer up through a moment at its edge (the same object kept within the reach plus 0.4 m and 90 degrees of facing; the button held 600 ms through a lost owner or a turn; a press then waits 500 ms for the object to be this client's again), never past 3 m centre to centre. Sonnet playtests of Pillow Dojo and Number Pals on phones: the Grab button came and went at the reach, the cone and a shared owner, and bouts went on walking. Client only; a place without them is sent and drawn exactly what it was |
|
|
1171
|
+
| 2026-10-04 (v1.21) | §1 `tiers`: a deck may ask for device tiers, a cheaper picture drawn by a slow device's client (no sun shadow, decorative actors not drawn, scenery past 30 m and NPC bodies past 20 m not drawn) and a Graphics: Auto / Low / High row in the Character card. Phones the town was measured on (Galaxy Tab A7 Lite, Redmi 9A) drew it at 12 fps. Client only; a deck without `tiers` is drawn and behaves exactly as before |
|
|
1172
|
+
| 2026-10-04 (v1.20) | §5 a jump onto a pad (Doors Go, a party's go) is put on a spot no one stands within 1.1 m of (a ring 1.2 m about the pad's middle, at most half its radius, then a ring nearer its edge, then the middle, else the spot with the most room): a body put down touching another was pushed apart by physics and could push the one already there off the pad, so a pad that needed both never fired (production 18:00Z Oct 4). |
|
|
1173
|
+
| 2026-10-04 (v1.19) | §5 Join and starting beside a friend (`hub-goto`, an arrival's `near`) never place a player on a door's pad or within a body's width of one, the friend's own pad included: a friend on a pad is joined from just off its edge, facing them, so nobody is taken into a game they did not step into. With no clear spot off every pad the player stays where they were put. A place whose players never stand on pads sees no change |
|
|
1174
|
+
| 2026-10-04 (v1.18) | §5 a place replaced under its players: a place that is not a game, reached through a door, whose session ends under a player (a new version saved) sends them back the way they came with a line saying it was updated, instead of leaving them in its scene with no HUD, labels or controls; they walk in again through the door, into the new version. Also written down: the town at the root of the host's trail joins again where it stands (kit behaviour since 2026-10-04, not recorded until now). A game's ending is unchanged, and a deck changes nothing |
|
|
1175
|
+
| 2026-10-04 (v1.17) | §13 a player's conversation with a character is theirs alone: a turn names no listener (the client sends an empty audience and the server refuses any other), a mind's reply is drawn over the body for its speaker only (it was drawn for up to seven players within 6 m, and ghost kept the speaker's words for them too, so the character repeated them to those players later), `npcs.disclosure` is read and no longer acted on, and the Say panel's "Players nearby can hear" line is gone. Authored and ambient lines are public as before |
|
|
1176
|
+
| 2026-10-04 (v1.16) | §4 `hub.partyOf(playerId)`: the other members of a player's party who are in the place, so a place may wait for them (the town adds 7 s to a pad's countdown). §5 a Doors row carries `late: true` where the door takes late joiners; a friend who went through a door that does not is announced as "back soon" with no Follow |
|
|
1177
|
+
| 2026-10-04 (v1.15) | §5 in a town, the players who stay are told who went through which door (`hub-went`, §12: `{ players, door }`, never across a block, not for a cabinet); each client shows it only for its own friends and party members ("amy went into Tile Fall": Follow / Not now, for 45 s, Follow being a jump to that door's pad). A game sends none of it |
|
|
1108
1178
|
| 2026-10-04 (v1.14) | §5 a town's Doors rows carry `featured` (listed first, starred), `solo` (a door that takes one player: a party is told so and is not asked to come) and `need` (its minimum when over one); a member who picks the door their party is already going to has answered yes; a friend or party member who comes in after the first moments is announced ("amy is here") and pointed to. §6 the chat field is always shown where the host has chat, disabled with the reason when it cannot be used ("Follow each other to chat. Nobody here follows you back yet.", "Chat isn't available on this account"). A deck changes nothing |
|
|
1109
1179
|
| 2026-10-04 (v1.13) | §10 goals: `hub.label`'s `style: "goal"`, a per-player pointer to a scene actor drawn at the screen's edge while it is out of view. Pebble Cove's playtesters could not find the villager an errand named: a sign is drawn only where it projects on screen, and the camera looks down. A place that sets no goal is drawn exactly as before |
|
|
1110
1180
|
| 2026-10-03 (v1.12) | §6 free-text chat between players who follow each other and are both over 13, enforced by ghost through the host (`Hub.chat`, `Hub.say`, `Hub.reportChat`); the kit draws what it is handed and says only "Follow each other to chat" otherwise. Nothing on the place's wire, and nothing at all on a host without the commands |
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"private": true,
|
|
4
4
|
"type": "module",
|
|
5
5
|
"scripts": {
|
|
6
|
-
"check": "eslint . && node scripts/test-manifest.mjs && node scripts/test-npcs.mjs && node scripts/test-avatar.mjs && node scripts/test-hub-ops.mjs && node scripts/test-actors.mjs && node scripts/test-grab.mjs && node scripts/test-idle.mjs && node scripts/test-keys.mjs && node scripts/test-attention.mjs && node scripts/test-hub-trip.mjs && node scripts/test-pack.mjs && node scripts/test-interest.mjs && node scripts/test-blocks.mjs && node scripts/test-ban-join.mjs && node scripts/test-door.mjs && node scripts/test-door-jump.mjs && node scripts/test-together.mjs && node scripts/test-party.mjs && node scripts/test-say.mjs && node scripts/test-chat.mjs && node scripts/test-no-forms.mjs && node scripts/test-classic.mjs && node --input-type=module -e \"const { bundleProject } = await import('../../cli/dist/bundle.js'); await bundleProject('.');\"",
|
|
6
|
+
"check": "eslint . && node scripts/test-manifest.mjs && node scripts/test-npcs.mjs && node scripts/test-avatar.mjs && node scripts/test-hub-ops.mjs && node scripts/test-actors.mjs && node scripts/test-grab.mjs && node scripts/test-grab-client.mjs && node scripts/test-idle.mjs && node scripts/test-keys.mjs && node scripts/test-attention.mjs && node scripts/test-hub-trip.mjs && node scripts/test-pack.mjs && node scripts/test-interest.mjs && node scripts/test-blocks.mjs && node scripts/test-ban-join.mjs && node scripts/test-door.mjs && node scripts/test-door-jump.mjs && node scripts/test-together.mjs && node scripts/test-party.mjs && node scripts/test-say.mjs && node scripts/test-chat.mjs && node scripts/test-no-forms.mjs && node scripts/test-classic.mjs && node scripts/test-tiers.mjs && node --input-type=module -e \"const { bundleProject } = await import('../../cli/dist/bundle.js'); await bundleProject('.');\"",
|
|
7
7
|
"format": "prettier --write \"code/**/*.js\" \"scripts/**/*.mjs\" castle.json package.json"
|
|
8
8
|
},
|
|
9
9
|
"dependencies": {
|