networked chess

CLAUDE.md

@@ -36,9 +36,10 @@ Prosperon is an actor-based game engine inspired by Douglas Crockford's Misty sy
 
 ### JavaScript Style Guide
 - Use `use()` function for imports (Misty-style, not ES6 import/export)
-- Prefer objects and closures over ES6 classes  
+- 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)
@@ -59,8 +60,11 @@ Prosperon is an actor-based game engine inspired by Douglas Crockford's Misty sy
 
 ### 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
+- `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
@@ -91,6 +95,12 @@ 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`
@@ -117,4 +127,134 @@ meson test -C build_dbg
 - 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`
+- 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
+```