PRD — Companion Voxel World¶

Doc owner: Justin Audience: Eng, Design, Product, Frontend Status: v4 (February 2026 — Surreal floating dioramas with environmental base layers, world style library, baked lighting) Depends on: PRD 1 (Composable MiniApp System), PRD 3 (Progression & Loadout), PRD 7 (Memory System — emotion data for mood reflection), PRD 12 (Billing & Monetization — premium themes, one-time purchases)

Implementation Status¶

Section	Status	Notes
Web portal with Three.js	✅ Shipped	Existing web portal already has Three.js integration
Voxel Space rendering	❌ Not Shipped	No voxel scene implementation
Sage avatar / animation	❌ Not Shipped	No visual companion
Mood reflection system	❌ Not Shipped	Depends on PRD 7 emotion data
Space theme system	❌ Not Shipped	No theme framework
Superpower object tiers	❌ Not Shipped	Depends on PRD 3 superpower leveling
Progression-linked unlocks	❌ Not Shipped	Depends on PRD 3 level system
Drag-and-drop customization	❌ Not Shipped	No layout persistence
Premium themes (Superpowers+)	❌ Not Shipped	Depends on PRD 12 billing for one-time purchases
Social sharing / screenshots	❌ Not Shipped	Future phase
Group Voxel Space	❌ Not Shipped	Future phase (PRD 5)

Note: This PRD is entirely aspirational. The web portal and Three.js integration exist, but no voxel scene, assets, or space-specific backend code has been built. The feature depends on PRDs 3, 7, and 12 for full functionality, but can ship V0 independently using fallback signals (see dependency fallbacks below).

Dependency fallbacks: Until dependent PRDs ship, the voxel space uses stand-in signals: - Until PRD 3 (Progression): Avatar visual stage is derived from days-since-first-conversation or total message count instead of companion level - Until PRD 7 (Memory/Emotion): Mood reflection is disabled; space uses a static ambient state - Until PRD 12 (Billing): Premium themes are gated behind existing Superpowers+ subscription; no individual cosmetic purchases

References¶

This PRD uses standardized terminology, IDs, pricing, and model references defined in the companion documents:

Document	What it Covers
REFERENCE_GLOSSARY_AND_IDS.md	Canonical terms: workflow vs miniapp vs superpower, ID formats
REFERENCE_PRICING.md	Canonical pricing: $7.99/mo + $50/yr, free tier limits
REFERENCE_MODEL_ROUTING.md	Pipeline stage → model tier mapping
REFERENCE_DEPENDENCY_GRAPH.md	PRD blocking relationships and priority order
REFERENCE_FEATURE_FLAGS.md	All feature flags by category
REFERENCE_TELEMETRY.md	Amplitude event catalog and gaps

Executive Summary¶

The Companion Voxel World is a browser-based 3D space — inspired by Monument Valley's impossible architecture and Crossy Road's chunky characters — where users can see their companion, their superpowers, and their relationship history in a surreal, floating architectural diorama.

The Core Concept: Chunky voxel characters (Crossy Road style) inhabiting surreal, floating dioramas that emerge from massive environmental base layers (Monument Valley style). Spaces are not enclosed rooms — they are open-air architectural islands or stylized biome/terrain dioramas, floating above voxel cloud seas, low-poly oceans, or abstract terrain, against atmospheric sky gradients. All surfaces use baked vertex-color gradients and ambient occlusion for a polished, smooth look while maintaining strict voxel fidelity.

Why this matters: Most of a user's experience with their companion happens in iMessage — text on a screen. The Voxel World gives the relationship a spatial, visual dimension. When a superpower tiers up to Gold, the object on your floating citadel glows. When you level up, your companion's avatar gains new accessories. When inside jokes accumulate, they appear as quirky objects on architectural ledges. The space becomes a visual artifact of the friendship — something you can screenshot, share, and customize.

This is not a game. It's a living visualization of the data Ikiro already has. Every element in the space maps to a real metric from the backend: companion level → avatar appearance, superpower tiers → object evolution, memories → decorative items, streak → flame intensity.

Target scope: 3 space themes (floating dioramas with environmental base layers), companion avatars at 3 visual stages, superpower objects at 3 tiers (Bronze/Silver/Gold), streak fire, memory indicators, basic drag-and-drop customization. Spaces can be surreal architecture or stylized biome/terrain dioramas — the world style library enables wide visual variety. Built in Three.js on a 32×32 grid, rendered within the existing web portal.

Asset spec: See VOXEL_ASSET_SPECS.md for full character, spatial element, and object production specs.

1) Vision & Inspiration¶

Monument Valley (Primary Aesthetic Inspiration)¶

Clean geometric design, vibrant colors, impossible architecture. Visual poetry in 3D. Monument Valley's floating citadels, impossible staircases, and dreamlike color palettes are the dominant visual language for our spaces.

