​

Claude Development Guide

​

Quick Reference

​

Essential Commands

# Install dependencies
bun install

# Build all packages (required before first run)
bun run build

# Development mode with hot reload
bun run dev

# Run all tests
npm test

# Lint codebase
npm run lint

​

Package-Specific Commands

# Build individual packages
bun run build:shared    # Core engine (must build first)
bun run build:client    # Web client
bun run build:server    # Game server

# Development mode for specific packages
bun run dev:shared      # Shared package with watch mode
bun run dev:client      # Client with Vite HMR
bun run dev:server      # Server with auto-restart

​

Critical Development Rules

​

TypeScript Strong Typing

// ❌ FORBIDDEN
const player: any = getEntity(id);
if ('health' in player) { ... }

// ✅ CORRECT
const player = getEntity(id) as Player;
player.health -= damage;

• Prefer classes over interfaces for type definitions
• Use type assertions when you know the type
• Share types from types.ts files - don’t recreate them
• Use import type for type-only imports
• Make strong type assumptions based on context

​

File Management

• Revise existing files instead of creating _v2.ts variants
• Delete old files when replacing them
• Update all imports when moving code
• Clean up test files immediately after use
• Don’t create temporary check-*.ts, test-*.mjs, fix-*.js files

​

Testing Philosophy

1. Start a real Hyperscape server
2. Open a real browser with Playwright
3. Execute actual gameplay actions
4. Verify with screenshots + Three.js scene queries
5. Save error logs to /logs/ folder

​

Architecture Overview

​

Monorepo Structure

packages/
├── shared/              # Core 3D engine (ECS, Three.js, PhysX, networking, React UI)
├── server/              # Game server (Fastify, WebSockets, PostgreSQL)
├── client/              # Web client (Vite, React)
├── plugin-hyperscape/   # ElizaOS AI agent plugin
├── physx-js-webidl/     # PhysX WASM bindings
├── asset-forge/         # AI asset generation tools
└── website/             # Marketing website (Next.js 15)

​

Build Dependency Graph

1. physx-js-webidl — PhysX WASM (takes longest, ~5-10 min first time)
2. shared — Depends on physx-js-webidl
3. All other packages — Depend on shared

​

Recent Features

​

Ranged Combat (PR #691)

• Bows and arrows (Bronze → Adamant)
• Projectile rendering with 3D arrow meshes
• OSRS-accurate hit delay formulas
• Ammunition consumption (100% loss rate)
• Combat styles: Accurate, Rapid, Longrange

• packages/shared/src/systems/shared/combat/RangedDamageCalculator.ts
• packages/shared/src/systems/shared/combat/AmmunitionService.ts
• packages/shared/src/systems/shared/combat/ProjectileService.ts
• packages/client/src/game/systems/ProjectileRenderer.ts

​

Magic Combat (PR #691)

• Combat spells (Strike and Bolt tiers)
• Rune consumption with elemental staff support
• Autocast spell selection
• Spell projectile rendering
• OSRS-accurate magic damage formulas

• packages/shared/src/systems/shared/combat/MagicDamageCalculator.ts
• packages/shared/src/systems/shared/combat/RuneService.ts
• packages/shared/src/systems/shared/combat/SpellService.ts
• packages/client/src/game/panels/SpellsPanel.tsx
• packages/shared/src/data/spell-visuals.ts

​

Persistence Improvements (PR #695)

• Transactional equipment/bank saves
• Immediate persistence for critical operations
• Reduced auto-save intervals (30s → 5s)
• EventBus async handler tracking
• Write-ahead logging (Phase 2 scaffolding)

• packages/server/src/persistence/PersistenceService.ts
• packages/server/src/database/repositories/EquipmentRepository.ts
• packages/server/src/database/repositories/BankRepository.ts
• packages/shared/src/systems/shared/infrastructure/EventBus.ts

​

Security Enhancements (PR #687)

• URL parameter validation (authToken via postMessage)
• Configurable auth storage (localStorage/sessionStorage/memory)
• CSP violation monitoring
• Timestamp validation for replay attack prevention
• Type guards for event payloads

• packages/client/src/auth/PrivyAuthManager.ts
• packages/client/src/types/embeddedConfig.ts
• packages/client/src/lib/error-reporting.ts
• packages/server/src/systems/ServerNetwork/services/InputValidation.ts

​

UI/UX Improvements (PR #687)

• Minimap overhaul with independent width/height resizing
• Cached projection matrix for pip synchronization
• Extracted overlay controls (compass, teleport, stamina)
• Viewport scaling system with design resolution
• Combat panel 1×3 row layout for better mobile UX

• packages/client/src/game/hud/Minimap.tsx
• packages/client/src/game/hud/MinimapOverlayControls.tsx
• packages/client/src/ui/core/responsive/ViewportScaler.tsx
• packages/client/src/game/interface/useViewportResize.ts

​

Port Allocation

​

Common Patterns

​

Getting Systems

const combatSystem = world.getSystem('combat') as CombatSystem;
const inventorySystem = world.getSystem('inventory') as InventorySystem;

​

Entity Queries

const players = world.getEntitiesByType('Player');
const mobs = world.getEntitiesByType('Mob');

​

Event Handling

world.on('inventory:add', (event: InventoryAddEvent) => {
  // Handle event - assume properties exist
});

​

Troubleshooting

​

Build Issues

# Clean everything and rebuild
npm run clean
rm -rf node_modules packages/*/node_modules
bun install
bun run build

​

PhysX Build Fails

cd packages/physx-js-webidl
./make.sh  # Requires emscripten toolchain

​

Port Conflicts

# Kill processes on common Hyperscape ports
lsof -ti:3333 | xargs kill -9  # Game Client
lsof -ti:5555 | xargs kill -9  # Game Server

​

Tests Failing

• Ensure server is not running before tests
• Check /logs/ folder for error details
• Tests spawn their own Hyperscape instances
• Visual tests require headless browser support

​

Related Documentation

• Architecture
• Development Guide
• Testing
• Deployment