threejs-primitive-reconstructor

name	threejs-primitive-reconstructor
description	create robust, browser-runnable three.js primitive reconstructions from static low-poly, voxel, isometric, or stylized game-art reference images. use when the user asks to turn an image or prompt into a three.js/html asset, generate a primitive-only scene, debug non-rendering three.js output, or produce a reusable prompt/template for low-poly three.js reconstruction.

Three.js Primitive Reconstructor

Core workflow

Use this skill to generate a reliable single-file Three.js HTML scene from a low-poly, voxel, isometric, or stylized 3D reference image.

1. Inspect the reference image visually before coding.
2. Produce a short analysis inventory in the response and include the same inventory as a comment block at the top of the script.
3. Generate one plain .html file, not React, JSX, iframe, or srcDoc.
4. Use only primitive geometry: BoxGeometry, CylinderGeometry, ConeGeometry, SphereGeometry, Group, and MeshStandardMaterial.
5. Use the import-map loading pattern from assets/threejs-scene-template.html.
6. Keep objects aligned to integer or half-integer tile coordinates when reconstructing grid-based scenes.
7. Add soft shadows, matte materials, and an immediate camera view where the asset is visible without user adjustment.
8. When the user reports a loading or rendering error, first replace CDN/import patterns and wrappers with the robust plain HTML template in assets/threejs-scene-template.html.

Required analysis inventory

Before the code, summarize:

1. Camera and framing: projection feel, camera type, azimuth/elevation, crop/centering.
2. Palette: 8-15 hex colors visible in the reference.
3. Ground/podium: grid size, tile size, base thickness, grass variation, water/path positions.
4. Structures: type, grid position, footprint, height, wall/roof colors, distinguishing features.
5. Nature: trees, bushes, flowers, rocks, grass tufts, size variation.
6. Farm/details: crops, stairs, doors, windows, fence rails, small props.
7. Sky/atmosphere: sky color, fog, clouds/smoke.
8. Animation: optional rotation, drifting clouds, rising smoke, water shimmer.

Coding rules

• Use one self-contained .html file.
• Use an import map with unpkg.com exactly as shown in assets/threejs-scene-template.html.
• Import with import * as THREE from 'three' and OrbitControls from three/addons/controls/OrbitControls.js.
• Do not use esm.sh, cdn.jsdelivr, relative Three.js module paths, React, JSX, iframe, or srcDoc.
• Do not use external assets, textures, GLTF, OBJ, FBX, SVG, or postprocessing.
• Use MeshStandardMaterial throughout; default roughness: 1 and metalness: 0.
• Set renderer.outputColorSpace = THREE.SRGBColorSpace.
• Enable renderer.shadowMap.enabled = true and THREE.PCFSoftShadowMap.
• Add a resize listener.
• Append renderer.domElement directly to document.body.
• Keep comments sentence case.
• Keep the generated file under roughly 500 lines unless the user asks for more detail.

Reference and template files

• Read references/reconstruction-prompt.md when the user wants the reusable prompt or prompt wording.
• Use assets/threejs-scene-template.html as the starting point for generated HTML.
• Use scripts/write_scene_from_template.py only when a quick local template copy is useful; customize the copied file afterward.

Debugging non-rendering output

If a generated scene does not render:

1. Remove React, JSX, iframe, and srcDoc wrappers.
2. Replace module imports with the import-map pattern in the template.
3. Confirm the file is served through a local server, for example python3 -m http.server 8000, then opened at http://localhost:8000/scene.html.
4. Confirm renderer.domElement is appended to document.body.
5. Confirm the camera points at the asset and the object is near the origin.
6. Simplify animation until a static render works.

Cottage reference shortcut

For the cropped cottage reference, reconstruct:

• A 5 by 5 floating grass tile island with a brown dirt base.
• A front-left water strip slightly below grass level.
• One warm yellow cottage centered slightly back-left.
• A bright blue hipped roof with dark blue ridge/caps.
• A tall chimney with four rising smoke puffs.
• A brown front door, cyan windows with dark frames, and exterior stone stairs on the right.
• A wooden fence around the front/right/back of the yard.
• Grass tufts, small white/yellow flowers, sky-blue background, soft shadows, and matte materials.