< Summary

Information
Class: GridForge.Configuration.GridConfiguration
Assembly: GridForge
File(s): /home/runner/work/GridForge/GridForge/src/GridForge/Configuration/GridConfiguration.cs
Line coverage
100%
Covered lines: 45
Uncovered lines: 0
Coverable lines: 45
Total lines: 198
Line coverage: 100%
Branch coverage
100%
Covered branches: 18
Total branches: 18
Branch coverage: 100%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
get_GridCenter()100%11100%
.ctor(...)100%66100%
ToBoundsKey()100%11100%
ToGridKey()100%11100%
TryNormalize(...)100%1212100%
GetHashCode()100%11100%

File(s)

/home/runner/work/GridForge/GridForge/src/GridForge/Configuration/GridConfiguration.cs

#LineLine coverage
 1//=======================================================================
 2// GridConfiguration.cs
 3//=======================================================================
 4// MIT License, Copyright (c) 2024-present David Oravsky (mrdav30)
 5// See LICENSE file in the project root for full license information.
 6//=======================================================================
 7
 8using System;
 9using System.Text.Json.Serialization;
 10using FixedMathSharp;
 11using GridForge.Grids.Storage;
 12using GridForge.Grids.Topology;
 13using GridForge.Spatial;
 14using MemoryPack;
 15using SwiftCollections.Utility;
 16
 17namespace GridForge.Configuration;
 18
 19/// <summary>
 20/// Defines the configuration parameters for a grid, including boundaries, topology, storage, and scan cell size.
 21/// Used to describe grid properties before a world normalizes and registers the grid.
 22/// </summary>
 23[Serializable]
 24[MemoryPackable]
 25public readonly partial struct GridConfiguration
 26{
 27    /// <summary>
 28    /// The default size of each scan cell.
 29    /// </summary>
 30    public const int DefaultScanCellSize = 8;
 31
 32    #region Properties
 33
 34    /// <summary>
 35    /// The minimum boundary of the grid in world coordinates.
 36    /// </summary>
 37    [JsonInclude]
 38    [MemoryPackInclude]
 39    public readonly Vector3d BoundsMin;
 40
 41    /// <summary>
 42    /// The maximum boundary of the grid in world coordinates.
 43    /// </summary>
 44    [JsonInclude]
 45    [MemoryPackInclude]
 46    public readonly Vector3d BoundsMax;
 47
 48    /// <summary>
 49    /// The size of each scan cell, determining the granularity of spatial partitioning.
 50    /// Customizable based on grid density and expected entity distribution.
 51    /// </summary>
 52    [JsonInclude]
 53    [MemoryPackInclude]
 54    public readonly int ScanCellSize;
 55
 56    /// <summary>
 57    /// The cell topology used by this grid. Rectangular-prism grids interpret
 58    /// <see cref="VoxelIndex"/> as local X/Y/Z coordinates; hex-prism grids
 59    /// interpret it as axial Q, vertical layer, and axial R.
 60    /// </summary>
 61    [JsonInclude]
 62    [MemoryPackInclude]
 63    public readonly GridTopologyKind TopologyKind;
 64
 65    /// <summary>
 66    /// The deterministic cell geometry used by this grid's topology.
 67    /// Rectangular-prism metrics define cell width, layer height, and length.
 68    /// Hex-prism metrics define horizontal radius, layer height, and orientation.
 69    /// </summary>
 70    [JsonInclude]
 71    [MemoryPackInclude]
 72    public readonly GridTopologyMetrics TopologyMetrics;
 73
 74    /// <summary>
 75    /// The physical voxel storage used by this grid. Dense storage materializes every in-bounds voxel;
 76    /// sparse storage materializes only explicitly configured voxels.
 77    /// </summary>
 78    [JsonInclude]
 79    [MemoryPackInclude]
 80    public readonly GridStorageKind StorageKind;
 81
 82    /// <summary>
 83    /// The center point of the grid's bounding volume.
 84    /// </summary>
 85    [JsonIgnore]
 86    [MemoryPackIgnore]
 58087    public readonly Vector3d GridCenter => Vector3d.Midpoint(BoundsMin, BoundsMax);
 88
 89    #endregion
 90
 91    #region Constructors
 92
 93    /// <summary>
 94    /// Initializes a new instance of <see cref="GridConfiguration"/> with specified bounds and scan cell size.
 95    /// Ensures that <see cref="BoundsMin"/> is always less than or equal to <see cref="BoundsMax"/>.
 96    /// </summary>
 97    /// <param name="boundsMin">The minimum boundary of the grid.</param>
 98    /// <param name="boundsMax">The maximum boundary of the grid.</param>
 99    /// <param name="scanCellSize">The size of scan cells within the grid. Default is 8.</param>
 100    /// <param name="topologyKind">The topology kind used by the grid. Defaults to rectangular-prism.</param>
 101    /// <param name="topologyMetrics">Deterministic topology metrics. Defaults to 1x1x1 rectangular-prism cells.</param>
 102    /// <param name="storageKind">The physical voxel storage kind. Defaults to dense storage.</param>
 103    [JsonConstructor]
 104    public GridConfiguration(
 105        Vector3d boundsMin,
 106        Vector3d boundsMax,
 107        int scanCellSize = DefaultScanCellSize,
 108        GridTopologyKind topologyKind = GridTopologyKind.RectangularPrism,
 109        GridTopologyMetrics topologyMetrics = default,
 110        GridStorageKind storageKind = GridStorageKind.Dense)
 111    {
 8676112        if (boundsMin > boundsMax)
 4113            GridForgeLogger.Channel.Warn($"GridMin was greater than GridMax, auto-correcting values.");
 114
 8676115        BoundsMin = new Vector3d(
 8676116            FixedMath.Min(boundsMin.X, boundsMax.X),
 8676117            FixedMath.Min(boundsMin.Y, boundsMax.Y),
 8676118            FixedMath.Min(boundsMin.Z, boundsMax.Z));
 8676119        BoundsMax = new Vector3d(
 8676120            FixedMath.Max(boundsMin.X, boundsMax.X),
 8676121            FixedMath.Max(boundsMin.Y, boundsMax.Y),
 8676122            FixedMath.Max(boundsMin.Z, boundsMax.Z));
 123
 8676124        ScanCellSize = scanCellSize > 0 ? scanCellSize : DefaultScanCellSize;
 8676125        TopologyKind = topologyKind;
 8676126        TopologyMetrics = topologyMetrics == default
 8676127            ? GridTopologyMetrics.Normalize(topologyKind, topologyMetrics)
 8676128            : topologyMetrics;
 8676129        StorageKind = storageKind;
 8676130    }
 131
 132    #endregion
 133
 134    /// <summary>
 135    /// Creates an exact identity key for this configuration's current bounds.
 136    /// </summary>
 137    /// <remarks>Use <see cref="TryNormalize"/> before deriving a normalized bounds key.</remarks>
 5138    public readonly BoundsKey ToBoundsKey() => new(BoundsMin, BoundsMax);
 139
 140    /// <summary>
 141    /// Creates an exact identity key for this configuration's current bounds and topology.
 142    /// </summary>
 143    /// <remarks>Use the descriptor from <see cref="TryNormalize"/> for normalized registration identity.</remarks>
 144    public readonly GridConfigurationKey ToGridKey() =>
 10119145        new(BoundsMin, BoundsMax, TopologyKind, TopologyMetrics);
 146
 147    /// <summary>
 148    /// Validates and normalizes this configuration without registering a live grid.
 149    /// </summary>
 150    /// <param name="descriptor">
 151    /// The normalized configuration, exact binding key, dimensions, and local-index validator.
 152    /// </param>
 153    /// <returns>
 154    /// True when the topology and dimensions are supported; otherwise false and
 155    /// <paramref name="descriptor"/> is default.
 156    /// </returns>
 157    public readonly bool TryNormalize(out NormalizedGridConfiguration descriptor)
 158    {
 5390159        descriptor = default;
 5390160        if (!GridTopologyFactory.TryCreate(this, out IGridTopology? topology))
 12161            return false;
 162
 5378163        (Vector3d boundsMin, Vector3d boundsMax) =
 5378164            topology!.NormalizeBounds(BoundsMin, BoundsMax);
 5378165        GridConfiguration normalizedConfiguration = new(
 5378166            boundsMin,
 5378167            boundsMax,
 5378168            ScanCellSize,
 5378169            TopologyKind,
 5378170            TopologyMetrics,
 5378171            StorageKind);
 5378172        GridDimensions dimensions = topology.CalculateDimensions(boundsMin, boundsMax);
 173
 5378174        if (dimensions.Width <= 0 || dimensions.Height <= 0 || dimensions.Length <= 0)
 175        {
 8176            GridForgeLogger.Channel.Warn($"Grid dimensions must define a positive voxel address space.");
 8177            return false;
 178        }
 179
 5370180        long layerSize = (long)dimensions.Width * dimensions.Height;
 5370181        if (layerSize > int.MaxValue || layerSize * dimensions.Length > int.MaxValue)
 182        {
 4183            GridForgeLogger.Channel.Warn($"Grid dimensions exceed the supported int voxel address space.");
 4184            return false;
 185        }
 186
 5366187        descriptor = new NormalizedGridConfiguration(normalizedConfiguration, topology, dimensions);
 5366188        return true;
 189    }
 190
 191    /// <inheritdoc/>
 192    public override readonly int GetHashCode()
 193    {
 6194        int hash = SwiftHashTools.CombineHashCodes(BoundsMin.GetHashCode(), BoundsMax.GetHashCode());
 6195        hash = SwiftHashTools.CombineHashCodes(hash, TopologyKind.GetHashCode());
 6196        return SwiftHashTools.CombineHashCodes(hash, TopologyMetrics.GetHashCode());
 197    }
 198}