Class GridWorld

Namespace

GridForge.Grids

Assembly

GridForge.dll

Owns the mutable runtime state for one GridForge world.

public sealed class GridWorld : IDisposable

Inheritance

object

GridWorld

Implements

IDisposable

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Constructors

GridWorld(int)

Initializes a new world with optional ordinary-grid lookup tuning.

public GridWorld(int spatialGridCellSize = 50)

Parameters

spatialGridCellSize int

Optional ordinary-grid lookup cell size for this world.

Fields

DefaultRectangularCellSize

The default rectangular cell edge in world units.

public static readonly Fixed64 DefaultRectangularCellSize

Field Value

Fixed64

DefaultSpatialGridCellSize

The default cell size used to tune ordinary-grid lookup. Oversized grids are indexed automatically outside this tier.

public const int DefaultSpatialGridCellSize = 50

Field Value

int

MaxGrids

Maximum number of grids that can be managed within a world.

public const ushort MaxGrids = 65534

Field Value

ushort

Properties

ActiveGrids

Collection of all active grids owned by this world.

public SwiftBucket<VoxelGrid> ActiveGrids { get; }

Property Value

SwiftBucket<VoxelGrid>

BoundsTracker

Dictionary mapping exact grid configuration keys to grid indices to prevent duplicate grids.

public SwiftDictionary<GridConfigurationKey, ushort> BoundsTracker { get; }

Property Value

SwiftDictionary<GridConfigurationKey, ushort>

IsActive

Indicates whether this world is currently active.

public bool IsActive { get; }

Property Value

bool

SpatialGridCellSize

The cell size used to tune ordinary-grid lookup in this world. Oversized grids are indexed automatically outside this tier.

public int SpatialGridCellSize { get; }

Property Value

int

SpawnToken

Nonzero process-unique 64-bit runtime allocation token for this active world. Zero indicates an inactive world.

public long SpawnToken { get; }

Property Value

long

Version

The current version of the world, incremented on major changes.

public uint Version { get; }

Property Value

uint

Methods

AllocateObstacleToken()

Allocates a nonzero process-unique identity for one obstacle registration lifetime.

public ObstacleToken AllocateObstacleToken()

Returns

ObstacleToken

A fresh opaque obstacle token.

Exceptions

InvalidOperationException

The world is inactive or its token space is exhausted.

Dispose()

public void Dispose()

FindOverlappingGrids(VoxelGrid)

Finds active grids in this world that overlap the supplied target grid.

public IEnumerable<VoxelGrid> FindOverlappingGrids(VoxelGrid targetGrid)

Parameters

targetGrid VoxelGrid

Returns

IEnumerable<VoxelGrid>

FindOverlappingGridsInto(VoxelGrid, SwiftList<VoxelGrid>)

Clears and fills caller-owned storage with active grids that overlap the supplied target grid.

public void FindOverlappingGridsInto(VoxelGrid targetGrid, SwiftList<VoxelGrid> results)

Parameters

targetGrid VoxelGrid

The grid whose expanded topology bounds define the overlap query.

results SwiftList<VoxelGrid>

Caller-owned storage cleared and filled in ascending grid-slot order.

IncrementGridVersion(int, bool)

Increments the version of the specified grid and optionally the world version.

public void IncrementGridVersion(int index, bool significant = false)

Parameters

index int

significant bool

Reset(bool)

Clears all grids and spatial data owned by this world.

public void Reset(bool deactivate = false)

Parameters

deactivate bool

If true, marks the world inactive and releases its event handlers.

TryAddGrid(GridConfiguration, bool[,,]?, out ushort)

Adds a new grid to this world and materializes true cells from the supplied sparse voxel mask when sparse storage is configured. Dense grids ignore the configured voxel input and materialize every in-bounds voxel.

public bool TryAddGrid(GridConfiguration configuration, bool[,,]? configuredVoxels, out ushort allocatedIndex)

Parameters

configuration GridConfiguration

The grid configuration to normalize and register.

configuredVoxels bool[,,]

A [x, y, z] mask whose true values identify sparse voxels to materialize. Sparse masks must match the normalized grid dimensions.

allocatedIndex ushort

The allocated world-local grid slot on success.

Returns

bool

True if the grid was added; otherwise false.

TryAddGrid(GridConfiguration, IEnumerable<VoxelIndex>?, out ushort)

Adds a new grid to this world and materializes the supplied sparse voxel indices when sparse storage is configured. Dense grids ignore the configured voxel input and materialize every in-bounds voxel.

public bool TryAddGrid(GridConfiguration configuration, IEnumerable<VoxelIndex>? configuredVoxels, out ushort allocatedIndex)

