+
{#each elements as el (el.__key + ':' + el.id)}
-
+
{/each}
@@ -368,6 +380,12 @@
.hud-slot {
position: absolute;
}
+ /* 30 P1: a previewed GAME screen is a picture of the menu, not the menu — every click
+ goes through it to the viewport (the elements opt back INTO pointer events one by
+ one, so the override has to reach them) */
+ .hud-inert :global(*) {
+ pointer-events: none !important;
+ }
/* the keyboard ring, so a player under pointer lock can see where they are */
.hud-focused {
outline: 2px solid var(--accent, #ef562f);
diff --git a/src/components/menu/Controls.svelte b/src/components/menu/Controls.svelte
index 9adc16ed..5f21b136 100644
--- a/src/components/menu/Controls.svelte
+++ b/src/components/menu/Controls.svelte
@@ -39,6 +39,9 @@
import { visibleDockKey, dockOccupants, bottomInset, FLOW_FAMILY, armDockMode, DOCK_TITLES } from '$lib/bottomDock';
import { togglePanel } from '$lib/panelToggles';
import { requestPlay, willEnterXR, willEnterAR, vrSupported, arSupported, xrSessionFailed } from '$lib/playMode';
+ // 30 P2: Test play — the play button's right-click row beside the game chip's button
+ import { testPlay } from '$lib/gamePresence';
+ import { hudIsGame } from '$lib/hudDocs';
import { DOCK_VIEWS } from '$lib/dockMenu';
import { safeStorage } from '$lib/safeStorage';
import { VRButton, XRButton } from '@threlte/xr'
@@ -916,6 +919,18 @@
requestPlay();
}
},
+ // 30 P2: TEST PLAY — back to the menu, into Play, the Start screen. Offered only
+ // where it means something: a scene with no game shell has no menu to start from.
+ ...($hudIsGame
+ ? [
+ { section: 'Game' },
+ {
+ label: 'Test play (start from the menu)',
+ tooltip: 'Reset the game to its menu, enter Play, and start from the Start screen',
+ action: () => testPlay()
+ }
+ ]
+ : []),
// the FAB is a toolbar cell like any other, so it carries the same tail —
// minus "Hide button" (there is no toolbar without a way to press play)
...toolbarTail(null)
diff --git a/src/components/play/PlayReticle.svelte b/src/components/play/PlayReticle.svelte
index 993276a6..e8db4c9f 100644
--- a/src/components/play/PlayReticle.svelte
+++ b/src/components/play/PlayReticle.svelte
@@ -5,6 +5,7 @@
// playInteract.js.
import { isLocked, isVRMode } from '../../stores/sceneStore';
import { playInteractState } from '$lib/playInteract';
+ import { playCursorFree } from '$lib/playCursor';
import { safeStorage } from '$lib/safeStorage';
// the scroll hint is worth exactly one showing, so it is a LOCAL pref and
@@ -14,7 +15,10 @@
);
const reticle = $derived($playInteractState);
- const visible = $derived($isLocked && !$isVRMode && reticle.mode !== 'off');
+ // 30 P3: a free-cursor game aims with the real cursor, so there is no crosshair to draw.
+ // $playInteractState is the dependency that re-reads it (it moves on every aim change,
+ // and playCursorFree reads its stores through get()).
+ const visible = $derived($isLocked && !$isVRMode && reticle.mode !== 'off' && !playCursorFree());
const carrying = $derived(reticle.mode === 'carrying');
$effect(() => {
diff --git a/src/components/play/PointerLockControls.svelte b/src/components/play/PointerLockControls.svelte
index 018c6484..faa9a53a 100644
--- a/src/components/play/PointerLockControls.svelte
+++ b/src/components/play/PointerLockControls.svelte
@@ -7,6 +7,8 @@
import { userdata, peers } from '../../stores/appStore'
import { dungeonData, slideMove, spawnPointFor } from '$lib/dungeonPlay'
import { resolvePlaySettings } from '$lib/playSettings'
+ // 30 P3: free-cursor games never take the pointer — the real cursor aims
+ import { playCursorFree } from '$lib/playCursor'
import { inputClaims, getGamepadAxes } from '$lib/inputRuntime'
import { gamepadPrefs } from '$lib/gamepadPrefs'
import { coarsePointer } from '$lib/inputDevice'
@@ -111,7 +113,7 @@
if (document.pointerLockElement === domElement) document.exitPointerLock()
} else if (!free && wasFree) {
wasFree = false
- if (!noPointerLock && $isLocked === true && document.pointerLockElement !== domElement) {
+ if (!noPointerLock && !playCursorFree() && $isLocked === true && document.pointerLockElement !== domElement) {
const again: any = domElement.requestPointerLock({ unadjustedMovement: true })
again?.catch?.(() => {})
}
@@ -160,6 +162,10 @@
*/
function requestLock(first: boolean) {
if (noPointerLock) return cancelLockRetry() // W4: nothing to lock on a touch device
+ // 30 P3: a FREE-CURSOR game (`play.cursor: 'free'`) enters play without a lock: the
+ // cursor stays visible and aims (playCursor.playAimNdc), movement keys still walk or
+ // fly, and Escape still leaves — PLC's Escape branch already handles "no lock held"
+ if (playCursorFree()) return cancelLockRetry()
if (get(isLocked) !== true) return cancelLockRetry()
if (get(playPointerFree)) return cancelLockRetry() // 21-E3: the menu owns the pointer
if (document.pointerLockElement === domElement) return cancelLockRetry()
@@ -527,6 +533,7 @@
// a programmatic exit, so this stays idle.)
function onCanvasPointerDown() {
if (noPointerLock) return // W4: a touch tap is the look/interact gesture, not a re-lock
+ if (playCursorFree()) return // 30 P3: a click in a free-cursor game is the game's
if ($isLocked === true && !$playPointerFree && document.pointerLockElement !== domElement) {
const again: any = domElement.requestPointerLock({ unadjustedMovement: true })
again?.catch?.(() => {})
diff --git a/src/extensions/Grid.svelte b/src/extensions/Grid.svelte
index 8fb6b9af..c07a0725 100644
--- a/src/extensions/Grid.svelte
+++ b/src/extensions/Grid.svelte
@@ -1,7 +1,11 @@
- {#if showGrid}
+ {#if showGrid && ($isLocked !== true || $helpersInPlay)}
flowRuntime ->
@@ -1115,6 +1117,40 @@ function updateLeaderboardNodes(time, ctx) {
/** @type {Map} */
const hudSetActed = new Map();
+/** 30 P4: a Store Value / Stored Value key in THIS scene's namespace
+ * (`tp:scene::`). The name is the scene's own (levels'
+ * `currentLevel`), so a best score belongs to its game. @param {string} key */
+function storedKey(key) {
+ let name = null;
+ try {
+ name = levelsRef ? get(levelsRef.currentLevel)?.name ?? null : null;
+ } catch {}
+ return sceneStorageKey(name, key);
+}
+
+/** 30 P4: the Store Value write. `set` keeps whatever arrived (a number or text); `max`,
+ * `min` and `add` are numeric against what this device already holds, and an unchanged
+ * best writes nothing. @param {any} data */
+function storeValue(data) {
+ const key = String(data.key ?? '').trim();
+ if (!key) return;
+ const full = storedKey(key);
+ const mode = data.mode ?? 'set';
+ if (mode === 'set') {
+ writeStored(full, typeof data.value === 'string' ? data.value : num(data.value ?? 0));
+ return;
+ }
+ const value = num(data.value ?? 0);
+ const held = Number(readStored(full, undefined));
+ const has = Number.isFinite(held);
+ const next =
+ mode === 'max' ? (has ? Math.max(held, value) : value)
+ : mode === 'min' ? (has ? Math.min(held, value) : value)
+ : mode === 'add' ? (has ? held : 0) + value
+ : value;
+ if (!has || next !== held) writeStored(full, next);
+}
+
/** The element behind an id, across every HUD document. An input's OPTIONS and its
* `shared` flag live on the element, and a node names only the id. @param {string} id */
function findHudElement(id) {
@@ -1154,7 +1190,7 @@ function updateGameNodes(time, ctx) {
// 1. the ACTIONS, on a fresh trigger stamp only
for (const node of nodes) {
const type = node.type;
- if (type !== 'setgamestate' && type !== 'setcamera' && type !== 'setvariable' && type !== 'setlook' && type !== 'travel')
+ if (type !== 'setgamestate' && type !== 'setcamera' && type !== 'setvariable' && type !== 'setlook' && type !== 'travel' && type !== 'storevalue')
continue;
seeActionNode(node, time);
const stamp = triggerStampFor(node.id, ctx);
@@ -1197,6 +1233,12 @@ function updateGameNodes(time, ctx) {
const hash = typeof data.level === 'string' ? data.level : '';
if (sceneName && levelsRef?.travelToScene) levelsRef.travelToScene(sceneName);
else if (hash && levelsRef) levelsRef.travelToLevel(hash, String(data.levelName ?? ''));
+ } else if (type === 'storevalue') {
+ // 30 P4: a LOCAL write on the stamp edge, inside the actionSeenAt family above (a
+ // fresh node adopting an old stamp must not overwrite a best on connect). It
+ // sends NOTHING: every peer that sees the trigger acts for its own device, which
+ // is the whole semantics of "saved on this device".
+ storeValue(data);
} else if (type === 'setcamera') {
const uuid = typeof data.camera === 'string' ? data.camera : '';
if (uuid) lookThroughCamera(uuid);
@@ -1828,6 +1870,7 @@ export const valueTypes = [
'hudinput', // 21-D4: the HUD as a SOURCE - what the player set on a slider/toggle/etc
// 21-D6 the game shell
'ongamestate', 'getvariable', 'gametime',
+ 'storedvalue', // 30 P4: what Store Value saved on this device
// 24-A A4: `peervariable` was MISSING here since 21-G4, and the omission was silent in
// every direction that is easy to look at — it has an OUTPUT type in flowSockets, an
// evaluator case below, and the editor draws its source handle — but `resolveInputs`
@@ -2368,6 +2411,16 @@ function evalNodeBody(node, allNodes, allEdges, time, seen, ctx) {
// LOCAL read of REPLICATED state, so every peer computes the same number and
// nothing about the read goes on the wire
return num(gameVar(String(d.name ?? ''), d.fallback ?? 0));
+ // --- 30 P4: what THIS device saved (never replicated, legitimately per-peer) ---
+ case 'storedvalue': {
+ const key = String(d.key ?? '').trim();
+ const held = key ? readStored(storedKey(key), undefined) : undefined;
+ if (d.output === 'text') {
+ if (held === undefined) return String(d.fallback ?? '');
+ return typeof held === 'string' ? held : JSON.stringify(held);
+ }
+ return held === undefined ? num(d.fallback ?? 0) : num(held);
+ }
// --- 21-G4: the PER-PLAYER half of the same idea ---
case 'peervariable': {
// Also a LOCAL read of REPLICATED state — every peer holds every peer's row —
diff --git a/src/lib/flowSockets.js b/src/lib/flowSockets.js
index 96a5eaab..b2fb8e33 100644
--- a/src/lib/flowSockets.js
+++ b/src/lib/flowSockets.js
@@ -61,6 +61,9 @@ const OUTPUT = {
ongamestate: 'event',
getvariable: 'number',
gametime: 'number',
+ // 30 P4: the readable half of Store Value (a number socket; `output: text` carries a
+ // string down the same channel, the hudtext precedent)
+ storedvalue: 'number',
// 21-F3's `collectcount` MOVED to the collectible module (R3a); a module value
// node's socket type comes from its registerValueNode `vtype`, so no entry here.
// 21-G4: one player's own number (mine / a named peer / the sum / the max)
@@ -168,6 +171,7 @@ const INPUT = {
setcamera: { trigger: 'event', camera: 'object' },
setlook: { trigger: 'event', camera: 'object', on: 'boolean' },
setvariable: { trigger: 'event', value: 'number' },
+ storevalue: { trigger: 'event', value: 'number' }, // 30 P4
gamestart: { camera: 'object' },
// 21-F4: travel fires on its trigger edge; allplayers takes each player's own
// boolean answer (a Latch, a Gate, a Compare — anything true/false)
diff --git a/src/lib/gamePresence.js b/src/lib/gamePresence.js
index 3f38f0ca..3771d284 100644
--- a/src/lib/gamePresence.js
+++ b/src/lib/gamePresence.js
@@ -25,11 +25,15 @@
// history's import subtree, and nothing here registers a history kind.
import { writable, get } from 'svelte/store';
-import { peers } from '../stores/appStore';
+import { peers, showToast } from '../stores/appStore';
import { isLocked } from '../stores/sceneStore';
import { rolesInfo } from './cloudHooks';
import { sessionHost } from './connectionState';
import { gameState, resetGame } from './gameState';
+// 30 P2: both leaves (hudDocs: svelte/store + gameState + hudKinds + safeStorage; playMode:
+// sceneStore + appStore), so Test play lives here beside the reset permission it obeys
+import { hudIsGame, hudScreenOverride } from './hudDocs';
+import { requestPlay } from './playMode';
/** The two modes. A third would be a protocol change, so the reader treats anything it
* does not recognise as `editor` (the normalize-at-the-boundary rule). */
@@ -275,8 +279,11 @@ export function isSessionWriter() {
*/
export function tickAbandonWatch(now = Date.now()) {
const game = get(gameState);
- if (game.state !== 'playing') {
- // nothing to abandon; forget the arming so the NEXT round starts clean
+ // 30 P2 (roadmap 30 fork 5): EVERY state but `menu` is a round a player can leave — a
+ // paused round and a finished one (`over`, the victory screen) used to linger on the
+ // editor forever, because only `playing` was watched. `menu` is the one state with
+ // nothing to abandon, and reaching it forgets the arming so the NEXT round starts clean.
+ if (game.state === 'menu') {
armedRound = null;
return 'idle';
}
@@ -287,7 +294,11 @@ export function tickAbandonWatch(now = Date.now()) {
}
// a round nobody has entered yet is not an abandoned round
if (armedRound !== game.round) return 'idle';
- if (now - lastPlayingAt < ABANDON_MS) return 'waiting';
+ // 30 P2: ALONE, leaving IS abandoning — there is nobody whose reload or connect dance
+ // the ten-second window protects, and the round must not sit `playing` with its in-game
+ // HUD waiting for a player who is back in the editor. With peers the window stands.
+ const grace = livePeers().length ? ABANDON_MS : 0;
+ if (now - lastPlayingAt < grace) return 'waiting';
if (!isSessionWriter()) return 'notwriter';
// re-read through the single write path: `resetGame` is what the admin button calls,
// so the two ways a game ends up back at its menu are literally one function
@@ -342,6 +353,41 @@ export function requestResetGame() {
/** @type {(()=>void)[]} */
let disposers = [];
+/** was this peer in play at the last isLocked notification (the exit EDGE, not a state) */
+let wasPlaying = false;
+/** @type {any} */ let pokeTimer = null;
+
+/** One deferred watch pass; several notifications in one task coalesce into it. */
+function pokeWatch() {
+ if (pokeTimer || typeof setTimeout === 'undefined') return;
+ pokeTimer = setTimeout(() => {
+ pokeTimer = null;
+ tickAbandonWatch();
+ }, 0);
+}
+
+/**
+ * 30 P2 — ▶ TEST PLAY (roadmap 30 fork 4). What an author means by "try my game": back to
+ * the menu, into Play, the Start screen in front of them. Reached from the game chip and
+ * from the play button's right-click menu.
+ *
+ * The reset goes through `requestResetGame`, so it obeys the same rule as the Users
+ * popover's admin entry: the host (or anyone alone) may, an admin under a roles plugin
+ * may, and anybody else JOINS the game as it is — told so, never silently. This peer's
+ * own screen overrides are cleared either way (LOCAL), so the state-bound screen decides
+ * what shows. Play itself is the ordinary `requestPlay`, synchronously inside the click, so
+ * an immersive session is still requested within the gesture that asked for it.
+ * @returns {{ok: boolean, reason?: string}} the reset's verdict
+ */
+export function testPlay() {
+ const game = get(gameState);
+ const pristine = game.state === 'menu' && !game.startedAt;
+ const verdict = pristine ? { ok: true } : requestResetGame();
+ if (!verdict.ok) showToast((verdict.reason ?? 'The game cannot be reset.') + ' Joining the game as it is.');
+ hudScreenOverride.set({});
+ requestPlay();
+ return verdict;
+}
/** Install the presence broadcast + the abandon watch. Idempotent. */
export function startGamePresence() {
@@ -349,7 +395,26 @@ export function startGamePresence() {
// the subscribe lives HERE and not at module scope: a module-level subscribe runs
// its callback SYNCHRONOUSLY at module eval, and anything it reads that is declared
// below TDZ-crashes the SSR prerender (the documented meshEdit/faceEdit trap)
- disposers.push(isLocked.subscribe(() => publishPlayMode()));
+ disposers.push(
+ isLocked.subscribe((v) => {
+ publishPlayMode();
+ // 30 P2: a screen THIS peer chose during play (the pause menu a P press opened, a
+ // hudscreen node's override) is play state — it must not follow the player back
+ // into the editor, or the next Play lands on a stale pause screen over a round
+ // that has since returned to its menu. Games only: a plain HUD's overrides are
+ // authored behaviour and keep their old lifetime.
+ if (v !== true && wasPlaying && get(hudIsGame)) hudScreenOverride.set({});
+ wasPlaying = v === true;
+ pokeWatch();
+ })
+ );
+ // 30 P2: the watch also runs on the EDGES, not only on its 1s beat: entering play arms
+ // the round even if the player leaves inside the first second, and the last player
+ // leaving resets a solo round on the spot. Deferred a macrotask, because a tick may
+ // WRITE the game state and these are store notifications (never write a store from
+ // inside a subscriber).
+ disposers.push(gameState.subscribe(() => pokeWatch()));
+ disposers.push(peerPlayModes.subscribe(() => pokeWatch()));
watchTimer = setInterval(() => tickAbandonWatch(), WATCH_MS);
disposers.push(() => {
clearInterval(watchTimer);
@@ -361,6 +426,9 @@ export function startGamePresence() {
export function stopGamePresence() {
for (const dispose of disposers) dispose();
disposers = [];
+ if (pokeTimer) clearTimeout(pokeTimer);
+ pokeTimer = null;
+ wasPlaying = false;
}
/** Test/debug view — `abandonWrites` is the only way to tell WHICH peer wrote a
diff --git a/src/lib/gameStorage.js b/src/lib/gameStorage.js
new file mode 100644
index 00000000..e68d6544
--- /dev/null
+++ b/src/lib/gameStorage.js
@@ -0,0 +1,197 @@
+// 30 P4 — WHAT A GAME REMEMBERS ON THIS DEVICE (roadmap 30 fork 7).
+//
+// Two consumers, one rule: a module's `api.storage` and the Store Value / Stored Value flow
+// nodes. Both are LOCAL per device by design — a best score, unlocked levels, a "seen the
+// tutorial" flag — so nothing here replicates, nothing enters a scene file and nothing is
+// undone. A peer's best is theirs; the card says so ("Saved on this device only").
+//
+// THE KEYS ARE A CONTRACT, byte for byte, because a module that must run on an older core
+// (untangle's fallback for a 1.16 client) writes the SAME key itself so its data survives
+// the upgrade:
+//
+// tp:mod:: a module's own namespace (api.storage)
+// tp:scene:: a flow graph's namespace, per scene ('untitled'
+// when the scene has no name)
+//
+// VALUES ARE JSON. `set(key, value)` stores `JSON.stringify(value)`; `get` parses it back
+// and hands the fallback over on a missing key OR a value that does not parse (a hand-edited
+// entry, a truncated write), because a broken save must never crash a game's boot.
+//
+// THE CAP is per MODULE (256 KB), measured as the JSON text of every entry in the namespace
+// plus its key — what the browser actually spends. A write that would cross it returns
+// false and nothing is written; the caller hears it once per session through `onOverCap`
+// (moduleSDK turns that into ONE toast), never once per frame.
+//
+// A DELIBERATE LEAF: it imports safeStorage (itself a leaf) and nothing else, so moduleSDK,
+// flowRuntime and a unit test can all reach it. safeStorage is what makes the promise
+// honest: in Safari private mode, a sandboxed frame or a full quota the write falls back to
+// memory for the session instead of throwing.
+
+import { safeStorage } from './safeStorage';
+
+/** bytes (UTF-16 code units, i.e. JSON text length) one module may keep */
+export const MODULE_STORAGE_CAP = 256 * 1024;
+
+/** @param {string} moduleId */
+export function modulePrefix(moduleId) {
+ return 'tp:mod:' + String(moduleId) + ':';
+}
+
+/** @param {string|null|undefined} sceneName */
+export function scenePrefix(sceneName) {
+ const name = typeof sceneName === 'string' && sceneName.trim() ? sceneName.trim() : 'untitled';
+ return 'tp:scene:' + name + ':';
+}
+
+/** The full key a module writes. @param {string} moduleId @param {string} key */
+export function moduleStorageKey(moduleId, key) {
+ return modulePrefix(moduleId) + String(key);
+}
+
+/** The full key a Store Value node writes. @param {string|null|undefined} sceneName @param {string} key */
+export function sceneStorageKey(sceneName, key) {
+ return scenePrefix(sceneName) + String(key);
+}
+
+/** Parsed-value cache keyed by the FULL key. Every write through this module keeps it
+ * current, so a Stored Value node read every frame costs a Map lookup, not a
+ * localStorage read and a JSON.parse. @type {Map} */
+const cache = new Map();
+
+/** @param {string} full @returns {{text: string|null, value: any}} */
+function read(full) {
+ const hit = cache.get(full);
+ if (hit) return hit;
+ const text = safeStorage.getItem(full);
+ /** @type {any} */
+ let value;
+ let ok = text !== null;
+ if (ok) {
+ try {
+ value = JSON.parse(/** @type {string} */ (text));
+ } catch {
+ ok = false;
+ }
+ }
+ const entry = { text: ok ? text : null, value: ok ? value : undefined };
+ cache.set(full, entry);
+ return entry;
+}
+
+/** Read a full key: the parsed value, or `fallback` when it is missing or unreadable.
+ * @param {string} full @param {any} [fallback] */
+export function readStored(full, fallback = undefined) {
+ const entry = read(full);
+ return entry.text === null ? fallback : entry.value;
+}
+
+/** Does a full key hold a readable value? @param {string} full */
+export function hasStored(full) {
+ return read(full).text !== null;
+}
+
+/** Write a full key (JSON). `undefined` removes it. Returns the JSON text written, or
+ * null when the value cannot be serialized (a cycle, a BigInt).
+ * @param {string} full @param {any} value @returns {string|null} */
+export function writeStored(full, value) {
+ if (value === undefined) {
+ removeStored(full);
+ return '';
+ }
+ /** @type {string} */
+ let text;
+ try {
+ const out = JSON.stringify(value);
+ if (typeof out !== 'string') return null; // a function, a symbol
+ text = out;
+ } catch {
+ return null;
+ }
+ safeStorage.setItem(full, text);
+ cache.set(full, { text, value: JSON.parse(text) });
+ return text;
+}
+
+/** @param {string} full */
+export function removeStored(full) {
+ safeStorage.removeItem(full);
+ cache.delete(full);
+}
+
+/** Every full key under a prefix. @param {string} prefix @returns {string[]} */
+function fullKeysUnder(prefix) {
+ return safeStorage.keys().filter((key) => key.startsWith(prefix));
+}
+
+/** The JSON bytes a namespace holds, optionally pretending one key held `replace` instead.
+ * @param {string} prefix @param {string} [except] a full key to leave out */
+function usedBytes(prefix, except) {
+ let total = 0;
+ for (const full of fullKeysUnder(prefix)) {
+ if (full === except) continue;
+ const text = safeStorage.getItem(full);
+ if (text !== null) total += full.length + text.length;
+ }
+ return total;
+}
+
+/**
+ * The `api.storage` object for one module.
+ * @param {string} moduleId
+ * @param {{cap?: number, onOverCap?: (info: {key: string, bytes: number, cap: number}) => void}} [options]
+ */
+export function makeModuleStorage(moduleId, options = {}) {
+ const prefix = modulePrefix(moduleId);
+ const cap = options.cap ?? MODULE_STORAGE_CAP;
+ return {
+ /** @param {string} key @param {any} [fallback] */
+ get(key, fallback = undefined) {
+ return readStored(prefix + String(key), fallback);
+ },
+ /** @param {string} key @param {any} value @returns {boolean} written */
+ set(key, value) {
+ const full = prefix + String(key);
+ if (value === undefined) {
+ removeStored(full);
+ return true;
+ }
+ /** @type {string|undefined} */
+ let text;
+ try {
+ text = JSON.stringify(value);
+ } catch {
+ return false;
+ }
+ if (typeof text !== 'string') return false;
+ const bytes = usedBytes(prefix, full) + full.length + text.length;
+ if (bytes > cap) {
+ options.onOverCap?.({ key: String(key), bytes, cap });
+ return false;
+ }
+ return writeStored(full, value) !== null;
+ },
+ /** @param {string} key */
+ remove(key) {
+ removeStored(prefix + String(key));
+ },
+ /** this module's keys, without the prefix, sorted @returns {string[]} */
+ keys() {
+ return fullKeysUnder(prefix)
+ .map((full) => full.slice(prefix.length))
+ .sort();
+ },
+ /** forget everything this module stored — the module's own reset */
+ clear() {
+ for (const full of fullKeysUnder(prefix)) removeStored(full);
+ },
+ /** how much of the cap is spent (JSON text of every entry + its key) */
+ bytes() {
+ return usedBytes(prefix);
+ }
+ };
+}
+
+/** TEST SEAM: forget the parsed-value cache (a suite that writes localStorage directly). */
+export function debugResetGameStorage() {
+ cache.clear();
+}
diff --git a/src/lib/hudActions.js b/src/lib/hudActions.js
index 5579f1c1..efb51344 100644
--- a/src/lib/hudActions.js
+++ b/src/lib/hudActions.js
@@ -115,6 +115,10 @@ export const HUD_ACTIONS = [
// entry calls, so the two ways a game is reset are one function.
{ key: 'resetgame', label: 'Reset the game', group: 'Game', role: 'press', node: 'setgamestate', data: { state: 'menu', reset: true }, handle: 'trigger', hint: 'Back to the menu AND the round clock to zero — collectibles read un-collected again.' },
{ key: 'setvar', label: 'Set a variable', group: 'Game', role: 'press', node: 'setvariable', data: { name: 'score', op: 'add', value: 1 }, handle: 'trigger', hint: 'Add to, subtract from or set a shared number.' },
+ // 30 P4: keep the best on THIS device. The value is fed from the `score` variable by a
+ // `via` source (additive to the press role: absent everywhere else, so every other
+ // press action builds exactly what it built before).
+ { key: 'savebest', label: 'Save best score', group: 'Game', role: 'press', node: 'storevalue', data: { key: 'best', mode: 'max' }, handle: 'trigger', via: { node: 'getvariable', data: { name: 'score' }, handle: 'value' }, hint: 'Keeps the highest “score” seen on this device (Store Value, max) — each player keeps their own.' },
// 21-F4: LEVEL COMPLETE — travel to a level. The destination is the AUTHOR'S PICK
// on the Travel card, deliberately not a "next by folder order": the Explorer
// library is LOCAL, so two peers can hold different orders and a computed "next"
@@ -309,6 +313,10 @@ export function describeNode(node, handle = null) {
return 'Only once';
case 'getvariable':
return 'Variable “' + (d.name ?? '') + '”';
+ case 'storevalue':
+ return 'Save “' + (d.key ?? '') + '” on this device (' + (d.mode ?? 'set') + ')';
+ case 'storedvalue':
+ return 'Saved “' + (d.key ?? '') + '” (this device)';
case 'gametime':
return 'Round time (' + (d.read ?? 'elapsed') + ')';
case 'hudtext':
@@ -521,6 +529,13 @@ export function addBinding(elementId, actionKey) {
const actionNode = makeNode(action.node, baseX + 220, baseY, action.data);
created.push(actionNode);
createdEdges.push(makeEdge(press, actionNode, action.handle));
+ // 30 P4: a press action may name the VALUE it acts on too (Save best score reads
+ // the score) — the drives role's `via`, one socket over
+ if (action.via) {
+ const source = makeNode(action.via.node, baseX, baseY + 120, action.via.data);
+ created.push(source);
+ createdEdges.push(makeEdge(source, actionNode, action.via.handle));
+ }
}
} else {
const displayType = /** @type {any} */ (DISPLAY_NODE)[String(action.role === 'drives' ? currentKindOf(elementId) : '')] ?? 'hudtext';
diff --git a/src/lib/hudDocs.js b/src/lib/hudDocs.js
index 8b38b473..81c83f03 100644
--- a/src/lib/hudDocs.js
+++ b/src/lib/hudDocs.js
@@ -21,7 +21,7 @@
// computes the same string with no message of its own. Screen visibility is per-peer ON
// PURPOSE — one player on the start menu while another plays.
-import { writable, get } from 'svelte/store';
+import { writable, derived, get } from 'svelte/store';
import { sessionNow } from './sessionClock'; // 25-E: stamps another peer compares
// 21-D1: the kind REGISTRY. hudKinds imports nothing, so this stays a leaf.
import { HUD_KINDS as REGISTERED_KINDS, defaultsForKind, styleDefaultsForKind, kindDef } from './hudKinds';
@@ -75,6 +75,28 @@ export const activeHudDoc = writable(null);
* @type {import('svelte/store').Writable>} */
export const hudScreenOverride = writable({});
+/**
+ * 30 P1: IS THIS SCENE A GAME? The rule, and why it is this one: a scene is a game when ANY
+ * of its HUD documents holds a screen bound to a game state (`showWhile` set). That binding
+ * is the one thing that makes the editor MASQUERADE as the running game — the shared state
+ * picks the screen, so a menu whose state is `menu` paints itself over the editor with
+ * nobody in Play. Every Games-tab template has one; a hand-made HUD with no state-bound
+ * screen is a plain overlay and keeps its old behaviour (drawn in the editor, buttons live).
+ * A `hudbutton -> setgamestate` wiring alone was considered and NOT taken: with no
+ * state-bound screen nothing masquerades, and reading the graph here would put a flow edge
+ * into a leaf that keeps none.
+ * @param {Record} docs @returns {boolean}
+ */
+export function isGameHud(docs) {
+ for (const doc of Object.values(docs ?? {}))
+ for (const screen of Array.isArray(doc?.screens) ? doc.screens : [])
+ if (typeof screen?.showWhile === 'string' && screen.showWhile) return true;
+ return false;
+}
+
+/** 30 P1: the rule above as a store — HudLayer and the game chip both read it. */
+export const hudIsGame = derived(hudDocs, (docs) => isGameHud(docs));
+
/** The editor's current selection, per document key -> element ids. LOCAL.
* @type {import('svelte/store').Writable>} */
export const hudSelection = writable({});
diff --git a/src/lib/moduleSDK.js b/src/lib/moduleSDK.js
index c81f3631..24ae0f2e 100644
--- a/src/lib/moduleSDK.js
+++ b/src/lib/moduleSDK.js
@@ -43,6 +43,12 @@ import { ndcFromClient } from './canvasRect';
// 27-B: recovery paths report through the diagnostics ring (hardening audit H4)
import { log } from './diagnostics';
import { safeStorage } from './safeStorage';
+// 30 P4: api.storage — a LEAF (safeStorage only), shared with the Store Value flow node
+import { makeModuleStorage } from './gameStorage';
+
+/** modules already told they hit the storage cap this session (ONE toast each, never
+ * one per write — a game saving every frame would otherwise bury the screen) */
+const storageCapWarned = new Set();
// Module SDK v1 — in-repo modules under src/modules// register through
// the api object passed to their register(api). See MODULES.md for the guide.
@@ -1014,6 +1020,24 @@ function makeApi(moduleId, moduleName = moduleId) {
* immune to the shared-scope add race. Rows replicate on the presence channel,
* late joiners converge, a row drops with its owner's disconnect.
*/
+ /**
+ * 30 P4 (roadmap 30 fork 7): what this module remembers ON THIS DEVICE — a best
+ * score, unlocked levels, a settings choice. JSON values under
+ * `tp:mod::` through safeStorage (never throws: a private window or a
+ * full quota falls back to memory for the session), 256 KB per module (a `set` over
+ * it returns false and says so ONCE), LOCAL: never replicated, never in a scene
+ * file, never undone — and deliberately NOT cleared when the module is disabled or
+ * removed (a reinstall keeps your progress; `clear()` is the module's own reset).
+ * `get(key, fallback)` · `set(key, value) -> bool` · `remove(key)` · `keys()` ·
+ * `clear()` · `bytes()`.
+ */
+ storage: makeModuleStorage(moduleId, {
+ onOverCap: () => {
+ if (storageCapWarned.has(moduleId)) return;
+ storageCapWarned.add(moduleId);
+ showToast(`"${moduleName}" hit its 256 KB storage limit on this device — that value was not saved.`);
+ }
+ }),
peerVars: {
/** Write MY OWN row. @param {string} name @param {number} value */
setMine(name, value) {
diff --git a/src/lib/nodeCatalog.js b/src/lib/nodeCatalog.js
index a06ac847..ab712820 100644
--- a/src/lib/nodeCatalog.js
+++ b/src/lib/nodeCatalog.js
@@ -214,6 +214,33 @@ export const nodeCatalog = [
defaults: { name: 'score', fallback: 0 },
params: [{ key: 'name', kind: 'text', placeholder: 'score', maxLength: 40 }]
},
+ // 30 P4 (roadmap 30 fork 7): what a game remembers ON THIS DEVICE — a best score,
+ // a level reached. Keyed `tp:scene::` so a best belongs to its
+ // game. LOCAL by design: Store Value writes this peer's browser and sends
+ // nothing, so a REPLICATED trigger (an ordinary On Click) makes every peer save
+ // its own copy, while a per-player trigger saves only for the one who earned it.
+ {
+ type: 'storevalue',
+ label: 'Store Value',
+ defaults: { key: 'best', mode: 'max', value: 0 },
+ inputs: ['trigger', 'value'],
+ inputLabels: { value: 'value — wire a Counter, a variable, a score' },
+ params: [
+ { key: 'key', kind: 'text', placeholder: 'best', maxLength: 60 },
+ { key: 'mode', kind: 'select', options: ['set', 'max', 'min', 'add'] }
+ ],
+ note: 'Saved on this device only — never sent to other players, never in the scene file.'
+ },
+ {
+ type: 'storedvalue',
+ label: 'Stored Value',
+ defaults: { key: 'best', output: 'number', fallback: 0 },
+ params: [
+ { key: 'key', kind: 'text', placeholder: 'best', maxLength: 60 },
+ { key: 'output', kind: 'select', options: ['number', 'text'] }
+ ],
+ note: 'Reads what THIS device saved — each player sees their own.'
+ },
// the round clock, derived from the shared startedAt stamp — no clock of its own
{
type: 'gametime',
diff --git a/src/lib/nodeDocs.js b/src/lib/nodeDocs.js
index df0afa02..d93cf64d 100644
--- a/src/lib/nodeDocs.js
+++ b/src/lib/nodeDocs.js
@@ -35,6 +35,8 @@ export const NODE_DOCS = {
allplayers: "Iterates the connected players so a per-player value can be read, or a HUD row shown, for each of them.",
setvariable: "Stores a named value in the replicated scene variables when a pulse arrives - shared state without an object.",
getvariable: "Reads a named scene variable as a value - the read side of Set Variable, live on every peer.",
+ storevalue: "Saves a value on THIS device when a pulse arrives (set, keep the max or min, or add) - a best score or a level reached that survives a reload; never sent to other players.",
+ storedvalue: "Reads what Store Value saved on this device, as a number or text - the read side of a best score; each player sees their own.",
gametime: "Seconds since the game (or the round) started, the same on every peer - a clock that pauses with the game.",
peervariable: "A value kept PER PLAYER (score, lives, team) - each peer reads its own row, or a named player's.",
charcontroller: "Turns the connected object into a walking, jumping character driven by the player's movement input.",
@@ -70,6 +72,7 @@ export const NODE_DOCS = {
onclick: "Fires a short pulse when its object is clicked - the bridge from user input into the graph.",
keypress: "Fires a pulse while a keyboard key is pressed - the bridge from your keyboard into the graph.",
onimpact: "Fires a pulse when a physics simulation lands the connected object on the ground or another object.",
+ onhit: "Fires a pulse when a hand or a walking player knocks the object - with how hard it was hit (speed) and whether you did it (byMe).",
onenter: "Fires a pulse when something enters a trigger volume - the checkpoint, doorway and pressure-plate node.",
onexit: "Fires a pulse when something leaves a trigger volume - the other half of On Enter.",
onrest: "Fires a pulse when a physics body has finished moving - the counterpart to On Impact, which fires when it starts.",
diff --git a/src/lib/physics.js b/src/lib/physics.js
index 1ed12567..14f0268b 100644
--- a/src/lib/physics.js
+++ b/src/lib/physics.js
@@ -148,10 +148,34 @@ const IMPACT_MIN_DOWN_VY = 1.2; // m/s downward (pre-step) for a contact to coun
export async function warmup() {
if (RAPIER) return;
const module = await import('@dimforge/rapier3d-compat');
- await module.init();
+ await initQuietly(module);
RAPIER = module;
}
+// 30 P0: rapier-compat's own `init()` hands wasm-bindgen's init a bare byte array — the
+// pre-0.2.93 calling convention — and wasm-bindgen answers with "using deprecated
+// parameters for the initialization function; pass a single object instead". The call
+// is INSIDE rapier's bundle (`init` takes no arguments and the inner init is not
+// exported), so there is no single-object form for us to pass, and rapier is a FROZEN
+// dependency (solver behaviour). So the one warning is filtered for the length of that
+// call and nothing else: an exact-prefix match, restored in `finally`, every other
+// console.warn passes straight through.
+const RAPIER_INIT_WARNING = 'using deprecated parameters for the initialization function';
+
+/** @param {any} module */
+async function initQuietly(module) {
+ const warn = console.warn;
+ console.warn = (/** @type {any[]} */ ...args) => {
+ if (typeof args[0] === 'string' && args[0].startsWith(RAPIER_INIT_WARNING)) return;
+ warn.apply(console, args);
+ };
+ try {
+ await module.init();
+ } finally {
+ console.warn = warn;
+ }
+}
+
/** @param {any} object */
function transformOf(object) {
return {
diff --git a/src/lib/playCursor.js b/src/lib/playCursor.js
new file mode 100644
index 00000000..533c69f7
--- /dev/null
+++ b/src/lib/playCursor.js
@@ -0,0 +1,77 @@
+// 30 P3 — FREE-CURSOR GAMES (roadmap 30 fork 6): WHERE PLAY MODE AIMS.
+//
+// Play mode had exactly one aim: NDC (0, 0), the crosshair, because under pointer lock the
+// cursor is pinned to the centre of the canvas and does not exist for the player. A board
+// game, a puzzle or an instrument wants the opposite — the real cursor, visible, aiming
+// wherever it is — and `scenePhysics.play.cursor: 'free'` asks for that (absent = 'locked',
+// today, byte for byte). A module may publish it too, field by field, through the
+// `userData.play` contract (`resolvePlaySettings`).
+//
+// THIS LEAF IS THE ONE ANSWER to "where is the player aiming right now", so the pieces that
+// ask cannot disagree:
+// · playInteract's tap and grab (the crosshair ray before this),
+// · PointerLockControls, which must not ask for a lock in free mode,
+// · PlayReticle, which has no crosshair to draw in free mode,
+// · the module SDK's `pointerRay()` (lane 30-core-modes reads `playAimNdc()` in play:
+// the cursor when free, the crosshair under a lock — which is also the fix for the
+// stale-mouse ray it returned under a lock).
+//
+// The cursor is recorded in CLIENT pixels and converted to NDC against the canvas at read
+// time (the W9 rule `pointerRay` already keeps: the viewport can change with the pointer
+// perfectly still). LOCAL and unreplicated — an aim is a fact about this screen.
+//
+// Imports stores and leaves only (sceneStore, scenePhysics via playSettings, canvasRect),
+// so playInteract, PointerLockControls and moduleSDK can all reach it without a cycle.
+
+import { get } from 'svelte/store';
+import { isLocked, isVRMode, globalScene } from '../stores/sceneStore';
+import { resolvePlaySettings } from './playSettings';
+import { ndcFromClient } from './canvasRect';
+
+/** the last pointer position over the page, CLIENT pixels */
+const cursor = { x: 0, y: 0, seen: false };
+
+if (typeof window !== 'undefined') {
+ // capture phase + passive: we only read coordinates, and a panel that stops the event
+ // on its way up (the documented delegated-handler trap) must not hide the cursor from us
+ const note = (/** @type {PointerEvent} */ event) => {
+ cursor.x = event.clientX;
+ cursor.y = event.clientY;
+ cursor.seen = true;
+ };
+ window.addEventListener('pointermove', note, { capture: true, passive: true });
+ window.addEventListener('pointerdown', note, { capture: true, passive: true });
+}
+
+/** 'free' | 'locked' — the scene's play cursor, publishers included. Readable in the
+ * editor too (it is authored data), so the Inspector can show it. @returns {'free'|'locked'} */
+export function playCursorSetting() {
+ return resolvePlaySettings(get(globalScene)).cursor === 'free' ? 'free' : 'locked';
+}
+
+/** Is play running with a FREE cursor right now? Desktop play only: a headset has no
+ * cursor to free, and outside play there is no aim at all. */
+export function playCursorFree() {
+ if (get(isLocked) !== true || get(isVRMode)) return false;
+ return playCursorSetting() === 'free';
+}
+
+/** The last cursor position in client pixels, or null before the first pointer event. */
+export function cursorClient() {
+ return cursor.seen ? { x: cursor.x, y: cursor.y } : null;
+}
+
+/**
+ * WHERE PLAY MODE AIMS, in NDC: the cursor in free-cursor play (the centre until the first
+ * pointer event), the crosshair (0, 0) otherwise.
+ * @returns {{x: number, y: number}}
+ */
+export function playAimNdc() {
+ if (!playCursorFree() || !cursor.seen) return { x: 0, y: 0 };
+ return ndcFromClient(cursor.x, cursor.y);
+}
+
+/** test/debug view */
+export function playCursorDebug() {
+ return { setting: playCursorSetting(), free: playCursorFree(), cursor: cursorClient(), ndc: playAimNdc() };
+}
diff --git a/src/lib/playInteract.js b/src/lib/playInteract.js
index 88102534..1ace69f9 100644
--- a/src/lib/playInteract.js
+++ b/src/lib/playInteract.js
@@ -18,6 +18,8 @@ import { velocityFromSamples } from './throwVelocity';
import { resolvePlaySettings } from './playSettings';
import { nameOf } from './lockControl';
import { moduleClickHandlers, moduleInteractiveGroups, fireClickMiss } from './moduleSDK';
+// 30 P3: where play mode aims — the crosshair under a lock, the cursor in a free-cursor game
+import { playAimNdc, playCursorFree } from './playCursor';
// 21-B B3: play mode becomes INTERACT mode — a crosshair grab at distance,
// scroll to push and pull, and a release that throws with the velocity you
@@ -113,8 +115,13 @@ function dynamicUuids() {
/** @param {any} camera */
function aimFrom(camera) {
camera.getWorldPosition(camPos);
- camera.getWorldDirection(camDir);
+ // 30 P3: the aim is the crosshair (NDC 0,0) under a lock and the CURSOR in a
+ // free-cursor game; `camDir` then follows the ray rather than the view axis, which is
+ // what makes a carried object follow the cursor
+ const aim = playAimNdc();
+ centre.set(aim.x, aim.y);
raycaster.setFromCamera(centre, camera);
+ camDir.copy(raycaster.ray.direction);
return sceneHits(raycaster, {}); // no tinyProxies: a proxy carries no `face`
// and is a SELECTION affordance — grabbing an invisible speck is not a feature
}
@@ -218,6 +225,11 @@ function sendThrow(object, velocity, throwIt) {
/** @param {PointerEvent} event */
function onPointerDown(event) {
if (event.button !== 0) return;
+ // 30 P3: with a FREE cursor a press anywhere on the page reaches this window listener —
+ // a HUD button, a toast, the ✕ — so only a press on the VIEWPORT is a world gesture.
+ // Under a lock the target is the locked canvas anyway, which is why this is scoped to
+ // free mode (a synthesized window-level press keeps working there, as it always has).
+ if (playCursorFree() && !isViewportTarget(event)) return;
const mode = interactionMode();
if (mode === 'off' || !activeCamera) return;
const hits = aimFrom(activeCamera);
@@ -245,6 +257,13 @@ function onPointerDown(event) {
beginGrab(target, activeCamera);
}
+/** Is this event aimed at the 3D viewport (the renderer's canvas)? @param {Event} event */
+function isViewportTarget(event) {
+ /** @type {any} */
+ const target = event.target;
+ return !!target && target.tagName === 'CANVAS' && !!target.closest?.('.viewport');
+}
+
/** @param {PointerEvent} event */
function onPointerUp(event) {
if (event.button !== 0) return;
@@ -338,7 +357,11 @@ export function tickPlayInteract(delta, camera) {
return;
}
camera.getWorldPosition(camPos);
- camera.getWorldDirection(camDir);
+ // 30 P3: along the AIM ray, so a free-cursor carry follows the cursor
+ const aim = playAimNdc();
+ centre.set(aim.x, aim.y);
+ raycaster.setFromCamera(centre, camera);
+ camDir.copy(raycaster.ray.direction);
targetPos.copy(camPos).addScaledVector(camDir, carryDistance);
// dt-based, so a throttled tab does not change the feel
const k = Math.min(SPRING_K_MAX, Math.max(SPRING_K_MIN, SPRING_K / Math.sqrt(Math.max(grab.mass, 1))));
diff --git a/src/lib/playMode.js b/src/lib/playMode.js
index 6f573a36..a19f886b 100644
--- a/src/lib/playMode.js
+++ b/src/lib/playMode.js
@@ -3,6 +3,12 @@ import { isLocked, isVRMode, vrOverride, vrPassthrough } from '../stores/sceneSt
// appStore is a LEAF (svelte/store and nothing else — sceneStore already pulls in more
// than it does), so this does not widen the cycle surface the note below is about.
import { showToast } from '../stores/appStore';
+// 30 P0: the back-button marker goes through SvelteKit's shallow-routing entry, not a raw
+// `history.pushState` — the router patches the raw call in dev with a "will conflict with
+// SvelteKit's router" warning, and it is right: its own popstate handler reads the index
+// keys only ITS pushState writes. `$app/navigation` is SSR-safe to IMPORT (only a CALL on
+// the server throws, and the marker is only ever pushed from a browser play press).
+import { pushState } from '$app/navigation';
// THE PLAY STATE MACHINE, lifted out of Controls.svelte so the play FAB, the FAB's
// right-click mode menu and (next) a keyboard shortcut all press the same button.
@@ -154,20 +160,38 @@ export function exitPlay() {
// no history to go back to, pushing and popping our own entry is invisible.
//
// It is safe to pop because the marker is ALWAYS the top entry when we hold one: this
-// app keeps no state in the URL and nothing else in it calls pushState (grep), so
-// there is no router to fight and nothing of the user's can be underneath ours. The
-// flag is the whole guard — see `consumePlayMarker` for the double-pop it prevents.
+// app keeps no state in the URL and nothing else in it pushes history entries (grep), so
+// nothing of the user's can be underneath ours. The flag is the whole guard — see
+// `consumePlayMarker` for the double-pop it prevents.
+//
+// 30 P0: the entry is a SvelteKit SHALLOW entry (`pushState` from $app/navigation) —
+// same url, same navigation index, so the router's popstate handler treats the Back
+// that spends it as a state change and never navigates; our listener below still sees
+// the popstate. The state object lands under the router's `sveltekit:states` key, which
+// is where `playMarkerState()` reads it.
let backMarker = false;
function pushPlayMarker() {
if (backMarker || typeof history === 'undefined') return;
try {
- // the SAME url with a state object: no navigation, nothing for a router to
- // resolve, and `history.state.tpPlay` is a readable answer to "is the marker up?"
- history.pushState({ tpPlay: true }, '');
+ // the SAME url ('' resolves to the current one) with a state object: no
+ // navigation, nothing to load, and `playMarkerState()` is a readable answer to
+ // "is the marker up?"
+ pushState('', { tpPlay: true });
backMarker = true;
} catch {
- /* a sandboxed frame can refuse pushState; play simply keeps its normal exits */
+ /* a sandboxed frame can refuse pushState (and the router refuses before it has
+ started); play simply keeps its normal exits */
+ }
+}
+
+/** the marker's state object as the router stored it on the CURRENT entry (test/debug view) */
+export function playMarkerState() {
+ try {
+ const st = /** @type {any} */ (typeof history === 'undefined' ? null : history.state);
+ return !!st?.['sveltekit:states']?.tpPlay;
+ } catch {
+ return false;
}
}
diff --git a/src/lib/playSettings.js b/src/lib/playSettings.js
index 57784b0d..2f739586 100644
--- a/src/lib/playSettings.js
+++ b/src/lib/playSettings.js
@@ -41,7 +41,11 @@ export function playPublishers(scene) {
* The effective play settings: the scene's shared `play` block, overridden
* FIELD BY FIELD by each publisher (a module only overrides what it declares).
* @param {any} scene
- * @returns {{interaction: 'grab'|'click'|'off', grounded: boolean, eyeHeight: number}}
+ * 30 P3: `cursor` too — 'free' (the real cursor aims, no pointer lock) or 'locked' (the
+ * crosshair, today). A module publishing `userData.play.cursor` overrides the scene's, the
+ * way `grounded` does, which is how a board-game module asks for it without an authored
+ * scene field.
+ * @returns {{interaction: 'grab'|'click'|'off', grounded: boolean, eyeHeight: number, cursor: 'free'|'locked'}}
*/
export function resolvePlaySettings(scene) {
const base = get(scenePlay);
@@ -49,7 +53,8 @@ export function resolvePlaySettings(scene) {
const out = {
interaction: base.interaction,
grounded: base.grounded,
- eyeHeight: DEFAULT_EYE_HEIGHT
+ eyeHeight: DEFAULT_EYE_HEIGHT,
+ cursor: base.cursor === 'free' ? 'free' : 'locked'
};
const publishers = playPublishers(scene);
if (publishers.length > 1 && !warnedMultiple) {
@@ -67,6 +72,7 @@ export function resolvePlaySettings(scene) {
out.interaction = play.interaction;
if (typeof play.grounded === 'boolean') out.grounded = play.grounded;
if (typeof play.eyeHeight === 'number') out.eyeHeight = play.eyeHeight;
+ if (play.cursor === 'free' || play.cursor === 'locked') out.cursor = play.cursor;
}
return out;
}
diff --git a/src/lib/scenePhysics.js b/src/lib/scenePhysics.js
index 8992b6c7..0bc8c1d5 100644
--- a/src/lib/scenePhysics.js
+++ b/src/lib/scenePhysics.js
@@ -43,6 +43,10 @@ export const DEFAULT_SCENE_PHYSICS = Object.freeze({
});
const BOUNDS_ACTIONS = ['freeze', 'respawn', 'delete'];
+// 30 P3: the play cursor. 'locked' (the crosshair under pointer lock) is the default and
+// is NEVER written — a normalized play block carries `cursor` only when it is 'free' — so
+// every scene saved before this, and every scene that does not use it, stays byte-identical.
+const PLAY_CURSORS = ['free', 'locked'];
const INTERACTIONS = ['grab', 'click', 'off'];
/** @param {any} v @param {number} lo @param {number} hi @param {number} fallback */
@@ -142,9 +146,11 @@ export function normalizeScenePhysics(raw) {
{
interaction: pick(playRaw.interaction, INTERACTIONS, d.play.interaction),
grounded: bool(playRaw.grounded, d.play.grounded),
- simOnPlay: bool(playRaw.simOnPlay, d.play.simOnPlay)
+ simOnPlay: bool(playRaw.simOnPlay, d.play.simOnPlay),
+ // 30 P3: present only when free (see PLAY_CURSORS)
+ ...(pick(playRaw.cursor, PLAY_CURSORS, 'locked') === 'free' ? { cursor: 'free' } : {})
},
- ['interaction', 'grounded', 'simOnPlay']
+ ['interaction', 'grounded', 'simOnPlay', 'cursor']
),
// A1: the 20 ceiling is throwVelocity's MAX_LINVEL, restated rather than imported —
// this module is store-only and the response clamps through clampThrow anyway
@@ -189,7 +195,7 @@ scenePhysicsState_.subscribe((s) => sceneGravity.set(s.gravity));
export const scenePhysicsGround = derived(scenePhysicsState_, (s) => s.ground);
/** out-of-bounds config. NOT named `sceneBounds` — that is sceneBounds.js */
export const scenePhysicsBounds = derived(scenePhysicsState_, (s) => s.bounds);
-/** play-mode block ({interaction, grounded, simOnPlay}) */
+/** play-mode block ({interaction, grounded, simOnPlay, cursor?: 'free'}) */
export const scenePlay = derived(scenePhysicsState_, (s) => s.play);
/** A1: the knock block ({enabled, gain, maxSpeed, minSpeed, radius, spin, predict}) */
export const sceneKnock = derived(scenePhysicsState_, (s) => s.knock);
diff --git a/tests/e2e/console-hygiene.test.cjs b/tests/e2e/console-hygiene.test.cjs
new file mode 100644
index 00000000..10ae74ce
--- /dev/null
+++ b/tests/e2e/console-hygiene.test.cjs
@@ -0,0 +1,121 @@
+// 30 P0 — CONSOLE HYGIENE. Three warnings every session printed, each a real fault in
+// miniature and each reported from the diagnostics log of a user's Quest:
+//
+// 1. `WebGLShadowMap: PCFSoftShadowMap has been deprecated. Using PCFShadowMap instead.`
+// threlte's