Documentation for skXMapinfo.py

Warning: This documentation was generated from the comments in the source code (using progrutils.documentPyFile()), with a few tweaks, under the principle that poor documentation is better than no documentation. In case of ambiguity, please refer to the code itself.

 

Skirmish X Map Info

By Kuertee

 

features:

fight-clusters data compatible with m25-ai team data

to use:

1. from skXMapInfo import * or import skXMapInfo

2. initialise with GetMapInfo ()

3. to get a list of objects (including those that move): MapInfo_GetObjects ((x,y,z), distance)

4. to update the MapInfoFighters data: MapInfo_UpdateFighters (). do this once every "tick", so that other functions return up-to-date information.

5. to get a list of fighters: MapInfo_GetFighters ((x,y,z), distance)

6. to get a list of allies near a character: MapInfo_GetNearbyAllies (character name)

7. to get a list of enemies near a character: MapInfo_GetNearbyEnemies (character name)

uses:

1. returns an approximate bounding box and mid points of the map

2. an alternative to Mission_GetObjects ()

3. an alternative to Mission_GetDynamicObjects ()

why?

Mission_GetObjects () returns all objects in the map. while MapInfo_GetObjects () returns only those objects around a particular point. ultimately, looping through MapInfo_GetObjects () impacts the cpu less in exchange for a small amount of memory (to hold the MapInfo [] dictionary).

i.e.: these functions, instead of iterating through all objects in a map for nearest/furtherest checks, iterate through objects retrieved from a look-up dictionary. e.g. in airfield, retrieving all objects within a 100-unit radius from (0,0,0) iterates through 40 objects instead of all 200.

similarly, queries to MapInfoFighters saves from looping through Mission_GetDynamicObjects () several times in a "tick" just to retrieve a list of allies/enemies around a certain point. update the list once at the start of a "tick" with MapInfo_UpdateFighters (), and use MapInfo_GetNearbyAllies () or MapInfo_GetNearbyEnemies () to instantly retrieve data.

fight-cluster data can be used to quickly retrieve all teams/characters information in a fight-cluster. a fight-cluster does not only contain characters within a certain distance from a point, but all other characters that may be pulled into the fight because of their proximity to an ally who may be within a certain distance from an enemy.

unlike the object data, fight-clusters need to be updated regularly. so a call to MapInfo_UpdateFighters () is required.

how?

when GetMapInfo () is called (preferably at the beginning of the game in OnPostInit ()), the map is read by calling Mission_GetObjects ().

from this list of objects, the map's approximate dimensions are retrieved. then, invisible "red_suns" are spawned at the edges of this bounding box and triggered to move outwards. once they stop, the actual dimensions of the map are retrieved.

a grid with measurements given in MAPINFO_XGRID AND MAPINFO_YGRID is used to divide the map. the grid positions of all objects in the map are stored in the MapInfo dictionary.

when MapInfo_GetObjects () is called, it returns all objects within the given distance by reading the MapInfo [] dictionary. the number of objects returned is much smaller than from Mission_GetObjects ().

dynamic generic objects (i.e. not characters nor projectiles) are tracked automatically. once they stop moving, their grid information is updated. note that tracking automatically starts when MapInfo_GetObjects () is called. and tracking automatically stops when all these generic objects stop moving.

data in MapInfoFighters works similarly. at every call to MapInfo_UpdateFighters (), the grid positions of all characters and all moving objects (including projectiles and thrown objects) are stored in the MapInfoFighters dictionary.

from the MapInfoFighters dictionary, the fight-cluster information is built.

applications?

1. (implemented:) skXCamera2 constantly looks for buildings that may have blocked the view.

2. (implemented:) fight clusters working in my preliminary code to skX2.

3. (implemented:) projectiles/thrown-objects avoidance working in skX2.

4. (not yet:) custom ai looking for objects to throw (or objects to hide behind.)

 

scripting reference

these three functions may be customised to further filter-out valid enemies.

GET_TEAM_FUNCTION = is used to separate the characters into their teams IS_INVISIBLE_FUNCTION: optional filter used in "nearestEnemyVisible" assignment IS_ATTACKABLE_FUNCTION: optional filter used in "nearestEnemyAttackable" assignment

the best way to customise these functions are to assign it a function from the importing module. for example:

a "too pathetic to be attacked" attribute prevents any attacks. the function that determines the presence of this attribute (along with the standard non-attackable checks) need to be set in IS_ATTACKABLE_FUNCTION.