Parameters

configuration GridConfiguration

The grid configuration to normalize and register.

configuredVoxels IEnumerable<VoxelIndex>

Grid-local voxel indices to materialize for sparse storage.

allocatedIndex ushort

The allocated world-local grid slot on success.

Returns

bool

True if the grid was added; otherwise false.

TryAddGrid(GridConfiguration, out ushort)

Adds a new grid to this world and registers it in the spatial index.

public bool TryAddGrid(GridConfiguration configuration, out ushort allocatedIndex)

Parameters

configuration GridConfiguration

The grid configuration to normalize and register.

allocatedIndex ushort

The allocated world-local grid slot on success.

Returns

bool

True if the grid was added; otherwise false.

TryGetClosestGrid(Vector2d, Fixed64, out VoxelGrid?, GridTopologyKind?)

Retrieves the active grid whose bounds are nearest to a 2D XZ-plane world position on the supplied world Y layer.

public bool TryGetClosestGrid(Vector2d position, Fixed64 layerY, out VoxelGrid? outGrid, GridTopologyKind? topologyKind = null)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

layerY Fixed64

The world Y layer to resolve. Defaults to zero when omitted by paired overloads.

outGrid VoxelGrid

The closest grid, if found.

topologyKind GridTopologyKind?

Optional topology filter. When supplied, only grids using the requested topology are considered.

Returns

bool

True if a closest active grid was resolved; otherwise false.

TryGetClosestGrid(Vector2d, out VoxelGrid?, GridTopologyKind?)

Retrieves the active grid whose bounds are nearest to a 2D XZ-plane world position on the default world Y layer.

public bool TryGetClosestGrid(Vector2d position, out VoxelGrid? outGrid, GridTopologyKind? topologyKind = null)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

outGrid VoxelGrid

The closest grid, if found.

topologyKind GridTopologyKind?

Optional topology filter. When supplied, only grids using the requested topology are considered.

Returns

bool

True if a closest active grid was resolved; otherwise false.

TryGetClosestGrid(Vector3d, out VoxelGrid?, GridTopologyKind?)

Retrieves the active grid whose bounds are nearest to the supplied world position.

public bool TryGetClosestGrid(Vector3d position, out VoxelGrid? outGrid, GridTopologyKind? topologyKind = null)

Parameters

position Vector3d

The world position to resolve.

outGrid VoxelGrid

The closest grid, if found.

topologyKind GridTopologyKind?

Optional topology filter. When supplied, only grids using the requested topology are considered.

Returns

bool

True if a closest active grid was resolved; otherwise false.

TryGetClosestGridAndVoxel(Vector2d, Fixed64, out VoxelGrid?, out Voxel?, GridTopologyKind?)

Retrieves the physical voxel whose center is nearest to a 2D XZ-plane world position on the supplied world Y layer and the grid that owns it. Sparse grids only consider configured physical voxels.

public bool TryGetClosestGridAndVoxel(Vector2d position, Fixed64 layerY, out VoxelGrid? outGrid, out Voxel? outVoxel, GridTopologyKind? topologyKind = null)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

layerY Fixed64

The world Y layer to resolve. Defaults to zero when omitted by paired overloads.

outGrid VoxelGrid

The grid that owns the closest physical voxel, if found.

outVoxel Voxel

The closest physical voxel, if found.

topologyKind GridTopologyKind?

Optional topology filter. When supplied, only grids using the requested topology are considered.

Returns

bool

True if a physical voxel was resolved; otherwise false.

TryGetClosestGridAndVoxel(Vector2d, out VoxelGrid?, out Voxel?, GridTopologyKind?)

Retrieves the physical voxel whose center is nearest to a 2D XZ-plane world position on the default world Y layer and the grid that owns it. Sparse grids only consider configured physical voxels.

public bool TryGetClosestGridAndVoxel(Vector2d position, out VoxelGrid? outGrid, out Voxel? outVoxel, GridTopologyKind? topologyKind = null)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

outGrid VoxelGrid

The grid that owns the closest physical voxel, if found.

outVoxel Voxel

The closest physical voxel, if found.

topologyKind GridTopologyKind?

Optional topology filter. When supplied, only grids using the requested topology are considered.

Returns

bool

True if a physical voxel was resolved; otherwise false.

TryGetClosestGridAndVoxel(Vector3d, out VoxelGrid?, out Voxel?, GridTopologyKind?)

Retrieves the physical voxel whose center is nearest to the supplied world position and the grid that owns it. Sparse grids only consider configured physical voxels.

