Web 3D Engineering Standards

Use this reference when a game explicitly chooses the 3D path. The default web 3D engine is Three.js with TypeScript; this path is opt-in and does not silently convert an existing 2D Phaser game.

Choose and pin the runtime

Record Rendering Mode: 3D and the exact three version in TECH_STACK.md before implementation.
Install Three.js through the project's package manager. Do not depend on a CDN-only runtime, an unpinned latest tag, or a copied dependency whose version is not recorded in the lockfile.
Keep the browser game boundary explicit: the renderer owns scene presentation, while rules, scoring, progression, and content state stay in plain TypeScript modules where practical.
Use WebGLRenderer as the compatibility baseline unless the project has a separately verified WebGPU plan. Do not claim WebGPU support from a local-only experiment.

Keep a small 3D architecture

Keep one obvious browser entry point that creates one renderer, one scene root, and one active camera graph for the current game view.
Separate responsibilities into main.ts/bootstrap, renderer setup, scene or world composition, input mapping, domain state, and asset loading. Do not put all behavior in one animation loop.
Use a typed camera contract and explicit coordinate/unit conventions. Record world-up, player height, movement units, near/far planes, and collision assumptions in TECH_STACK.md or the relevant role artifact.
Prefer a small vertical slice: one camera, one controllable object, one interaction, one feedback path, and one restart/continue outcome before adding a large world.
Keep animation and gameplay timing based on elapsed time, not frame count. Make pause, resume, restart, and visibility changes explicit.

Load and own 3D assets

Prefer GLB/glTF for runtime models. Load them through GLTFLoader or the project's verified loader boundary, and keep model paths project-relative.
Use a loading state with progress or a clear fallback. A missing model, texture, environment map, or decoder must produce an actionable error instead of an empty canvas.
Keep source models, runtime copies, previews, and license metadata distinct. ASSET_PLAN.md is the source-of-truth handoff; only approved project-local paths enter the runtime.
When removing a model or scene, dispose geometries, materials, textures, render targets, and other GPU-owned resources that are no longer used. Do not assume JavaScript garbage collection releases GPU memory.
Keep texture dimensions, color space, normal-map conventions, compression, polygon budget, animation clips, and file size visible in ART_GUIDE.md or ASSET_PLAN.md.

Camera, input, and responsive rendering

Update the camera aspect/projection and renderer size from the actual drawing buffer when the viewport changes. Do not stretch a 3D scene by leaving a stale aspect ratio.
Cap device pixel ratio to the project's measured performance target. Prefer stable frame time and readable interaction over maximum resolution.
Make pointer lock, pointer/touch input, keyboard input, and camera movement explicit. Provide a non-pointer-lock fallback for the first playable result when the platform allows it.
Ensure the game remains understandable on the supported desktop and mobile viewports. Record unsupported controls or browser constraints in TEST_REPORT.md.

Performance and visual correctness

Measure frame time, draw calls, visible triangles, texture memory, model size, and load time before optimizing. Fix the measured bottleneck.
Frustum-cull or simplify content only when the scene needs it; do not add a scene graph or streaming framework without evidence.
Verify lighting, tone mapping, output color space, shadows, transparency, depth ordering, and animation transitions in the target browser. A model loading successfully is not visual acceptance.
Test resize, device-pixel-ratio changes, tab background/foreground, pause/resume, restart, and a missing-asset failure path.

Completion evidence

For a 3D playable result, record:

the exact three version and browser/runtime assumptions;
a real-browser path from load to interaction, feedback, outcome, and restart/continue;
desktop and mobile viewport behavior, camera/resize evidence, and console/network results;
model/texture paths, license metadata, approval state, and any placeholder or unsupported feature;
measured performance risks and the next smallest playable result.

Do not call a 3D game complete because the renderer compiled or a screenshot exists. The playable interaction and the relevant browser evidence must be observed.

4.7 KiB Raw Blame History