import skXMapInfo
 def OnPostInit (event = None):
	skXMapInfo.GET_TEAM_FUNCTION = getTeam
	skXMapInfo.IS_INVISIBLE_FUNCTION = isInvisible
	skXMapInfo.IS_ATTACKABLE_FUNCTION = isAttackable
def getTeam (name):
	return Object_GetAttr (name, "team")
def isInvisible (name):
	return Object_GetSecondaryStates (name) & SCSTATE_INVISIBLE
def isAttackable (name):
	return not tooPatheticToBeAttacked (name) and not frozen (name) and not isInvisible (name) and not isObjectified (name)
def isObjectified (name):
	banishedStates = [PCSTATE_OBJECT, PCSTATE_TOAD]
	return Object_GetPrimaryState (name) in banishedStates
def tooPatheticToBeAttacked (name):
	return Object_GetAttr (name, "strength") == 0

by default, GET_TEAM_FUNCTION uses isHero (name) to differentiate between teams
by default, IS_INVISIBLE_FUNCTION and IS_ATTACKABLE_FUNCTION are as per below:

def isInvisible (name):
	return Object_GetSecondaryStates (name) & SCSTATE_INVISIBLE
def isAttackable (name):
	return Object_IsAlive (name) and not frozen (name) and not isInvisible (name) and not staticked (name) and not isObjectified (name)
def isObjectified (name):
	banishedStates = [PCSTATE_OBJECT, PCSTATE_TOAD]
	return Object_GetPrimaryState (name) in banishedStates

 

MapInfo

 

MapInfo_GetObjects (tuple (x, y, z), distance, tfFilter=function)

distance: number or the strings: "nearest" or "furthest". if "nearest"/"furthest" is used, only one object is returned. tfFilter: function (note: not string). only objects that satisfy this check is returned. note that not all objects in the map is queried. only objects around the point at the given distance is used. when not given or "nearest" or "furthest" is used, distance defaults to the constant DISTANCE_VISIBLE = 400. returns an array of all objects around the given point or a string of the objects's name that is "nearest" or "furthest" from the point.

MapInfo_GetMapPosition (array of markers, objects or tuples)

returns a point inside the map bounding box. the point returned is either a random point anywhere in the map or a point randomly selected from the given list.

MapInfo_GetPointFromCentre (integer heading, integer distance from edge, float factor to edge)

returns a point from the centre of the map at the heading\tangle and a certain distance from the edge of the map.

MapInfo_Update ()

updates MapInfo's grid information. not necessary because a query with MapInfo_GetObjects () will update the information automatically.

 

MapInfoFighters

MapInfoFighters ["clusters"] = array of fight clusters in map MapInfoFighters [cluster name] = dictionary of (for each team in cluster:) teamlt;team name>: array of characters in cluster teamlt;team name>Health: integer total health of team in cluster teamlt;team name>MaxHealth: integer total maxHealth of team in cluster teamlt;team name>Prestige: integer total prestige of team in cluster

MapInfo_UpdateFighters ()

updates MapInfoFighters' grid and fight cluster information

MapInfo_GetFighters (tuple (x,y,z), distance, tfFilter=function)

distance: number or the strings: "nearest" or "furthest". if "nearest"/"furthest" is used, only one object is returned. tfFilter: function (note: not string). only objects that satisfy this check is returned. this defaults to Object_IsAlive. returns an array of all characters around the given point or a string of the characters's name that is "nearest" or "furthest" from the point.

MapInfo_GetNearbyAllies (string character name)

returns an array of allies near the character.

MapInfo_GetNearbyEnemies (string character name)

returns an array of enemies near the character.

 

building information

the functions relating to building information, require: 1. heightcheck.py (v1.2) 2. heightcheckdata.py with building data

MapInfo_GetBuildingCorners (string building name)

returns the positions of the corners of the building

MapInfo_GetBuildingPointsOfNearestSide (string building name, tuple (x,y,z)) MapInfo_GetBuildingPointsOfFurthestSide (string building name, tuple (x,y,z))

returns points of nearest/furthest side of the building from the given point

MapInfo_PutPointOutsideBuilding (tuple (x,y,z), string building name)

returns a point that is outside a building

MapInfo_EnsurePointIsOutsideBuilding (tuple (x,y,z))

returns a point that is definately outside buildings by recursively running MapInfo_PutPointOutsideBuilding until the point is outside any building

MapInfo_IsPointInsideBuilding (tuple (x,y,z))

returns true if the point is inside a building

MapInfo_GetBuildingPointInsideOf (tuple (x,y,z))

returns the building the point is inside of

credits