Class ScyllaSparseTriGrid<TCell>

Sparse, dictionary-backed triangular grid that stores per-cell data of type TCell only for cells that have been explicitly set.

Inheritance
object
ScyllaSparseTriGrid<TCell>
Implements
Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
public sealed class ScyllaSparseTriGrid<TCell> : IScyllaGrid<TriCoord, TCell>, IScyllaCollection
Type Parameters
Name Description
TCell

The type of data stored in each grid cell. May be a value type or a reference type.
Remarks

Unlike ScyllaTriGrid<TCell>, this class does not pre-allocate storage for every cell. Only cells with explicitly assigned values occupy memory, making it suitable for large or infinite grids where most cells are unused. Average-case access time is O(1) via the internal dictionary.

The grid may be created in two modes:

  • Unbounded: any valid TriCoord (sum = 1 or 2) may be set. Construct with ScyllaSparseTriGrid(TriGridLayout).
  • Bounded: only cells whose A and B lanes fall within the specified inclusive ranges are accepted. Construct with the five-parameter overload or the builder's WithBounds option.

This class is unsynchronized by default. Call AsSynchronized(object) or use the builder's Synchronized() option to obtain a thread-safe wrapper.

Constructors

ScyllaSparseTriGrid(TriGridLayout)

Creates a new unbounded sparse triangular grid. Any valid TriCoord (lane sum = 1 or 2) may be used as a key regardless of coordinate magnitude.

Declaration
public ScyllaSparseTriGrid(TriGridLayout layout)
Parameters
Type Name Description
TriGridLayout layout

The TriGridLayout supplying the triangle edge length and world-space origin for coordinate conversion.

ScyllaSparseTriGrid(TriGridLayout, int, int, int, int)

Creates a new bounded sparse triangular grid. Only cells whose A lane falls in [aMin, aMax] and B lane falls in [bMin, bMax] may be stored; all lane-sum validity checks still apply.

Declaration
public ScyllaSparseTriGrid(TriGridLayout layout, int aMin, int bMin, int aMax, int bMax)
Parameters
Type Name Description
TriGridLayout layout

The TriGridLayout supplying the triangle edge length and world-space origin for coordinate conversion.
int aMin

The minimum A lane value (inclusive lower bound).
int bMin

The minimum B lane value (inclusive lower bound).
int aMax

The maximum A lane value (inclusive upper bound). Must be >= aMin.
int bMax

The maximum B lane value (inclusive upper bound). Must be >= bMin.
Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown when aMax is less than aMin, or when bMax is less than bMin.

Properties

AMax

Gets the maximum A lane value that cells in this grid may have (inclusive). Only meaningful when HasBounds is true.

Declaration
public int AMax { get; }
Property Value
Type Description
int

AMin

Gets the minimum A lane value that cells in this grid may have (inclusive). Only meaningful when HasBounds is true.

Declaration
public int AMin { get; }
Property Value
Type Description
int

BMax

Gets the maximum B lane value that cells in this grid may have (inclusive). Only meaningful when HasBounds is true.

Declaration
public int BMax { get; }
Property Value
Type Description
int

BMin

Gets the minimum B lane value that cells in this grid may have (inclusive). Only meaningful when HasBounds is true.

Declaration
public int BMin { get; }
Property Value
Type Description
int

Capabilities

Gets the feature and capability flags supported by this collection instance.

Declaration
public ScyllaCollectionCapabilities Capabilities { get; }
Property Value
Type Description
ScyllaCollectionCapabilities

A bitfield of ScyllaCollectionCapabilities flags describing which optional operations the concrete instance supports. The value None indicates that only the base contract (Count, IsEmpty, Clear()) is available.
Remarks

Use Capabilities for feature detection in place of type-casting. For example: 

if ((collection.Capabilities & ScyllaCollectionCapabilities.SupportsPeek) != 0)
{
    // safe to call TryPeek through IScyllaCollection<T>
}

Synchronized wrappers cache the capability flags of their inner collection at construction time, so the value returned is stable and does not require synchronization.