public bool TryGetClosestGridAndVoxel(Vector3d position, out VoxelGrid? outGrid, out Voxel? outVoxel, GridTopologyKind? topologyKind = null)

Parameters

position Vector3d

The world position to resolve.

outGrid VoxelGrid

The grid that owns the closest physical voxel, if found.

outVoxel Voxel

The closest physical voxel, if found.

topologyKind GridTopologyKind?

Optional topology filter. When supplied, only grids using the requested topology are considered.

Returns

bool

True if a physical voxel was resolved; otherwise false.

TryGetClosestVoxel(Vector2d, Fixed64, out Voxel?, GridTopologyKind?)

Retrieves the physical voxel whose center is nearest to a 2D XZ-plane world position on the supplied world Y layer. Sparse grids only consider configured physical voxels.

public bool TryGetClosestVoxel(Vector2d position, Fixed64 layerY, out Voxel? result, GridTopologyKind? topologyKind = null)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

layerY Fixed64

The world Y layer to resolve. Defaults to zero when omitted by paired overloads.

result Voxel

The closest physical voxel, if found.

topologyKind GridTopologyKind?

Optional topology filter. When supplied, only grids using the requested topology are considered.

Returns

bool

True if a physical voxel was resolved; otherwise false.

TryGetClosestVoxel(Vector2d, out Voxel?, GridTopologyKind?)

Retrieves the physical voxel whose center is nearest to a 2D XZ-plane world position on the default world Y layer. Sparse grids only consider configured physical voxels.

public bool TryGetClosestVoxel(Vector2d position, out Voxel? result, GridTopologyKind? topologyKind = null)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

result Voxel

The closest physical voxel, if found.

topologyKind GridTopologyKind?

Optional topology filter. When supplied, only grids using the requested topology are considered.

Returns

bool

True if a physical voxel was resolved; otherwise false.

TryGetClosestVoxel(Vector3d, out Voxel?, GridTopologyKind?)

Retrieves the physical voxel whose center is nearest to the supplied world position. Sparse grids only consider configured physical voxels.

public bool TryGetClosestVoxel(Vector3d position, out Voxel? result, GridTopologyKind? topologyKind = null)

Parameters

position Vector3d

The world position to resolve.

result Voxel

The closest physical voxel, if found.

topologyKind GridTopologyKind?

Optional topology filter. When supplied, only grids using the requested topology are considered.

Returns

bool

True if a physical voxel was resolved; otherwise false.

TryGetGrid(Vector2d, Fixed64, out VoxelGrid?)

Retrieves the grid containing a 2D XZ-plane world position on the supplied world Y layer.

public bool TryGetGrid(Vector2d position, Fixed64 layerY, out VoxelGrid? outGrid)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

layerY Fixed64

The world Y layer to resolve. Defaults to zero when omitted by paired overloads.

outGrid VoxelGrid

The resolved grid, if found.

Returns

bool

True if a containing grid was found; otherwise false.

TryGetGrid(Vector2d, out VoxelGrid?)

Retrieves the grid containing a 2D XZ-plane world position on the default world Y layer.

public bool TryGetGrid(Vector2d position, out VoxelGrid? outGrid)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

outGrid VoxelGrid

The resolved grid, if found.

Returns

bool

True if a containing grid was found; otherwise false.

TryGetGrid(Vector3d, out VoxelGrid?)

Retrieves the grid containing a given world position.

public bool TryGetGrid(Vector3d position, out VoxelGrid? outGrid)

Parameters

position Vector3d

The world position to resolve.

outGrid VoxelGrid

The resolved grid, if found.

Returns

bool

True if a containing grid was found; otherwise false.

TryGetGrid(WorldVoxelIndex, out VoxelGrid?)

Retrieves a grid by a world-scoped voxel identity.

public bool TryGetGrid(WorldVoxelIndex worldVoxelIndex, out VoxelGrid? result)

Parameters

worldVoxelIndex WorldVoxelIndex

The voxel identity whose grid should be resolved.

result VoxelGrid

The resolved grid, if found.

Returns

bool

True if the grid was resolved; otherwise false.

TryGetGrid(int, out VoxelGrid?)

Retrieves a grid by its world-local index.

public bool TryGetGrid(int index, out VoxelGrid? outGrid)

Parameters

index int

The world-local grid slot to resolve.

outGrid VoxelGrid

The resolved grid, if found.

Returns

bool

True if the grid was resolved; otherwise false.

TryGetGridAndVoxel(Vector2d, Fixed64, out VoxelGrid?, out Voxel?)

Retrieves the grid and voxel containing a 2D XZ-plane world position on the supplied world Y layer.

