# 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.

## References

- [Three.js documentation](https://threejs.org/docs/)
- [Three.js examples](https://threejs.org/examples/)
- [glTF specification](https://www.khronos.org/gltf/)