Functions Reference
Written by: Alian713, Kramb
1. Rules¶
1.1. xsDisableRule¶
Returning Type: void
Prototype: void xsDisableRule(string ruleName)
Parameters:
string ruleName
: The name of the rule to disable
Disables the given rule.
1.2. xsDisableRuleGroup¶
Returning Type: void
Prototype: void xsDisableRuleGroup(string ruleGroupName)
Parameters:
string ruleGroupName
: The name of the rule group to disable
Disables all the rules in the given rule group
1.3. xsDisableSelf¶
Returning Type: void
Prototype: void xsDisableSelf()
Disables the rule this function is called inside. Cannot be used outside of a rule's body!
1.4. xsEnableRule¶
Returning Type: void
Prototype: void xsEnableRule(string ruleName)
Parameters:
string ruleName
: The name of the rule to enable
Enables the given rule.
1.5. xsEnableRuleGroup¶
Returning Type: void
Prototype: void xsEnableRuleGroup(string ruleGroupName)
Parameters:
string ruleGroupName
: The name of the rule group to enable
Enables all the rules in the given rule group
1.6. xsIsRuleEnabled¶
Returning Type: bool
Prototype: bool xsIsRuleEnabled(string ruleName)
Parameters:
string ruleName
: The name of the rule to check
Returns true if the rule is enabled, else returns false.
1.7. xsIsRuleGroupEnabled¶
Returning Type: bool
Prototype: bool xsIsRuleGroupEnabled(string ruleGroupName)
Parameters:
string ruleGroupName
: The name of the rule group to check
Returns true, if all the rules in the given rule group are enabled
1.8. xsSetRuleMaxInterval¶
Returning Type: void
Prototype: void xsSetRuleMaxInterval(string ruleName, int interval)
Parameters:
string ruleName
: The name of the rule to set the max interval ofint interval
: The new max interval of the rule
Sets the max interval of the given rule.
1.9. xsSetRuleMaxIntervalSelf¶
Returning Type: void
Prototype: void xsSetRuleMaxIntervalSelf(int interval)
Parameters:
int interval
: The new max interval of the rule
Sets the max interval of the rule this function is called inside. Cannot be used outside of a rule's body!
1.10. xsSetRuleMinInterval¶
Returning Type: void
Prototype: void xsSetRuleMinInterval(string ruleName, int interval)
Parameters:
string ruleName
: The name of the rule to set the min interval ofint interval
: The new min interval of the rule
Sets the min interval of the given rule.
1.11. xsSetRuleMinIntervalSelf¶
Returning Type: void
Prototype: void xsSetRuleMinIntervalSelf(int interval)
Parameters:
int interval
: The new min interval of the rule
Sets the min interval of the rule this function is called inside. Cannot be used outside of a rule's body!
1.12. xsSetRulePriority¶
Returning Type: void
Prototype: void xsSetRulePriority(string ruleName, int rulePriority)
Parameters:
string ruleName
: The name of the rule to set the priority ofint rulePriority
: The new priority of the rule
Sets the priority of the given rule.
1.13. xsSetRulePrioritySelf¶
Returning Type: void
Prototype: void xsSetRulePrioritySelf(int rulePriority)
Parameters:
int rulePriority
: The new priority of the rule
Sets the priority of the rule this function is called inside. Cannot be used outside of a rule's body!
2. Vectors¶
2.1. xsVectorGetX¶
Returning Type: float
Prototype: float xsVectorGetX(vector v)
Parameters:
vector v
: The vector to get the X coordinate of
The X coordinate of the vector given.
2.2. xsVectorGetY¶
Returning Type: float
Prototype: float xsVectorGetY(vector v)
Parameters:
vector v
: The vector to get the Y coordinate of
The Y coordinate of the vector given.
2.3. xsVectorGetZ¶
Returning Type: float
Prototype: float xsVectorGetZ(vector v)
Parameters:
vector v
: The vector to get the Z coordinate of
The Z coordinate of the vector given.
2.4. xsVectorLength¶
Returning Type: float
Prototype: float xsVectorLength(vector v)
Parameters:
vector v
: The vector to calculate the length of
Returns the length of the given vector.
2.5. xsVectorNormalize¶
Returning Type: vector
Prototype: vector xsVectorNormalize(vector v)
Parameters:
vector v
: The vector to normalise
Returns the normalised vector in the direction of the given vector.
2.6. xsVectorSet¶
Returning Type: vector
Prototype: vector xsVectorSet(float x, float y, float z)
Parameters:
float x
: The value to set the X coordinate tofloat y
: The value to set the Y coordinate tofloat z
: The value to set the Z coordinate to
Returns a vector with the given X, Y and Z components.
2.7. xsVectorSetX¶
Returning Type: vector
Prototype: vector xsVectorSetX(vector v, float x)
Parameters:
vector v
: The vector to modify the X coordinate offloat x
: The value to set the X coordinate to
Returns a new vector with the X component of the given vector changed to the given value. Note: This function DOES NOT modify the vector given as the parameter!
2.8. xsVectorSetY¶
Returning Type: vector
Prototype: vector xsVectorSetY(vector v, float y)
Parameters:
vector v
: The vector to modify the Y coordinate offloat y
: The value to set the Y coordinate to
Returns a new vector with the Y component of the given vector changed to the given value. Note: This function DOES NOT modify the vector given as the parameter!
2.9. xsVectorSetZ¶
Returning Type: vector
Prototype: vector xsVectorSetZ(vector v, float z)
Parameters:
vector v
: The vector to modify the Z coordinate offloat z
: The value to set the Z coordinate to
Returns a new vector with the Z component of the given vector changed to the given value. Note: This function DOES NOT modify the vector given as the parameter!
3. Arrays¶
3.1. xsArrayCreateBool¶
Returning Type: int
Prototype: int xsArrayCreateBool(int size, bool defaultValue, string uniqueName)
Parameters:
int size
: The length of the array to create- (Optional)
bool defaultValue
: The default value to initialise all the values in the array to. If not set all array values will be false - (Optional)
string uniqueName
: A unique name of the created array. Note that when set, this name cannot be reused, and subsequent array creation attempts with the same name will fail (e.g. in loops)
Creates an array of type bool and returns its ID. Created arrays never go out of scope so be careful when creating them inside repeated code patterns as that can introduce memory leaks.
3.2. xsArrayCreateFloat¶
Returning Type: int
Prototype: int xsArrayCreateFloat(int size, float defaultValue, string uniqueName)
Parameters:
int size
: The length of the array to create- (Optional)
float defaultValue
: The default value to initialise all the values in the array to. If not set all array values will be 0.0 - (Optional)
string uniqueName
: A unique name of the created array. Note that when set, this name cannot be reused, and subsequent array creation attempts with the same name will fail (e.g. in loops)
Creates an array of type float and returns its ID. Created arrays never go out of scope so be careful when creating them inside repeated code patterns as that can introduce memory leaks.
3.3. xsArrayCreateInt¶
Returning Type: int
Prototype: int xsArrayCreateInt(int size, int defaultValue, string uniqueName)
Parameters:
int size
: The length of the array to create- (Optional)
int defaultValue
: The default value to initialise all the values in the array to. If not set all array values will be 0 - (Optional)
string uniqueName
: A unique name of the created array. Note that when set, this name cannot be reused, and subsequent array creation attempts with the same name will fail (e.g. in loops)
Creates an array of type int and returns its ID. Created arrays never go out of scope so be careful when creating them inside repeated code patterns as that can introduce memory leaks.
3.4. xsArrayCreateString¶
Returning Type: int
Prototype: int xsArrayCreateString(int size, string defaultValue, string uniqueName)
Parameters:
int size
: The length of the array to create- (Optional)
string defaultValue
: The default value to initialise all the values in the array to. If not set all array values will be "" - (Optional)
string uniqueName
: A unique name of the created array. Note that when set, this name cannot be reused, and subsequent array creation attempts with the same name will fail (e.g. in loops)
Creates an array of type String and returns its ID. Created arrays never go out of scope so be careful when creating them inside repeated code patterns as that can introduce memory leaks.
3.5. xsArrayCreateVector¶
Returning Type: int
Prototype: int xsArrayCreateVector(int size, vector defaultValue, string uniqueName)
Parameters:
int size
: The length of the array to create- (Optional)
vector defaultValue
: The default value to initialise all the values in the array to. If not set all array values will be vector(-1.0, -1.0, -1.0) - (Optional)
string uniqueName
: A unique name of the created array. Note that when set, this name cannot be reused, and subsequent array creation attempts with the same name will fail (e.g. in loops)
Creates an array of type Vector and returns its ID. Created arrays never go out of scope so be careful when creating them inside repeated code patterns as that can introduce memory leaks.
3.6. xsArrayGetBool¶
Returning Type: bool
Prototype: bool xsArrayGetBool(int arrayId, int index)
Parameters:
int arrayId
: The ID of the array to get the value fromint index
: The index to get the value of
Gets and returns the value of the given bool array at the specified index.
3.7. xsArrayGetFloat¶
Returning Type: float
Prototype: float xsArrayGetFloat(int arrayId, int index)
Parameters:
int arrayId
: The ID of the array to get the value fromint index
: The index to get the value of
Gets and returns the value of the given float array at the specified index.
3.8. xsArrayGetInt¶
Returning Type: int
Prototype: int xsArrayGetInt(int arrayId, int index)
Parameters:
int arrayId
: The ID of the array to get the value fromint index
: The index to get the value of
Gets and returns the value of the given int array at the specified index.
3.9. xsArrayGetSize¶
Returning Type: int
Prototype: int xsArrayGetSize(int arrayId)
Parameters:
int arrayId
: The ID of the array to get the length of
Returns the length of the given array.
3.10. xsArrayGetString¶
Returning Type: string
Prototype: string xsArrayGetString(int arrayId, int index)
Parameters:
int arrayId
: The ID of the array to get the value fromint index
: The index to get the value of
Gets and returns the value of the given string array at the specified index.
3.11. xsArrayGetVector¶
Returning Type: vector
Prototype: vector xsArrayGetVector(int arrayId, int index)
Parameters:
int arrayId
: The ID of the array to get the value fromint index
: The index to get the value of
Gets and returns the value of the given vector array at the specified index.
3.12. xsArrayResizeBool¶
Returning Type: int
Prototype: int xsArrayResizeBool(int arrayId, int newSize)
Parameters:
int arrayId
: The ID of the array to resizeint newSize
: The new size of the array
Resizes the the given bool array to the specified size and returns 1.
3.13. xsArrayResizeFloat¶
Returning Type: int
Prototype: int xsArrayResizeFloat(int arrayId, int newSize)
Parameters:
int arrayId
: The ID of the array to resizeint newSize
: The new size of the array
Resizes the the given float array to the specified size and returns 1.
3.14. xsArrayResizeInt¶
Returning Type: int
Prototype: int xsArrayResizeInt(int arrayId, int newSize)
Parameters:
int arrayId
: The ID of the array to resizeint newSize
: The new size of the array
Resizes the the given int array to the specified size and returns 1.
3.15. xsArrayResizeString¶
Returning Type: int
Prototype: int xsArrayResizeString(int arrayId, int newSize)
Parameters:
int arrayId
: The ID of the array to resizeint newSize
: The new size of the array
Resizes the the given string array to the specified size and returns 1.
3.16. xsArrayResizeVector¶
Returning Type: int
Prototype: int xsArrayResizeVector(int arrayId, int newSize)
Parameters:
int arrayId
: The ID of the array to resizeint newSize
: The new size of the array
Resizes the the given vector array to the specified size and returns 1.
3.17. xsArraySetBool¶
Returning Type: int
Prototype: int xsArraySetBool(int arrayId, int index, bool value)
Parameters:
int arrayId
: The ID of the array to set the value inint index
: The index to set the value ofbool value
: The new value to set
Sets the value at the specified index of the given bool array to the provided value and returns 1.
3.18. xsArraySetFloat¶
Returning Type: int
Prototype: int xsArraySetFloat(int arrayId, int index, float value)
Parameters:
int arrayId
: The ID of the array to set the value inint index
: The index to set the value offloat value
: The new value to set
Sets the value at the specified index of the given float array to the provided value and returns 1.
3.19. xsArraySetInt¶
Returning Type: int
Prototype: int xsArraySetInt(int arrayId, int index, int value)
Parameters:
int arrayId
: The ID of the array to set the value inint index
: The index to set the value ofint value
: The new value to set
Sets the value at the specified index of the given int array to the provided value and returns 1.
3.20. xsArraySetString¶
Returning Type: int
Prototype: int xsArraySetString(int arrayId, int index, string value)
Parameters:
int arrayId
: The ID of the array to set the value inint index
: The index to set the value ofstring value
: The new value to set
Sets the value at the specified index of the given string array to the provided value and returns 1.
3.21. xsArraySetVector¶
Returning Type: int
Prototype: int xsArraySetVector(int arrayId, int index, vector value)
Parameters:
int arrayId
: The ID of the array to set the value inint index
: The index to set the value ofvector value
: The new value to set
Sets the value at the specified index of the given vector array to the provided value and returns 1.
4. Maths¶
4.1. abs¶
Returning Type: float
Prototype: float abs(float x)
Parameters:
float x
: The number to find the absolute value of
Returns the absolute value (magnitude) of the given number.
4.2. acos¶
Returning Type: float
Prototype: float acos(float x)
Parameters:
float x
: The value to find the inverse cosine of
Returns the inverse cosine (arccos) of the given value
4.3. asin¶
Returning Type: float
Prototype: float asin(float x)
Parameters:
float x
: The value to find the inverse sine of
Returns the inverse sine (arcsin) of the given value
4.4. atan¶
Returning Type: float
Prototype: float atan(float x)
Parameters:
float x
: The value to find the inverse tangent of
Returns the inverse tangent (arctan) of the given value
4.5. atan2¶
Returning Type: float
Prototype: float atan2(float y, float x)
Parameters:
float y
: The Y coordinate of the point to find the X+ angle offloat x
: The X coordinate of the point to find the X+ angle of
Returns the angle of the given point (x, y) made from the X+ axis, in the range \([-\pi, \pi]\)
4.6. atan2v¶
Returning Type: float
Prototype: float atan2v(vector v)
Parameters:
vector v
: The vector to get the atan2 from
Returns the angle of the given vector from the X+ axis, in the range \([-\pi, \pi]\). Ignores the Z component
4.7. bitCastToFloat¶
Returning Type: float
Prototype: float bitCastToFloat(int number)
Parameters:
int number
: The value toreinterpret/bit_cast
tofloat
Reinterprets/Bit casts the given int
value to float
. Equivalent to std::mem::transmute::<i32, f32>(number)
4.8. bitCastToInt¶
Returning Type: int
Prototype: int bitCastToInt(float number)
Parameters:
float number
: The value toreinterpret/bit_cast
toint
Reinterprets/Bit casts the given float
value to int
. Equivalent to std::mem::transmute::<f32, i32>(number)
4.9. ceil¶
Returning Type: float
Prototype: float ceil(float x)
Parameters:
float x
: The value to find the ceil of
Returns \(\left \lceil{x}\right \rceil\)
4.10. cos¶
Returning Type: float
Prototype: float cos(float x)
Parameters:
float x
: The angle (in radians) to find the cosine of
Returns the cosine of the angle in radians
4.11. exp¶
Returning Type: float
Prototype: float exp(float x)
Parameters:
float x
: The value to find the exp of
Returns \(e^x\)
4.12. floor¶
Returning Type: float
Prototype: float floor(float x)
Parameters:
float x
: The value to find the floor of
Returns \(\left \lfloor{x}\right \rfloor\)
4.13. pow¶
Returning Type: float
Prototype: float pow(float x, float y)
Parameters:
float x
: The base valuefloat y
: The exponent to raise the base value to
Returns x raised to the power y (x**y).
4.14. sin¶
Returning Type: float
Prototype: float sin(float x)
Parameters:
float x
: The angle (in radians) to find the sine of
Returns the sine of the angle in radians.
4.15. sqrt¶
Returning Type: float
Prototype: float sqrt(float x)
Parameters:
float x
: The number to find the square root of
Returns the square root of the given number.
4.16. tan¶
Returning Type: float
Prototype: float tan(float x)
Parameters:
float x
: The angle (in radians) to find the tangent of
Returns the tangent of the angle in radians
4.17. xsCeilToInt¶
Returning Type: int
Prototype: int xsCeilToInt(float value)
Parameters:
float value
: The value to determine the ceil of
Rounds the number up to the next integer
5. General¶
5.1. xsChatData¶
Returning Type: void
Prototype: void xsChatData(string message, int value)
Parameters:
string message
: The message to display in chat- (Optional)
int value
: This value is inserted in place of any%d
used in the message of the function
Shows the given message in the game chat
5.2. xsDoesUnitExist¶
Returning Type: bool
Prototype: bool xsDoesUnitExist(int unitId)
Parameters:
int unitId
: The unit ID to check
Returns true if a unit with the given ID exists on the map.
5.3. xsEffectAmount¶
Returning Type: void
Prototype: void xsEffectAmount(int effectId, int objectOrTechnologyId, int attributeOrOperation, float value, int playerNumber)
Parameters:
int effectId
: The ID of the effect to useint objectOrTechnologyId
: The ID of the object or technology to effectint attributeOrOperation
: The attribute to modify or the operation to performfloat value
: The value of the effect- (Optional)
int playerNumber
: The player to apply the effect to. If unspecified, applies to all players except Gaia.
Change the specified attribute of the specified object or technology by the value for the specified player. For more information on this, check the UserPatch section of the guide
5.4. xsGetGameTime¶
Returning Type: int
Prototype: int xsGetGameTime()
Returns the current game time in seconds
5.5. xsGetGroupMoveTarget¶
Returning Type: vector
Prototype: vector xsGetGroupMoveTarget(int groupId)
Parameters:
int groupId
: The group (formation) to get the movement target for
Returns the location this group (formation) is currently moving to
5.6. xsGetMapHeight¶
Returning Type: int
Prototype: int xsGetMapHeight()
Returns the Height of the map.
5.7. xsGetMapID¶
Returning Type: int
Prototype: int xsGetMapID()
Returns the AI map type.
5.8. xsGetMapName¶
Returning Type: string
Prototype: string xsGetMapName(bool showFileExtension)
Parameters:
bool showFileExtension
: If this is set to true, then the returned name also contains the file extension
Returns the name of the map currently being played.
5.9. xsGetMapWidth¶
Returning Type: int
Prototype: int xsGetMapWidth()
Returns the Width of the map.
5.10. xsGetNumPlayers¶
Returning Type: int
Prototype: int xsGetNumPlayers()
Returns the number of players in the game
5.11. xsGetObjectAttribute¶
Returning Type: float
Prototype: float xsGetObjectAttribute(int playerId, int objectId, int attribute, int damageClass)
Parameters:
int playerId
: The player whose object to get the attribute forint objectId
: The object to get the attribute forint attribute
: The attribute to getint damageClass
: For use with armor/attack attributes - specifies which armor/attack class to get
Returns the attribute value for an object
5.12. xsGetObjectClass¶
Returning Type: int
Prototype: int xsGetObjectClass(int playerId, int objectId)
Parameters:
int playerId
: The player to get the object's class forint objectId
: The object to get the class for
Returns the given object's class for the specified player. See cClass constants
5.13. xsGetObjectCopyId¶
Returning Type: int
Prototype: int xsGetObjectCopyId(int playerId, int objectId)
Parameters:
int playerId
: The player to get the object's copy ID forint objectId
: The object to get the copy ID for
Returns the given object's copy ID in data for the specified player
5.14. xsGetObjectCount¶
Returning Type: int
Prototype: int xsGetObjectCount(int playerId, int objectOrClassId)
Parameters:
int playerId
: The player to get the object count forint objectOrClassId
: The ID of the object or class to get the count for
Returns the number of currently alive objects with the given ID of the specified player
5.15. xsGetObjectCountTotal¶
Returning Type: int
Prototype: int xsGetObjectCountTotal(int playerId, int objectOrClassId)
Parameters:
int playerId
: The player to get the object count forint objectOrClassId
: The ID of the object or class to get the count for
Returns the number of currently alive/standing + queued/foundation objects with the given ID of the specified player
5.16. xsGetObjectName¶
Returning Type: string
Prototype: string xsGetObjectName(int objectId, int playerId, bool internalName)
Parameters:
int objectId
: The object to get the name forint playerId
: The player to get the object's name for- (Optional)
bool internalName
: Returns the internal name of the object if set.!#xs false
by default.
Returns the current name of the given object for the specified player.
5.17. xsGetObjectType¶
Returning Type: int
Prototype: int xsGetObjectType(int playerId, int objectId)
Parameters:
int playerId
: The player to get the object's type forint objectId
: The object to get the type for
Returns the given object's type for the specified player. See cObjectType constants
5.18. xsGetPlayerCivilization¶
Returning Type: int
Prototype: int xsGetPlayerCivilization(int playerNumber)
Parameters:
int playerNumber
: The player to get the civilization of
Returns the civilization ID of the given player. Refer to the Constant Reference for all the different civ IDs
5.19. xsGetPlayerInGame¶
Returning Type: bool
Prototype: bool xsGetPlayerInGame(int playerNumber)
Parameters:
int playerNumber
: Check if this player is still alive
Returns true if the player given is still alive, and false otherwise.
5.20. xsGetPlayerName¶
Returning Type: string
Prototype: string xsGetPlayerName(int playerId)
Parameters:
int playerId
: The lobby index of the player
Returns the given player's name.
5.21. xsGetPlayerNumberOfTechs¶
Returning Type: int
Prototype: int xsGetPlayerNumberOfTechs(int playerNumber)
Parameters:
int playerNumber
: The player whose technology count is being requested.
Returns the number of technologies available to the player in the entire game.
5.22. xsGetPlayerUnitIds¶
Returning Type: int
Prototype: int xsGetPlayerUnitIds(int playerId, int objectOrClassId, int arrayId)
Parameters:
int playerId
: The player to get the unit IDs forint objectOrClassId
: The ID of the object or class to get the unit reference IDs for- (Optional)
int arrayId
: Reuse an existing array to save memory
Returns an array of unit IDs on the map for the given player and the specified object ID or class. The IDs here are the same as the reference_id
used by the scenario editor
5.23. xsGetRandomNumber¶
Returning Type: int
Prototype: int xsGetRandomNumber()
Returns a random number between 0 and 32766.
5.24. xsGetRandomNumberLH¶
Returning Type: int
Prototype: int xsGetRandomNumberLH(int low, int high)
Parameters:
int low
: The lower bound for the range for the random number returned (included)int high
: The upper bound for the range for the random number returned (excluded)
Returns a random number between low
and high
5.25. xsGetRandomNumberMax¶
Returning Type: int
Prototype: int xsGetRandomNumberMax(int max)
Parameters:
int max
: The upper bound for the range for the random number returned (excluded)
Returns a random number between 0 and max
.
5.26. xsGetTechName¶
Returning Type: string
Prototype: string xsGetTechName(int techId, int playerId, bool internalName)
Parameters:
int techId
: The tech to get the name forint playerId
: The player to get the tech's name for- (Optional)
bool internalName
: Returns the internal name of the tech if set.!#xs false
by default.
Returns the current name of the given tech for the specified player.
5.27. xsGetTechState¶
Returning Type: int
Prototype: int xsGetTechState(int techId, int playerId)
Parameters:
int techId
: The tech to get the state forint playerId
: The player to get the tech's state for
Returns one of the cTechState constants based on the tech's status
5.28. xsGetTime¶
Returning Type: int
Prototype: int xsGetTime()
Returns the current game time - 1 in seconds
5.29. xsGetTurn¶
Returning Type: int
Prototype: int xsGetTurn()
Returns the current game tick (called turn).
5.30. xsGetUnitAttribute¶
Returning Type: float
Prototype: float xsGetUnitAttribute(int unitId, int attribute, int damageClass)
Parameters:
int unitId
: The unit to get the attribute for.int attribute
: The attribute to getint damageClass
: For use with armor/attack attributes - specifies which armor/attack class to get
Returns the attribute value for a specific unit on the map.
5.31. xsGetUnitAttributeHeld¶
Returning Type: float
Prototype: float xsGetUnitAttributeHeld(int unitId, int attributeId)
Parameters:
int unitId
: The unit to get the resource held for- (Optional)
int attributeId
: The ID of the resource to get. If unspecified, return the first resource which the unit holds
Returns the given unit's amount of the specified resource held.
5.32. xsGetUnitAttributeTypesHeld¶
Returning Type: int
Prototype: int xsGetUnitAttributeTypesHeld(int unitId)
Parameters:
int unitId
: The unit to get the held resource types for
Returns the given unit's type of resources held as an array of ints. The only unit that this currently returns multiple values for is the trade cart/cog.
5.33. xsGetUnitBuildPoints¶
Returning Type: float
Prototype: float xsGetUnitBuildPoints(int unitId)
Parameters:
int unitId
: The unit to get the Build Points for
Returns the given unit's Built Points
5.34. xsGetUnitCharge¶
Returning Type: float
Prototype: float xsGetUnitCharge(int unitId)
Parameters:
int unitId
: The unit to get the charge for
Returns the given unit's charge
5.35. xsGetUnitClass¶
Returning Type: int
Prototype: int xsGetUnitClass(int unitId)
Parameters:
int unitId
: The unit to get the class for
Returns the given unit's class See cClass constants
5.36. xsGetUnitCopyId¶
Returning Type: int
Prototype: int xsGetUnitCopyId(int unitId)
Parameters:
int unitId
: The unit to get the copy ID for
Returns the given unit's copy ID in data
5.37. xsGetUnitGroupId¶
Returning Type: int
Prototype: int xsGetUnitGroupId(int unitId)
Parameters:
int unitId
: The unit to get the group ID (formation) for
Returns the ID of the group (formation) for this unit
5.38. xsGetUnitHitpoints¶
Returning Type: float
Prototype: float xsGetUnitHitpoints(int unitId)
Parameters:
int unitId
: The unit to get the HP for
Returns the given unit's HP
5.39. xsGetUnitMoveTarget¶
Returning Type: vector
Prototype: vector xsGetUnitMoveTarget(int unitId)
Parameters:
int unitId
: The unit to get the movement target for
Returns the location this unit is currently moving to
5.40. xsGetUnitName¶
Returning Type: string
Prototype: string xsGetUnitName(int unitId, bool internalName)
Parameters:
int unitId
: The unit ID to check- (Optional)
bool internalName
: Returns the internal name of the unit if set.!#xs false
by default.
Returns the current name of a given unit
5.41. xsGetUnitObjectId¶
Returning Type: int
Prototype: int xsGetUnitObjectId(int unitId)
Parameters:
int unitId
: The unit to get the object ID for
Returns the given unit's ID in data
5.42. xsGetUnitOwner¶
Returning Type: int
Prototype: int xsGetUnitOwner(int unitId)
Parameters:
int unitId
: The unit to get the owner ID for
Returns the lobby index of the player owning this unit.
5.43. xsGetUnitPosition¶
Returning Type: vector
Prototype: vector xsGetUnitPosition(int unitId)
Parameters:
int unitId
: The unit to get the position for
Returns the current position of a unit.
5.44. xsGetUnitTargetUnitId¶
Returning Type: int
Prototype: int xsGetUnitTargetUnitId(int unitId)
Parameters:
int unitId
: The unit to get the target for
Returns the ID of the currently targeted unit for this unit
5.45. xsGetUnitType¶
Returning Type: int
Prototype: int xsGetUnitType(int unitId)
Parameters:
int unitId
: The unit to get the type for
Returns the given unit's type. See cObjectType constants
5.46. xsGetVictoryCondition¶
Returning Type: int
Prototype: int xsGetVictoryCondition()
Returns one of these constants: cStandardVictory
cWonderVictory
cRelicVictory
cKingOfTheHillVictory
5.47. xsGetVictoryConditionForSecondaryGameMode¶
Returning Type: int
Prototype: int xsGetVictoryConditionForSecondaryGameMode()
Returns one of these constants: cStandardVictory
cWonderVictory
cRelicVictory
cKingOfTheHillVictory
5.48. xsGetVictoryPlayer¶
Returning Type: int
Prototype: int xsGetVictoryPlayer()
Returns the number of the player with the highest score in a normal game. Returns the number of the player who owns 5 relics or has a wonder if standard victory is enabled. In a game like KoTH, returns the number of the player who owns the monument.
5.49. xsGetVictoryPlayerForSecondaryGameMode¶
Returning Type: int
Prototype: int xsGetVictoryPlayerForSecondaryGameMode()
Returns 1
when no secondary game mode is set. Returns the number of the player who owns the monument in game modes like KotH
5.50. xsGetVictoryTime¶
Returning Type: int
Prototype: int xsGetVictoryTime()
For game modes like KoTH and other game modes where there is a timer on the screen, it returns the amount of time left in half seconds. meaning if the value returned is 799, it means there are 399.5s remaining. Returns -1
otherwise
5.51. xsGetVictoryTimeForSecondaryGameMode¶
Returning Type: int
Prototype: int xsGetVictoryTimeForSecondaryGameMode()
For game modes like KoTH and other game modes where there is a timer on the screen, it returns the amount of time left in half seconds. meaning if the value returned is 799, it means there are 399.5s remaining. Returns -1
otherwise
5.52. xsGetVictoryType¶
Returning Type: int
Prototype: int xsGetVictoryType()
Returns an integer corresponding to different victory settings in game. These are:
0: Standard
1: Conquest
2: Time Limit
3: Score
4: Custom (scenarios only).
Last Man Standing returns 0 as well.
5.53. xsIsObjectAvailable¶
Returning Type: bool
Prototype: bool xsIsObjectAvailable(int objectId, int playerId)
Parameters:
int objectId
: The object to check the availability forint playerId
: The player to get the object's availability for
Returns true if this object can currently be trained or built.
5.54. xsObjectHasAction¶
Returning Type: bool
Prototype: bool xsObjectHasAction(int playerId, int objectOrClassId, int actionId, int targetPlayerId, int targetType, int targetUnitLevel)
Parameters:
int playerId
: The player to check unit actions forint objectOrClassId
: The ID of the object or class to check actions forint actionId
: The type of action to check for- (Optional)
int targetPlayerId
: Check if the action is being performed on a unit (eg. attacking) of this player. Can use -1 to ignore this filter. - (Optional)
int targetType
: Check if the action is being performed on a unit of this type. Values 9xx refer to classes. Can use -1 to ignore this filter. - (Optional)
int targetUnitLevel
: Check if the action is being performed on a unit with thisInterface Kind
(look in the A.G.E.), eg: 3 - villagers, 4 - most military units. Can be used as an alternative totargetType
. If both are used, will pick units that match either. Can use -1 to ignore this filter.
Checks and returns if any unit matching the set filters of the given player has the specified action.
5.55. xsPlayerAttribute¶
Returning Type: float
Prototype: float xsPlayerAttribute(int playerNumber, int resourceId)
Parameters:
int playerNumber
: The player to get the resource of (0 for Gaia)int resourceId
: The ID of the resource to get the amount of
Returns the amount the specified resource of the given player.
5.56. xsRemoveTask¶
Returning Type: void
Prototype: void xsRemoveTask(int objectOrClassId, int actionType, int targetObjectOrClassId, int playerId)
Parameters:
int objectOrClassId
: The object or class ID to remove the task from.int actionType
: Task type. Refer to cTaskType constants- (Optional)
int targetObjectOrClassId
: Target object or class ID for the task to filter by. - (Optional)
int playerId
: The player from whose objects the task will be removed. If unspecified or -1, applies to all players except Gaia.
Removes a task from a object if the specified actionType
, objectId
, and Search Wait Time
(set by xsTaskAmount) match an existing task in a object. No other fields are used for filtering (same as when xsTask edits instead of adding a new task)
5.57. xsResearchTechnology¶
Returning Type: bool
Prototype: bool xsResearchTechnology(int techId, bool force, bool techAvailable, int playerNumber)
Parameters:
int techId
: The technology ID to research.bool force
: Force researching the tech even if it is not enabled. To force an unavailable tech, the argumenttechAvailable
must be set to falsebool techAvailable
: This flag determines if it is required to check if a tech is available before researching itint playerNumber
: The player to research the technology for
Returns a boolean based on whether the technology was researched or not.
5.58. xsResetTaskAmount¶
Returning Type: void
Prototype: void xsResetTaskAmount()
Resets all the values of the global XS task struct to their defaults. See also xsTask.
5.59. xsSetPlayerAttribute¶
Returning Type: void
Prototype: void xsSetPlayerAttribute(int playerNumber, int resourceId, float value)
Parameters:
int playerNumber
: The player to set the resource of (0 for Gaia)int resourceId
: The ID of the resource to set the amount offloat value
: The amount to set the resource to
Sets the amount of the specified resource of the given player to the provided value.
5.60. xsSetTriggerVariable¶
Returning Type: void
Prototype: void xsSetTriggerVariable(int variableId, int value)
Parameters:
int variableId
: The ID of the variable to set the value ofint value
: The value to set the variable to
Sets the value of the variable of the given variable ID to the provided value.
5.61. xsSetUnitAttributeHeld¶
Returning Type: bool
Prototype: bool xsSetUnitAttributeHeld(int unitId, float value, int attributeId)
Parameters:
int unitId
: The unit to set the resource held forfloat value
: The amount to set the held resource to- (Optional)
int attributeId
: The ID of the resource to set. If unspecified, sets the first resource which the unit holds
Sets the given unit's amount of the specified resource. The only unit this can currently add extra resources to is the trade cart/cog.
5.62. xsSetUnitBuildPoints¶
Returning Type: bool
Prototype: bool xsSetUnitBuildPoints(int unitId, float value)
Parameters:
int unitId
: The unit to set the build points forfloat value
: The value to set the build points to
Sets the given unit's Build Points
5.63. xsSetUnitCharge¶
Returning Type: bool
Prototype: bool xsSetUnitCharge(int unitId, float value)
Parameters:
int unitId
: The unit to set the charge forfloat value
: The value to set the charge to
Sets the given unit's charge
5.64. xsSetUnitHitpoints¶
Returning Type: bool
Prototype: bool xsSetUnitHitpoints(int unitId, float value)
Parameters:
int unitId
: The unit to set the HP forfloat value
: The value to set the HP to
Sets the given unit's HP
5.65. xsTask¶
Returning Type: void
Prototype: void xsTask(int objectOrClassId, int actionType, int targetObjectOrClassId, int playerId)
Parameters:
int objectOrClassId
: The object or class ID to add the task toint actionType
: Task type. Refer to cTaskType constants- (Optional)
int targetObjectOrClassId
: Target object or class ID for the task to filter by. - (Optional)
int playerId
: The player to whose objects the task will be inserted. If unspecified or -1, applies to all players except Gaia.
Adds a new (or edits an existing) task with the fields previously defined by calls to xsTaskAmount for the specified object at the end of the task list (see A.G.E.). If a task with the specified actionType
, objectId
, and Search Wait Time
(set by xsTaskAmount
) already exists, it is edited instead of a new one being added.
Note that xsTaskAmount
modifies a global task struct which is re-used every time xsTask
is called (For non programmers, this is similar to filling out a form once (the calls to xsTaskAmount) and then submitting multiple copies of it for different people)
5.66. xsTaskAmount¶
Returning Type: void
Prototype: void xsTaskAmount(int taskFieldId, float value)
Parameters:
int taskFieldId
: Specifies which property of the task to change. Refer to cTaskAttr constantsfloat value
: The value to set the task field to
Sets the value of the given field of the global XS task struct to the provided value. See also xsTask. It is recommended to always set all values before inserting or updating a task otherwise the insert/update might fail.
5.67. xsTriggerVariable¶
Returning Type: int
Prototype: int xsTriggerVariable(int variableId)
Parameters:
int variableId
: The ID of the variable to get the value of
Returns the value of the variable of the given variable ID.
6. Read/Write¶
6.1. xsCloseFile¶
Returning Type: bool
Prototype: bool xsCloseFile()
Close the currently opened or created file. Returns true
if the file was successfully closed
6.2. xsCreateFile¶
Returning Type: bool
Prototype: bool xsCreateFile(bool append)
Parameters:
- (Optional)
bool append
: Default:true
. If set tofalse
, this will overwrite any existing file with the same name.
Creates a new (or appends to an existing) .xsdat
file with the same name as the RMS/scenario being played. After invoking this function, the writing functions can be used to write data to the file. Returns true
if the file was successfully created. In a multiplayer game a file is created for each player, and subsequent writes will be duplicated to each player.
6.3. xsGetDataTypeSize¶
Returning Type: int
Prototype: int xsGetDataTypeSize(int type)
Parameters:
int type
: One of thecOffsetXXX
constants may be used as a parameter
Returns the number of bytes used to store a given type value.
6.4. xsGetFilePosition¶
Returning Type: int
Prototype: int xsGetFilePosition()
Gets the byte (0-indexed) of the file that the next read function will start reading from.
6.5. xsGetFileSize¶
Returning Type: int
Prototype: int xsGetFileSize()
Gets the size (in bytes) of the currently open file
6.6. xsOffsetFilePosition¶
Returning Type: bool
Prototype: bool xsOffsetFilePosition(int dataType, bool forward)
Parameters:
int dataType
: The cOffset constants can be used to specify the datatype used for the offset. Integers and floats are 4 bytes long, vectors are 12 bytes long and strings can be of variable length (specified by the 32 bit int preceding the chars of the string)- (Optional)
bool forward
: Default:true
. Setting this tofalse
will make the file position move back
Moves the file position forward (or backward) relative to the current file position, and by an amount of bytes equivalent to reading the given data type
6.7. xsOpenFile¶
Returning Type: bool
Prototype: bool xsOpenFile(string filename)
Parameters:
string filename
: The name of the file to open, without the.xsdat
extension
Opens an existing .xsdat
file in read only mode. After invoking this function, the reading functions can be used to read data from the file. Returns true
if the file was successfully opened. In a multiplayer game, the file being read must exist for all players and contain the same data to avoid an out of sync error
6.8. xsReadFloat¶
Returning Type: float
Prototype: float xsReadFloat()
Reads and returns a float from the previously opened .xsdat
file. Note that this function does not check if the value being read is actually meant to be a float, which means the value being read is bit casted into a float regardless of what it originally was. This function also moves the file position forward by 4 bytes
6.9. xsReadInt¶
Returning Type: int
Prototype: int xsReadInt()
Reads and returns an integer from the previously opened .xsdat
file. Note that this function does not check if the value being read is actually meant to be an integer, which means the value being read is bit casted into an integer regardless of what it originally was. This function also moves the file position forward by 4 bytes
6.10. xsReadString¶
Returning Type: string
Prototype: string xsReadString()
Reads and returns a string from the previously opened .xsdat
file. Note that this function does not check if the value being read is actually meant to be a string, which means the value being read is bit casted into a string regardless of what it originally was. This function also moves the file position forward by 4 bytes + the amount of bytes in the length of the string
6.11. xsReadVector¶
Returning Type: vector
Prototype: vector xsReadVector()
Reads and returns a vector from the previously opened .xsdat
file. Note that this function does not check if the value being read is actually meant to be a vector, which means the value being read is bit casted into a vector regardless of what it originally was. This function also moves the file position forward by 12 bytes
6.12. xsSetFilePosition¶
Returning Type: bool
Prototype: bool xsSetFilePosition(int byteOffset)
Parameters:
int byteOffset
: 0 indexed byte offset to determine which byte to read and return from the file
Sets the byte (0-indexed) of the file that the next read function will start reading from.
6.13. xsWriteFloat¶
Returning Type: bool
Prototype: bool xsWriteFloat(float data)
Parameters:
float data
: The float value to write
Writes a floating point number to the previously created .xsdat
file. Causes an error if a file hasn't been opened before using. Returns true
if the floating point number was successfully written. Floats are written in the 32 bit IEEE 754 format
6.14. xsWriteInt¶
Returning Type: bool
Prototype: bool xsWriteInt(int data)
Parameters:
int data
: The integer to write
Writes an integer to the previously created .xsdat
file. Causes an error if a file hasn't been opened before using. Returns true
if the integer was successfully written. Integers are written as signed 32 bit numbers
6.15. xsWriteString¶
Returning Type: bool
Prototype: bool xsWriteString(string data)
Parameters:
string data
: The string to write
Writes a string to the previously created .xsdat
file. Causes an error if a file hasn't been opened before using. Returns true
if the string was successfully written. A string is written to the file in two parts, an unsigned 32 bit integer (indicates the length of the string) followed by that many bytes making up the actual characters of the string
6.16. xsWriteVector¶
Returning Type: bool
Prototype: bool xsWriteVector(vector data)
Parameters:
vector data
: The vector to write
Writes a vector to the previously created .xsdat
file. Causes an error if a file hasn't been opened before using. Returns true
if the vector was successfully written. Vectors are written as 3 consecutive floating point numbers, one for each coordinate.
7. Ai Scripting¶
7.1. xsGetGoal¶
Returning Type: int
Prototype: int xsGetGoal(int id)
Parameters:
int id
: The goal id/number to get for the current AI
Gets the goal id/number of the current AI
7.2. xsGetStrategicNumber¶
Returning Type: int
Prototype: int xsGetStrategicNumber(int id)
Parameters:
int id
: The SN to get for the current AI
Gets the SN of the current AI
7.3. xsSetGoal¶
Returning Type: int
Prototype: int xsSetGoal(int id, int value)
Parameters:
int id
: The goal id/number to get for the current AIint value
: The value to set the goal id/number to
Sets the goal id/number of the current AI
7.4. xsSetStrategicNumber¶
Returning Type: int
Prototype: int xsSetStrategicNumber(int id, int value)
Parameters:
int id
: The SN to get for the current AIint value
: The value to set the SN to
Sets the SN of the current AI
8. Functions With Seemingly No Practical Use¶
8.1. xsAddRuntimeEvent¶
Returning Type: bool
Prototype: bool xsAddRuntimeEvent(string runtimeName, string functionName, int functionArgument)
Parameters:
string runtimeName
: This is the name of the runtime to create the event in. This should be"Random Map"
for RMS and"Scenario Triggers"
for scenarios. Find which one to use in a general script by using thexsGetMapName(true)
function and checking the extension. To use with an AI, set the runtime name to "Expert" and pass the player number as the argstring functionName
: This is the name of a user defined function that takes a single integer argumentint functionArgument
: This is an integer argument that is passed to the function given to the argumentfunctionName
when this event runs.
A runtime event is called after all the XS code has finished executing but before rules start executing. It calls the function functionName
given to it with the functionArgument
passed to it as a parameter. For programmers familiar with the terminology, this is basically a way to set a callback. It also returns true if the function name given to it exists, otherwise it returns false. Does not work with built-ins
8.2. xsBreakPoint¶
Returning Type: void
Prototype: void xsBreakPoint()
This function is meant to add a break point to the execution of XS code for debugging. This used to cause a crash in crash earlier versions of DE.
8.3. xsDumpArrays¶
Returning Type: void
Prototype: void xsDumpArrays()
This function is supposed to blogs out all XS arrays. Currently, it does absolutely nothing.
8.4. xsGetContextPlayer¶
Returning Type: int
Prototype: int xsGetContextPlayer()
Returns the current context player ID.
8.5. xsGetFunctionID¶
Returning Type: int
Prototype: int xsGetFunctionID(string functionName)
Parameters:
string functionName
: The name of the function to get the hash of
Returns the hash of a given function. This function has no practical application and is probably for internal usage only.
8.6. xsSetContextPlayer¶
Returning Type: void
Prototype: void xsSetContextPlayer(int playerNumber)
Parameters:
int playerNumber
: The player to set the context player to
In other functions involving a playerNumber
argument, the value of the context player is used if -1
is passed as playerNumber
to them. xsEffectAmount
will use the value of the context player as its player if -2
is passed to it as the player argument.