59 lines
4.7 KiB
Markdown
59 lines
4.7 KiB
Markdown
# 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/)
|