See Also

CellCount

Gets the number of populated (logically active) cells in the grid.

Declaration
public int CellCount { get; }
Property Value
Type Description
int

For dense grids, this always equals Count - every cell slot is pre-allocated and considered populated regardless of its stored value. The value is fixed at construction and never changes.

For sparse grids, this equals the number of cells that have been explicitly written via TrySet(TCoord, TCell) and not yet removed. The value may be zero on a freshly created or cleared sparse grid.

See Also
TrySet(TCoord, TCell)

Count

Gets the number of items currently contained in the collection.

Declaration
public int Count { get; }
Property Value
Type Description
int

A non-negative integer representing the current element count. Returns 0 when the collection is empty.
Remarks

On unsynchronized collections, Count is not thread-safe and may return a stale value when accessed concurrently. On synchronized wrappers, reading Count is protected by the internal lock.

HasBounds

Gets a value indicating whether this grid was constructed with explicit A and B lane bounds. When false the grid is unbounded and accepts any valid TriCoord.

Declaration
public bool HasBounds { get; }
Property Value
Type Description
bool

IsEmpty

Gets a value indicating whether the collection contains no items.

Declaration
public bool IsEmpty { get; }
Property Value
Type Description
bool

true when Count is 0; false otherwise.
Remarks

This is a convenience property equivalent to Count == 0. Prefer it over comparing Count directly when the actual count is not needed, as some implementations may compute it more efficiently.

this[TriCoord]

Gets or sets the cell value at the specified triangle coordinate.

Declaration
public TCell this[TriCoord coord] { get; set; }
Parameters
Type Name Description
TriCoord coord

The triangle coordinate of the cell to access or write.
Property Value
Type Description
TCell
Remarks

The getter throws KeyNotFoundException when no value has been set at coord; use TryGet(TriCoord, out TCell) to avoid exceptions on potentially absent cells.

The setter throws ArgumentOutOfRangeException when the coordinate has an invalid lane sum (not 1 or 2) or when the grid is bounded and coord falls outside the defined A and B ranges. Use TrySet(TriCoord, TCell) for a non-throwing alternative.

Exceptions
Type Condition
KeyNotFoundException

Thrown by the getter when no value is stored at coord.
ArgumentOutOfRangeException

Thrown by the setter when coord is invalid or out of bounds.

Layout

Gets the TriGridLayout that defines the triangle edge length and world-space origin used by GridToWorld(TriCoord) and WorldToGrid(Vector2).

Declaration
public TriGridLayout Layout { get; }
Property Value
Type Description
TriGridLayout

SyncRoot

Gets the synchronization root object used to externally coordinate multi-step operations with this collection.

Declaration
public object SyncRoot { get; }
Property Value
Type Description
object

A non-null object suitable for use with lock when ThreadSafety is Synchronized. Returns null for unsynchronized collections, which do not own a lock.
Remarks

When this collection is a synchronized wrapper, SyncRoot must be non-null and stable for the entire lifetime of the wrapper. All internal operations on the wrapper must lock on this same object. This allows callers to perform atomic multi-step sequences: 

lock (collection.SyncRoot)
{
    if (!collection.IsEmpty)
        typedCollection.TryRemove(out var item);
}

For unsynchronized collections (SyncRoot == null), callers are responsible for supplying and consistently applying their own external synchronization mechanism. A null SyncRoot does not mean the collection is thread-safe; consult ThreadSafety for the authoritative guarantee.

See Also

ThreadSafety

Gets the thread-safety guarantees provided by this collection instance.

Declaration
public ScyllaCollectionThreadSafety ThreadSafety { get; }
Property Value
Type Description
ScyllaCollectionThreadSafety

A ScyllaCollectionThreadSafety value indicating whether the collection is unsynchronized, synchronized via a lock, or safe for lock-free concurrent access. Most core implementations return Unsynchronized. Synchronized wrappers return Synchronized.
Remarks

