ICmpRangeManager Class Reference

Provides efficient range-based queries of the game world, and also LOS-based effects (fog of war). More...

#include <ICmpRangeManager.h>

Inheritance diagram for ICmpRangeManager:

Collaboration diagram for ICmpRangeManager:

Public Types
typedef u32	tag_t
	External identifiers for active queries. More...
Public Types inherited from IComponent
using	AllocFunc = IComponent *(*)(const ScriptInterface &scriptInterface, JS::HandleValue ctor)
using	DeallocFunc = void(*)(IComponent *)

Public Member Functions
virtual FastSpatialSubdivision *	GetSubdivision ()=0
	Access the spatial subdivision kept by the range manager. More...
virtual void	SetBounds (entity_pos_t x0, entity_pos_t z0, entity_pos_t x1, entity_pos_t z1)=0
	Set the bounds of the world. More...
virtual std::vector< entity_id_t >	ExecuteQuery (entity_id_t source, entity_pos_t minRange, entity_pos_t maxRange, const std::vector< int > &owners, int requiredInterface, bool accountForSize)=0
	Execute a passive query. More...
virtual std::vector< entity_id_t >	ExecuteQueryAroundPos (const CFixedVector2D &pos, entity_pos_t minRange, entity_pos_t maxRange, const std::vector< int > &owners, int requiredInterface, bool accountForSize)=0
	Execute a passive query. More...
virtual tag_t	CreateActiveQuery (entity_id_t source, entity_pos_t minRange, entity_pos_t maxRange, const std::vector< int > &owners, int requiredInterface, u8 flags, bool accountForSize)=0
	Construct an active query. More...
virtual tag_t	CreateActiveParabolicQuery (entity_id_t source, entity_pos_t minRange, entity_pos_t maxRange, entity_pos_t yOrigin, const std::vector< int > &owners, int requiredInterface, u8 flags)=0
	Construct an active query of a paraboloic form around the unit. More...
virtual entity_pos_t	GetEffectiveParabolicRange (entity_id_t source, entity_id_t target, entity_pos_t range, entity_pos_t yOrigin) const =0
	Get the effective range in a parablic range query. More...
virtual entity_pos_t	GetElevationAdaptedRange (const CFixedVector3D &pos, const CFixedVector3D &rot, entity_pos_t range, entity_pos_t yOrigin, entity_pos_t angle) const =0
	Get the average elevation over 8 points on distance range around the entity. More...
virtual void	DestroyActiveQuery (tag_t tag)=0
	Destroy a query and clean up resources. More...
virtual void	EnableActiveQuery (tag_t tag)=0
	Re-enable the processing of a query. More...
virtual void	DisableActiveQuery (tag_t tag)=0
	Disable the processing of a query (no RangeUpdate messages will be sent). More...
virtual bool	IsActiveQueryEnabled (tag_t tag) const =0
	Check if the processing of a query is enabled. More...
virtual std::vector< entity_id_t >	ResetActiveQuery (tag_t tag)=0
	Immediately execute a query, and re-enable it if disabled. More...
virtual std::vector< entity_id_t >	GetEntitiesByPlayer (player_id_t player) const =0
	Returns a list of all entities for a specific player. More...
virtual std::vector< entity_id_t >	GetNonGaiaEntities () const =0
	Returns a list of all entities of all players except gaia. More...
virtual std::vector< entity_id_t >	GetGaiaAndNonGaiaEntities () const =0
	Returns a list of all entities owned by a player or gaia. More...
virtual void	SetDebugOverlay (bool enabled)=0
	Toggle the rendering of debug info. More...
virtual u8	GetEntityFlagMask (const std::string &identifier) const =0
	Returns the mask for the specified identifier. More...
virtual void	SetEntityFlag (entity_id_t ent, const std::string &identifier, bool value)=0
	Set the flag specified by the identifier to the supplied value for the entity. More...
virtual CLosQuerier	GetLosQuerier (player_id_t player) const =0
	Returns a CLosQuerier for checking whether vertex positions are visible to the given player (or other players it shares LOS with). More...
