Stigma Engine Architecture Document
-
Abstract The Stigma engine leverages Hecs, Rayon, and Rapier2D to simulate a virtually infinite 2D universe. By maintaining a single unified Hecs registry, Stigma decouples logical game state from localized physics execution. Rayon provides parallel processing across isolated physics instances, while Rapier2D handles deterministic, high-performance collision resolution. To circumvent the limitations of floating-point mathematics at astronomical scales, Stigma operates on a macro-level coordinate system utilizing 64-bit and 32-bit integer math. Localized interactions are dynamically clustered into Inertial Simulation Zones, allowing the engine to adaptively scale physics computations while maintaining precision and performance.
-
Core World Structure The foundational universe is maintained within a single, universal hecs::World. This container acts as the definitive source of truth for all entities across the entire server node.
Instead of relying on standard floating-point coordinates, the macro-world operates on a strict integer-based coordinate system. Entity positions are stored as i64 vectors, providing immense spatial scale down to millimeter precision. Velocities are stored as i32 vectors. When entities exist in deep space without imminent collision risks, they remain in a singleton, unzoned state. In this state, their positions are updated kinematically using simple integer arithmetic, completely bypassing the Rapier physics engine to preserve CPU cycles.
- Inertial Simulation Zones (ISZ) When two or more entities approach an interactable proximity, Stigma dynamically generates an Inertial Simulation Zone (ISZ). Each ISZ contains its own isolated Rapier2D physics simulation.
To prevent floating-point precision loss and high-velocity solver explosions, each ISZ establishes its own Local Inertial Reference Frame. The zone calculates the average i64 position and i32 velocity of its constituent entities to define its origin and base velocity. Entities injected into the ISZ have their coordinates transformed into localized f32 offsets relative to the zone's moving frame. This guarantees that Rapier only processes coordinates near zero and velocities near zero, ensuring perfectly stable physics. Once all entities drift apart and a zone is left with a single entity, the ISZ is dissolved, and the entity returns to the unzoned kinematic state.
- Zone Management and Macro-Broadphase Stigma continuously monitors the universe by calculating Swept Axis-Aligned Bounding Boxes (AABB) using the i64 and i32 data within the unified Hecs world. This macro-broadphase determines when entities and zones interact.
When the AABBs of unzoned entities overlap, they are merged into a newly spawned ISZ. If the AABBs of two active ISZs overlap and a collision is predicted, the zones are temporarily merged into a single Rapier simulation to resolve the high-velocity impact. Conversely, Stigma employs Connected Component Analysis to evaluate diverging entities within a single ISZ. If groups of entities drift far enough apart, the macro-manager algorithmically splits the Rapier simulation, carving out a new ISZ to prevent the physics bounds from stretching too wide.
- Scaling Tiers, Filtering, and Level of Detail The engine categorizes entities and zones into 256 distinct size scales. This scale hierarchy governs both physics interactions and rendering visibility.
Within the physics pipeline, the scale tier dictates interaction rules to prevent mass-ratio solver failures. If two interacting objects have vastly disparate scales, Rapier's physics hooks intercept the collision. The significantly larger object is treated dynamically for interactions with its peers, but acts as a fixed, immovable static body from the perspective of the smaller object.
For rendering and long-range sensors, these 256 scales function as a built-in Level of Detail (LOD) system. As the camera or sensor range extends outward, smaller scale zones are culled from view. Only zones classified at larger scales are rendered at extreme distances, allowing players to perceive macro-structures like star systems and planetary bodies without overwhelming the rendering pipeline with localized debris.
- Distributed Network Architecture Stigma is designed for horizontally scalable, multi-node deployment. Because all entity data is centralized in a single Hecs world and physics interactions are strictly bound to isolated ISZs, transferring state across servers is highly streamlined.
In a distributed environment, multiple servers each run an identical Stigma architecture, holding authority over specific regions of the i64 universe. If a server node becomes computationally overloaded or an ISZ approaches a server boundary, the authoritative server packages the affected ISZs and unzoned entities. The Hecs components are serialized, and the localized Rapier state is snapshotted. This data is then handed off to a neighboring, under-loaded server node. The receiving server deserializes the payload directly into its local Hecs world and resumes the ISZ simulation, ensuring seamless load balancing and infinite universe scalability.