Hugging Face's logo

Spaces:
dylanebert
/
VibeGame
Running

App Files Community
VibeGame / layers /structure.md
dylanebert
refactor
bc7e9cd
preview code
|
raw
history blame contribute delete
3.84 kB

Project Structure

AI-assisted iterative game development environment with real-time feedback

Stack

  • Runtime: Bun
  • Language: TypeScript
  • UI Framework: Svelte
  • Game Engine: VibeGame (3D physics, ECS)
  • Code Editor: Monaco Editor
  • AI Agent: LangGraph.js with Hugging Face Inference
  • WebSocket: ws (for real-time communication)
  • Build: Vite
  • Animation: GSAP (bundled with VibeGame)
  • Physics: Rapier (via VibeGame)
  • Rendering: Three.js (via VibeGame)

Commands

  • bun dev - Development server with hot reload on port 7860
  • bun run build - Build for production
  • bun run preview - Preview production build
  • bun run check - TypeScript + Svelte type checking
  • bun run lint - ESLint code quality check
  • bun run format - Auto-format with Prettier
  • bun run validate - Complete validation (format, lint, type check)

Layout 

vibegame/
├── CLAUDE.md          # Global context (Tier 0)
├── PLAN.md           # Development roadmap
├── layers/
│   ├── structure.md   # Project structure (Tier 1)
│   └── context-template.md
├── src/
│   ├── main.ts        # Svelte app initialization
│   ├── App.svelte     # Root UI component (declarative)
│   └── lib/
│       ├── stores/        # State management
│       ├── services/      # Business logic
│       ├── server/        # WebSocket server & agent
│       ├── components/    # UI components
│       │   ├── chat/      # AI chat interface
│       │   ├── console/
│       │   ├── editor/
│       │   ├── game/
│       │   └── layout/
│       └── config/        # Configuration
├── index.html         # Entry point
├── package.json       # Dependencies and scripts
├── tsconfig.json      # TypeScript configuration
├── vite.config.ts     # Vite + Svelte + VibeGame config
├── bun.lock          # Dependency lock file
├── agents.md          # VibeGame documentation
└── README.md

Architecture

Three-layer architecture: UI (Svelte) → Agent (Hugging Face) → Game (VibeGame)

  • UI Layer: Svelte components for chat, code editing, console display
  • Agent Layer: LangGraph.js agent via WebSocket with Read/Write tools
  • Game Layer: VibeGame ECS with declarative XML scene definition

Entry points

  • Main entry: index.html (HTML shell)
  • UI entry: src/main.ts (Svelte app mount)
  • App root: src/App.svelte (Component tree root)
  • Game definition: <world> tag in editor (Live-editable XML)

Naming Conventions

TypeScript/Web standards with Svelte and ECS conventions

  • Files: kebab-case for utilities, PascalCase for components (e.g., Chat.svelte, mcp-tools.js)
  • Directories: lowercase (e.g., src/, components/, stores/)
  • Svelte components: PascalCase (e.g., Editor.svelte, Preview.svelte)
  • Stores: camelCase (e.g., gameState, consoleMessages)
  • ECS Components: PascalCase (e.g., Health, Transform)
  • Systems: PascalCase with "System" suffix (e.g., HealthSystem)

Configuration

  • TypeScript: tsconfig.json (Strict mode, ESNext target)
  • Build: vite.config.ts (Vite with Svelte, VibeGame, WebSocket plugins)
  • Dependencies: package.json (Svelte, VibeGame, Monaco, Hugging Face, ws)
  • Game Scene: Live-editable in Monaco editor

Where to add code

  • UI components → src/lib/components/[feature]/[Component].svelte
  • State management → src/lib/stores/[store].ts
  • Business logic → src/lib/services/[service].ts
  • Server/Agent logic → src/lib/server/[module].ts
  • Configuration → src/lib/config/[config].ts
  • Game entities → XML in Monaco editor
  • Custom ECS components → src/lib/game/components/[Component].ts
  • Custom systems → src/lib/game/systems/[System].ts