Development Setup

Local development workflow, hot reload, and debugging

Development Commands

Core Commands

Command	Description
bun run dev	Start game (client + server + shared)
bun run dev:ai	Game + ElizaOS AI agents (simplified)
bun run dev:elizaos	Game + ElizaOS AI agents (legacy)
bun run dev:all	Everything: game + AI + AssetForge
bun run build	Build all packages
bun start	Start production server

Package-Specific

# From package.json scripts
bun run dev:client    # Client only (port 3333)
bun run dev:server    # Server only (port 5555)
bun run dev:shared    # Shared package with watch mode
bun run dev:turbo     # Turbo-based dev (excludes asset-forge)
bun run dev:reset     # Clean + rebuild + dev (nuclear option)

# Website (in packages/website/)
cd packages/website
bun run dev           # Next.js dev server (port 3334)
bun run build         # Build static site
bun run start         # Start production server

# Server build tasks
cd packages/server
bun run extract-bounds  # Generate model-bounds.json from GLB files
bun run build           # Build server (runs extract-bounds automatically)

# Asset Forge (in packages/asset-forge/)
cd packages/asset-forge
bun run dev           # Frontend (Vite) + Backend (Elysia) concurrently
bun run dev:frontend  # Vite only
bun run dev:backend   # Elysia API only

Build Pipeline

The server package includes automated tasks for collision footprint extraction:

# Extract model bounds (auto-runs during build)
bun run extract-bounds

This scans world/assets/models/**/*.glb and generates world/assets/manifests/model-bounds.json with bounding box data for automatic collision footprint calculation.

Turbo Caching:

• Only re-runs when GLB files or script changes
• Outputs cached between builds
• Configured in packages/server/turbo.json

Port Allocation

Port	Service	Started By
3333	Game Client	bun run dev
3334	Website	bun run dev:website
5555	Game Server	bun run dev
8080	Asset CDN	bun run dev
5432	PostgreSQL	Docker (auto)
4001	ElizaOS API	bun run dev:elizaos
4000	ElizaOS Dashboard	bun run dev:elizaos (internal)
3400	AssetForge UI	bun run dev:forge
3401	AssetForge API	bun run dev:forge

Hot Reload

The dev server provides:

• Client: Vite HMR for instant updates
• Server: Auto-restart on file changes
• Shared: Watch mode with rebuild

Docker Services

CDN Container (Required)

The CDN serves game assets and manifests. It must be running before starting the game:

bun run cdn:up      # Start CDN container
bun run cdn:down    # Stop CDN container
bun run cdn:logs    # View CDN logs
bun run cdn:verify  # Verify CDN is working

What it serves:

• 3D models: http://localhost:8080/models/
• Audio: http://localhost:8080/audio/
• Manifests: http://localhost:8080/manifests/

Why it’s required: The server fetches manifests from PUBLIC_CDN_URL at startup. In development, this defaults to http://localhost:8080, so the CDN must be running.

Unlike PostgreSQL which starts automatically, the CDN must be started manually with bun run cdn:up before running bun run dev.

PostgreSQL Container (Automatic)

PostgreSQL starts automatically when the server runs:

# No manual start needed - runs automatically with bun run dev
# To manually control:
cd packages/server
docker-compose up postgres    # Start
docker-compose down postgres  # Stop

Manifest Loading

The server fetches manifests from the CDN at startup:

Development:

• Skips CDN fetch if local manifests exist in packages/server/world/assets/manifests/
• Falls back to local files for offline development

Production:

• Always fetches from PUBLIC_CDN_URL/manifests/
• Caches locally with 5-minute TTL
• Logs fetch status and errors

Manifest Files:

• 25+ JSON files including NPCs, items, recipes, gathering data
• Organized in subdirectories: items/, gathering/, recipes/
• See Manifest-Driven Design for full list

Testing

npm test                              # Run all tests
npm test --workspace=packages/server  # Test specific package

Tests use real Hyperscape instances with Playwright—no mocks allowed. The server must not be running before tests.

Linting

npm run lint        # Lint codebase
npm run typecheck   # TypeScript type checking

GitHub Actions

The repository includes automated workflows for code quality and documentation:

Claude Code Integration

• .github/workflows/claude.yml - Responds to @claude mentions in issues and PRs for automated assistance
• .github/workflows/claude-code-review.yml - Automated code review on pull requests
• .github/workflows/update-docs.yml - Automatically updates documentation when manifest files change

To use Claude Code:

1. Comment @claude in any issue or PR
2. Claude will analyze the context and provide assistance
3. For code reviews, Claude automatically reviews new PRs

Requires CLAUDE_CODE_OAUTH_TOKEN and MINTLIFY_API_KEY secrets to be configured in repository settings.

Common Workflows

Adding a New Feature

1. Make changes in appropriate package:
   • Game logic: packages/shared/src/systems/
   • UI components: packages/client/src/ui/ (reusable) or packages/client/src/game/ (game-specific)
   • Server handlers: packages/server/src/systems/ServerNetwork/handlers/
2. Hot reload applies automatically
3. Test in browser at localhost:3333

Adding UI Components

1. Create component in packages/client/src/ui/components/
2. Add to barrel export in index.ts
3. Import via @/ui alias
4. Use theme tokens from useThemeStore

// Example: Creating a new UI component
import { useThemeStore } from '@/ui';

export function MyComponent() {
  const theme = useThemeStore((s) => s.theme);
  
  return (
    <div style={{ 
      background: theme.colors.background.primary,
      border: `1px solid ${theme.colors.border.default}`,
    }}>
      Content
    </div>
  );
}

Updating Game Content

1. Edit manifest files in world/assets/manifests/
2. Restart server to reload manifests
3. Documentation updates automatically via GitHub Actions

Debugging Server

1. Check terminal output for errors
2. Server logs show WebSocket activity
3. Database queries logged in dev mode

Clean Rebuild

bun run clean
rm -rf node_modules packages/*/node_modules
bun install
bun run build