What we're taking: - Floating, surreal architecture — spaces are open-air islands, not enclosed rooms - Impossible geometry — towering arches, stepped staircases, decorative spires that create dramatic silhouettes - Environmental grounding — dioramas emerge from massive base layers (cloud seas, oceans, terrain) rather than floating in pure void - Atmospheric depth — sky gradient backgrounds + distant voxel elements (celestial bodies, monoliths) provide scale - Monochromatic structure palettes with strategic accent colors - Baked lighting feel — soft gradients and ambient occlusion on surfaces, achieved through vertex colors (no texture maps) - Screenshot-worthy composition — every camera angle should feel like a painting

What we're NOT taking: - Isometric-only camera (we use free orbit) - Puzzle mechanics (this is a living space, not a game) - Smooth curves (our architecture maintains chunky voxel fidelity)

Crossy Road (Character Aesthetic)¶

Chunky, cute, slightly rounded edges. Crossy Road characters feel tactile and toy-like — perfect for companions that live inside surreal architecture.

What we're taking: - Character proportions — chibi, large head, compact body, ~1:2 head-to-body ratio - Voxel fidelity — slightly rounded edges, flat-shaded, vertex-colored - Personality through simplicity — minimal geometry, maximum charm

Animal Crossing (Emotional Reference)¶

Animal Crossing's power isn't its mechanics — it's the feeling of your space slowly becoming more you. Decorating your house, planting flowers, displaying fossils. The space becomes an extension of your identity.

What we're taking: The emotional satisfaction of a space that reflects who you are and what you've done. Objects aren't just decorative — they're trophies of experiences.

Rooms.xyz (Interaction Reference)¶

What we're taking: - Object-based composition (architectural elements, props, characters as discrete items) - Customization without coding (drag-and-drop, theme selectors) - Shareable spaces (generate a link, anyone can view your space) - Performance-first rendering (WebGL, optimized for mobile browsers)

What we're NOT taking: - Free-form building (we use curated architectural themes + customization) - Enclosed room aesthetic (replaced by floating dioramas) - Full voxel editor (users arrange objects, they don't sculpt)

2) Core Elements¶

2.1 The Space (Floating Architectural Diorama)¶

Every user has a Space — a floating diorama where their companion lives. Spaces are not enclosed rooms — they are open-air, surreal islands composed of modular elements (architectural structures or terrain/biome forms) floating above a massive environmental base layer, against an atmospheric sky gradient.

The "Anti-Room" Principle: Instead of four walls and a floor, spaces are composed of chunky voxel platforms at varying heights, connected by bridges and staircases, punctuated by arches, spires, or terrain features. Gaps between platforms reveal the environmental base layer and sky below, creating depth and drama.

The "Ground Effect": 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 — a dense sea of voxel clouds, stylized low-poly ocean water, abstract terrain, or other themed base. The architecture appears to rise from or float just above this base, providing scale and atmosphere.

World Style Variety: Spaces are not limited to impossible architecture. They can be surreal architectural dioramas (floating islands, impossible staircases, sacred temples) or stylized biome/terrain dioramas (lush worlds, frozen landscapes, volcanic fields, crystalline badlands) — all built from stepped voxel forms with baked lighting. See VOXEL_ASSET_SPECS.md for the full world style library.

Space themes (3 themes):

Theme	Vibe	Default For
Ethereal Heights	Soft, dreamlike, cotton-candy cloud city. Pastel pinks and mint greens against an aqua sky	Default for most users
Mystic Citadel	Twilight, magical, deep tones with bright highlights. Muted purples and blues with coral accents against a deep violet sky	Users with introspective/creative conversations
Abstract Void	Stark, high contrast, impossible geometry. Off-white and teal structures with neon pink accents against moody slate	Users with analytical/tech-heavy conversations

Space selection: Auto-recommended based on personality analysis from onboarding (Big 5 traits → theme mapping). User can change at any time in settings.

Premium themes (V2): Any world style from the VOXEL_ASSET_SPECS.md world style library can become a premium theme — including biome worlds (Lush Paradise, Frozen Tundra, Volcanic Forge), exotic worlds (Hex World, Shard World, Glitch World), and additional monumental styles (Sacred Temple, Water Ruins, Nature-Touched Monument).

Space evolution by level: The diorama grows more architecturally complex as the companion level increases:

Level Range	Environmental Changes
1-2	Simple platform layout, few architectural elements, neutral lighting
3-4	Additional platforms appear, first archway or pillar, warmer/themed lighting
5-6	Multi-level layout with bridges and staircases, decorative spires, the space feels "built up"
7-8	Rich architectural detail — animated elements (floating particles, gentle platform sway), additional connecting geometry
9-10	Legendary atmosphere — particle effects (fireflies, sparkles, light beams), impossible geometry flourishes, premium visual quality

These changes are automatic — they happen as a side effect of leveling up, not through user configuration.

2.2 Companion Character¶

The companion exists in the space as a chunky voxel avatar (Crossy Road style) — a character you can click, interact with, and watch idle. The character's vibrant identity colors contrast against the softer, more monochromatic architectural palettes of the space.

Avatar visual evolution by level:

