> ## Documentation Index
> Fetch the complete documentation index at: https://hyperscape-ai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# 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:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# 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:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
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.

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

### PostgreSQL Container (Automatic)

PostgreSQL starts automatically when the server runs:

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# 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](/concepts/manifests) for full list

## Testing

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
npm test                              # Run all tests
npm test --workspace=packages/server  # Test specific package
```

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

## Linting

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
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

<Info>
  Requires `CLAUDE_CODE_OAUTH_TOKEN` and `MINTLIFY_API_KEY` secrets to be configured in repository settings.
</Info>

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

```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}}
// 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

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
bun run clean
rm -rf node_modules packages/*/node_modules
bun install
bun run build
```