Always check this property (or SyncRoot) before assuming a collection is safe for concurrent use. Do not rely solely on the absence of a non-null SyncRoot to infer thread safety; use this property as the authoritative source.

See Also

Methods

AsSynchronized(object)

Creates and returns a thread-safe ScyllaSparseTriGrid<TCell>.SynchronizedScyllaSparseTriGrid wrapper that serialises all operations on this grid using a lock.

Declaration
public ScyllaSparseTriGrid<TCell>.SynchronizedScyllaSparseTriGrid AsSynchronized(object syncRoot = null)
Parameters
Type Name Description
object syncRoot

An optional external lock object to share with other synchronized collections for compound atomic operations. If null, a new private lock object is created inside the wrapper.
Returns
Type Description
ScyllaSparseTriGrid<TCell>.SynchronizedScyllaSparseTriGrid

A ScyllaSparseTriGrid<TCell>.SynchronizedScyllaSparseTriGrid wrapping this instance with ThreadSafety = Synchronized.

Clear()

Removes all items from the collection and resets it to an empty state.

Declaration
public void Clear()
Remarks

Implementations that store reference-type elements should null out internal slots after clearing to avoid retaining object references and preventing garbage collection. After Clear returns, Count must be 0 and IsEmpty must be true.

On synchronized wrappers this operation is protected by the collection's internal lock. On unsynchronized collections, callers are responsible for external coordination.

Contains(TriCoord)

Determines whether the specified coordinate is addressable and populated in this grid.

Declaration
public bool Contains(TriCoord coord)
Parameters
Type Name Description
TriCoord coord

The coordinate to test.
Returns
Type Description
bool

For dense grids, returns true when coord maps to a valid index within the grid's pre-allocated array - that is, when the coordinate is geometrically within the grid's dimensions, regardless of the stored value.

For sparse grids, returns true only when coord has been explicitly written via TrySet(TCoord, TCell) and not since removed. An in-bounds coordinate that has never been written returns false.

Remarks

This method is equivalent to checking whether TryGet(TCoord, out TCell) would return true for the same coordinate. Use it when you only need the existence check and do not need the value.

See Also
TryGet(TCoord, out TCell)
TrySet(TCoord, TCell)

CreateBuilder()

Creates a new fluent builder for constructing a ScyllaSparseTriGrid<TCell> with complex or optional configuration.

Declaration
public static ScyllaSparseTriGrid<TCell>.Builder CreateBuilder()
Returns
Type Description
ScyllaSparseTriGrid<TCell>.Builder

A new ScyllaSparseTriGrid<TCell>.Builder instance with default settings.

GetEnumerator()

Returns an allocation-free enumerator that iterates through all populated cells in this sparse grid.

Declaration
public ScyllaSparseTriGrid<TCell>.Enumerator GetEnumerator()
Returns
Type Description
ScyllaSparseTriGrid<TCell>.Enumerator

An ScyllaSparseTriGrid<TCell>.Enumerator positioned before the first populated cell.
Remarks

Use this method on the concrete ScyllaSparseTriGrid<TCell> type (not via an interface) to avoid boxing the value-type ScyllaSparseTriGrid<TCell>.Enumerator. The enumeration order matches the internal dictionary's unspecified traversal order. Mutating the grid during enumeration results in undefined behaviour.

GetNeighborsNonAlloc(TriCoord, Span<TriCoord>)

Writes the edge-sharing neighbors of the specified coordinate that are currently populated in this sparse grid into the provided buffer, without allocating.

Declaration
public int GetNeighborsNonAlloc(TriCoord coord, Span<TriCoord> buffer)
Parameters
Type Name Description
TriCoord coord

The triangle coordinate whose populated neighbors are needed.
Span<TriCoord> buffer

A span to receive the neighbor coordinates. Entries are written starting at index 0. Writing stops when the buffer is full.
Returns
Type Description
int

The number of populated neighbors written into buffer - between 0 and 3 inclusive.
Remarks

