Tinyworld Runtime State

Tiny World Runtime State

Most browser-local persisted user state lives in localStorage under the tinyworld:* prefix. Read/write convention: stringified primitives or JSON.stringify for objects. Never store credentials, local world saves, cloud world saves, or per-viewport pixel positions in the shipped defaults file — see exclusion list below.

Persisted render/material settings that affect shared Three materials must be re-applied during late boot, not only from control input handlers. In particular, material wear (tinyworld:render:materialWear) needs the applyPersistedMaterialSettingsOnBoot() pass so saved wear is visible on first render without toggling the slider.

Builder directional sun defaults to 10.0 (1000%) under tinyworld:render:directionalSun. Keep the one-time migration narrow: upgrade missing/old untouched 1.0 builder values to 10.0, but preserve clearly user-edited non-default values. Island Viewer has its own tinyworld:island-viewer:* graphics keys and migrates its old 1.1 default separately.

Cloud saves are separate from defaults/localStorage:

• The account modal posts full TinyWorld JSON to Netlify Functions (/api/builds) backed by Netlify Database.
• On authenticated boot, local named worlds from tinyworld:worlds.v1 are uploaded to /api/builds; the active unslotted tinyworld:v1 state gets a local slot first so it can be bound to a cloud row. Top-menu "My worlds" and account-modal "My Worlds" must read from the same cloud-aware list.
• The world menu's share action posts the same full state to /api/share; public share URLs load by resolving ?share=<id> to same-origin /api/share?id=<id>.
• Local custom assets are also synced once authenticated. /api/assets stores custom voxel-build stamps and saved asset templates, then merges the remote library into localStorage before pushing the merged local copy back up.
• Keep snapshotCurrentState() in sync with saveState() so account saves and share URLs include grid size, islands, moorings, custom voxel stamps, camera, landscape settings, and cells outside the home board that the user edited.
• Top-bar JSON import should accept the app's own portability shapes: a bare world state (cells at the root), cloud/account envelopes (data or state containing a world), named-world/localStorage lists, and exported asset bundles. Imported worlds should be inserted into tinyworld:worlds.v1 so the account DB sync can pick them up after login.
• The visible top-bar JSON import affordance should be a native <label for="import-file"> trigger with an off-screen file input, not only a button that programmatically clicks a hidden input. Some browsers silently drop hidden-input file picker calls even when the click handler ran.
• Queued account syncs must not be dropped while a previous /api/builds request is in flight. Keep a pending retry flag around twCloudWorldSyncing so imports and saves made during bootstrap still reach the database.
• Live multiplayer rooms are ephemeral runtime state. Keep PartyKit presence (cursor, selected cells, active tool) out of saved world JSON and send durable edits as full cell.set snapshots, then apply them through setCell() so rendering and later account saves stay on the normal persistence path.

Defaults pipeline (dev → all users)

There is a "Save Defaults" button in Settings → Workspace (visible only on localhost / 127.0.0.1 / file:). When clicked:

1. The browser snapshots every tinyworld:* localStorage key (minus the exclusion list).
2. POSTs { settings: { key: value, ... } } to /api/save-defaults.
3. tools/dev-server.js writes the result to tinyworld-defaults.json at the repo root.
4. publish.sh copies that file into dist/ so it ships with the site.
5. On every page load, the first inline <script id="tinyworld-defaults-bootstrap"> does a synchronous XMLHttpRequest for tinyworld-defaults.json. For each key the user does NOT already have in localStorage, it seeds the default. Existing user prefs win — defaults never overwrite.

The bootstrap script MUST have an attribute (e.g. id="tinyworld-defaults-bootstrap") so the tools/check.js regex doesn't grab it. See the inline-script gotcha below.

Exclusion list (must stay in sync, two copies)

Mirror these regexes in both tools/dev-server.js (server filter) and the inline setupDevSaveDefaults() IIFE (client filter):