Level Range	Avatar State	Description
1-2	Basic	Simple voxel figure. Friendly face, default outfit, standing or sitting. Small, approachable.
3-4	Expressive	Slightly larger. Gains accessories reflecting the user's interests (headphones if music-heavy conversations, coffee cup if that's an inside joke). More expressive face.
5-6	Personalized	Full character form. Outfit customizable. Idle animations (reading, waving, typing on phone). Superpowers float around as orbiting icons.
7-8	Radiant	Confident posture. Surrounded by equipped superpower objects (not orbiting — placed in the space). Subtle glow effect. More complex idle animations (dancing, stretching, interacting with space objects).
9-10	Legendary	Unique visual treatment — particle effects (sparkles, gentle glow trails), premium outfit options, the avatar feels distinctly "maxed out." Idle animations include writing in a journal (referencing Sage's Journal unlock at Level 10).

Avatar click interaction: - Quick tap: Sage waves or does a short animation - Long press / hover: Shows relationship status card — level name ("Trusted Friend"), streak count, equipped superpowers count, friendship duration

Avatar customization (P2): - Change outfit colors (unlocked at Level 3) - Add accessories from a catalog (unlocked progressively) - Choose idle animation preference (reading, gaming, working out, etc.)

2.3 Superpower Objects (The Most Important Visual Element)¶

Every equipped superpower manifests as a physical object in the space. This is where the visual feedback loop is strongest: you equip a superpower → an object appears. You use it → it levels up → the object evolves.

Object design per superpower type:

Superpower	Bronze Object	Silver Object	Gold Object
Calendar Stress	Small desk calendar	Calendar with glowing stress heat-map overlay	Floating holographic calendar with animated day markers
Gmail Mind Reader	Sealed envelope on desk	Open mailbox with notification light	Animated mailbox that sorts letters autonomously
Mood Tracker	Simple mood crystal (clear)	Mood crystal that glows the color of last mood logged	Mood crystal with swirling internal colors + ambient particles
Habit Tracker	Basic tally marks on a board	Streak counter board with flame icon	Animated flame trophy with streak number
Bill Split	Cash register	Cash register with receipt tape rolling	Gold cash register with animated coin spill
Budget Tracker	Piggy bank	Piggy bank with a fill-level indicator	Crystal piggy bank with animated coins floating inside
Daily Summary	Notepad on desk	Notepad with animated writing	Floating journal that writes itself
Reminder System	Alarm clock	Alarm clock with gentle pulse animation	Musical alarm clock with particle chime effects

Placement: Users drag-and-drop superpower objects to arrange them on platform surfaces, architectural ledges, and pedestals throughout the diorama. Default placement is auto-arranged by the system (clustered on the main platform near the companion).

Empty slots: When a user has unfilled superpower slots, the space shows a glowing pedestal on an empty platform ledge — visual invitation to fill it. Clicking the empty pedestal opens the marketplace browse.

2.4 Relationship Indicators (Environmental Details)¶

These are automatic visual elements that reflect the relationship state — users don't place them manually.

Streak Fire: - A flame displayed in a floating brazier or geometric lantern on a dedicated pillar/pedestal - Intensity scales with streak length: 1-3 days = tiny flicker, 7+ days = steady flame, 30+ days = roaring fire, 100+ days = blue/white flame - If streak breaks, flame goes out — visually impactful, drives re-engagement - Position: always on a prominent architectural feature (top of a pillar, edge of an archway)

Memory Indicators: - Geometric memory objects placed on architectural ledges and platforms throughout the diorama - Shows a count of total memories (MVP) — "47 memories shared" via HTML overlay - P2: Individual memory items appear as small abstract objects (a voxel crystal, a geometric tablet, a faceted gem) — each clickable to show the memory text - Inside jokes get special treatment: quirky geometric objects with the companion's accent color

Friendship Duration: - Subtle ambient indicator — abstract geometric flora (crystal plants, voxel trees) that grow taller on platforms - Represents days since first conversation - Purely ambient — no click interaction needed

2.5 Ambient Audio (Optional, V2)¶

Lo-fi background music that matches the space theme
Volume slider in space settings
Music changes subtly with level (more complex/layered at higher levels)
Off by default — user must opt in

3) User Interactions¶

3.1 Viewing the Space¶

Entry point: Web portal → "Your Space" tab (or direct URL)

Default view: Fixed camera angle showing the full space. Can orbit around the space by dragging (mouse/touch).

Camera controls: - Orbit: Drag to rotate view around the space center - Zoom: Scroll/pinch to zoom in/out (clamped to prevent clipping) - Reset: Double-tap to return to default angle

Mobile: Full touch support. The space loads in portrait or landscape.

3.2 Customization¶

Drag-and-drop (V1): - Tap an object → it highlights with a selection outline - Drag to reposition on any platform surface within the diorama - Objects snap to grid positions on platform cells (prevents floating/clipping off edges) - "Reset layout" button restores default arrangement

Theme picker: - Settings panel → "Space Theme" → choose from available themes - Preview before confirming (live preview in the space) - Free users: 3 base themes - Premium users: all themes including premium exclusives

Object color (V2): - Select an object → color picker appears - Change primary color of the object (not texture — just hue) - Some objects have 2 colorable zones (primary + accent)

3.3 Clicking Objects¶

