SwarmingLilMen

SwarmingLilMen is an experimental engine for emergent multi-agent systems, currently grounded in a 2D boids/swarm simulation built from first principles in C#/.NET 8.0. It emphasizes emergence over scripting: a few simple, composable steering rules produce rich macro patterns. The project is in early development (GPL-3.0-only) and undergoing an architectural transition from an aggregate-driven systems approach to independently testable, Reynolds-style steering rules. Two implementations exist side-by-side: a Legacy default pipeline (aggregate-driven SoA steering systems with uniform-grid boids and interactive Raylib renderer) and a Canonical path (scaffolding plus three steering rules, enabled via --canonical). The canonical perception/spatial-index contract and force-budget enforcement are done, but instrumentation UX, prescribed behavioral scenarios, multi-group semantics, and canonical benchmarks remain open. Evidenced capabilities include Structure-of-Arrays (SoA) data layout for cache efficiency; fixed-timestep seeded legacy and canonical paths with exact 500-tick ordered-kinematic-hash coverage; agent-genome data structures and mutation API; configurable simulation parameters with presets (balanced, strong-separation, tight-flocking, fast-loose, slow-cohesive); legacy uniform-grid boids pipeline and interactive Raylib renderer; opt-in canonical single-group renderer with steering instrumentation; and an xUnit test suite whose non-performance subset forms the CI gate. A BenchmarkDotNet suite exists for performance measurement. The systems pipeline rebuilds a uniform grid then runs Sense, Behavior, Wander, and Integrate systems each tick. Performance principles include allocation-conscious hot paths, no LINQ/delegates/boxing in inner loops, tight for-loops with hoisted invariants, and direct/static calls over virtual dispatch. Performance targets of 50k-100k agents at 60 FPS interactive and 1M+ headless are explicitly stated as unmet goals; the 50k measurement misses the 16.67 ms/tick budget by more than an order of magnitude, and canonical throughput, renderer FPS, and per-tick allocations are unmeasured. The project also ships standalone JavaScript browser demos: Boids Basic (Reynolds algorithm with real-time parameter adjustment), Self-Propelled Particles/Vicsek Model (phase transitions in active matter with order parameter tracking), Ant Colony Optimization (stigmergy-based pathfinding with pheromone trails), and Particle Swarm Optimization (continuous global optimization with fitness landscape visualization). These demos require no installation and serve for quick iteration, demonstrations, learning, and prototyping. Roadmap phases include multi-group interactions/combat/metabolism (Phase 3), reproduction/evolution/trait drift (Phase 4), SIMD optimization/parallelization/NativeAOT (Phase 5), and additional scenario presets/replay/advanced metrics (Phase 6). The tech stack comprises C# 12 on .NET 8.0, Raylib-cs 7.0.2 for rendering, xUnit 2.9.3 for testing, and BenchmarkDotNet 0.15.6 for benchmarking.