threejs-photoreal-interior

Photorealistic Interior Scene (Master Guide)

This skill chains the following sub-skills into a complete workflow and provides a directly executable project template. The method is based on room-at-dawn (MIT): an early morning bedroom, entirely procedurally generated, running in a browser. The original project's scale is approximately:

• 1.07 million triangles, loading in about 7 seconds (RTX 4090).
• The baked GI file gi.bin is about 13 MB, baking once takes about 30 minutes.
• The output video is 4K HDR10.

Which Skill for Each Step

Step	Skill	Deliverable
0	3d-spec-prompt	Write the idea into verifiable specs: mood, time, scale, hero objects, camera
1 Dimensions & shell	This skill's template/src/layout.js, parts/room.js	Real-world dimensions (meters), windows, wall thickness, shell
2 Hero objects	threejs-procedural-cloth (blankets, curtains), threejs-procedural-vegetation (trees outside window), threejs-procedural-pothos (indoor plants)	Focal point objects
2b Sky & outside	threejs-sky-backdrop (sky presets, clouds, grass outside, houses, distant tree walls, only build what's visible)	Same sky for both baking and rendering
3 Materials	threejs-procedural-textures	Walls, floors, wood, fabric, wear & tear, book covers
4 Props	threejs-lived-in-props	Cloth draped over chair back, cups, kettle, socks, wires, crumpled paper
5 Lighting	threejs-baked-gi	Sky & sun bounce light baked to vertices, saved as gi.bin; direct sunlight uses real-time light
6 Visuals	threejs-realtime-post	AO, bloom, separate exposure for outside and interior, color grading
7 Verification, recording	webgl-deterministic-recording	Screenshot regression, frame-by-frame rendering, cinematic output (depth of field, motion blur, HDR10)

Starting a New Project

bash <skill folder>/scripts/new-project.sh ~/git_project/my-room
cd ~/git_project/my-room && python3 -m http.server 5430 --bind 127.0.0.1
# http://127.0.0.1:5430/            Pre-baked bake/gi.bin included
# http://127.0.0.1:5430/?bake=128   Re-bake after changing the scene, press "Download gi.bin", save to bake/

(<skill folder> is the Base directory shown when loading this skill; when installed as a plugin, it's under ~/.claude/plugins/cache/)

• This script copies the template and copies each sub-skill's libraries to src/lib/ (gi, post, props, textures, cloth, vegetation, pothos, sky, film). The project becomes standalone.
• No bundler or npm required. three and three-mesh-bvh are loaded from jsdelivr.
• URL parameters:
  • ?cam= : Camera (room, desk, window, corner, view = standing by window looking out).
  • ?t= : Fixed time (leaves, clouds don't move, for screenshots).
  • ?view=gi : View only lighting.
  • ?only=furniture : Build only a specific part.
  • ?exp= : Exposure.
• The page exposes window.__ready, window.__stats, window.__camera for direct connection to webgl-deterministic-recording tools.
• Controls: Drag to orbit; WASD / arrow keys to move (Shift to walk slowly, collides with walls and furniture); click on the screen to switch to mouse look with eye height at 1.6 m (Esc to exit). Orbit camera and point of interest are constrained within the room; zooming out or panning won't clip through walls.

Template structure:

File	Content
src/layout.js	The only place for dimensions, sun, sky (with SKIES presets), outside configuration (OUTSIDE), color grading, camera, and furniture collision bounds (BLOCKERS)
src/materials.js	lit() (GI patch, preserves original shader patch, records albedo), solid(), tbox(), tplane(), metres()
src/scene.js	Builds each part by order; order is fixed
src/parts/room.js	Floor, ceiling, four walls, window openings and sills, black outer shell, wall cores
src/parts/outside.js	Outside the window: sky sphere, grass, gravel path, hedges, house, distant tree wall, main tree & mid-distance trees (only what's visible, threejs-sky-backdrop + threejs-procedural-vegetation). All gi = false, don't block baking light
src/parts/furniture.js	Table, chair, towel draped over chair back (PBD), cup, kettle, books on table, books on shelf
src/main.js	Create scene → Bake / load file or flat lighting → Sun → Reflections → Post-processing → Camera (orbit + walk, constrained to room)

Cross-Skill Rules (Must Follow)

1. Units are meters, coordinates are fixed. X along the window wall, Z into the room (window wall at z = 0, z < 0 is outside), Y up. All dimensions are written only in layout.js.
2. Deterministic. Random numbers always use RNG(seed). If the order, name, or vertex count of a part changes, the bake for that mesh becomes invalid; applyBake reports stale meshes.
3. Light exists on vertices, so subdivide. Surfaces with objects on top: subdivide to 1.5–2 cm. Large areas: 4–8 cm. Use tbox/tplane.
4. All lit materials must go through lit(). giPatch directly replaces onBeforeCompile; lit() chains the original patch behind it, including wall variation (wallPatch), cloth backlighting, and wind. Textured materials must provide albedo (the avg of the texture) for correct bounce light colors.
5. Division of sun: Direct sunlight uses DirectionalLight (intensity equals bake settings sun.irr). Bounce light is baked into the file. Do not add any ambient or hemisphere light.
6. Walls must have a solid wall core with shadowSide set to FrontSide. Without it, the sun leaks a row of bright points at wall bases and corners (real issue encountered; see references/integration.md).
7. Exposure targets the interior. Interior is about 1/20 of exterior: exposure ≈ 4.5, outside window use ext ≈ 0.3 to dim.
8. Capture reflections after baking. captureEnv must run after applyBake/runBake, with the probe placed in the center of the room.
9. When distant exteriors are visible, the camera far plane must be larger than the farthest object. The template uses 400 m (tree wall at 100 m, grass extends to 260 m). With far only 100, the clipped distant area exposes a white horizon fog band that moves with the camera (real issue encountered).
10. The sun's shadow camera must cover the tree canopy outside the window so tree shadows fall inside: the template places the sun 30 m away, near 12, far 40.

Benchmarks (Template, RTX 4090, Chrome headless, 1280×800)

• Scene creation 1.2 seconds, with towel simulation about 0.65 seconds; 107k triangles; page to first frame about 1.6 seconds.
• On-site bake at 128 spp: 61,407 sample points, 26 workers, 6 seconds, gi.bin 743 KB. On reload, applied 39 meshes, 0 stale meshes.
• preview.jpg: Room, desk side, window, lighting only. preview-bake.jpg: Left is flat lighting, right is after baking.

Further Reading

• references/workflow.md: Each step's method, decisions to make, deliverables, and checkpoints.
• references/integration.md: Interfaces between skills, gotchas, encountered issues.
• references/checklist.md: Acceptance checklist and reference ranges for numbers.