179 lines
6.1 KiB
Markdown
179 lines
6.1 KiB
Markdown
# 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)
|