clawdbot-workspace/buba-dashboard/WORLD-DESIGN.md

Buba World — 3D Interactive Dashboard Design Doc

Vision

A kawaii pastel 3D world where Jake can control Buba in third-person, walk around a floating island, approach project buildings, and interact with them to view/manage live project data. Think Animal Crossing meets a work dashboard.

Asset Pipeline

KayKit Assets (CC0, free, GLTF format):

1. Character Pack: Adventurers — 5 rigged/animated characters + 25 accessories
   • Use the Mage or Rogue character (recolor to pink/lavender for Buba)
   • Teal recolor for sub-agents
2. Character Animations — 161 humanoid animations (GLTF)
   • Need: Idle, Walk, Run, Interact, Wave
   • Separated by category — we pick what we need
3. City Builder Bits — 32+ building models (GLTF)
   • Houses, shops, offices — assign to our projects
   • Recolor to match project color scheme
4. Forest Nature Pack — 100+ models (free tier)
   • Trees (various sizes), bushes, rocks, grass
   • Perfect for decorating the island
5. Furniture Bits — 50+ interior props (optional, for building interiors later)

Download Plan:

• All free tiers from itch.io → extract GLTF files → serve from buba-dashboard/assets/
• Total download: ~50-100MB of GLTF models
• Only load what's visible (lazy load interiors)

World Layout

        ☁️            ☁️
  
     🌳  [MCP Factory]  🌳
          (teal, biggest)
    
  [OSKV]     🌸      [SOLVR]
  (purple)  🌳     (gold)
    
      [CannaBri]  🏊  [NicheQuiz]
      (green)   pond   (peach)
    
  🌳    [CREdispo]    🌳
        (blue)
    
        [OpenClaw]
     (pink, Buba's HQ)
         
       🌸  BUBA  🌸
     (spawn point)

• Floating island: circular, ~80 unit radius
• Soft green ground with dirt paths connecting buildings
• Buildings arranged in a loose circle around center
• Buba spawns at center near OpenClaw (home base)
• Trees, flowers, rocks scattered between buildings
• Small pond with blue water
• Clouds drifting above
• Pastel gradient sky sphere

Character System

Buba (Player Character)

• Model: KayKit Adventurer (Mage?) recolored pink/lavender
• Or: Keep procedural chibi but add proper walk animation
• Animations: Idle (breathing/bobbing), Walk, Run, Interact (wave)
• Camera: Third-person, offset behind and above (like Animal Crossing)
• Controls:
  • WASD / Arrow Keys = move
  • Mouse = rotate camera
  • Shift = run
  • E = interact (when near a building)
  • Space = jump (fun, not functional)
• Name tag: "BUBA" floating above head (sprite)

Sub-Agents

• Smaller versions of character model, teal colored
• Spawn from Buba's position, walk to their assigned building
• Simple AI: idle near building, occasionally pace around
• When working: small particle effect above head
• Pulled from live API data

Building Interactions

Approach Detection

• Each building has an invisible trigger sphere (~5 unit radius)
• When Buba enters sphere: show "Press E to enter [Project Name]" prompt
• Visual: building glows/pulses when in range

Project Panel (on Enter)

• Full-screen overlay panel (HTML over canvas) with glassmorphism
• Shows:
  • Project name + status
  • Live data from API (sub-agents working on it, recent activity)
  • Quick actions (if applicable)
  • "Exit" button or press E/Escape to close
• Panel slides in from right with smooth animation

Technical Architecture

Stack

• Three.js r169 via CDN (importmap)
• GLTFLoader for loading .glb/.gltf models
• AnimationMixer for character animations
• CSS2DRenderer for labels/prompts (or sprites)
• Raycaster for interaction detection (or simple distance checks)
• No physics engine — simple AABB collision for buildings + ground clamp

File Structure

buba-dashboard/
├── server.js           (Express backend, serves API + static)
├── assets/
│   ├── characters/     (KayKit character GLTF files)
│   ├── animations/     (KayKit animation GLTF files)
│   ├── buildings/      (KayKit city builder GLTF files)
│   ├── nature/         (KayKit forest pack GLTF files)
│   └── textures/       (gradient atlas textures)
├── public/
│   └── index.html      (main Three.js application)

Performance Targets

• 60fps on Mac mini M2
• Initial load < 5 seconds (lazy load non-essential)
• ~30-50 visible models max
• Single draw call for static scenery (instancing where possible)
• LOD not needed at this scale

Data Flow

1. Frontend fetches /api/state every 5 seconds
2. Updates sub-agent positions/visibility
3. Updates building glow states (active projects glow brighter)
4. Updates HUD stats
5. Building panel content refreshes when open

Pastel Color Scheme

• Sky: gradient pink (#FFE4EC) → lavender (#E8DFFF) → blue (#DDE8FF)
• Ground: soft mint (#C5E8D0)
• Buildings: project colors (pastel versions)
  • MCP Factory: #A8E6CF (mint)
  • SOLVR: #FFE5A0 (gold)
  • CannaBri: #B8E6C8 (emerald)
  • TheNicheQuiz: #FFDAB9 (peach)
  • CREdispo: #B8D4FF (blue)
  • OpenClaw: #FFB5C8 (pink)
  • OSKV Coaching: #D4B8FF (lavender)

Build Phases

Phase 1: World + Movement (THIS BUILD)

• Download and organize all KayKit assets
• Set up Three.js scene with pastel sky, floating island ground
• Place buildings using KayKit city models (or our procedural ones with KayKit nature)
• Load character model with idle/walk animations
• Implement WASD third-person controller
• Camera follow system
• Basic collision with buildings
• Place nature decorations (trees, flowers, rocks)
• HUD overlay (stats, minimap?)

Phase 2: Interactions

• Building approach detection + glow
• "Press E" prompts
• Project panels with live data
• Sub-agent spawning + pathfinding

Phase 3: Polish

• Sound effects (footsteps, ambient)
• Day/night cycle
• Weather effects (cherry blossoms falling?)
• Building interiors
• Multiplayer? (stretch)

Open Questions

• KayKit characters may not look "chibi" enough — may need to scale head up
• Download automation: itch.io requires manual download — may need browser
• Alternative: use Poly.pizza API for individual model downloads (GLTF, no login)