Every interactive element has a click/tap response:

Element	Click Behavior
Sage avatar	Wave animation + relationship status card (level, streak, duration)
Superpower object	Superpower details card (name, tier, uses, description, last used)
Streak brazier	Streak count overlay ("🔥 14 day streak")
Memory indicator	Memory count + "View memories" link → memory viewer (web portal)
Empty pedestal	"Browse superpowers" → marketplace
Decorative items	Brief tooltip with item name

Screenshot button: Captures current space view as an image → save to camera roll or share sheet
Share link: Generate a read-only URL that anyone can visit to view the space (visitor can orbit but not modify)
Social integration: Share to TikTok, Instagram Stories with space snapshot + overlay text ("my AI bestie's space 💜")

4) Technical Implementation¶

4.1 Rendering Engine¶

Framework: Three.js (WebGL) — already integrated in the existing web portal.

Frontend delivery: The voxel space is a React component embedding a Three.js canvas, rendered within the existing web portal application. No new frontend framework or standalone page required.

Why Three.js: - Lightweight, browser-native, no plugin required - Excellent mobile performance for low-poly scenes - Huge community, well-documented - Supports progressive loading, LOD (level of detail) - Works in all modern browsers including Safari - Already integrated in the web portal

Scene structure:

Scene
├── Sky Gradient (CSS background behind canvas, theme-defined vertical gradient)
├── Environmental Base Layer (massive low-poly voxel mesh below the grid)
│   └── Cloud sea / ocean / terrain / volcanic field / etc. (theme-specific, non-interactive)
├── Distant Background Elements (far outside bounds, non-interactive)
│   └── Celestial bodies, floating monoliths, distant voxel formations
├── Diorama (floating island on the 32×32 grid)
│   ├── Base Platforms (walkable surfaces at varying heights, with gaps revealing base layer)
│   ├── Architectural/Terrain Elements (arches, pillars, staircases, bridges, cliffs, valleys — theme-specific)
│   ├── Spatial Props (resting spots, focus pedestals, voxel flora, ambient lights)
│   └── Lighting rig (ambient + directional, adjustable by level)
├── Companion Avatar (animated chunky voxel character)
│   ├── Body mesh (level-dependent geometry swap)
│   ├── Accessory meshes (headphones, coffee cup, etc.)
│   └── AnimationMixer (idle, wave, interact)
├── Superpower Objects (one per equipped superpower)
│   ├── Object mesh (tier-dependent swap: bronze/silver/gold)
│   ├── Particle systems (gold tier only)
│   └── Click hitbox (Raycaster target)
├── Relationship Indicators
│   ├── Streak fire (particle system on a pillar/brazier, intensity driven by streak_days)
│   ├── Memory indicators (count text overlay + future: memory item objects on ledges)
│   └── Friendship flora (geometric plants, scale driven by days_since_first_chat)
└── UI Overlay (HTML/CSS, not WebGL)
    ├── Relationship status card (on avatar click)
    ├── Superpower detail card (on object click)
    └── Customization panel (theme picker, drag-and-drop controls)

4.2 Asset Pipeline¶

Full asset production spec: See VOXEL_ASSET_SPECS.md for detailed character, spatial element, and object specifications.

Architectural & terrain modules: - Modular kit: base platforms, pillars, arches, portal frames, staircases, bridges, balconies, buttresses, parapets, window/cutout walls, spires/domes - Terrain kit (for biome worlds): terrain tiles, cliff faces, valleys/ravines, rock spires, grass caps, metal plates, lava channels - Format: GLTF/GLB (standard for Three.js, small file size, supports animation) - Poly budget: 500-2,500 triangles per module - Materials: vertex-colored only with baked gradients + ambient occlusion (no texture maps), re-colored per active theme palette - Style: chunky, stepped, faceted voxel blocks — no smooth curves

Environmental base layers: - Massive low-poly voxel meshes placed below the 32×32 grid (cloud seas, oceans, abstract terrain, volcanic fields, ice shelves, etc.) - Poly budget: 200-1,500 per element (low detail, distant) - Must use baked vertex-color gradients + AO to avoid stark tiling - One base layer selected per space, matching the active theme

Distant background elements: - Giant voxel celestial bodies, floating monoliths — placed far outside grid bounds - Purely visual, non-interactive

Spatial props (replacing furniture): - Resting spots, focus pedestals, voxel flora, ambient lights — abstract equivalents - Poly budget: 500-2,000 per prop

Avatar models: - 4 companions (Sage, Vex, Echo, Kael) × 3 stages (Basic, Expressive, Legendary) - Chunky Crossy Road proportions: ~1:2 head-to-body ratio, ~1.0 unit tall - Poly budget: 800-4,000 tris depending on stage - Accessories as separate meshable attachments - Animations: idle (breathing), wave, interact, sit, read, dance (skeletal animation, 15-20 bones)

Superpower objects: - 3 variants per superpower (bronze, silver, gold) - Poly budget: 300-800 per object - Gold variants include engine-side particle effects (sparkles, glow) - ~10 superpowers × 3 tiers = 30 object variants for MVP