• /^tinyworld:v\d+$/ — serialised home world
• /^tinyworld:worlds\.v\d+/ — multi-world saves
• /^tinyworld:ai:key:/ — API credentials (SECURITY)
• /^tinyworld:auth:/ — account/session credentials (SECURITY)
• /^tinyworld:ai:prompt$/ — user prompt text
• /^tinyworld:vehicle-demo:/ — session demo state
• /^tinyworld:audio:music-track$/ — per-user manual music choice
• /^tinyworld:audio:music-mode$/ — random vs manual music mode
• /^tinyworld:welcome:dismissedId$/ — per-user welcome dismissal
• /:backup$/ — any explicit backup
• /\.pos$/, /-pos$/, /:pos$/ — panel/widget positions (viewport-specific)

If you persist a new value that should NOT ship as a default, add a matching pattern to both lists in the same change.

Panel/widget positions — RELATIVE, not pixels

Draggable panels (minimap, crowd panel, agent panel, future panels) MUST save their position as percentage of viewport, not absolute pixels. Absolute pixels saved on a wide monitor land off-screen for users on smaller displays.

Format:

localStorage.setItem(KEY, JSON.stringify({
  topPct: +(r.top / window.innerHeight).toFixed(4),
  leftPct: +(r.left / window.innerWidth).toFixed(4),
}));

Read with backward compatibility for legacy absolute values:

let top, left;
if (Number.isFinite(p.topPct) && Number.isFinite(p.leftPct)) {
  top = p.topPct * window.innerHeight;
  left = p.leftPct * window.innerWidth;
} else if (Number.isFinite(p.top) && Number.isFinite(p.left)) {
  top = p.top; left = p.left;
}

Always re-apply on window.addEventListener('resize') and clamp to [8, innerWidth - w - 8] / [8, innerHeight - h - 8].

The existing minimap implementation (clampMinimapPosition / setMinimapPosition / applyStoredMinimapPos / endMinimapDrag) is the reference pattern. Minimap collapse must shrink in place; do not use a translateX(...) trick that pushes the map outside the viewport.

The AI chat panel is a fixed right-side rail, not a draggable bottom prompt. Persist only width/collapse state under tinyworld:agent:panel-pos (the -pos suffix keeps it out of shipped defaults). Do not restore absolute left/top coordinates for the AI chat; it should stay anchored to the right edge, with a left-edge resize grip and a compact collapsed rail.

Audio system

Two layers:

1. HTMLAudioElement for music (looped) and one-shot SFX (cloned per play).
2. Web Audio (PannerNode/StereoPannerNode) for positional sources (engines, water) — distance attenuation + L/R pan based on (sourceWorldPos - camera.position) projected onto camera-right.

State keys (AUDIO_LS):

• tinyworld:audio:music / music-muted / music-track / music-mode
• tinyworld:audio:sfx / sfx-muted
• tinyworld:audio:ambient / ambient-muted
• tinyworld:audio:engines / engines-muted

Music tracks: MUSIC_TRACKS array (currently 6 horizon + 1 rising). Random playback must use only MUSIC_RANDOM_TRACKS / the music-horizon-* files; music-rising-1.mp3 stays selectable manually but should not ship as a default or be picked by automatic random playback. Avoid prop engine files (large-prop-engine-*, foley-propellers-*) — the planes have jet engines, use foley-rocket-engines-1..4. Water variants: foley-water-1..4. Loop seams are hidden by overlaying two variants at different start offsets and per-source gains.

UI: single #sound-icon button lives inside the toolbar (appended in buildToolbar() near the audio panel reference). Click toggles the floating #sound-panel with track list + 4 volume rows (Music, Effects, Ambient, Engines). currentMusicTrack() resolves the persisted choice or random.

Camera / view persistence

Single key tinyworld:view.camera holds:

{ "mode": "perspective", "azimuth": 1.2, "polar": 0.9, "viewSize": 8.2,
  "target": { "x": 0, "y": 0, "z": 0 } }

updateCamera() schedules a throttled save (250ms debounce) every frame the camera changes. On boot, the let declarations read this key and apply with clamping (clampViewSize, MIN_ORBIT_POLAR/MAX_ORBIT_POLAR). Ships in defaults — sets the welcome shot for new users.