All three candidate neighbors are computed via GetEdgeNeighbors(TriCoord, Span<TriCoord>) on a stack-allocated buffer; only those whose coordinates exist as keys in the internal dictionary are included. For dense grids with bounds filtering, use GetNeighborsNonAlloc(TriCoord, Span<TriCoord>) instead.

GridToWorld(TriCoord)

Converts a triangle coordinate to the world-space centroid position using this grid's Layout.

Declaration
public Vector2 GridToWorld(TriCoord coord)
Parameters
Type Name Description
TriCoord coord

The triangle coordinate to convert.
Returns
Type Description
Vector2

The world-space Vector2 centroid of the triangle at coord.
See Also

IsInBounds(TriCoord)

Determines whether the specified coordinate is a valid triangle and lies within this grid's bounds (if bounded).

Declaration
public bool IsInBounds(TriCoord coord)
Parameters
Type Name Description
TriCoord coord

The triangle coordinate to test.
Returns
Type Description
bool

true if coord is a valid triangle that can be stored in this grid; false otherwise.
Remarks

For an unbounded grid this method only checks that the lane sum is 1 or 2. For a bounded grid it additionally checks that the A and B lanes fall within [AMin, AMax] and [BMin, BMax] respectively.

TryGet(TriCoord, out TCell)

Attempts to retrieve the value stored at the specified coordinate without throwing on failure.

Declaration
public bool TryGet(TriCoord coord, out TCell value)
Parameters
Type Name Description
TriCoord coord

The grid coordinate to look up.
TCell value

When this method returns true, contains the cell value at coord. When this method returns false, contains default(TCell). This parameter is passed uninitialized and is always written before this method returns.
Returns
Type Description
bool

true if coord is within the grid's valid range and a value was successfully read; false if the coordinate is out of bounds (dense grids) or has not been explicitly written (sparse grids).
Remarks

Prefer this method over direct indexer access when the coordinate's validity is not guaranteed, as it avoids the cost of exception handling on out-of-bounds access. For dense grids, "within bounds" means the coordinate maps to a valid flat-array index. For sparse grids, "within bounds" additionally requires that the cell has been set.

See Also
TrySet(TCoord, TCell)
Contains(TCoord)

TryRemove(TriCoord, out TCell)

Attempts to remove the cell at the specified coordinate from the sparse grid, returning the previously stored value.

Declaration
public bool TryRemove(TriCoord coord, out TCell value)
Parameters
Type Name Description
TriCoord coord

The triangle coordinate to remove.
TCell value

When this method returns, contains the value that was associated with coord if found; otherwise default.
Returns
Type Description
bool

true if a cell existed at coord and was removed; false if no cell was present at that coordinate.

TrySet(TriCoord, TCell)

Attempts to store a value at the specified coordinate without throwing on failure.

Declaration
public bool TrySet(TriCoord coord, TCell value)
Parameters
Type Name Description
TriCoord coord

The grid coordinate to write to.
TCell value

The value to store at coord.
Returns
Type Description
bool

true if the coordinate is valid and the value was successfully stored; false if the coordinate is out of bounds and no change was made.
Remarks

For dense grids, this writes to the pre-allocated cell at coord and returns false if the coordinate falls outside the grid's dimensions.

For sparse grids, this inserts or updates the entry at coord and returns false only when the grid is bounded and coord falls outside the defined bounds. On unbounded sparse grids this method always returns true.

A successful call increments CellCount on sparse grids when coord is newly written for the first time.

See Also
TryGet(TCoord, out TCell)
Contains(TCoord)

WorldToGrid(Vector2)

Converts a world-space position to the nearest triangle coordinate using this grid's Layout.

Declaration
public TriCoord WorldToGrid(Vector2 worldPos)
Parameters
Type Name Description
Vector2 worldPos

The world-space position to convert.
Returns
Type Description
TriCoord

The TriCoord of the triangle that contains worldPos. The result is not guaranteed to satisfy IsInBounds(TriCoord); check separately if needed.
See Also
WorldToGrid(Vector2)

Implements

Extension Methods

See Also