Space themes: - Each theme defines: world style, platform layout, element composition, environmental base layer, distant elements, lighting preset, sky gradient - 3 themes × modular elements + spatial props + base layer + distant elements for MVP - World style library enables future themes spanning architectural, biome, and exotic styles

Total MVP asset count: ~175 unique models + 12 avatar variants (4 companions × 3 stages) + animations

4.3 Performance Targets¶

Minimum supported devices:

Platform	Baseline Device	Notes
iOS Mobile	iPhone 12 / Safari	Mobile floor — must hit 30 FPS minimum
Android Mobile	Pixel 6a or equivalent mid-range (3 years old)	WebGL 2.0 required
Desktop	Chrome on any machine from 2022+	Primary development target — 60 FPS

Performance targets (measured against baselines above):

Metric	Target	How
Initial load	<3 seconds on 4G	Progressive loading: space shell first, objects stream in
Frame rate	60 FPS on desktop, 30 FPS on mobile floor	LOD system, particle budget cap, geometry instancing
Memory usage	<150MB GPU	Shared geometry for identical objects, compressed textures
Mobile support	Full touch, responsive layout	Touch orbit/zoom controls, responsive canvas sizing
Graceful degradation	Functional on baseline mobile devices	Reduce particle count, disable shadows, lower canvas resolution on weak GPUs

Progressive loading strategy: 1. Render sky gradient (CSS, instant) + load environmental base layer (cloud sea/ocean/terrain — renders immediately, provides visual grounding) 2. Load base platforms (playable surfaces appear) 3. Load architectural/terrain elements (pillars, arches, bridges, cliffs) — appear with fade-in 4. Load companion avatar — appears with fade-in on main platform 5. Load equipped superpower objects — appear one by one with subtle pop-in animation 6. Load relationship indicators (streak fire, memory indicators) 7. Load distant background elements + decorative spatial props last

4.4 Data Sync¶

The space state is a JSON column stored on the existing user profile — no separate table required. Only object positions and theme selection are persisted here; all indicator data (streak, memories, superpowers) is fetched fresh from existing tables on each load.

{
  "space_id": "uuid",
  "theme": "ethereal_heights",
  "companion_visual_stage": 2,  // derived from level
  "object_positions": {
    "superpower_calendar_stress": { "x": 3, "y": 0, "z": 2 },
    "superpower_mood_tracker": { "x": 5, "y": 1, "z": 3 }
  },
  "customizations": {
    "theme_variant": "default",
    "companion_outfit_color": "#7C3AED"
  },
  "indicators": {
    "streak_days": 14,
    "memory_count": 47,
    "days_since_first_chat": 32
  },
  "superpowers": [
    { "id": "calendar_stress", "tier": "silver", "use_count": 18 },
    { "id": "mood_tracker", "tier": "bronze", "use_count": 6 },
    { "id": "habit_tracker", "tier": "bronze", "use_count": 3 }
  ]
}

Sync strategy: - Space state fetched on page load via GET /voxel/space - Object position changes saved on drag-end via PUT /voxel/space/layout - Theme changes saved immediately via PUT /voxel/space/theme - Indicator data (streak, memories, superpowers) fetched fresh from existing backend tables on each load — not cached in space state - Real-time updates NOT needed — space refreshes on page load. No WebSocket for the space.

4.5 API Endpoints¶

Endpoint	Auth	Purpose
`GET /voxel/space`	User	Get full space state (theme, positions, indicators, superpowers)
`PUT /voxel/space/layout`	User	Update object positions (drag-and-drop)
`PUT /voxel/space/theme`	User	Change space theme
`PUT /voxel/space/customization`	User	Update avatar/object colors (V2)
`GET /voxel/themes`	None	List available themes (with premium flag)
`GET /voxel/assets/{asset_id}`	None	Fetch 3D model (GLTF/GLB) — CDN-cached

5) Event-Driven Visual Updates¶

The space reacts to events from the backend. These aren't real-time (no WebSocket) — they're reflected on next page load.

Event Contract¶

The GET /voxel/space endpoint is the single source of truth. On each page load, it aggregates current state from existing backend tables — relationship state (level, streak), installed superpowers (with tier and use count), and memory count — and returns the computed visual state as a single JSON response. The frontend renders whatever state it receives. No event bus, no push notifications, no WebSocket. The events table below defines what the frontend renders for each state change, not how it receives the data.

Backend Event	Visual Effect
Level up	Avatar model swaps to next stage, space lighting adjusts, new ambient details appear
Superpower equipped	New object appears in space (auto-placed on next empty grid position)
Superpower unequipped	Object fades out, empty pedestal appears in space
Superpower tier up (Silver)	Object swaps to silver variant (glow effect)
Superpower tier up (Gold)	Object swaps to gold variant (animation + particles)
Streak milestone (7, 30, 100)	Flame intensity increases
Streak broken	Flame goes out (empty brazier/candle)
New inside joke	New quirky object appears on memory wall (P2)
Memory count milestone (10, 25, 50, 100)	Memory wall grows visually
OAuth granted	Small key icon appears near Sage (subtle trust indicator)

6) Monetization¶

