Grids

[cazala]

This pull request introduces comprehensive support for grid-based simulation modules to the core engine and documentation. It adds a new ModuleRole.Grid for modules that simulate 2D cellular fields (such as Game of Life and reaction-diffusion), updates the engine API to support grid operations, and provides extensive documentation for authoring, using, and understanding grid modules and their interop with particles. Additionally, a new GridGeometry utility is introduced for consistent world-to-cell conversions across runtimes.

Core engine and API enhancements:

• Added support for grid modules by introducing the optional grids array to EngineOptions, and exposing getGrid(moduleName) and setGrid(moduleName, data) methods on the Engine class for explicit grid state read/write. [1] [2] [3]
• Introduced the new GridGeometry utility class in grid/geometry.ts to provide consistent world↔cell conversions and grid dimension calculations across both CPU and WebGPU runtimes.

Documentation and authoring guides:

• Updated all relevant documentation (README.md, AGENTS.md, docs/user-guide.md, docs/maintainer-guide.md, docs/module-author-guide.md, docs/playground-user-guide.md) to describe grid modules, their API, lifecycle, interop modules (GridFieldForce, ParticleDepositGrid), and usage patterns. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12]

Key documentation and authoring improvements:

• Added detailed guides for authoring grid modules, including lifecycle hooks (init, step, post, render), grid specs, and best practices for performance and correctness.
• Documented built-in grid modules (Game of Life, reaction-diffusion, elementary CA) and their usage in the playground and engine API. [1] [2]
• Clarified the distinction and interop patterns between particle modules and grid modules, with real-world use cases and authoring notes. [1] [2]

Summary of the most important changes:

1. Core engine and API:

• Added support for grid modules to the engine (grids array, getGrid, setGrid methods). [1] [2] [3]
• Added GridGeometry utility for world↔cell conversions and grid dimension calculations.

2. Documentation and guides:

• Updated documentation to describe grid modules, their roles, and usage throughout the engine and playground. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12]
• Provided detailed authoring instructions for grid modules, including lifecycle hooks, grid specs, and best practices.

3. Interop and patterns:

• Documented interop modules (GridFieldForce, ParticleDepositGrid) for particle↔grid workflows, with real-world example patterns and authoring notes. [1] [2]

These changes significantly expand the engine's capabilities to support grid-based simulations and provide clear guidance for both users and module authors.