public bool TryGetGridAndVoxel(Vector2d position, Fixed64 layerY, out VoxelGrid? outGrid, out Voxel? outVoxel)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

layerY Fixed64

The world Y layer to resolve. Defaults to zero when omitted by paired overloads.

outGrid VoxelGrid

The resolved grid, if found.

outVoxel Voxel

The resolved voxel, if found.

Returns

bool

True if both the grid and voxel were resolved; otherwise false.

TryGetGridAndVoxel(Vector2d, out VoxelGrid?, out Voxel?)

Retrieves the grid and voxel containing a 2D XZ-plane world position on the default world Y layer.

public bool TryGetGridAndVoxel(Vector2d position, out VoxelGrid? outGrid, out Voxel? outVoxel)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

outGrid VoxelGrid

The resolved grid, if found.

outVoxel Voxel

The resolved voxel, if found.

Returns

bool

True if both the grid and voxel were resolved; otherwise false.

TryGetGridAndVoxel(Vector3d, out VoxelGrid?, out Voxel?)

Retrieves the grid and voxel containing a given world position.

public bool TryGetGridAndVoxel(Vector3d position, out VoxelGrid? outGrid, out Voxel? outVoxel)

Parameters

position Vector3d

The world position to resolve.

outGrid VoxelGrid

The resolved grid, if found.

outVoxel Voxel

The resolved voxel, if found.

Returns

bool

True if both the grid and voxel were resolved; otherwise false.

TryGetGridAndVoxel(WorldVoxelIndex, out VoxelGrid?, out Voxel?)

Retrieves the grid and voxel for a given voxel identity.

public bool TryGetGridAndVoxel(WorldVoxelIndex worldVoxelIndex, out VoxelGrid? outGrid, out Voxel? result)

Parameters

worldVoxelIndex WorldVoxelIndex

The voxel identity to resolve.

outGrid VoxelGrid

The resolved grid, if found.

result Voxel

The resolved voxel, if found.

Returns

bool

True if both the grid and voxel were resolved; otherwise false.

TryGetVoxel(Vector2d, Fixed64, out Voxel?)

Retrieves a voxel from a 2D XZ-plane world position on the supplied world Y layer.

public bool TryGetVoxel(Vector2d position, Fixed64 layerY, out Voxel? result)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

layerY Fixed64

The world Y layer to resolve. Defaults to zero when omitted by paired overloads.

result Voxel

The resolved voxel, if found.

Returns

bool

True if the voxel was resolved; otherwise false.

TryGetVoxel(Vector2d, out Voxel?)

Retrieves a voxel from a 2D XZ-plane world position on the default world Y layer.

public bool TryGetVoxel(Vector2d position, out Voxel? result)

Parameters

position Vector2d

The 2D position whose X component maps to world X and Y component maps to world Z.

result Voxel

The resolved voxel, if found.

Returns

bool

True if the voxel was resolved; otherwise false.

TryGetVoxel(Vector3d, out Voxel?)

Retrieves a voxel from a world position.

public bool TryGetVoxel(Vector3d position, out Voxel? result)

Parameters

position Vector3d

The world position to resolve.

result Voxel

The resolved voxel, if found.

Returns

bool

True if the voxel was resolved; otherwise false.

TryGetVoxel(WorldVoxelIndex, out Voxel?)

Retrieves a voxel from a world-scoped voxel identity.

public bool TryGetVoxel(WorldVoxelIndex worldVoxelIndex, out Voxel? result)

Parameters

worldVoxelIndex WorldVoxelIndex

The voxel identity to resolve.

result Voxel

The resolved voxel, if found.

Returns

bool

True if the voxel was resolved; otherwise false.

TryRemoveGrid(ushort)

Removes a grid from this world and updates all references to ensure integrity.

public bool TryRemoveGrid(ushort removeIndex)

Parameters

removeIndex ushort

The world-local grid slot to remove.

Returns

bool

True if the grid was removed; otherwise false.

Events

OnActiveGridAdded

Event triggered when a new grid is added to this world.

public event Action<GridEventInfo> OnActiveGridAdded

Event Type

Action<GridEventInfo>

OnActiveGridChange

Event triggered when a grid in this world undergoes a significant change.

public event Action<GridEventInfo> OnActiveGridChange

Event Type

Action<GridEventInfo>

OnActiveGridRemoved

Event triggered when a grid is removed from this world.

public event Action<GridEventInfo> OnActiveGridRemoved

Event Type

Action<GridEventInfo>

OnReset

Event triggered when this world is reset.

public event Action OnReset

Event Type

Action