Voxel World Character & Asset Spec¶
Doc owner: Justin Purpose: Production spec for 3D asset creation (characters, floating architectural spaces, environmental base layers, objects) Companion PRD: PRD_4_COMPANION_VOXEL_WORLD.md
Art Direction (Revised)¶
The Core Concept: A chunky voxel character (Crossy Road style) inhabiting a surreal, floating architectural diorama that emerges from a massive environmental base layer (Monument Valley style).
Important Note on Variety (Non-Prescriptive Examples): The examples in this spec (arches, stairs, cloud seas, oceans) are illustrative motifs, not a required default layout. We want a wide range of silhouettes and compositions while keeping strict voxel fidelity and the baked-lighting look.
Style Contrast & Grounding: * Characters: Cute, grounded, slightly rounded edges, chunky proportions. They feel tactile and toy-like. * Spaces (The Diorama): Not limited to arches/stairs. Spaces can be surreal, impossible architecture or stylized biome/terrain dioramas—all built from stepped voxel forms with baked lighting. * Architectural styles (examples): Floating islands, arcades/archways, courtyards, bridges, stepped towers, monumental frames, decorative geometry. * Biome/terrain styles (examples): Grassy worlds (hills, berms, terraces), metallic/industrial terrains (plates, vents, ribs, grates), hellish landscapes (cliffs, valleys, ravines, lava channels), crystalline badlands, canyon cuts. * The "Ground Effect" (New): The floating diorama is not entirely untethered. It is visually "grounded" by a massive, low-poly environmental base layer situated just below the playable grid (e.g., a dense sea of voxel clouds, stylized low-poly ocean water, or abstract terrain). The architecture should appear to rise from or float just above this base.
Voxel Fidelity: * Everything—from the smallest character details to the massive cloud bases—must maintain strict voxel fidelity. * Surreal architecture is constructed from large, chunky voxel blocks, steps, and faceted slopes. No smooth curves.
World Style Library (Enabled Directions)¶
Spaces are allowed (and encouraged) to read as distinct “worlds,” not just architectural dioramas. Each space should pick one primary world style (and optionally one secondary accent) and express it through palette, terrain kit choices, props, and atmosphere—while staying voxel-stepped and baked-lit.
Monumental / Illusion-Architecture Worlds (First-Class): * Minimalist Impossible Monuments: Serene, contemplative puzzle-sculptures. Soft pastels and restrained gradients with clean separations so shapes read instantly. Geometry favors single iconic structures, impossible stairs/loops, Escher-like constructions, and an isometric “gallery piece” feel with minimal clutter. * Floating Islands in the Void: Dreamlike dioramas suspended in emptiness. Background is flat or subtly gradiented; no strong horizon line. Chunky islands, isolated towers, and bridges hanging over pure sky/void to emphasize scale and unmoored space. * Sacred Temples and Towers: Quiet spiritual spaces (palace/shrine lineage). Warm stone + gold accents with turquoise/teal details. Domes, arches, minarets, courtyards, and simplified ornamental repetition expressed as stepped voxel patterns (still no textures). * Water, Reflections, and Calm Ruins: Meditative half-submerged monuments. Cool blues/greens and desaturated backgrounds with rare bright accents. Pools/canals/bridges and steps disappearing into water; slow motion elements (ripples, rising platforms) are allowed as an atmosphere cue. * Stark Monochrome / High-Contrast Spaces: Graphic, poster-like worlds using limited schemes (e.g., white structures on deep fields). Simple prisms/ramps/stairs arranged for optical tricks and silhouette-first readability. * Nature-Touched Monuments: Architecture with gentle, curated natural intrusion (never messy). Soft greens/earth tones with small bursts (flowers/foliage). Vines along pillars, small roof trees, perched birds/crow-people silhouettes are valid accents. * Surreal Movement / Shifting Geometry: Calm surface, impossible underlying logic. Palette stays consistent; moving parts are indicated via shading/gradient shifts. Rotating bridges, sliding blocks, reversible depth cues, and “foreground/background swap” illusions are allowed.
Core World Styles (Biomes): * Lush Worlds: Soft sci‑fi paradise; saturated greens, vivid flowers, bright skies; rolling hills/meadows/forests; frequent clouds, gentle rainbows; variants include tropical islands, bubble‑lush flora, fungal forests with giant mushrooms. * Barren / Dead Worlds: Western desert or abandoned moons; ochres/rust/bone whites/desaturated blues; rocky mesas, dunes, cracked basins; sparse or no vegetation; harsh lighting and long shadows with dusty haze. * Scorched / Volcanic Worlds: Hostile hellscapes; dark ground (black/brown) with intense orange/red/sulfur highlights; jagged ridges, obsidian plains, smoking fissures, lava rivers; ash storms/embers and extreme contrast. * Frozen Worlds: Stark arctic; whites/pale blues/cyan ice with aurora accents; snow plains, ice cliffs, frozen seas, crystalline outcrops; blizzards/whiteouts and foggy silhouettes. * Toxic Worlds: Biohazard swamp/spill/diseased jungle; sickly greens/purples/acid yellows; boggy lowlands, luminous pools, bulbous sacs, twisted trees, fungal growth; constant mist/rain and drifting spores. * Irradiated Worlds: Nuclear wasteland/alien badlands; neon yellows/greens with ultraviolet skies; eroded rock fields, crystalline shards, cracked earth, bone-like formations; intense sky glow and occasional lightning. * Marsh / Swamp / Water Worlds: Humid, overgrown; deep greens/browns/murky teals with fog layers; shallow water, roots, sinking ruins, reeds, scattered islets; drizzle/fog and low visibility. * Ocean / Deep-Water Emphasis: Endless sea or submerged vistas; gradient blues/greens with god‑rays and bioluminescent accents; coral “trees,” kelp pillars, cave networks; particulate water depth and distant silhouettes. * Gas Giant Worlds (No Ground): Pure atmosphere; layered color bands and dense fog; storms, vortices, lightning; interest is in cloud structures and storm eyes (no traditional terrain).
Exotic / Glitch Worlds (Surreal Subtypes): Treat each subtype as its own concept sheet. Use limited, stylized palettes (often monochrome + accent) and “art-object” repetition. * Hex Worlds: Giant tiled hex surfaces, honeycomb hills, flat hex plates; very artificial. * Shard / Glass Worlds: Floating slabs, fractured planes, crystalline debris fields. * Bubble Worlds: Floating translucent/iridescent spheres clustered like jellyfish; soft terrain beneath. * Contour / Cable Worlds: Pods anchored by thick cable nets; biomechanical vibes; multi-leg stalk forms. * Glitch/Flicker Worlds: Synthetic artifacts and repeating motifs; “data” errors expressed via geometry repetition and vertex-color banding (no textures).
Mega-Exotic (Scale/Grade Variant): Any world style can be “mega” by pushing a single dominant color cast and scaling select assets absurdly (gigantic trees, mega rings, enormous tubes) while keeping voxel fidelity.
Infested / Dissonant (Horror Variant): Corruption/body-horror direction: bruised reds/purples/fleshy browns/oily sheens; organic growths over rock, vein-like tendrils, egg clusters, burrow scars; swarming particles and low visibility.
Monument Valley–Style World Design Levers (Use on Monumental Worlds): * Architectural Lineage: Middle Eastern (domes, lattices, courtyards) vs brutalist/minimal sculpture (monoliths, plates, sharp massing). * Density: Single iconic structure in void vs layered cities of interlocking towers and bridges. * Illusion Type: Penrose stairs, forced-perspective overlaps, reversible depth, or space that reconfigures on rotation. * Color Discipline: One dominant hue + single accent vs complementary duos defining different “sides” of geometry.
Quick Style Levers (Use on Any World): * Color Logic: Naturalistic vs fully synthetic lighting (e.g., cyan shadows + magenta highlights) achieved via baked vertex gradients/AO. * Sky Dominance: Some worlds are ground-driven; others are sky-driven (rings, multi-moons, thick nebulae, storm walls). Use the background gradient + distant voxel elements to reinforce.
Shading & Color: * Vertex-colored / baked lighting only. No texture maps. All color is baked into geometry via vertex colors. * Crucial Element: High-Fidelity Baking. To achieve a smooth, impressive look while retaining chunky voxel geometry, all assets must utilize heavily baked vertex-color gradients and baked ambient occlusion (AO). * Gradients: Surfaces should rarely be a single uniform flat color. Use soft fades (often vertical base-to-top, but also horizontal where appropriate) to mimic environmental lighting (e.g., a tall pink pillar fades from slightly darker at the base to lighter at the top). * Ambient Occlusion (AO): Crevices, inside corners, step recesses, and block junctions must be painted darker via vertex color to add weight, depth, and softness to the stepped forms. * Atmosphere: The background is a soft vertical CSS gradient layered with distant, large-scale voxel environment meshes (celestial bodies, distant monoliths) to provide depth beyond the immediate base layer.
Rendering: Three.js WebGL with NeutralToneMapping.
Character Spec (Per Companion)¶
No major changes to character structure from original spec.
4 companions (Luna, Nyx, Echo, Kael), each with 3 evolution stages.
Dimensions & Scale¶
| Property | Value |
|---|---|
| World space | 32×32 grid, 1 unit = 0.5m (The playable floating area) |
| Character height | ~1.0 unit (0.5m) |
| Grid footprint | 1×1 cell |
(Character Geometry budgets, Identity Colors, Rigs, and Animations remain unchanged from original spec.)
Export Format¶
| Property | Value |
|---|---|
| Format | GLTF 2.0 binary (.glb) |
| Compression | Draco mesh compression |
| Up axis | Y-up |
| Scale | 1 unit = 0.5m |
| Materials | Vertex colors required. Prefer unlit. If using PBR: keep it simple (metalness=0, roughness=1) and rely on baked vertex-color gradients + AO (no texture maps). |
Spatial Element & Prop Spec (The Playable Area)¶
We are building modular, floating architectural kits that snap to the 32x32 grid.
| Property | Value |
|---|---|
| Tri budget | 500-2,500 per architectural module |
| Grid size | Modular (1x1, 2x2, 1x4, etc.) fitting the 32x32 grid |
| Style | Chunky, stepped, faceted voxel architecture. Avoid smooth curves. Baked lighting (vertex gradients + AO) required. |
| Origin | Bottom center of the module (crucial for grid snapping) |
Style Note (Enforced): * Stepped, Not Smooth: Arches and domes remain stepped voxel constructions (no smooth curves). * Baked Lighting Requirement: All architectural modules must include baked vertex-color gradients (often vertical fades) and baked ambient occlusion in recesses/inside corners to soften chunky geometry and add depth.
Composition Guidance (Flexible, For Variety)¶
These are intentionally high-level rules to prevent “platform + arch + clouds” repetition while keeping a coherent voxel language: * Declare a world style: Each space should clearly read as one of the enabled world styles (lush, barren, volcanic, frozen, toxic, oceanic, gas giant, exotic, etc.) through terrain modules, props, and atmosphere—not just through color. * Silhouette diversity is required: Each space should have a distinct read at a glance (e.g., tall vertical stack, broad terrace, ring/courtyard, bridge network, canyon cut, spiral ascent). * No single hero motif every time: Arches are a strong motif but must not dominate every scene. * Guideline: 0–2 arch modules per space unless the theme/archetype is explicitly “Cathedral/Arcade.” * Prefer mixing frames (arches/portals), masses (monoliths/walls), and connectors (bridges/ramps) rather than repeating one type. * Require negative space: Include at least one intentional void/cutout (gap, window, hollow, underpass) to avoid “solid block diorama” sameness. * Vary height language: Use stepped tiering and offsets; avoid always-flat single-elevation platforms.
Scene Archetypes (Examples, Pick One Per Space)¶
Use these as templates to guide module selection. They are not theme-locked. * Courtyard/Ring: Walkable loop around a central void/feature. * Terraced Steps: Broad stepped plinths with multiple elevations and landings. * Bridge Network: Multiple small islands connected by bridges/ramps; strong negative space. * Spiral/Ascent: A stepped spiral stair/tower read with a clear vertical journey. * Split-Structure: Two major masses with a single dramatic connector. * Monolith Plaza: One dominant landmark (monolith/tower) plus smaller supporting forms. * Cliff & Valley: A stepped ravine/valley cut with traversable rims, bridges, and strong vertical drop. * Ridge Walk: Long, stepped ridgelines with side spurs and occasional underpasses/cutouts. * Crater/Basin: A lowered center basin with surrounding terraces and a landmark at the rim or core.
Modular Architectural Types¶
These assets are re-colored based on the active Theme palette.
| Module Type | Grid Size | Description & Voxel Style |
|---|---|---|
| Base Platform | Varies (e.g., 4x4) | The walkable islands. Gaps must exist to see the Environmental Base below. |
| Pillar/Column | 1x1 (Tall) | Verticality markers. Stacked cube segments. |
| Voxel Archway | 3x1 (spanning) | Frames views. Blocky, stepped voxel arches. |
| Stair/Ramp Block | 1x2 or 2x2 | Transitions between platform heights. Chunky stepped blocks. |
| Decorative Spire | 1x1 | Faceted, low-poly domes or pyramids made of large voxels. |
| Portal Frame (Non-Arch) | 3x1 or 2x1 | Rectilinear stepped doorway/viewport frame (strong alternative to arches). |
| Bridge/Connector | 1x2, 1x3, 2x3 | Narrow stepped bridges, causeways, or beam-like connectors between platforms. |
| Balcony/Overhang | 2x2, 2x3 | Cantilevered ledges and terraces to create layered silhouettes. |
| Retaining Wall/Buttress | 1x2, 2x2 | Support masses that add “weight” and reduce the toy-block feel via AO-rich recesses. |
| Parapet/Railing Edge | Edge strip | Repeating stepped edge detail to vary platform silhouettes without adding complexity. |
| Window/Cutout Wall | 2x2, 2x3 | Wall segment with a carved void (window) for negative space and depth. |
Modular Terrain & Biome Types (Optional Kits)¶
Use these when the space is more “landscape” than “architecture,” or when mixing terrain with architectural landmarks. These should still snap to the grid and follow the same baked-lighting requirements.
| Module Type | Grid Size | Description & Voxel Style |
|---|---|---|
| Terrain Tile (Flat/Soft-Step) | 1x1, 2x2, 4x4 | Walkable ground mass with subtle stepped height variation. Strong vertical gradients and AO in seams to avoid tiling. |
| Cliff Face / Escarpment | 1x2, 2x3, 4x2 | Stepped vertical wall segments with ledges and recesses (AO-heavy). Enables valleys, canyons, and sheer drops. |
| Valley/Ravine Segment | 2x2, 4x4 | A “cut” module that creates negative space: trench, ravine, or basin. Often paired with bridges/overhangs. |
| Rock Spire / Outcrop | 1x1, 2x2 | Natural landmark alternative to decorative spires; irregular stepped silhouette. |
| Grass Cap / Soil Layer | Surface variant | For grassy worlds: a top “cap” color treatment and micro-step edge breaks; rely on gradients (darker soil under lighter grass). |
| Metal Plate / Industrial Floor | 1x1, 2x2, 2x3 | For metallic terrains: stepped panel seams, vents, ribs. Use subtle vertex gradients + AO in panel gaps (no textures). |
| Lava Channel / Corrupted Ground | 1x2, 2x2 | For hellish worlds: recessed channels and jagged stepped edges with strong emissive-like color via vertex color (still no maps). |
Spatial Props (Functional & Decorative)¶
Replacing traditional furniture. Must fit on platform surfaces.
| Prop Type | Grid | Function / Visual Example |
|---|---|---|
| Resting Spot | 2x2 | Sleep location. Raised plinth with geometric voxel cushions. |
| Focus Pedestal | 1x1 | Work location. Chunky pedestal holding a glowing shape/tome. |
| Voxel Flora | 1x1 | Decoration. Abstract, geometric crystalline plants. |
| Ambient Light | Wall | Decoration. Geometric voxel lanterns integrated into architecture. |
Environment & Background Spec (New - The "Ground Effect")¶
These assets create the sense of scale and the "ground effect" below the floating diorama. They are purely visual, non-interactive, and placed outside/below the 32x32 grid.
| Property | Value |
|---|---|
| Tri Budget | 200-1,500 per element (kept very low-poly as they are distant) |
| Scale | Massive relative to character (Base layers cover the entire view below) |
| Style | Ultra-chunky stepped voxel forms. Composed of very large voxel blocks. Lower detail density than playable platforms. Must still use baked vertex-color gradients + AO to avoid stark tiling. |
| Placement | Fixed positions. Base layers are positioned Y-down, just below the lowest playable platform. Distant elements are far outside bounds. |
Environmental Base Layers (The "Ground")¶
Environmental Base Layers Style (Enforced): These massive layers must use strong baked vertex-color gradients and baked AO in recesses to avoid reading as stark tiles or flat blocks at a distance.
Variety Rule (Non-Prescriptive): The base layer is a style lever, not a constant. Avoid using the same base layer type repeatedly across spaces. If multiple spaces are presented in sequence, rotate base-layer types (cloud/ocean/terrain/etc.) to maintain visual novelty.
One of these is selected per space (typically matching the active theme), sitting just below the playable grid to ground the scene.
| Element Type | Description & Voxel Style |
|---|---|
| Voxel Cloud Sea | A massive, undulating layer of large voxel cubes. Must have soft baked blue-to-white gradients and darker baked AO in recesses to create soft shadows and depth (preventing a flat “cotton ball” look). The bottom of the architecture should appear to rest on or slightly penetrate this layer. (Ref: Image 7) |
| Low-Poly Ocean | A flat expanse of large blue voxel tiles. Tiles must have a baked color gradient (dark blue depths to lighter surface). The "foam" edging blocks must have soft baked white gradients so they blend smoothly with the water tiles rather than reading as stark white cubes. (Ref: Image 8) |
| Abstract Terrain Base | Jagged, crystalline, or geometric voxel terrain formations that the platforms float above. |
| Volcanic Field Base | Dark obsidian plates with stepped fissures and recessed lava channels (strong emissive-like vertex color + heavy AO). |
| Ice Shelf Base | Broad stepped ice plates with cliff edges and crack seams defined by gradients + AO; optional fog layer above. |
| Toxic Mire Base | Low, pooled basins with luminous liquid pockets and bulbous growth silhouettes; gradients to imply depth and haze. |
| Shard / Glass Debris Base | Fractured planes and scattered slab fields; strong silhouette and negative space; stylized palette (often limited). |
| Gas Giant Cloud Deck (No Ground) | A “base layer” made entirely of voxel cloud bands/vortices; ground is implied by altitude and fog rather than terrain. |
Distant Background Elements¶
| Element Type | Description |
|---|---|
| Distant Celestial Body | Giant, blocky planets or stylized moons hovering far away. |
| Floating Monoliths | Abstract clusters of giant geometric pillars floating disconnected in the far distance. |
Color Palettes Per Theme (Revised)¶
Colors define structure, atmosphere, and the environmental base.
Theme A: "Ethereal Heights"¶
Soft, dreamlike, cotton-candy cloud city.
| Role | Hex | Voxel Usage |
|---|---|---|
| Background (SkyGradient) | #AEEEEE → #E0F7FA |
Soft aqua to pale cyan gradient |
| Primary Structure | #F4AAB9 |
Pastel Pink (Main platforms, primary architectural masses/frames) |
| Secondary Structure | #8FD3B6 |
Soft Mint Green (Upper platforms, bridges) |
| Accents | #F7D1BA |
Peach/Cream (Domes, props) |
| Environmental Base | #E0F2F1 / #FFFFFF |
Suggested base: Voxel Cloud Sea (Pale aqua mixed with white blocks). Alternate bases are allowed if they fit the theme’s mood. |
| Distant Element | #FFF9C4 |
Pale Yellow (Distant blocky sun/moon shape) |
Theme B: "Mystic Citadel"¶
Twilight, magical, ocean stronghold.
| Role | Hex | Voxel Usage |
|---|---|---|
| Background (SkyGradient) | #2C1E4A → #5D4685 |
Deep night violet gradient |
| Primary Structure | #9D8EC4 |
Muted Purple (Primary architectural masses and landmarks) |
| Secondary Structure | #A3C6D9 |
Desaturated Blue (Secondary platforms) |
| Accents | #F27D55 |
Vibrant Coral/Orange (Highlights, props) |
| Environmental Base | #4A6585 / #AEEEEE |
Suggested base: Low-Poly Ocean (Deep slate blue water with bright aqua foam edges). Alternate bases are allowed if they fit the theme’s mood. |
| Distant Element | #C7CEFF |
Pale Lavender (Distant giant crescent moon) |
Theme C: "Abstract Void"¶
Stark, high contrast, impossible geometry feel.
| Role | Hex | Voxel Usage |
|---|---|---|
| Background (SkyGradient) | #37474F → #546E7A |
Moody slate gray gradient |
| Primary Structure | #E6F0F2 |
Off-White/Pale Cyan (Primary walkable masses/paths) |
| Secondary Structure | #80CBC4 |
Medium Teal (Supporting blocks) |
| Accents | #FF4081 |
Neon Pink (Focal points, props) |
| Environmental Base | #263238 |
Suggested base: Abstract Terrain Base (Dark, jagged geometric formations below). Alternate bases are allowed if they fit the theme’s mood. |
| Distant Element | #FF4081 |
Neon Pink (Massive distant geometric shape) |
Asset Manifest Format (Updated Categories)¶
```json { "asset_id": "env_cloud_sea_ethereal", "name": "Ethereal Cloud Sea Base", "category": "environment_base", "placement_type": "fixed_below_grid", ... }