Interface ISpatialMap<T>

Interface common to spatial map implementations provided with GoRogue, which are designed to be a convenient way to store items that reside on a map. TLDR; If you're about to use a List to store all the objects on a map, consider using a (GoRogue-provided) ISpatialMap implementation instead.

Inherited Members
System.Collections.Generic.IEnumerable<GoRogue.ISpatialTuple<T>>.GetEnumerator()
Namespace: GoRogue
Assembly: GoRogue.dll
Syntax
public interface ISpatialMap<T> : IReadOnlySpatialMap<T>, IEnumerable<ISpatialTuple<T>>, IEnumerable
Type Parameters
Name Description
T

The type of object that will be contained by the spatial map.
Remarks

Typical roguelikes will use a 2D array (or 1D array accessed as a 2D array), for terrain, and lists of objects for things like entities, items, etc. This is simple but ultimately not efficient; for example, in that implementation, determining if there is an object at a location takes an amount of time proportional to the number of objects in this list. However, the other simple option is to use an array with size equal to the size of the map (as many do for terrain) for all object lists. This is even less ideal, as in that case, the time to iterate over all objects becomes proportional to the size of the map (since one has to do that for rendering, that's bad!), which is typically much larger than the number of objects in a list. This is the problem spatial map implementions are designed to solve. They provide fast, near-constant-time operations for getting the item(s) at a location, adding items, and removing items. As well, they allow you to iterate through all objects in the spatial map in time proportional to the number of objects in it (the best possible). Effectively, it is a more efficient list for objects that have a position associated with them. Spatial maps also provide events for when things are added, removed, etc., to allow you to conveniently respond to those types of actions.

Spatial maps have to keep track of the position of each item in them in order to provide their fast-lookup functionality. Spatial maps can be used as the primary authority for what an item's position is in some cases -- however, in many cases, this may be undesireable, particularly when interfacing with more traditional infrastructures from other libraries, which likely record each item's position as a field or property of the item itself. In these cases, where the item itself records its position, you will need to call the Move(T, Coord) function (or a similar overload) whenever an object moves, to keep the spatial map's position for that item in sync with its actual position.

It is also worthy of note, that some implementations of ISpatialMap (such as SpatialMap<T>) have implemented Move(T, Coord) in such a way that it could fail in some cases. Move will return false in cases where it fails, so if you are using an implementation where that may happen, you may need to check this to avoid desync issues. The Move function documentation for each implementation clearly states in what cases a call to Move can fail.

Methods

| Improve this Doc View Source

Add(T, Coord)

Adds the given item at the given position, and returns true if the item was successfully added. If the item could not be added, returns false.

Declaration
bool Add(T newItem, Coord position)
Parameters
Type Name Description
T newItem

Item to add.
Coord position

Position to add item to.
Returns
Type Description
System.Boolean

True if item was successfully added, false otherwise.
| Improve this Doc View Source

Add(T, Int32, Int32)

Adds the given item at the given position, and returns true if the item was successfully added. If the item could not be added, returns false.

Declaration
bool Add(T newItem, int x, int y)
Parameters
Type Name Description
T newItem

Item to add.
System.Int32 x

X-value of the position to add item to.
System.Int32 y

Y-value of the position to add item to.
Returns
Type Description
System.Boolean

True if item was successfully added, false otherwise.
| Improve this Doc View Source

Clear()

Clears all items out of the spatial map.

Declaration
void Clear()
| Improve this Doc View Source

Move(T, Coord)

Moves the given item from its current location to the specified one. Returns true if the item was successfully moved, false otherwise.

Declaration
bool Move(T item, Coord target)
Parameters
Type Name Description
T item

Item to move.
Coord target

Location to move item to.
Returns
Type Description
System.Boolean

True if item was successfully moved, false otherwise.
| Improve this Doc View Source

Move(T, Int32, Int32)

Moves the given item from its current location to the specified one. Returns true if the item was successfully moved, false otherwise.

Declaration
bool Move(T item, int targetX, int targetY)
Parameters
Type Name Description
T item

Item to move
System.Int32 targetX

X-value of the location to move item to.
System.Int32 targetY

Y-value of the location to move item to.
Returns
Type Description
System.Boolean

True if item was successfully moved, false otherwise.
| Improve this Doc View Source

Move(Coord, Coord)

Moves any items at the specified location to the target one. Returns any items that were moved.

Declaration
IEnumerable<T> Move(Coord current, Coord target)
Parameters
Type Name Description
Coord current

Location to move items from.
Coord target

Location to move items to.
Returns
Type Description
System.Collections.Generic.IEnumerable<T>

Any items that were moved, or nothing if no items were moved.
| Improve this Doc View Source

Move(Int32, Int32, Int32, Int32)

Moves any items at the specified location to the target one. Returns any items that were moved.

Declaration
IEnumerable<T> Move(int currentX, int currentY, int targetX, int targetY)
Parameters
Type Name Description
System.Int32 currentX

X-value of the location to move items from.
System.Int32 currentY

Y-value of the location to move items from.
System.Int32 targetX

X-value of the location to move items to.
System.Int32 targetY

Y-value of the location to move items to.
Returns
Type Description
System.Collections.Generic.IEnumerable<T>

Any items that were moved, or nothing if no items were moved.
| Improve this Doc View Source

Remove(T)

Removes the given item from the spatial map, returning true if the item was removed, false otherwise.

Declaration
bool Remove(T item)
Parameters
Type Name Description
T item

The item to remove.
Returns
Type Description
System.Boolean

True if item was removed, false otherwise.
| Improve this Doc View Source

Remove(Coord)

Removes any items at the specified location from the spatial map. Returns any items that were removed.

Declaration
IEnumerable<T> Remove(Coord position)
Parameters
Type Name Description
Coord position

Position to remove items from.
Returns
Type Description
System.Collections.Generic.IEnumerable<T>

Any items that were removed, or nothing if no items were removed.
| Improve this Doc View Source

Remove(Int32, Int32)

Removes any items at the specified location from the spatial map. Returns any items that were removed.

Declaration
IEnumerable<T> Remove(int x, int y)
Parameters
Type Name Description
System.Int32 x

X-value of the position to remove items from.
System.Int32 y

Y-value of the position to remove items from.
Returns
Type Description
System.Collections.Generic.IEnumerable<T>

Any items that were removed, or nothing if no items were removed.

Extension Methods