newbury-exhibit-v3/docs/PAGES.md

Pages

Every HTML page the exhibit serves, and what it's for.

Production base URL: https://newburynights.hideawaygaming.com.au/

Keep this current. When a page is added, renamed, or removed, update this file in the same commit — it's the index there is, since there's no /admin/ landing page (admin URLs must be typed in full).

Visitor

Path	Page	What it does
/	Exhibit	Landing screen → camera AR view. The thing visitors use. Tracking HUD appears in dev mode.

Admin

Open in EXHIBIT_MODE=dev; password-protected in EXHIBIT_MODE=final (ADMIN_PASSWORD in .env).

Path	Page	What it does
/admin/layout.html	Layout Editor (3D)	Marker anchors, building occluders, spawn points, wander paths, table size. Save/load named layouts.
/admin/playlist.html	Playlist	Tracks (set, spawn timing, concurrency, priority), residents, behaviour tuning, time windows.
/admin/characters.html	Characters	Per-ghost visuals: model, part placement, gradient colours, opacity, height, scale, face/torso textures.
/admin/landing.html	Landing Page	Visitor landing screen: title, logo, background, accent colour, about text, disclaimer.
/admin/preview.html	Virtual Viewport	Live orbit view of whatever ghosts are currently active, straight off the same WebSocket feed as the exhibit. Ground truth when the AR view disagrees.
/admin/plan.html	Placement Plan	Measured plan for physically positioning crests and models on the real table.
/admin/print.html	Print Crests	Generates printable ArUco markers ("Newbury Crests") at the configured sizeMM.
/admin/calibrate.html	Calibrate	Camera/marker calibration helper. Detects crests without filtering against the scene, so it's the quickest way to prove a printed crest is readable at all.
/admin/errors.html	Client Errors	Errors reported by visitor devices (JS errors, unhandled rejections, ghost build and scene-fetch failures). First stop when something works on one phone but not another.
/admin/login.html	Login	Only relevant in final mode.

Useful API endpoints

Read-only ones are handy to open directly in a phone browser while debugging; the rest need auth in final mode.

Endpoint	Returns
/api/info	Mode (dev/final) and build info
/api/scene	Live scene: anchors, spawns, paths, buildings, table
/api/playlist	Live playlist config (tracks, residents, behaviours)
/api/ghosts	Full ghost roster + colour gradients
/api/characters	Per-ghost visual overrides
/api/models	Uploaded OBJ model manifest
/api/landing	Landing page content
/api/layouts	Saved named layouts
/api/client-errors	Reported client errors (auth in final mode)
/ws	WebSocket: scene, active, spawn, despawn, characters, pong

Gotcha worth remembering

Detection filters camera detections against the marker IDs in the active scene. A crest that isn't an anchor in the current layout is detected and then discarded, which used to look exactly like "the camera can't see anything".

• The scene is now fetched over HTTP at start, so a down or flapping WebSocket no longer breaks tracking.
• The HUD reports scene N anchors (or NOT LOADED) and markers 1/2 seen [0,7] — usable over raw — so a filtered-out crest is visible at a glance.
• The tracking chip says "Crest N not in this layout" rather than "Point at a Newbury Crest" when this happens.