# 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)