A Scriptable Runtime Service implementing a mini-database of occupied positions on Tilemaps. More...

Inheritance diagram for TilePlus.TpTilePositionDb:

[legend]

Collaboration diagram for TilePlus.TpTilePositionDb:

[legend]

Public Member Functions
bool	AddMapsToMonitor (IEnumerable< Tilemap > maps, int size=32)
	Add several Tilemaps to monitor using Tilemap references.
bool	AddMapToMonitor (Tilemap map, int size=32)
	Add a Tilemap to monitor.
override void	OnEnable ()
	OnEnable handler.
override void	OnDisable ()
	OnDisable handler.
bool	GetAllBoundsForMap (int mapIid, List<(BoundsInt, bool)> output)
	Get a list of all BoundsInts for a map. Can be slow - recommend editor-only!
bool	AddPosition (Tilemap? map, Vector3Int position)
	Add a position to a map's position DB using a Tilemap reference.
void	RemovePosition (Tilemap map, Vector3Int position)
	Remove a position from a map's position Db.
void	ForceUpdate ()
	Force an Update to any cached oversized sprites.
bool	IsThisMapMonitored (int mapId)
	Is the Tilemap with a given InstanceId being monitored?
bool	IsThisMapMonitored (Tilemap map)
	Is the Tilemap being monitored. Convenience overload.
override string	Status ()
	A status string for TpSysInfo.
void	Merge (HashSet< int > mapIds, HashSet< Vector3Int > output, bool clearOutput=true)
	Merge selected tilemap position-occupied data into one HashSet.
bool	IsPathBlocked4Way (int mapIid, Vector3Int position, TpTileUtils.DirectionType4 direction, uint distance=1)
	Path testing with Single-Tilemap support. Test for 'position occupied' over several grid positions in a specific direction.
bool	IsPathBlocked4Way (int[] mapIids, Vector3Int position, TpTileUtils.DirectionType4 direction, uint distance=1)
	Path testing with Multiple-Tilemap support. Test for 'position occupied' over several grid positions in a specific direction.
bool	IsPathBlocked8Way (int mapIid, Vector3Int position, TpTileUtils.DirectionType8 direction, uint distance=1)
	Path testing with Single-Tilemap support. Test for 'position occupied' over several grid positions in a specific direction.
bool	IsPathBlocked8Way (int[] mapIids, Vector3Int position, TpTileUtils.DirectionType8 direction, uint distance=1)
	Path testing with Multiple-Tilemap support. Test for 'position occupied' over several grid positions in a specific direction.
bool	PositionOccupied (int[] mapIids, Vector3Int position, Vector3Int? ignoreThisPosition=null)
	Is a position occupied on multiple maps using Tilemap Iids?
bool	PositionOccupied (int mapIid, Vector3Int position, out Bounds scaledSpriteBounds, out Vector3Int tilePosition, Vector3Int? ignoreThisPosition=null, bool ignoreScaledSprites=false)
	Is a position occupied on a single map?
bool	PositionOccupiedForWorldCoordinates (Tilemap map, Vector3Int gridPosition, Vector2 position, out Bounds scaledSpriteBounds, out Vector3Int tilePosition)
	Is a position occupied on a single map? Uses Vector2 position: suited for cases where the position may not be a grid position, i.e., the mouse world position (screen coords = NO).
Public Member Functions inherited from TilePlus.ScriptableRuntimeService< T >
virtual bool	CanPollForDetails ()
	Used by SRS inspector. If the contents of an SRS change frequently then this should be overridden to return true.
virtual string	Details (int length=-1)
	The SRS inspector utility will show whatever this returns.
override string	ToString ()
	Customize ToString in overrides.
Public Member Functions inherited from TilePlus.IScriptableService
void	MessageTarget (ObjectPacket packet)
	If Accepts messages is true, reimplement this to get messaged.

Properties
bool	Initialized `[get]`
	True after this component's OnEnable() has run and Tilemap callbacks initialized.
IEnumerable< string >	MonitoredTilemapNames `[get]`
	Get an IEnumerable of all Tilemap names monitored in this instance. Note that a name isn't entered into the list of names until the Tilemap callback does it.