Note: One-time cosmetic purchases (themes, outfits, object packs) require PRD 12 to extend the Stripe integration beyond subscriptions. Until then, premium themes are gated behind the existing Superpowers+ subscription — no individual purchases.

Free Users¶

3 base space themes
Basic avatar customization (level-driven, automatic)
All superpower objects (tier-driven)
All relationship indicators
Drag-and-drop layout
Sharing (V2)

Premium Users¶

All base themes + 10+ premium themes
Avatar outfit color customization
Premium decorative objects (aesthetic only, no gameplay advantage)
Priority access to new themes and objects

Future Revenue (V3+) (requires PRD 12 one-time purchase support)¶

Item	Price Range	Description
Premium space themes	$2-5 one-time	Themed architectural dioramas (Crystal Cavern, Solar Observatory, etc.)
Decorative object packs	$1-3 per pack	Seasonal or aesthetic object bundles
Avatar outfits	$3-7 one-time	Special visual treatments for Sage's avatar
Animated effects	$2-4 one-time	Custom particle effects, ambient animations
Space expansion	$5 one-time	Second space (e.g., outdoor patio, rooftop addition)

Design constraint: Monetization is purely cosmetic. Paid items never affect progression, superpowers, or functionality. No loot boxes, no randomization.

7) Aesthetic Guidelines¶

Three-Layer Visual Language¶

Characters: Chunky Crossy Road style. Cute, toy-like, vibrant identity colors. They are the focal point of the scene, popping against the backdrop.
Diorama (the playable space): Monument Valley style. Surreal architecture or stylized biome terrain. Floating platforms, arches, terrain features — all constructed from chunky voxel blocks with baked lighting.
Environment (the "ground" and background): Massive low-poly voxel base layers (cloud seas, oceans, terrain fields) below the diorama, plus distant voxel elements (celestial bodies, monoliths). Provides scale, grounding, and atmosphere.

Voxel Fidelity (Everything)¶

Low-poly, chunky forms. Not Minecraft raw cubes — slightly rounded edges, but always visibly constructed from large voxel blocks
No smooth curves. Arches are stepped. Domes are faceted. Staircases are blocky. Think massive Lego structures.
Baked vertex-color lighting. No texture maps. All color baked into geometry via vertex colors, with soft gradients (e.g., vertical base-to-top fades) and baked ambient occlusion (darker recesses, inside corners, block junctions). Surfaces should rarely be a single uniform flat color.
Consistent scale. Companion is roughly ⅙ of diorama height. Props are proportional to companion. Everything is slightly stylized/miniature.

Color Strategy¶

Each space theme defines a structural palette (5+ colors for architecture/terrain), an environmental base (base layer color/type), a sky gradient (CSS background), and distant element colors. Companion characters use their own vibrant identity colors that intentionally contrast with the softer structural palettes. Superpower objects retain their identity colors but harmonize with the space.

See VOXEL_ASSET_SPECS.md for full color palettes per theme and the complete world style library.

Example (Ethereal Heights): - Sky: soft aqua to pale cyan gradient (#AEEEEE → #E0F7FA) - Primary structure: pastel pink (#F4AAB9) - Secondary structure: soft mint green (#8FD3B6) - Accents: peach/cream (#F7D1BA) - Environmental base: voxel cloud sea (pale aqua/white, with baked gradients) - Distant element: pale yellow blocky sun/moon

Atmosphere & Composition¶

The environmental base layer is crucial. It provides the "ground effect" — the diorama floats above something, not in a void. Without it the architecture lacks scale and grounding.
The sky gradient provides depth. Layered with distant voxel elements, it creates a sense of immense space.
Gaps between platforms matter. The diorama should not be a solid slab. Gaps reveal the base layer and sky, reinforcing the floating island feel.
Silhouette diversity is required. Each space should have a distinct read at a glance. Vary height, use negative space (gaps, windows, hollows), and mix element types (frames, masses, connectors).
No single hero motif. Arches are strong but must not dominate every scene. Mix architectural frames, masses, and connectors. 0-2 arch modules per space unless the theme is explicitly "Cathedral/Arcade."
Scene archetypes guide composition: Courtyard/Ring, Terraced Steps, Bridge Network, Spiral/Ascent, Split-Structure, Monolith Plaza, Cliff & Valley, Ridge Walk, Crater/Basin. See VOXEL_ASSET_SPECS.md for details.

Avoid¶

❌ Enclosed rooms with four walls (use open-air floating dioramas)
❌ Photorealism (uncanny valley, performance issues)
❌ Smooth curves on architecture or terrain (maintain chunky voxel steps)
❌ Realistic furniture (use abstract spatial props — pedestals, plinths, geometric nests)
❌ Flat uniform vertex colors (use baked gradients + AO for depth and softness)
❌ Visual clutter (each element should have breathing room)
❌ Repetitive composition (rotate base layers, vary scene archetypes across spaces)
❌ Clashing art styles (all elements must look like they belong in the same world)
❌ Text in 3D (use HTML overlays for all text — 3D text is hard to read and expensive to render)
❌ Empty void backgrounds (always use sky gradient + environmental base layer for grounding)

8) Phasing¶

