big_space

big_space uses an integer grid system to extend Bevy's Transform component with up to 128 bits of added precision.

The Mental Model

• Grid: A large integer grid of cells. The root BigSpace also has a Grid component.
• CellCoord: An entity's index within its parent's grid.
• Transform: Positions the entity relative to the center of its current GridCell.
• Floating Origin: An entity marked with FloatingOrigin determines the 32-bit rendering origin for its BigSpace. All GlobalTransforms in that space are computed relative to this entity's grid cell.

Moving Entities: Best Practices

To avoid fighting the plugin's automatic re-centering logic and to maintain precision, avoid setting positions absolutely. Instead, apply relative deltas.

❌ Avoid:

transform.translation = a_huge_imprecise_position;

✅ Prefer:

let delta = new_pos - old_pos;
transform.translation += delta;

If you must use absolute positions (e.g., for a stable orbital path), calculate the position in high precision first, then use Grid::translation_to_grid to compute the correct CellCoord and Transform.

The PartitionLookup<F> resource is used to quickly find connected groups of occupied grid cells, known as Partitions. Partitions divide space into independent groups.

Key Mental Model:

• Partitions track cell occupancy, not entity occupancy. To find which entities are in a partition, you must look up the partition's CellIds in the CellLookup resource.
• PartitionLookup is built on top of a CellLookup resource using the same SpatialHashFilter (F).
• It provides a way to map a specific CellId to a PartitionId and vice versa.

// Assuming PartitionLookup<F> is already added as a resource in your Bevy app
// F is your SpatialHashFilter

// 1. Find which partition a specific cell belongs to
if let Some(partition_id) = partition_lookup.get(&some_cell_id) {
    // 2. Resolve the partition details using the ID
    if let Some(partition) = partition_lookup.resolve(partition_id) {
        // Do something with the partition
    }
}

// 3. Iterate over all existing partitions
for (id, partition) in partition_lookup.iter() {
    // Process each partition
}

The Stationary component works in tandem with CellCoord and CellId to maintain spatial consistency.

• CellCoord: Represents the logical grid coordinates of the entity.
• CellId: A component added by the system that represents the current cell the entity occupies. It is used for efficient spatial lookups.
• Stationary: A marker component that tells the system to optimize this entity. While Stationary is present, the system assumes the entity's CellCoord is stable.

Important Behavior: Wake-up and Movement If you need to move a Stationary entity to a new cell, you should remove the Stationary component in the same operation (or frame) that you update its CellCoord. Once Stationary is removed, the system's CellId::update logic (which runs Without<Stationary>) will detect the change in CellCoord and update the CellId accordingly on the next frame. This ensures the entity is correctly re-indexed in the CellLookup resource at its new location.

// Simulate wake-up: remove Stationary and change CellCoord in the same operation.
app.world_mut().entity_mut(entity).remove::<Stationary>();
app.world_mut()
    .entity_mut(entity)
    .get_mut::<CellCoord>()
    .unwrap()
    .x = 5;

// After app.update(), CellId will reflect the new CellCoord (5, 0, 0)
// and the entity will be tracked in CellLookup at the new cell.

In a high-precision BigSpace, an entity's position is defined by two components: a Transform and a CellCoord.

• CellCoord acts as the integer index of a cubic cell within its parent Grid.
• Transform represents the floating-point position of the entity relative to the center of that specific cell.

This dual-component approach allows for high precision even at massive scales by keeping the Transform values small. All entities with a CellCoord must be children of an entity with a Grid component. If an entity's Transform translation exceeds the maximum_distance_from_origin defined in its Grid, the system will automatically recompute the CellCoord and reset the Transform to keep the translation within bounds.

// An entity's position is the combination of its cell index and its local transform
// within that cell.
// Entity Hierarchy: Grid (Parent) -> Child (with CellCoord and Transform)