IEnumerable< int >	InstanceIds `[get]`
	Get an IEnumerable of all Tilemap IIDs set by AddMapsToMonitor.
float	MinPositionOffset = 0.1f `[get, set]`
	This value determines the minimum position shift for special handling. Note that the sprite transform is also used so this isn't the only factor.
float	MinScaleOffset `[get, set]`
	This value determines the minimum transform size change > 1,1 for special handling. Note that the sprite position is also used so this isn't the only factor.
int	PosDbRefreshPerUpdate `[get, set]`
	Number of PosDb updates per-update. Default is unlimited.
int	PendingUpdates `[get]`
	A count of pending updates.
int	TileDbSize `[get]`
	Size of the TileDb Dict.
Properties inherited from TilePlus.ScriptableRuntimeService< T >
string	ServiceName `[get]`
	A name for this service: used for profiling. Ordinarily just returns the 'name' property of the Service S.O. instance.
Properties inherited from TilePlus.IScriptableService
bool	PeristThruReload `[get]`
	If true, this will not be deleted when the Unity scene changes.
string[]	AcceptableMessages `[get]`
	If true, can accept ObjectPacket messages from the Service Manager with command-strings matching those returned here.

Additional Inherited Members
Static Protected Member Functions inherited from TilePlus.ScriptableRuntimeService< T >
static void	Create ()
	Create and initialize method.

Detailed Description

A Scriptable Runtime Service implementing a mini-database of occupied positions on Tilemaps.

IMPORTANT NOTES:

There's no 'Reset' for this. To perform a reset, kill the service and restart it.

Merge mode is optional and not used by any demos (at the time of this writing).

Either use the initializer param of GetServiceOfType or use the returned PositionDb does NOT check for deleted tilemaps. If you change Unity scenes, kill and restart this service.

PositionDb is intended for use with the 'Chunking'/Layout mode of TilePlus Toolkit, although there's no restriction on other uses..

Specifically: TileFabLib, TpZoneManager, and TpZoneLayout. Using the Chunking system ensures that even if you have a huge tilemap only the parts of it within the camera view (plus optional padding) are loaded into the Tilemap.

Hence, the HashSets in this SO never get that large. HOWEVER, this assumes that you do not use this subsystem to monitor dense maps such as a 'floor' or 'ground' tilemap where almost all positions are filled. One should use colliders or some other approach for dense maps.

Sparse tilemaps make sense to use with this SO, so roads, obstacles etc.

Tiles are added and deleted from the data structures in this SRS by the OntilemapTileChanged callback (from Tilemap).

Any tiles which are on the specified Tilemaps are added or deleted from a HashSet. But that only covers one single position. If you have sprites with sprites that are offset by the transform-position of the tile sprite then that doesn't work.

Scaled or position-shifted sprites are handled automatically.

** note that this service CANNOT deal with rotated sprites ** ** Scaled: OK ** Translated: OK ** Rotated: not handled, may intermittently work due to happenstance.

Since evaluating scaled sprites involves some computation and Tilemap access (to get the actual sprite transform) these are cached and evalutated when this SRS is updated. That occurs at EndOfFrame (using the Awaitable pump) or at PostLateUpdate when using the PlayerLoop pump.

Note that TileBase tiles like Rule Tile and AnimatedTile cannot have scaled or position-shifted sprites since these tiles don't have a transform. They appear at their actual Tilemap position only. However, this isn't much of a limitation: use TpAnimatedTile or TpFlexAnimatedTile; and Rule Tiles (this one assumes) never have enlarged sprites.

How to use: Create an instance when initializing the ZoneManager part of the Layout system. This can be seen in the Chunking Demo. Or you can create an instance directly using ScriptableObject.CreateInstance. The instance is a SRS or Scriptable Runtime Servce. When using the layout system you handle initialization via a callback (see Chunking Demo). Otherwise you use AddMapsToMonitor (several overloads). After initialization the only way to completely change the setup is to use the .ResetPositionDb method.

Once initialized, when a tile is added or deleted the internal HashSets are updated.

