Skip to content

CLAUDE.md

Latest commit

 

History

History
87 lines (68 loc) · 3.13 KB

CLAUDE.md

File metadata and controls

87 lines (68 loc) · 3.13 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

HexGL is a futuristic HTML5/WebGL racing game built with Three.js (r53). It's a static browser-based game requiring no build system.

Running Locally

python -m http.server 8000
# Visit: http://localhost:8000

Architecture

The game follows a modular architecture with these core components:

index.html (5-step UI flow)
    ↓
launch.js (menu & initialization)
    ↓
bkcore/hexgl/HexGL.js (main controller)
    ↓
┌─────────────────────────────────────────────────────┐
│ Gameplay.js    │ ShipControls.js │ HUD.js          │
│ (race logic,   │ (physics,       │ (canvas-based   │
│  lap tracking) │  input, boost)  │  UI overlay)    │
└─────────────────────────────────────────────────────┘
    ↓
bkcore/hexgl/tracks/Cityscape.js (track loader & definition)
    ↓
bkcore/threejs/RenderManager.js (render loop, delta time)

Key Files:

  • bkcore/hexgl/ShipControls.js (806L) - Physics engine: movement, rotation, drift, boost, collision, shield
  • bkcore/hexgl/HexGL.js (447L) - Main controller: initializes renderer, HUD, tracks, gameplay lifecycle
  • bkcore/hexgl/Gameplay.js (230L) - Race modes (timeattack/survival/replay), checkpoint detection, lap timing
  • bkcore/hexgl/tracks/Cityscape.js - Track definition with geometries, textures, collision/height maps, audio
  • bkcore/threejs/RenderManager.js - Multi-pass rendering (sky scene → game scene → post-processing)

Input Controllers (in bkcore.coffee/controllers/):

  • TouchController.js - Mobile touch/gesture
  • OrientationController.js - Device gyro
  • GamepadController.js - Controller support

Rendering Pipeline:

  1. Sky scene render
  2. Game scene render
  3. Post-processing: Bloom (quality 3+), Hex vignette (quality 1+)

Technology Stack

  • Three.js r53 for WebGL rendering
  • Web Audio API for spatial audio
  • CoffeeScript sources in bkcore.coffee/ (pre-compiled to JS)
  • No npm/build system - pure static files

Quality Settings (0-3)

Level Resolution Bloom Effects
0 (Low) 50% No Screen pass only
1 (Mid) 100% No Hex vignette
2 (High) 100% No Hex vignette, no shadows
3 (Very High) 100% Yes Full effects, shadows

Directory Structure

  • bkcore/hexgl/ - Game logic (HexGL, Gameplay, ShipControls, HUD, CameraChase)
  • bkcore/threejs/ - Three.js utilities (RenderManager, Loader, Shaders, Particles)
  • bkcore.coffee/ - CoffeeScript sources and controllers
  • geometries/ - JSON 3D models (ships, tracks, bonuses)
  • textures/ - Diffuse/normal maps, HUD, skybox
  • audio/ - OGG Vorbis audio files
  • libs/ - Three.js and postprocessing effects

Texture Swapping

For full-size textures (development uses compressed):

mv textures textures.compressed
mv textures.full textures