From 3aa2d549d1ecba5f59267a18427e19193c546c88 Mon Sep 17 00:00:00 2001
From: John Alanbrook <john@pockle.world>
Date: Sun, 18 May 2025 22:24:31 -0500
Subject: [PATCH] add claude.md

---
 CLAUDE.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..c877c2b9
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,120 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build Commands
+
+### Build variants
+- `make debug` - Build debug version (uses meson debug configuration)
+- `make fast` - Build optimized version  
+- `make release` - Build release version with LTO and optimizations
+- `make small` - Build minimal size version
+- `make web` - Build for web/emscripten platform
+- `make crosswin` - Cross-compile for Windows using mingw32
+
+### Testing
+- `meson test -C build_dbg` - Run all tests in debug build
+- `meson test -C build_<variant>` - Run tests in specific build variant
+- `./build_dbg/prosperon tests/<testname>.js` - Run specific test
+- Available tests: `spawn_actor`, `empty`, `nota`, `wota`, `portalspawner`, `overling`, `send`, `delay`
+
+### Common development commands
+- `meson setup build_<variant>` - Configure build directory
+- `meson compile -C build_<variant>` - Compile in build directory
+- `./build_dbg/prosperon examples/<example>` - Run example from build directory
+- Copy prosperon to game directory and run: `cp build_dbg/prosperon <game-dir>/ && cd <game-dir> && ./prosperon`
+
+## Architecture Overview
+
+Prosperon is an actor-based game engine inspired by Douglas Crockford's Misty system. Key architectural principles:
+
+### Actor Model
+- Each actor runs on its own thread
+- Communication only through message passing (no shared JavaScript objects)
+- Hierarchical actor system with spawning/killing
+- Actor lifecycle: awake, update, draw, garbage collection
+
+### JavaScript Style Guide
+- Use `use()` function for imports (Misty-style, not ES6 import/export)
+- Prefer objects and closures over ES6 classes  
+- Follow existing JavaScript patterns in the codebase
+- Functions as first-class citizens
+
+### Core Systems
+1. **Actor System** (scripts/core/engine.js)
+   - Message passing via `$_.send()`, `$_.receive()`
+   - Actor spawning/management
+   - Register-based component system (update, draw, gui, etc.)
+   
+2. **Module System**
+   - `use()` function for loading modules
+   - Module paths: `scripts/modules/`, `scripts/modules/ext/`
+   - Custom QuickJS build with embedded C modules
+
+3. **Build System**
+   - Meson build configuration (Makefile is convenience wrapper)
+   - Multiple platform targets (Windows, macOS, Linux, Web)
+   - Custom QuickJS build in `subprojects/`
+   - Uses SDL3 for cross-platform support
+
+### Engine Entry Points
+- `source/prosperon.c` - Main C entry point
+- `scripts/core/engine.js` - JavaScript engine initialization  
+- `scripts/core/base.js` - Base prototypes and utilities
+
+### Resource System
+- Scripts are bundled into `core.zip` during build
+- Runtime module loading via PhysFS
+- Resource paths checked in order: `/`, `scripts/modules/`, `scripts/modules/ext/`
+
+### Notable Dependencies
+- QuickJS (custom build) - JavaScript runtime
+- SDL3 - Platform abstraction
+- Chipmunk2D - Physics
+- ENet - Networking  
+- Soloud - Audio
+- Tracy - Profiling (when enabled)
+
+## Development Tips
+
+### Running Games
+```bash
+# Build first
+make debug
+
+# Run example from build directory
+./build_dbg/prosperon examples/chess
+
+# Or copy to game directory
+cp build_dbg/prosperon examples/chess/
+cd examples/chess
+./prosperon
+```
+
+### Shader Development
+- Shaders are in `shaders/` directory as HLSL
+- Compile script: `shaders/compile.sh`
+- Outputs to platform-specific formats: `dxil/`, `msl/`, `spv/`
+
+### Example Games
+Located in `examples/` directory:
+- `chess` - Chess implementation (has its own Makefile)
+- `pong` - Classic pong game
+- `snake` - Snake game
+- `tetris` - Tetris clone
+- `bunnymark` - Performance test
+
+### Testing
+```bash
+# Run all tests
+meson test -C build_dbg
+
+# Run specific test  
+./build_dbg/prosperon tests/spawn_actor.js
+```
+
+### Debugging
+- Use debug build: `make debug`
+- Tracy profiler support when enabled
+- Console logging available via `console.log()`, `console.error()`, etc.
+- Log files written to `.prosperon/log.txt`
\ No newline at end of file