Use PositionOccupied() to test if there's a tile at a position.

When done properly, this approach is WAY faster then testing all possible tilemaps which could be blocking the player, especially for certain games where each move requires many tests. And faster than raycasts (tested a long time ago). There are also NO transitions to C++ code when testing positions.

Member Function Documentation

◆ AddMapsToMonitor()

bool TilePlus.TpTilePositionDb.AddMapsToMonitor	(	IEnumerable< Tilemap >	maps,
		int	size = 32 )

Add several Tilemaps to monitor using Tilemap references.

Parameters

maps	IEnumerable of (map,merge).
size	initial HashSet size

If 'merge' is true then a merge dictionary entry is added. see docs for what this means.

Returns

◆ AddMapToMonitor()

bool TilePlus.TpTilePositionDb.AddMapToMonitor	(	Tilemap	map,
		int	size = 32 )

Add a Tilemap to monitor.

Parameters

map	map instance
size	initial HashSet size

Returns: false if inpuit map is null

◆ AddPosition()

bool TilePlus.TpTilePositionDb.AddPosition	(	Tilemap?	map,
		Vector3Int	position )

Add a position to a map's position DB using a Tilemap reference.

Parameters

map	map
position	position

Returns: false for error

This and RemovePosition are for use when your game adds/deletes tiles in a way that conflicts with the automatic handling provided by the OntilemapTileChanged callback. For example, if you make a tile invisible by setting it to null or setting its alpha to 0 - that won't remove it from the set of positions, which may not be what you want. See RemovePosition

NOTE THAT while the position is added to the non-enlarged set (s_TileDb) the add to s_MapPosToRectInt (ie for enlarged sprites) is done at the next call to PosDbUpdate from TpLib task module. This can also be affected by the PosDbRefreshPerUpdate value.

◆ ForceUpdate()

void TilePlus.TpTilePositionDb.ForceUpdate ( )

Force an Update to any cached oversized sprites.

◆ GetAllBoundsForMap()

bool TilePlus.TpTilePositionDb.GetAllBoundsForMap	(	int	mapIid,
		List<(BoundsInt, bool)>	output )

Get a list of all BoundsInts for a map. Can be slow - recommend editor-only!

Parameters

mapIid	Instance ID of tilemap
output	list of (BoundsInt,bool) where the bool is true for enlarged sprites.

Returns: false if map isn't monitored

◆ IsPathBlocked4Way() [1/2]

bool TilePlus.TpTilePositionDb.IsPathBlocked4Way	(	int	mapIid,
		Vector3Int	position,
		TpTileUtils.DirectionType4	direction,
		uint	distance = 1 )

Path testing with Single-Tilemap support. Test for 'position occupied' over several grid positions in a specific direction.

Parameters

mapIid	tilemap Instance Id
position	starting Grid position
direction	A TpTileUtils.DirectionType4 enum value
distance	# of positions to look-ahead

Returns: true if there are any occupied positions in a path starting at 'position' and extending 'distance' grid positions and false if the path is clear.

the location 'position' is not examined for 'position occupied'

◆ IsPathBlocked4Way() [2/2]

bool TilePlus.TpTilePositionDb.IsPathBlocked4Way	(	int[]	mapIids,
		Vector3Int	position,
		TpTileUtils.DirectionType4	direction,
		uint	distance = 1 )

Path testing with Multiple-Tilemap support. Test for 'position occupied' over several grid positions in a specific direction.

Parameters

mapIids	array of Tilemap instance IDs
position	starting Grid position
direction	A TpTileUtils.DirectionType4 enum value
distance	# of positions to look-ahead

Returns: true if there are any occupied positions in a path starting at 'position' and extending 'distance' grid positions and false if the path is clear.

the location 'position' is not examined for 'position occupied'

◆ IsPathBlocked8Way() [1/2]

bool TilePlus.TpTilePositionDb.IsPathBlocked8Way	(	int	mapIid,
		Vector3Int	position,
		TpTileUtils.DirectionType8	direction,
		uint	distance = 1 )

Path testing with Single-Tilemap support. Test for 'position occupied' over several grid positions in a specific direction.