The lifecycle of a stationary entity is managed via two components to ensure all initial computations (like spatial hashing) occur before the entity is optimized into a 'sleeping' state:

1. Stationary added: The entity is marked as potentially stationary. During this frame, it is still processed by standard propagation and spatial hashing systems.
2. One-frame delay: The plugin waits for one full frame and (if present) one FixedUpdate tick to ensure the entity is correctly registered in the world.
3. StationaryInitialized inserted: The plugin automatically inserts this marker. Once present, the entity is considered 'sleeping'. Propagation skips recomputing its GlobalTransform (unless the floating origin moves), and CellHashingPlugin skips recomputing its CellId.
4. Stationary removed: If the Stationary component is removed, the plugin automatically removes StationaryInitialized, returning the entity to the normal update path.

The Stationary component optimizes entities that do not move by skipping per-frame computations like grid recentering and spatial hashing updates.

Important Usage Rules

• Do not move stationary entities by mutating their Transform or CellCoord. The plugin will not detect these changes.
• To relocate a stationary entity: Remove the Stationary component, move the entity, and then re-add Stationary.
• Initialization Delay: Stationary takes effect one full frame after insertion. During this first frame, the entity has Stationary but not yet StationaryInitialized.

Recommended Query Patterns

• Systems that must run before the entity 'sleeps': Query `(With<Stationary>, Without<StationaryInitialized>)
• Systems that should skip sleeping entities: Query With<StationaryInitialized>

// To optimize an entity
commands.entity(entity).insert(Stationary);

// To move a stationary entity
commands.entity(entity).remove::<Stationary>();
// ... move entity ...
commands.entity(entity).insert(Stationary);

To optimize stationary entities in a large-scale spatial grid, attach the Stationary component to an entity. This signals to the system that the entity's position is relatively stable and can be managed via grid-based optimizations.

When an entity is marked as Stationary, the system automatically manages its CellId and tracks it in the CellLookup resource. To "wake up" an entity (making it dynamic again), simply remove the Stationary component. This removal triggers a chain that cleans up internal tracking components like StationaryInitialized and allows the spatial hash to detect changes to the entity's CellCoord on the next frame.

Lifecycle of a Stationary entity:

1. Spawn: Add Stationary and CellCoord to an entity.
2. Stabilization: After one or two app.update() cycles, the system adds CellId (to track its current cell) and StationaryInitialized (to mark it as fully registered).
3. Wake-up: Remove Stationary. The entity will then be treated as a dynamic entity, and its CellId will update automatically whenever its CellCoord changes.

// Spawn entity with Stationary
let entity = app
    .world_mut()
    .spawn((
        Transform::from_translation(Vec3::ZERO),
        CellCoord::new(1, 0, 0),
        Stationary,
    ))
    .set_parent_in_place(grid_entity)
    .id();

// To wake up the entity (make it dynamic):
app.world_mut().entity_mut(entity).remove::<Stationary>();

To use big_space for high-precision spatial hierarchies in Bevy, follow these three steps:

1. Add the plugin: Add BigSpaceDefaultPlugins to your App.
2. Spawn a BigSpace: Use spawn_big_space (via BigSpaceCommands) to create the root of a high-precision hierarchy.
3. Set the Floating Origin: Add the FloatingOrigin component to your active camera within that BigSpace. This camera will act as the 32-bit rendering origin, ensuring smooth movement and high precision for all entities in that space.

Note: Grids can be nested like Transforms to create moving high-precision hierarchies (e.g., a planet's surface grid orbiting a star).

// Example setup logic (conceptual based on documentation)
app.add_plugins(BigSpaceDefaultPlugins)
   .add_systems(Startup, setup_space);

fn setup_space(mut commands: Commands) {
    // 1. Spawn the root BigSpace
    commands.spawn_big_space();

    // 2. Spawn a camera and mark it as the FloatingOrigin
    commands.spawn(( 
        Camera3dBundle::default(), 
        FloatingOrigin 
    ));
}