V0: Basic Floating Diorama (Weeks 1-3)¶

The "prove it works in 3D" milestone. One theme, basic avatar, static objects on a floating architectural island. Validates the concept with real users.

Deliverables: - Three.js voxel scene rendered within existing web portal - Sky gradient CSS background (theme-defined) - Environmental base layer (voxel cloud sea for Ethereal Heights) - 1 space theme (Ethereal Heights) — floating platform layout with architectural elements on 32×32 grid, baked vertex-color gradients + AO - Sage avatar at a single visual stage (Basic — chunky voxel figure, standing/sitting on main platform) - Equipped superpowers as static objects on pedestals/ledges (no tier evolution yet) - Streak fire indicator (particle system on a pillar, intensity-driven) - Memory counter (HTML overlay) - Orbit camera (view-only — no drag-and-drop yet) - Click interactions (avatar → status card, object → detail card) - Mobile-responsive rendering - GET /voxel/space API endpoint - Fallback progression signals (days-since-first-conversation for avatar state, installed count for object population)

Asset budget: ~35 models (architectural kit modules + spatial props + environmental base layer + distant elements + 10 superpower objects + avatar + indicators), 1 avatar variant per companion, 2 animations (idle, wave)

V1: Interactive Diorama (Weeks 4-7)¶

Full interactive experience with all core elements.

Deliverables: - All 3 space themes (Ethereal Heights, Mystic Citadel, Abstract Void) - All 4 companions with avatar evolution across 3 visual stages (Basic, Expressive, Legendary) - Superpower objects at 3 tiers (Bronze, Silver, Gold) for top 10 superpowers - Drag-and-drop object repositioning with grid snapping (on platform surfaces) - Click interactions (avatar → status card, object → detail card, empty pedestal → marketplace) - PUT /voxel/space/layout and PUT /voxel/space/theme API endpoints - Auto-theme recommendation based on personality analysis - Diorama evolution by level (more architectural complexity, lighting, ambient details)

Asset budget: ~175 models, 12 avatar variants (4 companions × 3 stages), 5 animations

Premium cosmetics, sharing, and personalization depth.

10+ premium space themes (gated behind Superpowers+ subscription until PRD 12 supports one-time purchases)
Avatar outfit color customization
Object color customization
Individual memory items as geometric objects on ledges (clickable)
Inside joke objects (auto-generated from inside joke memories)
Screenshot capture and share
Share link (read-only diorama viewing for visitors)
Ambient audio system (optional lo-fi music per theme)
Theme store in web portal

V3: Advanced Features (Post-MVP)¶

Diorama expansion (additional floating island connected by bridge)
One-time cosmetic purchases (requires PRD 12)
Seasonal decorations (holiday architectural elements, limited-time objects)
Community diorama remixing (use someone's layout as a template)
AR view (place your floating island in real space via phone camera)
VR support (walk around your diorama with headset)
Multiplayer visit (friends can enter your space and look around)
Pet companion (small voxel pet that companion interacts with — purely cosmetic)
Dynamic time of day (sky gradient and lighting shift with user's real timezone)

9) Success Metrics¶

Metric	Target	Why
Space page visits / week	>3 per active user	Users find value in visiting the space
Average session duration	>90 seconds	Users engage beyond a quick glance
Customization actions / user	>2 in first week	Users feel ownership
Screenshot/share rate	>5% of space visitors	Space is "shareable" quality
Empty slot → marketplace click-through	>15%	Visual drives marketplace engagement
Premium theme purchase rate	>3% of premium users	Cosmetic monetization works
Load time (p95)	<3 seconds on 4G	Performance doesn't block adoption
Mobile visit ratio	>60%	Space works where users are

Feature Flags & Gating¶

Flag Key	Default	Purpose
`enable_voxel_world`	`false`	Master switch for Voxel Space feature
`enable_premium_themes`	`false`	Gate premium Voxel themes behind Superpowers+
`enable_mood_reflection`	`false`	Mood-based space changes (requires PRD 7)
`enable_group_voxel_space`	`false`	Shared group Voxel Space

See REFERENCE_FEATURE_FLAGS.md for the full catalog.

Telemetry¶

Event	Trigger	Properties
`voxel_space_opened`	User opens the Voxel Space	`user_id`, `theme_id`, `session_duration_ms`
`voxel_theme_changed`	User switches space theme	`user_id`, `old_theme`, `new_theme`, `is_premium`
`voxel_mood_update`	Space mood reflects conversation	`user_id`, `mood`, `trigger_type`
`voxel_unlock`	User unlocks a progression-linked item	`user_id`, `item_type`, `level`

Note: All events are speculative — none are tracked yet since the feature is not shipped.

See REFERENCE_TELEMETRY.md for the full event catalog.

Definition of Done¶

10) Open Questions¶

