Skip to content

AGENTS.md

Latest commit

 

History

History
84 lines (63 loc) · 3.1 KB

AGENTS.md

File metadata and controls

84 lines (63 loc) · 3.1 KB

AGENTS.md

Instructions for AI coding assistants (GitHub Copilot, Cursor, etc.) working with this codebase.

CRITICAL: WebGPU Required (NO WebGL)

Hyperscape requires WebGPU. WebGL WILL NOT WORK.

This is a hard requirement. DO NOT:

  • Add WebGL fallback code
  • Use --disable-webgpu flags
  • Use forceWebGL parameters
  • Create headless Chrome configurations without GPU/WebGPU support
  • Suggest WebGL as an alternative

Why WebGPU-Only?

  • All materials use TSL (Three Shading Language) which ONLY works with WebGPU
  • Post-processing effects use TSL-based node materials
  • There is NO WebGL fallback path - the game simply won't render

Browser Requirements

  • Chrome 113+, Edge 113+, Safari 17+
  • WebGPU must be available and working

Server/Streaming (Vast.ai)

  • NVIDIA GPU with Vulkan support is REQUIRED
  • Must run headful with Xorg or Xvfb (NOT headless Chrome)
  • CRITICAL LINUX NOTE: It is important on Linux to use Chrome Canary and the ANGLE backend, NOT Vulkan (--use-vulkan). Using the native Vulkan backend with WebGPU will crash.
  • CRITICAL MAC NOTE: It is important on macOS to use Google Chrome with the Metal backend for ANGLE (--use-angle=metal).
  • If WebGPU cannot initialize, deployment MUST FAIL

Project Overview

Hyperscape is a RuneScape-style MMORPG built on Three.js WebGPURenderer with TSL shaders.

CRITICAL: Secrets and Private Keys

Never put private keys, seed phrases, API keys, tokens, RPC secrets, or wallet secrets into any file that could be committed.

  • ALWAYS use local untracked .env files for real secrets
  • NEVER hardcode secrets in source files, tests, docs, JSON fixtures, scripts, config files, or workflow YAML
  • NEVER put real secrets in .env.example; placeholders only
  • If a secret is needed in production or CI, use the platform secret store, not a tracked file
  • If a task requires a new secret, document the variable name and load it from .env, .env.local, or deployment secrets

Key Rules

  1. No any types - ESLint will reject them
  2. WebGPU only - No WebGL code or fallbacks
  3. No mocks in tests - Use real Playwright browser sessions
  4. Bun package manager - Use bun install, not npm
  5. Strong typing - Prefer classes over interfaces
  6. Secrets stay out of git - Real keys must only come from local .env files or secret managers

Tech Stack

  • Runtime: Bun v1.1.38+
  • Rendering: WebGPU ONLY (Three.js WebGPURenderer + TSL)
  • Engine: Three.js 0.180.0, PhysX (WASM)
  • UI: React 19.2.0
  • Server: Fastify, WebSockets
  • Database: PostgreSQL (production), SQLite (local)

Common Commands

bun install          # Install dependencies
bun run build        # Build all packages
bun run dev          # Development mode
npm test             # Run tests

File Structure

packages/
├── shared/          # Core engine (ECS, Three.js, networking)
├── server/          # Game server (Fastify)
├── client/          # Web client (Vite + React)
├── physx-js-webidl/ # PhysX WASM bindings
└── asset-forge/     # AI asset generation

See CLAUDE.md for complete documentation.