DS - Voxel Cutaway World Generator MVP Design

Version: 0.2.0
Date: 2026-03-08
Author: Rens Roosloot / Codex collaboration

1. Purpose

This document defines the design specification for the first implementation of the Voxel Cutaway World Generator described in URS.md and FS.md.

2. Implementation Strategy

• standalone page under site/voxel-cutaway-world/
• browser-rendered 3D scene
• static-site compatible deployment
• client-side seeded generation
• no backend services

3. Technology Direction

Recommended direction:

• Three.js for 3D rendering
• plain JavaScript modules for generation and UI logic
• Node.js for local development tooling only

The runtime should avoid unnecessary framework weight.

4. High-Level Architecture

Recommended runtime modules:

1. page bootstrap
2. seed and parameter manager
3. world generator
4. voxel mesh builder
5. scene and lighting setup
6. camera controls
7. UI controls
8. theme manager

5. World Data Model

The world should be represented as a finite 3D block grid.

Recommended block categories:

• empty
• grass/top surface
• dirt
• stone
• water
• snow
• trunk
• leaves
• ore
• lava

Recommended design rule:

• hidden internal faces should not be rendered

6. Generation Design

6.1 Terrain

• use seeded noise or equivalent deterministic height generation
• produce moderate terrain variation only
• reserve lower regions for water

6.2 Biome-like Surface Rules

• grass/default top layer at moderate elevation
• snow at high elevation
• tree placement on stable surface positions only

6.3 Underground Rules

• top subsurface layer: dirt
• deeper layer: stone
• caves carved from underground volume
• ore clusters embedded in underground solids
• lava restricted to deeper levels

7. Scene Design

• floating chunk centered in open space
• default three-quarter elevated camera
• atmosphere/background kept subtle
• the chunk is the visual focal point

8. Lighting Design

Day mode:

• brighter ambient light
• one directional or key light
• clear shape readability

Night mode:

• lower ambient light
• cooler scene balance
• optional emissive treatment for lava

The lighting system should remain simple enough for mobile performance.

9. Interaction Design

• orbit control with constrained vertical angle
• bounded zoom distance
• touch gestures mapped to the same camera model
• regenerate action rebuilds world and recenters scene cleanly

10. Performance Design Notes

• keep chunk dimensions modest
• prefer a single merged mesh path per material class where practical
• avoid rendering hidden faces
• keep material count low
• treat shadows as optional and disable them if mobile performance suffers

11. Security and Deployment Notes

• no secrets in client code
• no third-party runtime scripts unless clearly justified
• all production assets and code remain within site/
• generated content remains local to the client session

12. Suggested Implementation Sequence

1. page shell and viewport
2. static test chunk rendering
3. seed-based block generation
4. mesh generation for visible faces
5. camera orbit/zoom for desktop and mobile
6. day/night theme support
7. regenerate flow
8. visual polish and performance tuning

13. Traceability

• URS interaction requirements -> Sections 7, 8, 9
• URS technical constraints -> Sections 2, 3, 11
• FS world behavior -> Sections 5, 6
• FS camera behavior -> Section 9
• FS performance expectations -> Section 10

14. Current Prototype State

Current implementation status in site/voxel-cutaway-world/:

• standalone public page exists
• seeded world generation is active
• live WebGL 3D rendering is active
• orbit/zoom interaction works on desktop and mobile
• day/night lighting toggle is active

Still to improve:

• mesh efficiency and geometry batching
• stronger material polish
• richer cave/ore/lava tuning
• optional move from vendored runtime files to a formal asset-copy workflow if the project grows