Spatial Grid

The spatial grid is a performance optimization tool used by the physics engine (defined in engine/physics.py).
It divides the 3D game world into a series of uniform "cells."

The grid can be viewed (during Play Mode) using the console command: sg

Instead of performing a "narrow-phase" collision check between every single object in the scene (which would be computationally expensive (O(N^2)) )the engine uses the grid for a "broad-phase" check. It only calculates collisions for objects that occupy the same or adjacent grid cells.

Implementation Details

• Grid Size: The dimensions of each cell are generally defined in engine/constants.py

• Dynamic Updates: As entities move, they are removed from their old cell and registered into a new one. Toggling sg allows you to verify that these updates are happening correctly and that objects aren't "leaking" out of the partitioning system.

• Command Registration: In editor/console_commands.py, the command is mapped to the toggle_spatial_grid method, which interacts directly with the Physics class.

The default grid size is 512

• Increasing it (e.g., 1024 or 2048) will lower memory usage and speed up map loading, but it will degrade collision performance by crowding too many objects into the same cell, forcing the engine to check irrelevant brushes.

• Decreasing it (e.g., 128 or 256) will optimize short-range collision queries by narrowing down candidate brushes, but it will increase memory footprint, slow down map loading, and create more processing overhead for line-of-sight raycasts.