Class Map
Base class for a map that consists of one or more objects of base type IGameObject. It implements basic functionality to manage and access these objects, as well as commonly needed functionality like tile exploration, FOV, and pathfinding. It also provides methods to easily access these objects as instances of some derived type. This can be used to easily access functionality you've implemented in a subclass. Finally, it provides the ability to attach components to the map.
Inherited Members
Namespace: GoRogue.GameFramework
Assembly: GoRogue.dll
Syntax
public class Map : GridViewBase<MapObjectsAtEnumerator>, IGridView<MapObjectsAtEnumerator>, IObjectWithComponents
Remarks
A Map consists of IGameObject instances on one or more layers. These layers are numbered, from the lowest layer of 0 upward. Each Map contains at minimum a layer 0, which is considered the "terrain" layer. All objects added to this layer cannot move while they are added to a map; though they can move when they aren't a part of any map.
A map will typically also have some other layers, for non-terrain objects like monsters, items, etc. The number of these layers present on the map, along with which of all the layers participate in collision detection, etc., can be specified in the constructor.
If ComponentCollection (or some other custom collection implementing the proper functionality) is used, as the component collection, this object provides support for its components to (optionally) implement IParentAwareComponent, or inherit from ParentAwareComponentBase. In this case, the Parent will be updated automatically as components are added/ removed. Typically, you will want to inherit your components from ParentAwareComponentBase<TParent>, where TParent would be Map or some class inheriting from it.
Constructors
View SourceMap(ISettableGridView<IGameObject?>, int, Distance, Func<int, IListPool<IGameObject>>?, uint, uint, uint, IEqualityComparer<Point>?, IFOV?, AStar?, IComponentCollection?, bool)
Constructor. Constructs map with the given terrain layer, determining width/height based on the width/height of that terrain layer. Note that the terrainLayer you pass it is subject to some very specific restrictions; see the remarks for details. Consider using ApplyTerrainOverlay<T>(IGridView<T>, Func<Point, T, IGameObject>) instead of this constructor for more use cases.
Declaration
public Map(ISettableGridView<IGameObject?> terrainLayer, int numberOfEntityLayers, Distance distanceMeasurement, Func<int, IListPool<IGameObject>>? customListPoolCreator = null, uint layersBlockingWalkability = 4294967295, uint layersBlockingTransparency = 4294967295, uint entityLayersSupportingMultipleItems = 4294967295, IEqualityComparer<Point>? pointComparer = null, IFOV? customPlayerFOV = null, AStar? customPather = null, IComponentCollection? customComponentCollection = null, bool useCachedGridViews = true)
Parameters
Type | Name | Description |
---|---|---|
ISettableGridView<IGameObject> | terrainLayer | The ISettableGridView<T> that represents the terrain layer for this map. See the remarks section for some invariants that must be adhered to regarding this parameter. |
int | numberOfEntityLayers | Number of non-terrain layers for the map. |
Distance | distanceMeasurement | Distance measurement to use for pathfinding/measuring distance on the map. |
Func<int, IListPool<IGameObject>> | customListPoolCreator | A function used to determine the list pool implementation used for the spatial maps which support multiple items in a location (if any). The function takes the layer it is creating the pool for as a parameter. If no custom creator is specified, a ListPool is used. |
uint | layersBlockingWalkability | Layer mask containing those layers that should be allowed to have items that block walkability. Defaults to all layers. |
uint | layersBlockingTransparency | Layer mask containing those layers that should be allowed to have items that block FOV. Defaults to all layers. |
uint | entityLayersSupportingMultipleItems | Layer mask containing those layers that should be allowed to have multiple objects at the same location on the same layer. Defaults to all layers. |
IEqualityComparer<Point> | pointComparer | Equality comparer to use for comparison and hashing of points, as object are added to/removed from/moved around the map. Be especially mindful of the efficiency of its GetHashCode function, as it will determine the efficiency of many AMap functions. Defaults to a fast hashing algorithm that generates a unique integer for each point based on the width of the map. |
IFOV | customPlayerFOV | Custom FOV to use for PlayerFOV. Defaults to a GoRogue's recursive shadow-casting implementation. It may also be useful to specify this if you want the PlayerFOV property to not use TransparencyView for data. |
AStar | customPather | Custom A* pathfinder for the map. Typically, you wont' need to specify this; By default, uses WalkabilityView to determine which locations can be reached, and calculates distance based on the Distance passed to the Map in the constructor. |
IComponentCollection | customComponentCollection | A custom component container to use for GoRogueComponents. If not specified, a ComponentCollection is used. Typically you will not need to specify this, as a ComponentCollection is sufficient for nearly all use cases. |
bool | useCachedGridViews | Whether or not to use cached grid views for TransparencyView and WalkabilityView, rather than calculating values on the fly. Calculating on the fly is notably slower, but takes up less memory. |
Remarks
Because of the way polymorphism works for custom classes in C#, the terrainLayer
parameter MUST be of type ISettableGridView<T>, rather than
ISettableGridView<T> where T is a type that derives from or implements
IGameObject. If you need to use a map view storing some type T rather than IGameObject, use
the CreateMap<T>(ISettableGridView<T?>, int, Distance, Func<int, IListPool<IGameObject>>?, uint, uint, uint, IEqualityComparer<Point>?, IFOV?, AStar?, IComponentCollection?) function to create the map.
Note that this constructor exists pretty much entirely for maximum compatibility; however using it is subject
to a few restrictions. Primarily, the terrainLayer
given must:
Always consist of persistent objects. This is to say, the layer cannot be creating objects whenever they are requested via the indexer. For example, a SettableLambdaGridView which creates a new GameObject based on some other data is NOT a valid
terrainLayer
. For this use case, ApplyTerrainOverlay<T>(IGridView<T>, Func<Point, T, IGameObject>) is recommended instead.Always have its values swapped out via SetTerrain(IGameObject) function after it is passed to this constructor, rather than via its set indexer. Basically, the terrain view must not be changed by anything other than the map after this constructor takes it.
Violating either of these conditions will create desync bugs that can leave the map in a completely unusable state. Generally, this constructor should be used as a matter of last resort when there isn't a better way to accomplish your integration goals. You should probably prefer the ApplyTerrainOverlay<T>(IGridView<T>, Func<Point, T, IGameObject>) approach until/unless you have a reason not to.
Map(int, int, int, Distance, Func<int, IListPool<IGameObject>>?, uint, uint, uint, IEqualityComparer<Point>?, IFOV?, AStar?, IComponentCollection?, bool)
Constructor. Constructs terrain map as ArrayView<T>; with the given width/height.
Declaration
public Map(int width, int height, int numberOfEntityLayers, Distance distanceMeasurement, Func<int, IListPool<IGameObject>>? customListPoolCreator = null, uint layersBlockingWalkability = 4294967295, uint layersBlockingTransparency = 4294967295, uint entityLayersSupportingMultipleItems = 4294967295, IEqualityComparer<Point>? pointComparer = null, IFOV? customPlayerFOV = null, AStar? customPather = null, IComponentCollection? customComponentCollection = null, bool useCachedGridViews = true)
Parameters
Type | Name | Description |
---|---|---|
int | width | Width of the map. |
int | height | Height of the map. |
int | numberOfEntityLayers | Number of non-terrain layers for the map. |
Distance | distanceMeasurement | Distance measurement to use for pathfinding/measuring distance on the map. |
Func<int, IListPool<IGameObject>> | customListPoolCreator | A function used to determine the list pool implementation used for the spatial maps which support multiple items in a location (if any). The function takes the layer it is creating the pool for as a parameter. If no custom creator is specified, a ListPool is used. |
uint | layersBlockingWalkability | Layer mask containing those layers that should be allowed to have items that block walkability. Defaults to all layers. |
uint | layersBlockingTransparency | Layer mask containing those layers that should be allowed to have items that block FOV. Defaults to all layers. |
uint | entityLayersSupportingMultipleItems | Layer mask containing those layers that should be allowed to have multiple objects at the same location on the same layer. Defaults to all layers. |
IEqualityComparer<Point> | pointComparer | Equality comparer to use for comparison and hashing of points, as object are added to/removed from/moved around the map. Be especially mindful of the efficiency of its GetHashCode function, as it will determine the efficiency of many AMap functions. Defaults to a fast hashing algorithm that generates a unique integer for each point based on the width of the map. |
IFOV | customPlayerFOV | Custom FOV to use for PlayerFOV. Defaults to a GoRogue's recursive shadow-casting implementation. It may also be useful to specify this if you want the PlayerFOV property to not use TransparencyView for data. |
AStar | customPather | Custom A* pathfinder for the map. Typically, you wont' need to specify this; By default, uses WalkabilityView to determine which locations can be reached, and calculates distance based on the Distance passed to the Map in the constructor. |
IComponentCollection | customComponentCollection | A custom component container to use for GoRogueComponents. If not specified, a ComponentCollection is used. Typically you will not need to specify this, as a ComponentCollection is sufficient for nearly all use cases. |
bool | useCachedGridViews | Whether or not to use cached grid views for TransparencyView and WalkabilityView, rather than calculating values on the fly. Calculating on the fly is notably slower, but takes up less memory. |
Fields
View SourcePlayerExplored
Whether or not each tile is considered explored. Tiles start off unexplored, and become explored as soon as they are within PlayerFOV. This ArrayView may also have values set to it, to easily allow for custom serialization or wizard-mode like functionality.
Declaration
public ArrayView<bool> PlayerExplored
Field Value
Type | Description |
---|---|
ArrayView<bool> |
Properties
View SourceAStar
A* pathfinder for the map. By default, uses WalkabilityView to determine which locations can be reached, and calculates distance based on the Distance passed to the Map in the constructor.
Declaration
public AStar AStar { get; set; }
Property Value
Type | Description |
---|---|
AStar |
DistanceMeasurement
Distance measurement used for pathfinding and measuring distance on the map.
Declaration
public Distance DistanceMeasurement { get; }
Property Value
Type | Description |
---|---|
Distance |
Entities
IReadOnlyLayeredSpatialMap<T> of all entities (non-terrain objects) on the map.
Declaration
public IReadOnlyLayeredSpatialMap<IGameObject> Entities { get; }
Property Value
Type | Description |
---|---|
IReadOnlyLayeredSpatialMap<IGameObject> |
GoRogueComponents
Collection holding components that GoRogue has recorded as being attached to the implementing object.
Declaration
public IComponentCollection GoRogueComponents { get; }
Property Value
Type | Description |
---|---|
IComponentCollection |
Height
Height of the map, in grid spaces.
Declaration
public override int Height { get; }
Property Value
Type | Description |
---|---|
int |
Overrides
this[Point]
Gets all objects at the given location, from the highest layer (layer with the highest number) down.
Declaration
public override MapObjectsAtEnumerator this[Point pos] { get; }
Parameters
Type | Name | Description |
---|---|---|
Point | pos | The position to retrieve objects for. |
Property Value
Type | Description |
---|---|
MapObjectsAtEnumerator | All objects at the given location, in order from highest layer to lowest layer. |
Overrides
LayerMasker
LayerMasker that should be used to create layer masks for this Map.
Declaration
public LayerMasker LayerMasker { get; }
Property Value
Type | Description |
---|---|
LayerMasker |
LayersBlockingTransparency
Layer mask that contains only layers that block transparency. A non-transparent IGameObject can only be added to this map if the layer it is on is contained within this layer mask.
Declaration
public uint LayersBlockingTransparency { get; }
Property Value
Type | Description |
---|---|
uint |
LayersBlockingWalkability
Layer mask that contains only layers that block walkability. A non-walkable IGameObject can only be added to this map if the layer it resides on is contained within this layer mask.
Declaration
public uint LayersBlockingWalkability { get; }
Property Value
Type | Description |
---|---|
uint |
PlayerFOV
FOV for the player. By default, calculated based upon TransparencyView. PlayerExplored is updated automatically when this is calculated.
Declaration
public IFOV PlayerFOV { get; set; }
Property Value
Type | Description |
---|---|
IFOV |
Terrain
Terrain of the map. Terrain at each location may be set via the SetTerrain(IGameObject) function.
Declaration
public IGridView<IGameObject?> Terrain { get; }
Property Value
Type | Description |
---|---|
IGridView<IGameObject> |
TransparencyView
IGridView<T> representing transparency values for each tile. Each location returns true if the location is transparent (there are no non-transparent objects at that location), and false otherwise.
Declaration
public IGridView<bool> TransparencyView { get; }
Property Value
Type | Description |
---|---|
IGridView<bool> |
WalkabilityView
IGridView<T> representing walkability values for each tile. Each location is true if the location is walkable (there are no non-walkable objects at that location), and false otherwise.
Declaration
public IGridView<bool> WalkabilityView { get; }
Property Value
Type | Description |
---|---|
IGridView<bool> |
Width
Width of the map, in grid spaces.
Declaration
public override int Width { get; }
Property Value
Type | Description |
---|---|
int |
Overrides
Methods
View SourceAddEntity(IGameObject)
Adds the given entity (non-terrain object) to its recorded location, removing it from the map it is currently a part of. Throws ArgumentException if the entity could not be added (eg., collision detection would not allow it, etc.)
Declaration
public void AddEntity(IGameObject entity)
Parameters
Type | Name | Description |
---|---|---|
IGameObject | entity | Entity to add. |
ApplyTerrainOverlay(IGridView<IGameObject?>)
Sets all terrain on the current map to be equal to the corresponding values from the map view you pass in.
All terrain will in the map view will be removed from its current Map, if any, and its position edited
to what it is in the overlay
, before it is added to the map.
Declaration
public void ApplyTerrainOverlay(IGridView<IGameObject?> overlay)
Parameters
Type | Name | Description |
---|---|---|
IGridView<IGameObject> | overlay | Grid view specifying the terrain apply to the map. Must have identical dimensions to the current map. |
Remarks
If translation between the overlay and IGameObject is required, see the overloads of this function that take a translation function.
ApplyTerrainOverlay<T>(IGridView<T>, Func<Point, T, IGameObject>)
Sets all terrain on the map to the result of running the given translator on the value in
overlay
at the corresponding position. Useful, for example, for applying the map view
resulting from map generation to a Map as terrain.
Declaration
public void ApplyTerrainOverlay<T>(IGridView<T> overlay, Func<Point, T, IGameObject> translator)
Parameters
Type | Name | Description |
---|---|---|
IGridView<T> | overlay | _grid view to translate. |
Func<Point, T, IGameObject> | translator | Function that translates values of the type that |
Type Parameters
Name | Description |
---|---|
T | Type of values exposed by map view to translate. Generally inferred by the compiler. |
CanAddEntity(IGameObject)
Returns true if the entity given can be added to this map at its current position; false otherwise.
Declaration
public bool CanAddEntity(IGameObject entity)
Parameters
Type | Name | Description |
---|---|---|
IGameObject | entity | The entity to add. |
Returns
Type | Description |
---|---|
bool | true if the entity given can be added to this map at its current position; false otherwise. |
CanAddEntityAt(IGameObject, Point)
Returns true if the entity given can be added to this map at the position given; false otherwise.
Declaration
public bool CanAddEntityAt(IGameObject entity, Point position)
Parameters
Type | Name | Description |
---|---|---|
IGameObject | entity | The entity to add. |
Point | position | The position to add the entity at. |
Returns
Type | Description |
---|---|
bool | true if the entity given can be added to this map at the given position; false otherwise. |
CreateMap<T>(ISettableGridView<T?>, int, Distance, Func<int, IListPool<IGameObject>>?, uint, uint, uint, IEqualityComparer<Point>?, IFOV?, AStar?, IComponentCollection?)
Effectively a helper-constructor. Constructs a map using an ISettableGridView<T> for the terrain map, where type T can be any type that implements IGameObject. Note that a Map that is constructed using this function will throw an InvalidCastException if any IGameObject is given to SetTerrain(IGameObject) that cannot be cast to type T. Also, the terrain layer given is subject to the same restrictions as noted in the corresponding map constructor.
Declaration
public static Map CreateMap<T>(ISettableGridView<T?> terrainLayer, int numberOfEntityLayers, Distance distanceMeasurement, Func<int, IListPool<IGameObject>>? customListPoolCreator = null, uint layersBlockingWalkability = 4294967295, uint layersBlockingTransparency = 4294967295, uint entityLayersSupportingMultipleItems = 4294967295, IEqualityComparer<Point>? pointComparer = null, IFOV? customPlayerFOV = null, AStar? customPather = null, IComponentCollection? customComponentContainer = null) where T : class, IGameObject
Parameters
Type | Name | Description |
---|---|---|
ISettableGridView<T> | terrainLayer | The ISettableGridView<T> that represents the terrain layer for this map. After the map has been created, you should use the SetTerrain(IGameObject) function to modify the values in this map view, rather than setting the values via the map view itself. If you re-assign the value at a location via the map view, the ObjectAdded/ObjectRemoved events are NOT guaranteed to be called, and many invariants of map may not be properly enforced. |
int | numberOfEntityLayers | Number of non-terrain layers for the map. |
Distance | distanceMeasurement | Distance measurement to use for pathfinding/measuring distance on the map. |
Func<int, IListPool<IGameObject>> | customListPoolCreator | A function used to determine the list pool implementation used for the spatial maps which support multiple items in a location (if any). The function takes the layer it is creating the pool for as a parameter. If no custom creator is specified, a ListPool is used. |
uint | layersBlockingWalkability | Layer mask containing those layers that should be allowed to have items that block walkability. Defaults to all layers. |
uint | layersBlockingTransparency | Layer mask containing those layers that should be allowed to have items that block FOV. Defaults to all layers. |
uint | entityLayersSupportingMultipleItems | Layer mask containing those layers that should be allowed to have multiple objects at the same location on the same layer. Defaults to all layers. |
IEqualityComparer<Point> | pointComparer | Equality comparer to use for comparison and hashing of points, as object are added to/removed from/moved around the map. Be especially mindful of the efficiency of its GetHashCode function, as it will determine the efficiency of many AMap functions. Defaults to a fast hashing algorithm that generates a unique integer for each point based on the width of the map. |
IFOV | customPlayerFOV | Custom FOV to use for PlayerFOV. Defaults to a GoRogue's recursive shadow-casting implementation. It may also be useful to specify this if you want the PlayerFOV property to not use TransparencyView for data. |
AStar | customPather | Custom A* pathfinder for the map. Typically, you wont' need to specify this; By default, uses WalkabilityView to determine which locations can be reached, and calculates distance based on the Distance passed to the Map in the constructor. |
IComponentCollection | customComponentContainer | A custom component container to use for GoRogueComponents. If not specified, a ComponentCollection is used. Typically you will not need to specify this, as a ComponentCollection is sufficient for nearly all use cases. |
Returns
Type | Description |
---|---|
Map | A new Map whose terrain is created using the given terrainLayer, and with the given parameters. |
Type Parameters
Name | Description |
---|---|
T | The type of terrain that will be stored in the created Map. Can be any type that implements IGameObject. |
Remarks
Suppose you have a class MyTerrain that inherits from BaseClass and implements IGameObject. This construction function allows you to construct your map using an ISettableGridView<T> instance as the terrain map, which you cannot do with the regular constructor since ISettableGridView<T> does not satisfy the constructor's type requirement of ISettableGridView<T>.
Since this function under the hood creates a SettableTranslationGridView<T1, T2> that translates to/from IGameObject as needed, any change made using the map's SetTerrain(IGameObject) function will be reflected both in the map and in the original ISettableGridView.
Note that the terrain view passed in is subject to the same restrictions as in the constructor which takes a custom terrain layer:
Always consist of persistent objects. This is to say, the layer cannot be creating objects whenever they are requested via the indexer. For example, a SettableLambdaGridView which creates a new GameObject based on some other data is NOT a valid
terrainLayer
. For this use case, ApplyTerrainOverlay<T>(IGridView<T>, Func<Point, T, IGameObject>) is recommended instead.Always have its values swapped out via SetTerrain(IGameObject) function after it is passed to this constructor, rather than via its set indexer. Basically, the terrain view must not be changed by anything other than the map after this constructor takes it.
Violating either of these conditions will create desync bugs that can leave the map in a completely unusable state. Generally, this helper-constructor should be used as a matter of last resort when there isn't a better way to accomplish your integration goals. You should probably prefer the ApplyTerrainOverlay<T>(IGridView<T>, Func<Point, T, IGameObject>) approach until/unless you have a reason not to.
GameObjectCanMove(IGameObject, Point)
Returns whether or not the given game object is allowed to move to the position specified. The object specified must be part of the map.
Declaration
public bool GameObjectCanMove(IGameObject gameObject, Point newPosition)
Parameters
Type | Name | Description |
---|---|---|
IGameObject | gameObject | Object to check. |
Point | newPosition | New position to check if the object can move to. |
Returns
Type | Description |
---|---|
bool | True if the object given can move to the given position, false otherwise. |
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if the given object is not part of this map. |
GameObjectCanSetWalkability(IGameObject, bool)
Returns whether or not the given game object is allowed to set its IsWalkable property to the given value. The object specified must be part of the map.
Declaration
public bool GameObjectCanSetWalkability(IGameObject gameObject, bool value)
Parameters
Type | Name | Description |
---|---|---|
IGameObject | gameObject | Object to check. |
bool | value | New value to check for walkability. |
Returns
Type | Description |
---|---|
bool | True if the object may set its walkability to the given value without violating collision detection; false otherwise. |
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if the given object is not part of this map. |
GetEntitiesAt<TEntity>(Point, uint)
Gets all (non-terrain) entities encountered at the given position that are castable to type EntityType, in order from the highest existing layer in the layer mask downward. Layer mask defaults to all layers.
Declaration
public MapEntitiesAtCastEnumerator<TEntity> GetEntitiesAt<TEntity>(Point position, uint layerMask = 4294967295) where TEntity : IGameObject
Parameters
Type | Name | Description |
---|---|---|
Point | position | Position to get entities for. |
uint | layerMask | Layer mask for which layers can return an object. Defaults to all layers. |
Returns
Type | Description |
---|---|
MapEntitiesAtCastEnumerator<TEntity> | All entities encountered at the given position that are castable to the given type, in order from the highest existing layer in the mask downward. |
Type Parameters
Name | Description |
---|---|
TEntity | Type of entities to return. |
Remarks
This function returns a custom iterator which is very fast when used in a foreach loop. If you need an IEnumerable to use with LINQ or other code, the returned struct does implement that interface; however note that iterating over it this way will not perform as well as iterating directly over this object.
GetEntitiesAt<TEntity>(int, int, uint)
Gets all (non-terrain) entities encountered at the given position that are castable to type EntityType, in order from the highest existing layer in the layer mask downward. Layer mask defaults to all layers.
Declaration
public MapEntitiesAtCastEnumerator<TEntity> GetEntitiesAt<TEntity>(int x, int y, uint layerMask = 4294967295) where TEntity : IGameObject
Parameters
Type | Name | Description |
---|---|---|
int | x | X-value of the position to get entities for. |
int | y | Y-value of the position to get entities for. |
uint | layerMask | Layer mask for which layers can return an object. Defaults to all layers. |
Returns
Type | Description |
---|---|
MapEntitiesAtCastEnumerator<TEntity> | All entities encountered at the given position that are castable to the given type, in order from the highest existing layer in the mask downward. |
Type Parameters
Name | Description |
---|---|
TEntity | Type of entities to return. |
Remarks
This function returns a custom iterator which is very fast when used in a foreach loop. If you need an IEnumerable to use with LINQ or other code, the returned struct does implement that interface; however note that iterating over it this way will not perform as well as iterating directly over this object.
GetEntityAt<TEntity>(Point, uint)
Gets the first (non-terrain) entity encountered at the given position that can be cast to the specified type, moving from the highest existing layer in the layer mask downward. Layer mask defaults to all layers. null is returned if no entities of the specified type are found, or if there are no entities at the location.
Declaration
public TEntity? GetEntityAt<TEntity>(Point position, uint layerMask = 4294967295) where TEntity : class, IGameObject
Parameters
Type | Name | Description |
---|---|---|
Point | position | Position to check get entity for. |
uint | layerMask | Layer mask for which layers can return an entity. Defaults to all layers. |
Returns
Type | Description |
---|---|
TEntity | The first entity encountered, moving from the highest existing layer in the layer mask downward, or null if there are no entities of the specified type are found. |
Type Parameters
Name | Description |
---|---|
TEntity | Type of entities to return. |
GetEntityAt<TEntity>(int, int, uint)
Gets the first (non-terrain) entity encountered at the given position that can be cast to the specified type, moving from the highest existing layer in the layer mask downward. Layer mask defaults to all layers. null is returned if no entities of the specified type are found, or if there are no entities at the location.
Declaration
public TEntity? GetEntityAt<TEntity>(int x, int y, uint layerMask = 4294967295) where TEntity : class, IGameObject
Parameters
Type | Name | Description |
---|---|---|
int | x | X-value of the position to get entity for. |
int | y | Y-value of the position to get entity for. |
uint | layerMask | Layer mask for which layers can return an entity. Defaults to all layers. |
Returns
Type | Description |
---|---|
TEntity | The first entity encountered, moving from the highest existing layer in the layer mask downward, or null if there are no entities of the specified type are found. |
Type Parameters
Name | Description |
---|---|
TEntity | Type of entities to return. |
GetObjectAt(Point, uint)
Gets the first object encountered at the given position, moving from the highest existing layer in the layer mask downward. Layer mask defaults to all layers.
Declaration
public IGameObject? GetObjectAt(Point position, uint layerMask = 4294967295)
Parameters
Type | Name | Description |
---|---|---|
Point | position | Position to get object for. |
uint | layerMask | Layer mask for which layers can return an object. Defaults to all layers. |
Returns
Type | Description |
---|---|
IGameObject | The first object encountered, moving from the highest existing layer in the layer mask downward. |
GetObjectAt(int, int, uint)
Gets the first object encountered at the given position that can be cast to the specified type, moving from the highest existing layer in the layer mask downward. Layer mask defaults to all layers. null is returned if no objects of the specified type are found, or if there are no objects at the location.
Declaration
public IGameObject? GetObjectAt(int x, int y, uint layerMask = 4294967295)
Parameters
Type | Name | Description |
---|---|---|
int | x | X-value of the position to get object for. |
int | y | Y-value of the position to get object for. |
uint | layerMask | Layer mask for which layers can return an object. Defaults to all layers. |
Returns
Type | Description |
---|---|
IGameObject | The first object encountered, moving from the highest existing layer in the layer mask downward. |
GetObjectAt<TObject>(Point, uint)
Gets the first object encountered at the given position that can be cast to the type specified, moving from the highest existing layer in the layer mask downward. Layer mask defaults to all layers. null is returned if no objects of the specified type are found, or if there are no objects at the location.
Declaration
public TObject? GetObjectAt<TObject>(Point position, uint layerMask = 4294967295) where TObject : class, IGameObject
Parameters
Type | Name | Description |
---|---|---|
Point | position | Position to get object for. |
uint | layerMask | Layer mask for which layers can return an object. Defaults to all layers. |
Returns
Type | Description |
---|---|
TObject | The first object encountered, moving from the highest existing layer in the layer mask downward, or null if there are no objects of the specified type are found. |
Type Parameters
Name | Description |
---|---|
TObject | Type of objects to return. |
GetObjectAt<TObject>(int, int, uint)
Gets the first object encountered at the given position that can be cast to the specified type, moving from the highest existing layer in the layer mask downward. Layer mask defaults to all layers. null is returned if no objects of the specified type are found, or if there are no objects at the location.
Declaration
public TObject? GetObjectAt<TObject>(int x, int y, uint layerMask = 4294967295) where TObject : class, IGameObject
Parameters
Type | Name | Description |
---|---|---|
int | x | X-value of the position to get object for. |
int | y | Y-value of the position to get object for. |
uint | layerMask | Layer mask for which layers can return an object. Defaults to all layers. |
Returns
Type | Description |
---|---|
TObject | The first object encountered, moving from the highest existing layer in the layer mask downward, or null if there are no objects of the specified type are found. |
Type Parameters
Name | Description |
---|---|
TObject | Type of objects to return. |
GetObjectsAt(Point, uint)
Gets all objects encountered at the given position, in order from the highest existing layer in the layer mask downward. Layer mask defaults to all layers.
Declaration
public MapObjectsAtEnumerator GetObjectsAt(Point position, uint layerMask = 4294967295)
Parameters
Type | Name | Description |
---|---|---|
Point | position | Position to get objects for. |
uint | layerMask | Layer mask for which layers can return an object. Defaults to all layers. |
Returns
Type | Description |
---|---|
MapObjectsAtEnumerator | All objects encountered at the given position, in order from the highest existing layer in the mask downward. |
Remarks
This function returns a custom iterator which is very fast when used in a foreach loop. If you need an IEnumerable to use with LINQ or other code, the returned struct does implement that interface; however note that iterating over it this way will not perform as well as iterating directly over this object.
GetObjectsAt(int, int, uint)
Gets all objects encountered at the given position, in order from the highest existing layer in the layer mask downward. Layer mask defaults to all layers.
Declaration
public MapObjectsAtEnumerator GetObjectsAt(int x, int y, uint layerMask = 4294967295)
Parameters
Type | Name | Description |
---|---|---|
int | x | X-value of the position to get objects for. |
int | y | Y-value of the position to get objects for. |
uint | layerMask | Layer mask for which layers can return an object. Defaults to all layers. |
Returns
Type | Description |
---|---|
MapObjectsAtEnumerator | All objects encountered at the given position, in order from the highest existing layer in the mask downward. |
Remarks
This function returns a custom iterator which is very fast when used in a foreach loop. If you need an IEnumerable to use with LINQ or other code, the returned struct does implement that interface; however note that iterating over it this way will not perform as well as iterating directly over this object.
GetObjectsAt<TObject>(Point, uint)
Gets all objects encountered at the given position that are castable to type ObjectType, in order from the highest existing layer in the layer mask downward. Layer mask defaults to all layers.
Declaration
public MapObjectsAtCastEnumerator<TObject> GetObjectsAt<TObject>(Point position, uint layerMask = 4294967295) where TObject : class, IGameObject
Parameters
Type | Name | Description |
---|---|---|
Point | position | Position to get objects for. |
uint | layerMask | Layer mask for which layers can return an object. Defaults to all layers. |
Returns
Type | Description |
---|---|
MapObjectsAtCastEnumerator<TObject> | All objects encountered at the given position that are castable to the given type, in order from the highest existing layer in the mask downward. |
Type Parameters
Name | Description |
---|---|
TObject | Type of objects to return. |
Remarks
This function returns a custom iterator which is very fast when used in a foreach loop. If you need an IEnumerable to use with LINQ or other code, the returned struct does implement that interface; however note that iterating over it this way will not perform as well as iterating directly over this object.
GetObjectsAt<TObject>(int, int, uint)
Gets all objects encountered at the given position that are castable to type ObjectType, in order from the highest existing layer in the layer mask downward. Layer mask defaults to all layers.
Declaration
public MapObjectsAtCastEnumerator<TObject> GetObjectsAt<TObject>(int x, int y, uint layerMask = 4294967295) where TObject : class, IGameObject
Parameters
Type | Name | Description |
---|---|---|
int | x | X-value of the position to get objects for. |
int | y | Y-value of the position to get objects for. |
uint | layerMask | Layer mask for which layers can return an object. Defaults to all layers. |
Returns
Type | Description |
---|---|
MapObjectsAtCastEnumerator<TObject> | All objects encountered at the given position that are castable to the given type, in order from the highest existing layer in the mask downward. |
Type Parameters
Name | Description |
---|---|
TObject | Type of objects to return. |
Remarks
This function returns a custom iterator which is very fast when used in a foreach loop. If you need an IEnumerable to use with LINQ or other code, the returned struct does implement that interface; however note that iterating over it this way will not perform as well as iterating directly over this object.
GetTerrainAt(Point)
Gets the terrain object at the given location, or null if no terrain is set to that location.
Declaration
public IGameObject? GetTerrainAt(Point position)
Parameters
Type | Name | Description |
---|---|---|
Point | position | The position to get the terrain for. |
Returns
Type | Description |
---|---|
IGameObject | The terrain at the given position, or null if no terrain exists at that location. |
GetTerrainAt(int, int)
Gets the terrain object at the given location, or null if no terrain is set to that location.
Declaration
public IGameObject? GetTerrainAt(int x, int y)
Parameters
Type | Name | Description |
---|---|---|
int | x | X-value of the position to get the terrain for. |
int | y | Y-value of the position to get the terrain for. |
Returns
Type | Description |
---|---|
IGameObject | The terrain at the given position, or null if no terrain exists at that location. |
GetTerrainAt<TTerrain>(Point)
Gets the terrain object at the given location, as a value of type TerrainType. Returns null if no terrain is set, or the terrain cannot be cast to the type specified.
Declaration
public TTerrain? GetTerrainAt<TTerrain>(Point position) where TTerrain : class, IGameObject
Parameters
Type | Name | Description |
---|---|---|
Point | position | The position to get the terrain for. |
Returns
Type | Description |
---|---|
TTerrain | The terrain at the given position, or null if either no terrain exists at that location or the terrain was not castable the given type. |
Type Parameters
Name | Description |
---|---|
TTerrain | Type to check for/return the terrain as. |
GetTerrainAt<TTerrain>(int, int)
Gets the terrain object at the given location, as a value of type TerrainType. Returns null if no terrain is set, or the terrain cannot be cast to the type specified.
Declaration
public TTerrain? GetTerrainAt<TTerrain>(int x, int y) where TTerrain : class, IGameObject
Parameters
Type | Name | Description |
---|---|---|
int | x | X-value of the position to get the terrain for. |
int | y | Y-value of the position to get the terrain for. |
Returns
Type | Description |
---|---|
TTerrain | The terrain at the given position, or null if either no terrain exists at that location or the terrain was
not castable to |
Type Parameters
Name | Description |
---|---|
TTerrain | Type to return the terrain as. |
RemoveEntity(IGameObject)
Removes the given entity (non-terrain object) from the map. Throws ArgumentException if the entity was not part of this map.
Declaration
public void RemoveEntity(IGameObject entity)
Parameters
Type | Name | Description |
---|---|---|
IGameObject | entity | The entity to remove from the map. |
RemoveTerrain(IGameObject)
Removes the given terrain object from the map. If the given terrain object is not a part of the map, throws ArgumentException.
Declaration
public void RemoveTerrain(IGameObject terrain)
Parameters
Type | Name | Description |
---|---|---|
IGameObject | terrain | Terrain to remove. |
RemoveTerrainAt(Point)
Removes the terrain at the given location and returns it. Throws ArgumentException if no terrain object has been added at that location.
Declaration
public IGameObject RemoveTerrainAt(Point position)
Parameters
Type | Name | Description |
---|---|---|
Point | position | Position to remove terrain from. |
Returns
Type | Description |
---|---|
IGameObject | Terrain that was at the position given. |
RemoveTerrainAt(int, int)
Removes the terrain at the given location and returns it. Throws ArgumentException if no terrain object has been added at that location.
Declaration
public IGameObject RemoveTerrainAt(int x, int y)
Parameters
Type | Name | Description |
---|---|---|
int | x | X-value of the position to remove terrain from. |
int | y | Y-value of the position to remove terrain from. |
Returns
Type | Description |
---|---|
IGameObject | Terrain that was at the position given. |
SetTerrain(IGameObject)
Sets the terrain at the given objects location to the given object, overwriting any terrain already present there.
Declaration
public void SetTerrain(IGameObject terrain)
Parameters
Type | Name | Description |
---|---|---|
IGameObject | terrain | Terrain to replace the current terrain with. |
Remarks
A GameObject that is added as Terrain must have a Layer of 0, must not be part of a map currently, and must have a position within the bounds of the map.
TryAddEntity(IGameObject)
Adds the given entity (non-terrain object) to this map, removing it from the map it is currently a part of. Returns false if the entity could not be added (eg., collision detection would not allow it, etc.); true otherwise.
Declaration
public bool TryAddEntity(IGameObject entity)
Parameters
Type | Name | Description |
---|---|---|
IGameObject | entity | Entity to add. |
Returns
Type | Description |
---|---|
bool | True if the entity was successfully added; false otherwise. |
TryAddEntityAt(IGameObject, Point)
Adds the given entity (non-terrain object) to the location specified, removing it from the map it is currently a part of. Returns false if the entity could not be added (eg., collision detection would not allow it, etc.); true otherwise.
Declaration
public bool TryAddEntityAt(IGameObject entity, Point position)
Parameters
Type | Name | Description |
---|---|---|
IGameObject | entity | Entity to add. |
Point | position | Location to add the entity to. |
Returns
Type | Description |
---|---|
bool | True if the entity was successfully added to the location specified; false otherwise. |
Remarks
The entity's Position property will be set to the location specified before it is added, but only if the function returns true. No changes will have been made to the entity if the function returns false; that is; you may assume that Moved events will not have fired, the entity will not have been removed from any map it is already a part of, etc.
TryRemoveEntity(IGameObject)
Removes the given entity (non-terrain object) from the map. Does nothing and returns false if the entity was not part of this map; returns true and removes it otherwise.
Declaration
public bool TryRemoveEntity(IGameObject entity)
Parameters
Type | Name | Description |
---|---|---|
IGameObject | entity | The entity to remove from the map. |
Returns
Type | Description |
---|---|
bool | True if the given entity was removed from the map; false otherwise (eg the entity given was not in the map). |
Events
View SourceObjectAdded
Event that is fired whenever some object is added to the map.
Declaration
public event EventHandler<ItemEventArgs<IGameObject>>? ObjectAdded
Event Type
Type | Description |
---|---|
EventHandler<ItemEventArgs<IGameObject>> |
ObjectMoved
Event that is fired whenever some object that is part of the map is successfully moved.
Declaration
public event EventHandler<ItemMovedEventArgs<IGameObject>>? ObjectMoved
Event Type
Type | Description |
---|---|
EventHandler<ItemMovedEventArgs<IGameObject>> |
ObjectRemoved
Event that is fired whenever some object is removed from the map.
Declaration
public event EventHandler<ItemEventArgs<IGameObject>>? ObjectRemoved
Event Type
Type | Description |
---|---|
EventHandler<ItemEventArgs<IGameObject>> |