Parameters

mapIid	tilemap Instance Id
position	starting Grid position
direction	A TpTileUtils.DirectionType8 enum value
distance	# of positions to look-ahead

Returns: true if there are any occupied positions in a path starting at 'position' and extending 'distance' grid positions and false if the path is clear.

the location 'position' is not examined for 'position occupied'

◆ IsPathBlocked8Way() [2/2]

bool TilePlus.TpTilePositionDb.IsPathBlocked8Way	(	int[]	mapIids,
		Vector3Int	position,
		TpTileUtils.DirectionType8	direction,
		uint	distance = 1 )

Path testing with Multiple-Tilemap support. Test for 'position occupied' over several grid positions in a specific direction.

Parameters

mapIids	array of Tilemap instance IDs
position	starting Grid position
direction	A TpTileUtils.DirectionType4 enum value
distance	# of positions to look-ahead

Returns: true if there are any occupied positions in a path starting at 'position' and extending 'distance' grid positions and false if the path is clear.

the location 'position' is not examined for 'position occupied'

◆ IsThisMapMonitored() [1/2]

bool TilePlus.TpTilePositionDb.IsThisMapMonitored ( int mapId )

Is the Tilemap with a given InstanceId being monitored?

Parameters

mapId Tilemap instance ID

Returns: true if this map is being monitored.

◆ IsThisMapMonitored() [2/2]

bool TilePlus.TpTilePositionDb.IsThisMapMonitored ( Tilemap map )

Is the Tilemap being monitored. Convenience overload.

Parameters

map Tilemap

Returns: true if this map is being monitored.

◆ Merge()

void TilePlus.TpTilePositionDb.Merge	(	HashSet< int >	mapIds,
		HashSet< Vector3Int >	output,
		bool	clearOutput = true )

Merge selected tilemap position-occupied data into one HashSet.

Parameters

mapIds	HashSet of mapIds as input
output	HashSet for position info as output.
clearOutput	if true, clears the output HashSet

This can be slow. Not intended to use every Monobehaviour Update.

◆ OnDisable()

override void TilePlus.TpTilePositionDb.OnDisable ( )

virtual

OnDisable handler.

Reimplemented from TilePlus.ScriptableRuntimeService< T >.

◆ OnEnable()

override void TilePlus.TpTilePositionDb.OnEnable ( )

virtual

OnEnable handler.

Reimplemented from TilePlus.ScriptableRuntimeService< T >.

◆ PositionOccupied() [1/2]

bool TilePlus.TpTilePositionDb.PositionOccupied	(	int	mapIid,
		Vector3Int	position,
		out Bounds	scaledSpriteBounds,
		out Vector3Int	tilePosition,
		Vector3Int?	ignoreThisPosition = null,
		bool	ignoreScaledSprites = false )

Is a position occupied on a single map?

Parameters

mapIid	Tilemap instance ID
position	position to test
scaledSpriteBounds	If what was found was a scaled sprite here's its Rect. If not, this will always be an empty Rect.
tilePosition	If what was found was a scaled sprite then this is the position of the parent tile (may not be the same value as the input param 'position').
ignoreThisPosition	OPTIONAL: exclude this position. Typically the tile you're searching from.
ignoreScaledSprites	OPTIONAL: ignore scaled sprites.

Returns: true if position occupied. May return false for some errors.

This is the only method using Tilemap coordinates (ie not world coords) that supports returning the found RectInt for a scaled sprite. If nothing is found or not handling scaled sprites an empty RectInt (pos,size both zero) is returned. If ignoreThisPosition has value then when examining scaled sprites, this particular position is ignored/rejected. That's useful if two (adjacent or not) tiles have sprites which overlap the tile you're searching from.

◆ PositionOccupied() [2/2]

bool TilePlus.TpTilePositionDb.PositionOccupied	(	int[]	mapIids,
		Vector3Int	position,
		Vector3Int?	ignoreThisPosition = null )

Is a position occupied on multiple maps using Tilemap Iids?

Parameters

mapIids	instance IDs of maps
position	position to test
ignoreThisPosition	OPTIONAL: exclude this position. Typically the tile you're searching from.

