Skip to main content

​
Development Commands

​
Core Commands

CommandDescription
bun run devStart game (client + server + shared)
bun run dev:aiGame + ElizaOS AI agents (simplified)
bun run dev:elizaosGame + ElizaOS AI agents (legacy)
bun run dev:allEverything: game + AI + AssetForge
bun run buildBuild all packages
bun startStart 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

PortServiceStarted By
3333Game Clientbun run dev
3334Websitebun run dev:website
5555Game Serverbun run dev
8080Asset CDNbun run dev
5432PostgreSQLDocker (auto)
4001ElizaOS APIbun run dev:elizaos
4000ElizaOS Dashboardbun run dev:elizaos (internal)
3400AssetForge UIbun run dev:forge
3401AssetForge APIbun 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