virtual void	ActivateScriptedVisibility (entity_id_t ent, bool status)=0
	Toggle the scripted Visibility component activation for entity ent. More...
virtual LosVisibility	GetLosVisibility (CEntityHandle ent, player_id_t player) const =0
	Returns the visibility status of the given entity, with respect to the given player. More...
virtual LosVisibility	GetLosVisibility (entity_id_t ent, player_id_t player) const =0
virtual LosVisibility	GetLosVisibilityPosition (entity_pos_t x, entity_pos_t z, player_id_t player) const =0
	Returns the visibility status of the given position, with respect to the given player. More...
virtual void	RequestVisibilityUpdate (entity_id_t ent)=0
	Request the update of the visibility cache of ent at next turn. More...
std::string	GetLosVisibility_wrapper (entity_id_t ent, player_id_t player) const
	GetLosVisibility wrapped for script calls. More...
std::string	GetLosVisibilityPosition_wrapper (entity_pos_t x, entity_pos_t z, player_id_t player) const
	GetLosVisibilityPosition wrapped for script calls. More...
virtual void	ExploreMap (player_id_t p)=0
	Explore the map (but leave it in the FoW) for player p. More...
virtual void	ExploreTerritories ()=0
	Explore the tiles inside each player's territory. More...
virtual void	RevealShore (player_id_t p, bool enable)=0
	Reveal the shore for specified player p. More...
virtual void	SetLosRevealAll (player_id_t player, bool enabled)=0
	Set whether the whole map should be made visible to the given player. More...
virtual bool	GetLosRevealAll (player_id_t player) const =0
	Returns whether the whole map has been made visible to the given player. More...
virtual void	SetLosCircular (bool enabled)=0
	Set the LOS to be restricted to a circular map. More...
virtual bool	GetLosCircular () const =0
	Returns whether the LOS is restricted to a circular map. More...
virtual void	SetSharedLos (player_id_t player, const std::vector< player_id_t > &players)=0
	Sets shared LOS data for player to the given list of players. More...
virtual u32	GetSharedLosMask (player_id_t player) const =0
	Returns shared LOS mask for player. More...
virtual u8	GetPercentMapExplored (player_id_t player) const =0
	Get percent map explored statistics for specified player. More...
virtual u8	GetUnionPercentMapExplored (const std::vector< player_id_t > &players) const =0
	Get percent map explored statistics for specified set of players. More...
virtual size_t	GetVerticesPerSide () const =0
virtual void	Verify ()=0
	Perform some internal consistency checks for testing/debugging. More...
Public Member Functions inherited from IComponent
virtual	~IComponent ()
virtual void	Init (const CParamNode &paramNode)=0
virtual void	Deinit ()=0
virtual void	HandleMessage (const CMessage &msg, bool global)
CEntityHandle	GetEntityHandle () const
void	SetEntityHandle (CEntityHandle ent)
entity_id_t	GetEntityId () const
CEntityHandle	GetSystemEntity () const
const CSimContext &	GetSimContext () const
void	SetSimContext (const CSimContext &context)
virtual void	Serialize (ISerializer &serialize)=0
virtual void	Deserialize (const CParamNode &paramNode, IDeserializer &deserialize)=0
virtual bool	NewJSObject (const ScriptInterface &scriptInterface, JS::MutableHandleObject out) const
	Returns false by default, indicating that a scripted wrapper of this IComponent is not supported. More...
virtual JS::Value	GetJSInstance () const
virtual int	GetComponentTypeId () const =0

Additional Inherited Members
Static Public Member Functions inherited from IComponent
static std::string	GetSchema ()
static void	RegisterComponentType (CComponentManager &mgr, EInterfaceId iid, EComponentTypeId cid, AllocFunc alloc, DeallocFunc dealloc, const char *name, const std::string &schema)
static void	RegisterComponentTypeScriptWrapper (CComponentManager &mgr, EInterfaceId iid, EComponentTypeId cid, AllocFunc alloc, DeallocFunc dealloc, const char *name, const std::string &schema)
static u8	GetSerializationVersion ()