Returns: true if a match

◆ PositionOccupiedForWorldCoordinates()

bool TilePlus.TpTilePositionDb.PositionOccupiedForWorldCoordinates	(	Tilemap	map,
		Vector3Int	gridPosition,
		Vector2	position,
		out Bounds	scaledSpriteBounds,
		out Vector3Int	tilePosition )

Is a position occupied on a single map? Uses Vector2 position: suited for cases where the position may not be a grid position, i.e., the mouse world position (screen coords = NO).

Parameters

map	Tilemap instance
gridPosition	Tilemap grid position
position	position to test
scaledSpriteBounds	If what was found was a scaled sprite here's its Rect. If not, this will always be an empty Rect.
tilePosition	If what was found was a scaled sprite then this is the position of the parent tile (may not be the same value as the input param 'position').

Returns: true if position occupied. May return false for some errors.

◆ RemovePosition()

void TilePlus.TpTilePositionDb.RemovePosition	(	Tilemap	map,
		Vector3Int	position )

Remove a position from a map's position Db.

Parameters

map	map
position	position

AddPosition Note: map name not removed from mapNames HashSet

◆ Status()

override string TilePlus.TpTilePositionDb.Status ( )

virtual

A status string for TpSysInfo.

Reimplemented from TilePlus.ScriptableRuntimeService< T >.

Property Documentation

◆ Initialized

bool TilePlus.TpTilePositionDb.Initialized

get

True after this component's OnEnable() has run and Tilemap callbacks initialized.

◆ InstanceIds

IEnumerable<int> TilePlus.TpTilePositionDb.InstanceIds

get

Get an IEnumerable of all Tilemap IIDs set by AddMapsToMonitor.

◆ MinPositionOffset

float TilePlus.TpTilePositionDb.MinPositionOffset = 0.1f

getset

This value determines the minimum position shift for special handling. Note that the sprite transform is also used so this isn't the only factor.

◆ MinScaleOffset

float TilePlus.TpTilePositionDb.MinScaleOffset

getset

This value determines the minimum transform size change > 1,1 for special handling. Note that the sprite position is also used so this isn't the only factor.

Values <1 are ignored.

◆ MonitoredTilemapNames

IEnumerable<string> TilePlus.TpTilePositionDb.MonitoredTilemapNames

get

Get an IEnumerable of all Tilemap names monitored in this instance. Note that a name isn't entered into the list of names until the Tilemap callback does it.

◆ PendingUpdates

int TilePlus.TpTilePositionDb.PendingUpdates

get

A count of pending updates.

◆ PosDbRefreshPerUpdate

int TilePlus.TpTilePositionDb.PosDbRefreshPerUpdate

getset

Number of PosDb updates per-update. Default is unlimited.

◆ TileDbSize

int TilePlus.TpTilePositionDb.TileDbSize

get

Size of the TileDb Dict.

The documentation for this class was generated from the following file:

/Users/jms/Documents/Tpt_55/TPT55/Assets/Plugins/TilePlus/Runtime/Services/TpTilePositionDb.cs

Public Member Functions

Properties

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ AddMapsToMonitor()

◆ AddMapToMonitor()

◆ AddPosition()

◆ ForceUpdate()

◆ GetAllBoundsForMap()

◆ IsPathBlocked4Way() [1/2]

◆ IsPathBlocked4Way() [2/2]

◆ IsPathBlocked8Way() [1/2]

◆ IsPathBlocked8Way() [2/2]

◆ IsThisMapMonitored() [1/2]

◆ IsThisMapMonitored() [2/2]

◆ Merge()

◆ OnDisable()

◆ OnEnable()

◆ PositionOccupied() [1/2]

◆ PositionOccupied() [2/2]

◆ PositionOccupiedForWorldCoordinates()

◆ RemovePosition()

◆ Status()

Property Documentation

◆ Initialized

◆ InstanceIds

◆ MinPositionOffset

◆ MinScaleOffset

◆ MonitoredTilemapNames

◆ PendingUpdates

◆ PosDbRefreshPerUpdate

◆ TileDbSize