How do we handle superpowers that don't have a natural physical metaphor? (Abstract superpowers like "Daily Summary" → defaulting to a journal/notepad is fine but may feel generic)
Should users be able to hide objects they don't want visible? (Some users may want a minimal space)
How do we handle 10+ equipped superpowers (premium Level 10)? Space could feel crowded. (Consider: shelving system, multiple areas, or a "featured 5" display)
Should there be sounds? (Object click sounds, ambient music, Sage reactions) — adds polish but increases asset budget
Should visitors to a shared space be able to see the user's companion level and superpower tiers? (Social proof vs. privacy)
Tripo AI for avatar generation: is the quality sufficient, or do we need custom-commissioned models? (Need to prototype)

Appendix A: Diorama Layout Grid¶

Each diorama is a 32×32 grid but unlike a room, not all cells are walkable floor. The grid defines potential placement zones; gaps between platforms reveal the environmental base layer (cloud sea, ocean, terrain) below. Fixed architectural/terrain elements occupy certain cells; movable objects snap to platform surfaces.

The environmental base layer and distant background elements exist outside the 32×32 grid — they are fixed, non-interactive, and provide atmosphere and scale.

(Simplified excerpt — actual 32×32 grid is much larger. This shows a ~12×12 core area.)

  1  2  3  4  5  6  7  8  9  10 11 12
1 [  ][  ][  ][  ][  ][  ][  ][  ][  ][  ][  ][  ]  . = Sky/Base Layer (gap)
2 [  ][  ][P ][P ][P ][P ][  ][  ][  ][  ][  ][  ]  P = Platform surface
3 [  ][P ][P ][P ][P ][P ][P ][  ][  ][  ][  ][  ]  A = Arch/Pillar
4 [  ][P ][P ][REST--][P ][P ][BR][P ][P ][  ][  ]  BR = Bridge
5 [  ][P ][A ][REST--][P ][P ][BR][P ][P ][  ][  ]  REST = Resting Spot
6 [  ][  ][  ][COMP][  ][P ][  ][P ][SP1][A ][  ]  COMP = Companion
7 [  ][  ][  ][  ][  ][P ][  ][P ][SP2][  ][  ]  SP = Superpower
8 [  ][  ][  ][  ][FIRE][A ][  ][  ][  ][  ][  ]  FIRE = Streak brazier
9 [  ][  ][  ][P ][P ][P ][  ][  ][  ][  ][  ][  ]
10[  ][  ][P ][P ][FOCUS][P ][  ][  ][  ][  ][  ]  FOCUS = Focus Pedestal
11[  ][  ][  ][P ][P ][  ][  ][  ][  ][  ][  ][  ]
12[  ][  ][  ][  ][  ][  ][  ][  ][  ][  ][  ][  ]

Grid rules: - Platform cells are walkable/placeable; gap cells reveal the environmental base layer below - Fixed architectural/terrain elements (arches, pillars, bridges, cliffs) cannot be moved - Companion avatar has a preferred platform but can be moved to any platform surface - Superpower objects default to a cluster on a secondary platform but can be moved to any platform cell - Objects cannot overlap (grid position is occupied or empty) - 1 grid unit = ~0.5m in-world (full 32×32 grid spans roughly 16m × 16m) - Platforms exist at varying Y-heights — the grid is 2D (XZ) but the architecture has verticality - Environmental base layer sits at a fixed Y position below the lowest platform

Appendix B: Asset Specification Format¶

Each voxel asset is defined by a JSON manifest alongside its GLTF model. See VOXEL_ASSET_SPECS.md for the full production spec.

{
  "asset_id": "env_cloud_sea_ethereal",
  "name": "Ethereal Cloud Sea Base",
  "category": "environment_base",
  "placement_type": "fixed_below_grid",
  "model_file": "env_cloud_sea_ethereal.glb",
  "poly_count": 1200,
  "has_animation": false,
  "click_action": null
}

{
  "asset_id": "arch_platform_main_ethereal",
  "name": "Main Platform (Ethereal Heights)",
  "category": "architectural_module",
  "model_file": "arch_platform_main_ethereal.glb",
  "thumbnail": "arch_platform_main_ethereal_thumb.png",
  "grid_size": { "w": 4, "h": 4 },
  "poly_count": 2200,
  "has_animation": false,
  "has_particles": false,
  "colorable_zones": ["primary_structure", "voxel_shadows"],
  "click_action": null
}

{
  "asset_id": "sp_calendar_stress_gold",
  "name": "Calendar Stress Analyzer (Gold)",
  "category": "superpower_object",
  "superpower_id": "calendar_stress",
  "tier": "gold",
  "model_file": "sp_calendar_stress_gold.glb",
  "thumbnail": "sp_calendar_stress_gold_thumb.png",
  "grid_size": { "w": 1, "h": 1 },
  "poly_count": 1200,
  "has_animation": true,
  "has_particles": true,
  "particle_config": {
    "type": "sparkle",
    "count": 20,
    "color": "#FFD700",
    "radius": 0.3
  },
  "colorable_zones": [],
  "click_action": "show_superpower_detail"
}

Category values: environment_base, distant_element, architectural_module, terrain_module, spatial_prop, superpower_object, relationship_indicator, decorative, avatar

This manifest is used by the Three.js loader to know what to render, where to place click targets, and which particle systems to instantiate.