Detailed Description

Provides efficient range-based queries of the game world, and also LOS-based effects (fog of war).

(These are somewhat distinct concepts but they share a lot of the implementation, so for efficiency they're combined into this class.)

Possible use cases:

• combat units need to detect targetable enemies entering LOS, so they can choose to auto-attack.
• auras let a unit have some effect on all units (or those of the same player, or of enemies) within a certain range.
• capturable animals need to detect when a player-owned unit is nearby and no units of other players are in range.
• scenario triggers may want to detect when units enter a given area.
• units gathering from a resource that is exhausted need to find a new resource of the same type, near the old one and reachable.
• projectile weapons with splash damage need to find all units within some distance of the target point.
• ...

In most cases the users are event-based and want notifications when something has entered or left the range, and the query can be set up once and rarely changed. These queries have to be fast. Entities are approximated as points or circles (queries can be set up to ignore sizes because LOS currently ignores it, and mismatches are problematic).

Current design:

This class handles just the most common parts of range queries: distance, target interface, and player ownership. The caller can then apply any more complex filtering that it needs.

There are two types of query: Passive queries are performed by ExecuteQuery and immediately return the matching entities. Active queries are set up by CreateActiveQuery, and then a CMessageRangeUpdate message will be sent to the entity once per turn if anybody has entered or left the range since the last RangeUpdate. Queries can be disabled, in which case no message will be sent.

Member Typedef Documentation

tag_t

typedef u32 ICmpRangeManager::tag_t

External identifiers for active queries.

Member Function Documentation

ActivateScriptedVisibility()

virtual void ICmpRangeManager::ActivateScriptedVisibility ( entity_id_t  ent, bool  status  )

pure virtual

Toggle the scripted Visibility component activation for entity ent.

Implemented in CCmpRangeManager.

CreateActiveParabolicQuery()

virtual tag_t ICmpRangeManager::CreateActiveParabolicQuery ( entity_id_t  source, entity_pos_t  minRange, entity_pos_t  maxRange, entity_pos_t  yOrigin, const std::vector< int > &  owners, int  requiredInterface, u8  flags  )

pure virtual

Construct an active query of a paraboloic form around the unit.

The query will be disabled by default.

Parameters

source	the entity around which the range will be computed.
minRange	non-negative minimum horizontal distance in metres (inclusive). MinRange doesn't do parabolic checks.
maxRange	non-negative maximum distance in metres (inclusive) for units on the same elevation; or -1.0 to ignore distance. For units on a different height positions, a physical correct paraboloid with height=maxRange/2 above the unit is used to query them
yOrigin	extra bonus so the source can be placed higher and shoot further
owners	list of player IDs that matching entities may have; -1 matches entities with no owner.
requiredInterface	if non-zero, an interface ID that matching entities must implement.
flags	if a entity in range has one of the flags set it will show up. NB: this one has no accountForSize parameter (assumed true), because we currently can only have 7 arguments for JS functions.

Returns

unique non-zero identifier of query.

Implemented in CCmpRangeManager.

CreateActiveQuery()

virtual tag_t ICmpRangeManager::CreateActiveQuery ( entity_id_t  source, entity_pos_t  minRange, entity_pos_t  maxRange, const std::vector< int > &  owners, int  requiredInterface, u8  flags, bool  accountForSize  )

pure virtual

Construct an active query.

The query will be disabled by default.

Parameters

source	the entity around which the range will be computed.
minRange	non-negative minimum distance in metres (inclusive).
maxRange	non-negative maximum distance in metres (inclusive); or -1.0 to ignore distance.
owners	list of player IDs that matching entities may have; -1 matches entities with no owner.
requiredInterface	if non-zero, an interface ID that matching entities must implement.
flags	if a entity in range has one of the flags set it will show up.
accountForSize	if true, compensate for source/target entity sizes.

Returns

unique non-zero identifier of query.

Implemented in CCmpRangeManager.

DestroyActiveQuery()

virtual void ICmpRangeManager::DestroyActiveQuery ( tag_t  tag )

pure virtual

Destroy a query and clean up resources.

This must be called when an entity no longer needs its query (e.g. when the entity is destroyed).

Parameters

tag	identifier of query.

Implemented in CCmpRangeManager.

DisableActiveQuery()

virtual void ICmpRangeManager::DisableActiveQuery ( tag_t  tag )

pure virtual

Disable the processing of a query (no RangeUpdate messages will be sent).

Parameters

tag	identifier of query.

Implemented in CCmpRangeManager.

EnableActiveQuery()

virtual void ICmpRangeManager::EnableActiveQuery ( tag_t  tag )

pure virtual

Re-enable the processing of a query.

Parameters

tag	identifier of query.

Implemented in CCmpRangeManager.

ExecuteQuery()

virtual std::vector< entity_id_t > ICmpRangeManager::ExecuteQuery ( entity_id_t  source, entity_pos_t  minRange, entity_pos_t  maxRange, const std::vector< int > &  owners, int  requiredInterface, bool  accountForSize  )

pure virtual

Execute a passive query.

Parameters

source	the entity around which the range will be computed.
minRange	non-negative minimum distance in metres (inclusive).
maxRange	non-negative maximum distance in metres (inclusive); or -1.0 to ignore distance.
owners	list of player IDs that matching entities may have; -1 matches entities with no owner.
requiredInterface	if non-zero, an interface ID that matching entities must implement.
accountForSize	if true, compensate for source/target entity sizes.

Returns

list of entities matching the query, ordered by increasing distance from the source entity.

Implemented in CCmpRangeManager.

ExecuteQueryAroundPos()

virtual std::vector< entity_id_t > ICmpRangeManager::ExecuteQueryAroundPos ( const CFixedVector2D &  pos, entity_pos_t  minRange, entity_pos_t  maxRange, const std::vector< int > &  owners, int  requiredInterface, bool  accountForSize  )

pure virtual

Execute a passive query.

Parameters

pos	the position around which the range will be computed.
minRange	non-negative minimum distance in metres (inclusive).
maxRange	non-negative maximum distance in metres (inclusive); or -1.0 to ignore distance.
owners	list of player IDs that matching entities may have; -1 matches entities with no owner.
requiredInterface	if non-zero, an interface ID that matching entities must implement.
accountForSize	if true, compensate for source/target entity sizes.

Returns

list of entities matching the query, ordered by increasing distance from the source entity.

Implemented in CCmpRangeManager.

ExploreMap()

virtual void ICmpRangeManager::ExploreMap ( player_id_t  p )

pure virtual

Explore the map (but leave it in the FoW) for player p.

Implemented in CCmpRangeManager.

ExploreTerritories()

virtual void ICmpRangeManager::ExploreTerritories ( )

pure virtual

Explore the tiles inside each player's territory.

This is done only at the beginning of the game.

Implemented in CCmpRangeManager.

GetEffectiveParabolicRange()

virtual entity_pos_t ICmpRangeManager::GetEffectiveParabolicRange ( entity_id_t  source, entity_id_t  target, entity_pos_t  range, entity_pos_t  yOrigin  ) const

pure virtual

Get the effective range in a parablic range query.

Parameters

source	The entity id at the origin of the query.
target	A target entity id.
range	The distance to compare terrain height with.
yOrigin	Height the source gains over the target by default.

Returns

a fixed number representing the effective range correcting parabolicly for the height difference. Returns -1 when the target is too high compared to the source to be in range.

Implemented in CCmpRangeManager.

GetElevationAdaptedRange()

virtual entity_pos_t ICmpRangeManager::GetElevationAdaptedRange ( const CFixedVector3D &  pos, const CFixedVector3D &  rot, entity_pos_t  range, entity_pos_t  yOrigin, entity_pos_t  angle  ) const

pure virtual

Get the average elevation over 8 points on distance range around the entity.

Parameters

id	the entity id to look around
range	the distance to compare terrain height with

Returns

a fixed number representing the average difference. It's positive when the entity is on average higher than the terrain surrounding it.

Implemented in CCmpRangeManager.

GetEntitiesByPlayer()

virtual std::vector< entity_id_t > ICmpRangeManager::GetEntitiesByPlayer ( player_id_t  player ) const

pure virtual

Returns a list of all entities for a specific player.

(This is on this interface because it shares a lot of the implementation. Maybe it should be extended to be more like ExecuteQuery without the range parameter.)

Implemented in CCmpRangeManager.

GetEntityFlagMask()

virtual u8 ICmpRangeManager::GetEntityFlagMask ( const std::string &  identifier ) const

pure virtual

Returns the mask for the specified identifier.

Implemented in CCmpRangeManager.

GetGaiaAndNonGaiaEntities()

virtual std::vector< entity_id_t > ICmpRangeManager::GetGaiaAndNonGaiaEntities ( ) const

pure virtual

Returns a list of all entities owned by a player or gaia.

Implemented in CCmpRangeManager.

GetLosCircular()

virtual bool ICmpRangeManager::GetLosCircular ( ) const

pure virtual

Returns whether the LOS is restricted to a circular map.

Implemented in CCmpRangeManager.

GetLosQuerier()

virtual CLosQuerier ICmpRangeManager::GetLosQuerier ( player_id_t  player ) const

pure virtual

Returns a CLosQuerier for checking whether vertex positions are visible to the given player (or other players it shares LOS with).

Implemented in CCmpRangeManager.

GetLosRevealAll()

virtual bool ICmpRangeManager::GetLosRevealAll ( player_id_t  player ) const

pure virtual

Returns whether the whole map has been made visible to the given player.

Implemented in CCmpRangeManager.

GetLosVisibility() [1/2]

virtual LosVisibility ICmpRangeManager::GetLosVisibility ( CEntityHandle  ent, player_id_t  player  ) const

pure virtual

Returns the visibility status of the given entity, with respect to the given player.

Returns LosVisibility::HIDDEN if the entity doesn't exist or is not in the world. This respects the GetLosRevealAll flag.

Implemented in CCmpRangeManager.

GetLosVisibility() [2/2]

virtual LosVisibility ICmpRangeManager::GetLosVisibility ( entity_id_t  ent, player_id_t  player  ) const

pure virtual

Implemented in CCmpRangeManager.

GetLosVisibility_wrapper()

std::string ICmpRangeManager::GetLosVisibility_wrapper	(	entity_id_t	ent,
		player_id_t	player
	)		const

GetLosVisibility wrapped for script calls.

Returns "hidden", "fogged" or "visible".

GetLosVisibilityPosition()

virtual LosVisibility ICmpRangeManager::GetLosVisibilityPosition ( entity_pos_t  x, entity_pos_t  z, player_id_t  player  ) const

pure virtual

Returns the visibility status of the given position, with respect to the given player.

This respects the GetLosRevealAll flag.

Implemented in CCmpRangeManager.

GetLosVisibilityPosition_wrapper()

std::string ICmpRangeManager::GetLosVisibilityPosition_wrapper	(	entity_pos_t	x,
		entity_pos_t	z,
		player_id_t	player
	)		const

GetLosVisibilityPosition wrapped for script calls.

Returns "hidden", "fogged" or "visible".

GetNonGaiaEntities()

virtual std::vector< entity_id_t > ICmpRangeManager::GetNonGaiaEntities ( ) const

pure virtual

Returns a list of all entities of all players except gaia.

Implemented in CCmpRangeManager.

GetPercentMapExplored()

virtual u8 ICmpRangeManager::GetPercentMapExplored ( player_id_t  player ) const

pure virtual

Get percent map explored statistics for specified player.

Implemented in CCmpRangeManager.

GetSharedLosMask()

virtual u32 ICmpRangeManager::GetSharedLosMask ( player_id_t  player ) const

pure virtual

Returns shared LOS mask for player.

Implemented in CCmpRangeManager.

GetSubdivision()

virtual FastSpatialSubdivision * ICmpRangeManager::GetSubdivision ( )

pure virtual

Access the spatial subdivision kept by the range manager.

Returns

pointer to spatial subdivision structure.

Implemented in CCmpRangeManager.

GetUnionPercentMapExplored()

virtual u8 ICmpRangeManager::GetUnionPercentMapExplored ( const std::vector< player_id_t > &  players ) const

pure virtual

Get percent map explored statistics for specified set of players.

Note: this function computes statistics from scratch and should not be called too often.

Implemented in CCmpRangeManager.

GetVerticesPerSide()

virtual size_t ICmpRangeManager::GetVerticesPerSide ( ) const

pure virtual

Returns

The number of LOS vertices.

Implemented in CCmpRangeManager.

IsActiveQueryEnabled()

virtual bool ICmpRangeManager::IsActiveQueryEnabled ( tag_t  tag ) const

pure virtual

Check if the processing of a query is enabled.

Parameters

tag	identifier of a query.

Implemented in CCmpRangeManager.

RequestVisibilityUpdate()

virtual void ICmpRangeManager::RequestVisibilityUpdate ( entity_id_t  ent )

pure virtual

Request the update of the visibility cache of ent at next turn.

Typically used for fogging.

Implemented in CCmpRangeManager.

ResetActiveQuery()

virtual std::vector< entity_id_t > ICmpRangeManager::ResetActiveQuery ( tag_t  tag )

pure virtual

Immediately execute a query, and re-enable it if disabled.

The next RangeUpdate message will say who has entered/left since this call, so you won't miss any notifications.

Parameters

tag	identifier of query.

Returns

list of entities matching the query, ordered by increasing distance from the source entity.

Implemented in CCmpRangeManager.

RevealShore()

virtual void ICmpRangeManager::RevealShore ( player_id_t  p, bool  enable  )

pure virtual

Reveal the shore for specified player p.

This works like for entities: if RevealShore is called multiple times with enabled, it will be necessary to call it the same number of times with !enabled to make the shore fall back into the FoW.

Implemented in CCmpRangeManager.

SetBounds()

virtual void ICmpRangeManager::SetBounds ( entity_pos_t  x0, entity_pos_t  z0, entity_pos_t  x1, entity_pos_t  z1  )

pure virtual

Set the bounds of the world.

Entities should not be outside the bounds (else efficiency will suffer).

Parameters

x0,z0,x1,z1

Coordinates of the corners of the world

Implemented in CCmpRangeManager.

SetDebugOverlay()

virtual void ICmpRangeManager::SetDebugOverlay ( bool  enabled )

pure virtual

Toggle the rendering of debug info.

Implemented in CCmpRangeManager.

SetEntityFlag()

virtual void ICmpRangeManager::SetEntityFlag ( entity_id_t  ent, const std::string &  identifier, bool  value  )

pure virtual

Set the flag specified by the identifier to the supplied value for the entity.

Parameters

ent	the entity whose flags will be modified.
identifier	the flag to be modified.
value	to which the flag will be set.

Implemented in CCmpRangeManager.

SetLosCircular()

virtual void ICmpRangeManager::SetLosCircular ( bool  enabled )

pure virtual

Set the LOS to be restricted to a circular map.

Implemented in CCmpRangeManager.

SetLosRevealAll()

virtual void ICmpRangeManager::SetLosRevealAll ( player_id_t  player, bool  enabled  )

pure virtual

Set whether the whole map should be made visible to the given player.

If player is -1, the map will be made visible to all players.

Implemented in CCmpRangeManager.

SetSharedLos()

virtual void ICmpRangeManager::SetSharedLos ( player_id_t  player, const std::vector< player_id_t > &  players  )

pure virtual

Sets shared LOS data for player to the given list of players.

Implemented in CCmpRangeManager.

Verify()

virtual void ICmpRangeManager::Verify ( )

pure virtual

Perform some internal consistency checks for testing/debugging.

Implemented in CCmpRangeManager.

---

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

• /home/docker/jenkins/workspace/technical-docs/source/simulation2/components/ICmpRangeManager.h
• /home/docker/jenkins/workspace/technical-docs/source/simulation2/components/ICmpRangeManager.cpp