cell/CLAUDE.md

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 closures and javascript objects and prototypes over ES6 style classes
• Follow existing JavaScript patterns in the codebase
• Functions as first-class citizens
• Do not use const or let; only var

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 for system
• scripts/core/base.js has modifications to this Javascript runtime (for example, additions to the base Array, String, etc)

Subprojects

• C code has many subprojects, who's source and sometimes documentation can be found in subprojects. subprojects/quickjs/doc has documentation for quickjs

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

# 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

Documentation

• Documentation is found in docs
• Documentation for the JS modules loaded with 'use' is docs/api/modules
• .md files directly in docs gives a high level overview
• docs/dull is what this specific Javascript system is (including alterations from quickjs/es6)

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

# 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

Project Structure Notes

Core JavaScript Modules

• JavaScript modules are defined using the MISTUSE macro in jsffi.c
• The js_os_funcs, js_io_funcs, etc. arrays define the available functions for each module
• New functions are added with MIST_FUNC_DEF(module, function, args_count)

File I/O

• io.slurp(path) - Reads a file as text
• io.slurpbytes(path) - Reads a file as an ArrayBuffer
• io.slurpwrite(path, data) - Writes data (string or ArrayBuffer) to a file
• io.exists(path) - Checks if a file exists

Script Loading

• The use(path) function in engine.js loads JavaScript modules
• Script loading happens in prosperon.c and the engine.js script
• jsffi.c contains the C hooks for the QuickJS JavaScript engine
• Added functionality for bytecode compilation and loading:
  • os.compile_bytecode(source, filename) - Compiles JS to bytecode, returns ArrayBuffer
  • os.eval_bytecode(bytecode) - Evaluates bytecode from an ArrayBuffer
  • compile(scriptPath) - Compiles a JS file to a .jso bytecode file
  • Modified use() to check for .jso files before loading .js files

QuickJS Bytecode API

• JS_Eval with JS_EVAL_FLAG_COMPILE_ONLY - Compiles without executing
• JS_WriteObject with JS_WRITE_OBJ_BYTECODE - Serializes to bytecode
• JS_ReadObject with JS_READ_OBJ_BYTECODE - Deserializes and loads bytecode
• Bytecode files use .jso extension alongside .js files

Available JavaScript APIs

Core APIs

• actor - Base prototype for all actor objects
• $_ - Special global for actor messaging
• prosperon - Global engine interface
• console - Logging and debugging interface

Framework APIs

• moth - Higher-level game framework that simplifies Prosperon usage
  • Handles window creation, game loop, and event dispatching
  • Provides simple configuration via config.js
  • Auto-initializes systems like rendering and input
  • Manages camera, resolution, and FPS automatically

Rendering

• draw2d - 2D drawing primitives
• render - Low-level rendering operations
• graphics - Higher-level graphics utilities
• camera - Camera controls and transformations
• sprite - Sprite rendering and management

Physics and Math

• math - Mathematical utilities
• geometry - Geometric calculations and shapes
• transform - Object transformations

Input and Events

• input - Mouse, keyboard, and touch handling
• event - Event management system

Networking

• enet - Networking through ENet library
• http - HTTP client capabilities

Audio

• sound - Audio playback using SoLoud

Utility Modules

• time - Time management and delays
• io - File I/O operations
• json - JSON parsing and serialization
• util - General utilities
• color - Color manipulation
• miniz - Compression utilities
• nota - Structured data format
• wota - Serialization format
• qr - QR code generation/reading
• tween - Animation tweening
• spline - Spline calculations
• imgui - Immediate mode GUI

Game Development Patterns

Project Structure

• Game config is typically in config.js
• Main entry point is main.js
• Resource loading through resources.js

Actor Pattern Usage

• Create actors with actor.spawn(script, config)
• Manage actor hierarchy with overlings and underlings
• Schedule actor tasks with delay() method
• Clean up with kill() and garbage()

Game Loop Registration

• Register functions like update, draw, gui, etc.
• Set function.layer property to control execution order
• Use Register system to manage callbacks

Program vs Module Pattern

• Programs are actor scripts that don't return values, they execute top-to-bottom
• Modules are files that return single values (usually objects) that get frozen
• Programs can spawn other programs as underlings
• Programs have lifecycle hooks: awake, update, draw, garbage, etc.

Technical Capabilities

Graphics Pipeline

• Supports multiple render backends (Direct3D, Metal, Vulkan via SDL3)
• Custom shader system with cross-platform compilation
• Sprite batching for efficient 2D rendering
• Camera systems for both 2D and 3D

Asset Support

• Images: PNG, JPG, QOI, etc.
• Audio: Various formats through SoLoud
• Models: Basic 3D model support
• Custom formats: Aseprite animations, etc.

Developer Tools

• Built-in documentation system with prosperon.DOC
• Tracy profiler integration for performance monitoring
• Imgui debugging tools
• Console logging with various severity levels