Starship Explorer
A first-person starship you can walk, fly and land, built in Three.js with no asset files: every panel, texture and planet is generated at runtime.
Play it in your browser (desktop, WebGL) · How it was built: directed by Samuel Bates and built by a fleet of Claude Code agents under typed contracts and verification gates. The rules they worked under are public: CLAUDE.md and KICKOFF.md.
A first-person walkable starship built entirely in Three.js, with no external assets and no frameworks. Every surface is procedurally generated at runtime: panel textures, grime overlays, emissive teal strips, animated console screens. The aesthetic is a worn industrial freighter lifted from Alien (1979) and rendered with ACES filmic tone-mapping, PBR materials with sRGB-honest 2K procedural textures, GTAO contact shadows, SMAA, filmic grain, and cinematic pooled lighting: warm fixture pools with real falloff, fixture halation, volumetric light shafts with drifting dust motes, and a reactor that breathes (v0.9 "RADIANCE").
Outside the windows the ship is on a Living Cruise: a seeded encounter director streams a two-layer parallax starfield past the hull and schedules a rolling cast of procedurally-painted planets, moons, asteroid fields, and rare events (comets, nebulae, derelicts), all named and all scannable from the cockpit console. Three persistent deep-field nebula sprites (teal, rust-red and magenta, additive, opacity 0.08-0.16) give space permanent color depth. Portholes are framed by thick round bezels: PBR gunmetal torus rings with bolt heads and cylindrical reveal tubes, matching the reference ship's porthole design.
And the ship flies (v1.1 "SOVEREIGN"): take the port cockpit seat, grab the virtual stick, and steer the whole universe: the hull is pinned at the origin while a universe rig counter-rotates space around it. A chase camera reveals the full exterior hull with throttle-keyed engine plumes; an approach assist flies you to a seeded destination planet and parks you at proximity hold. From there (v1.2 "LANDFALL") press L and ride a cinematic atmosphere entry (heat glow, turbulence, cloud punch-through) down to a streamed procedural desert planet: kilometers of terraced mesas under a fog-matched sky, boulder fields and rock spires, roaming dune-strider herds and ridge gliders (scannable into the codex), an optional storm system with rain and lightning, and your own ship parked on the scorched landing pad. Walk out, explore, board the hatch, and you're back at hold. The whole loop repeats, and the entire planet costs nothing measurable against the frame budget.
v1.2.1 hardening (latest)
Real keyboard paths now cover the interactions that older proximity-only hooks missed: sleep, all seven doors, cockpit and survey consoles, the crate panel, relic collection, and the surface hatch. Doors slide, collide, and auto-close; cockpit screens/dust and reactor breathing tick from the live loop; overlay close paths clean up keyboard handlers. Landing detaches the helm, restores surface walking, rejects duplicate requests during the fade, and refines terrain as you move.
Hero planet textures paint across bounded frame slices with identical final pixels and seeded outcomes, including cancellation and disposal. All TypeScript source files fit the 300-line architecture limit. Strict name/dead-hook sweeps and real-input suites guard the two bug classes.
Verified 2026-09-29: headed 16/16 functional tests plus all real-input suites, 131 FPS / p95 8.2 ms, with a 6.2 ms worst measured deferred spawn frame including setup. Detailed recovery and verification evidence: resume-v1.2.1.md.
Screenshots
Controls
| Key / Action | Effect |
|---|
W A S D | Move forward / left / backward / right |
| Mouse (after click) | Look around (pointer-lock) |
E | Interact with highlighted object (take the helm from the port cockpit seat) |
W/S + mouse (at helm) | Throttle and steer; Shift boost, X all-stop, A/D roll trim |
V (at helm) | Toggle the exterior chase camera |
F (at helm) | Approach assist: autopilot to the destination planet |
L (at proximity hold) | Land: descend to the planet surface and walk |
` (backquote) | Toggle debug overlay (fps / draw calls / position) |
Quickstart
npm install
npm run dev
Open http://localhost:5173 in a browser. Click the canvas to capture the mouse.
URL flags:
?bloom=0: disable bloom; AO and anti-aliasing retain their other configured settings.?quality=high: explicitly select the default quality path: GTAO contact shadows, SMAA and shadow-mapped spotlights.?quality=low: disable AO, SMAA and shadow casting for compatibility or battery use.
Commands
| Command | Description |
|---|
npm run dev | Vite dev server with HMR |
npm run build | Production build to dist/ |
npm run typecheck | tsc --noEmit: must be clean before verify |
npm run verify | Headless Playwright: build, screenshot every camera, run all functional tests, write verify/report.json |
npm run verify:headed | Same harness, headed Chromium with GPU; fps numbers here are authoritative |
node scripts/capture.mjs | Records a ~72s showcase video tour to verify/capture/showcase.webm |
Architecture
src/
core/
cameras.ts Named-camera registry; window.__setCam(name) teleport
perf.ts Rolling fps tracker, p95 frame time, window.__perf.sample()
state.ts Ship state: accelerated clock, energy and hunger bars
world/
assembly.ts Positions all rooms, registers lights and space environment
cockpit.ts Forward command room with canopy window cutout
corridor.ts Central spine connecting fore to aft
quarters.ts Port and starboard crew cabins (A + B)
galley.ts Mess / kitchen with interactive stove
engineering.ts Aft reactor room with pulsing column
roomBuilder.ts Shared wall/floor/ceiling panel geometry helpers
roomDressing.ts Shared prop factories (crates, vents, strips)
materials.ts Shared MeshStandardMaterial instances
types.ts AABB, Interactable, RoomModule interfaces
player/
controller.ts WASD + PointerLockControls, capsule collision, isMoving()
interact.ts Centre-screen raycaster, E-key trigger, headless fallback
fx/
textures.ts Procedural CanvasTexture generators (panels, grime, hazard)
texturesEmissive.ts Emissive teal strip and ceiling panel textures
textureHelpers.ts Canvas drawing utilities
shipMaterials.ts Emissive material factories reused across rooms
starfield.ts NEAR streaming parallax star layer (one draw call)
planet.ts Thin PlanetResult adapter over the v0.4 SpaceDirector
space/ 'Living Cruise' flight system (see below)
director.ts Encounter director: seeded scheduler + master tick + scan API
starLayer.ts GPU-streamed star layer (shared NEAR + FAR)
cast.ts Rolling cast entries: spawn geometry, motion, despawn
bodies.ts Procedural body factory (gas giant / rocky / ice / lava / ringed / moon)
bodyTextures.ts Per-body CanvasTextures with baked day/night terminator
asteroids.ts One InstancedMesh asteroid field (one draw call)
events.ts Rare events: comet, nebula sprite, derelict satellite
palette.ts Hue families + shared space palette
names.ts Seeded catalogue-name generator
rng.ts Deterministic mulberry32 PRNG
sway.ts Barely-perceptible ±0.2° camera roll oscillation
audio.ts WebAudio synthesis: engine hum + footsteps (zero files)
bloom.ts UnrealBloomPass + optional SSAO (?quality=high); ?bloom=0 kills bloom
ui/
hud.ts DOM HUD: ship clock, energy/hunger bars, interaction prompt
debug.ts Backquote debug overlay (fps, draw calls, triangles, position)
scripts/
verify.mjs Playwright verification harness (screenshots + perf + functional tests)
Performance Budget
| Metric | Budget | v0.4 (headless, worst camera) |
|---|
| Draw calls | ≤ 300 | 144 |
| Triangles | ≤ 500 k | ~4.9 k |
Headed runs with a real GPU report the authoritative fps (npm run verify:headed); headless fps numbers are not meaningful. The verify harness samples perf from the worst-case camera and records it as perfCamera in report.json. Flags: ?bloom=0 disables post-processing; ?quality=high adds SSAO + shadows (off by default).
Interactions
Everything below is on E (prompts appear when you look at something within reach):
- Sleep: bunks in either crew quarters. Fade to black, clock +8h, energy restored. Restocks the fridge.
- Eat / Take Ration: cook at the galley stove, or open the fridge (hinged door, 3 rations per cycle).
- Drink Coffee: the teal cup on the galley counter. Energy +15.
- Sit: pilot seats (canopy view) and galley mess benches.
E again to stand.
- Doors: all six room doors slide and toggle open/closed.
- Access Console: the cockpit console bank cycles NAV / SYSTEMS / PLANET SCAN overlay modes. PLANET SCAN reads the live nearest body from the flight director: name, class, composition, and range in km (or a no-contact notice when nothing is in range).
- Read: crew-log datapads in both quarters; a cargo manifest in engineering.
- Access Panel: the engineering breaker cabinet offers coolant venting and reactor boosts (number keys).
- Open Locker: one locker per quarters swings open.
- Save Log: the corridor save terminal persists your clock/energy/hunger to localStorage.
- And one crate in engineering that the maintenance log says you should not move.
The ship clock runs at 1 real-second = 1 ship-minute and is displayed in the top-left HUD, along with energy/hunger bars. A flight status strip at the top-center shows STREL-7 · T+HH:MM · CRUISE in the HUD visual language (monospace, cream, letter-spaced), updating live from the ship clock. Walking changes footstep sound by deck surface, each room has its own ambient bed, and the room name toasts as you cross thresholds.
Audio
All sounds are synthesised at runtime via the Web Audio API, with no audio files.
- Engine hum: white noise passed through a 90 Hz bandpass filter, layered with a 58 Hz sine sub-oscillator, modulated by a slow 0.08 Hz LFO for organic breathing.
- Footsteps: short filtered-noise bursts (55 ms, ~700 Hz LPF) fired at a randomised 420–540 ms cadence whenever the player is walking. Playback-rate jitter prevents mechanical repetition.
AudioContext starts suspended and only resumes on the first click or keydown (browser autoplay policy). The game and npm run verify work correctly with audio blocked.
Flight system: "Living Cruise"
The whole space environment is driven through a single call (ship.planet.tick(elapsed)) from the render loop. Under that adapter sits the SpaceDirector (fx/space/director.ts), seeded for deterministic verify screenshots.
- Streaming parallax starfield: two GPU-streamed
THREE.Points layers (one draw call each). The NEAR layer flows aft at cruise speed; the FAR shell scrolls at 25% for depth parallax. Stars wrap in the vertex shader, so there is zero per-star CPU work.
- Encounter director: a seeded soft-timeline scheduler maintains a rolling cast: heroes (radius 60–140), ambient bodies at the window edges, one asteroid field, and at most one rare event (comet / nebula / derelict) at a time. Everything streams aft and self-disposes past the despawn boundary.
- Named, painted bodies: each body is a self-contained group with its own
CanvasTexture, slow self-spin, and a catalogue name (e.g. OORT-339 / d). Textures bake a seeded day/night terminator so bodies read as vivid, self-lit planets rather than flat spheres. Gas giants pick from four hue families; ringed giants add a translucent ring; lava worlds get an emissive crack overlay that blooms.
- Deterministic opening cast: at t=0 the director pins a bright teal gas giant in the canopy (left of the COCKPIT roundel) and a moon in the starboard porthole's sightline, so the hero shots are stable run-to-run.
- Scan API:
getScanData() returns the nearest visible hero (name / class / composition / distance) or null. Surfaced in the PLANET SCAN console mode and via window.__test.getScan().
Material note: space bodies use MeshBasicMaterial (self-lit) because there is no directional sun out in the lane; the terminator is painted into the texture. The cel-comic interior uses MeshLambert. For a future PBR pass, the recommended path is to add a single directional "system primary" light and switch bodies to MeshStandardMaterial, dropping the baked terminator in favour of real lighting; this pairs naturally with the ?quality=high shadow path.
Verification & tests
npm run verify runs a headless Playwright harness that builds, screenshots every named camera, samples perf from the worst-case camera, and runs 16 functional tests, then the real-input suites in scripts/tests/ (the real keys and the real game loop, not test hooks):
| # | Test | Asserts |
|---|
| 1 | Sleep (bunk) | clock +8h, energy restored |
| 2 | Eat (stove) | hunger restored |
| 3 | Door toggle | closed, then re-opened with the real E key |
| 4 | Fridge ration | drained hunger +30 |
| 5 | Fridge state machine | open → ration → close cycle |
| 6 | Door auto-close | an armed door shuts on the real tick when the player walks away |
| 7 | Scan API smoke | getScan() is well-formed and non-null with the deterministic t=0 hero |
| 8 | Quest 0→1→2→3 | panel → breaker boost → file report |
| 9 | Portal roundtrip | ship → verdant → ship, with spawn, return and ship state intact |
| 10 | Codex, relic, save/load | scan a creature, collect a relic, save, reload, socket still lit |
| 11 | Flight model | boot state, auto-bank, heading sweep, damping, monotonic speed, unit attitude |
| 12 | Universe coherence | the rig's rotation flips a world-fixed bearing; the cast stays well-formed under fast flow |
| 13a | Helm | enter and exit, throttle, steering sweep, autopilot holds when you stand |
| 13b | Exterior hull + chase camera | the chase view shows the hull; the cockpit view hides it |
| 14 | Planet approach | F-assist engages, HOLD is reached and clamped, release, reset |
| 15 | Landing roundtrip | entry to walking, ground clamp, hatch re-board, HOLD restored, repeatable |
All tests and the screenshot contract must stay green, and doors must default open.
