Functions

Written by: Alian713, Kramb, KSneijders

All Available Functions¶

Rules

xsDisableRule xsDisableSelf xsEnableRule xsIsRuleEnabled xsSetRulePriority xsSetRulePrioritySelf xsSetRuleMinInterval xsSetRuleMinIntervalSelf xsSetRuleMaxInterval xsSetRuleMaxIntervalSelf xsEnableRuleGroup xsDisableRuleGroup xsIsRuleGroupEnabled

Vectors

xsVectorGetX xsVectorGetY xsVectorGetZ xsVectorSetX xsVectorSetY xsVectorSetZ xsVectorSet xsVectorLength xsVectorNormalize

Arrays

Maths

abs sqrt pow sin cos tan asin acos atan atan2 atan2v exp ceil floor bitCastToFloat bitCastToInt xsCeilToInt ln log2 log10 round radians degrees dist bitAnd bitOr bitXor bitLsh bitRsh bitNot

Randomization

xsGetRandomNumber xsGetRandomNumberLH xsGetRandomNumberMax

Techs

xsResearchTechnology xsGetTechName xsGetTechState xsGetTechAttribute xsSetTechName xsSetTechDescription xsInitiateResearch xsHasResearchedLocalTechnology xsResearchLocalTechnology

Player

Tasks

xsTaskAmount xsResetTaskAmount xsGetObjectTaskCount xsGetUnitTaskCount xsObjectTaskAmount xsUnitTaskAmount xsGetTaskAmount xsModifyObjectTasks xsModifyUnitTasks xsTask xsRemoveTask

Units And Objects

xsCreateUnit xsRemoveUnit xsGetObjectAttribute xsGetUnitAttribute xsDoesUnitExist xsGetUnitOwner xsGetUnitPosition xsSetUnitPosition xsGetUnitName xsGetObjectName xsGetUnitTargetUnitId xsGetUnitMoveTarget xsGetUnitGroupId xsGetGroupMoveTarget xsIsObjectAvailable xsGetUnitHitpoints xsSetUnitHitpoints xsGetUnitBuildPoints xsSetUnitBuildPoints xsGetUnitObjectId xsGetUnitCopyId xsGetObjectCopyId xsGetUnitClass xsGetObjectClass xsGetUnitType xsGetObjectType xsGetUnitAttributeTypesHeld xsGetUnitAttributeHeld xsSetUnitAttributeHeld xsGetUnitCharge xsSetUnitCharge xsGetGarrisonedInUnitId xsGetGarrisonedUnitIds xsGetObjectCount xsGetObjectCountTotal xsObjectHasAction xsIsObjectValid xsGetPlayerNumberOfObjects xsTrainObject xsSetUnitGatherPoint xsGetUnitGatherPoint xsGetUnitCaption xsSetUnitCaption xsSetUnitName xsGetUnitCivName xsSetUnitCivName xsGetUnitPlayerName xsSetUnitPlayerName xsSetObjectDescription xsGetUnitProperty xsSetUnitProperty xsSetUnitOwner xsFlashUnit xsStopUnit xsBuildUnit xsTaskUnits

Map

xsGetMapName xsGetMapID xsGetMapHeight xsGetMapWidth xsGetColorMood xsSetColorMood xsGetMapSeed xsTriggerVariable xsSetTriggerVariable xsGetMapTileAttribute

Game Info

xsGetNumPlayers xsGetTime xsGetGameTime xsGetWorldTime xsGetTurn xsGetVictoryType xsGetVictoryPlayer xsGetVictoryPlayerForSecondaryGameMode xsGetVictoryTime xsGetVictoryTimeForSecondaryGameMode xsGetVictoryCondition xsGetVictoryConditionForSecondaryGameMode xsGetCivName

Ui

File Io

xsCreateFile xsOpenFile xsWriteString xsWriteInt xsWriteFloat xsWriteVector xsReadString xsReadInt xsReadFloat xsReadVector xsSetFilePosition xsOffsetFilePosition xsCloseFile xsGetFilePosition xsGetDataTypeSize xsGetFileSize

Ai Scripting

xsGetGoal xsGetStrategicNumber xsSetGoal xsSetStrategicNumber xsGetAiSignal xsSetAiSignal xsGetAiScriptGoal xsSetAiScriptGoal

Misc

xsDumpArrays xsGetContextPlayer xsSetContextPlayer xsGetFunctionID xsBreakPoint xsAddRuntimeEvent

Strings

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. 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.3. xsEnableRule¶

Returning Type: void

Prototype: void xsEnableRule(string ruleName)

Parameters:

string ruleName: The name of the rule to enable

Enables the given rule.

1.4. 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.5. xsSetRulePriority¶

Returning Type: void

Prototype: void xsSetRulePriority(string ruleName, int rulePriority)

Parameters:

string ruleName: The name of the rule to set the priority of
int rulePriority: The new priority of the rule

Sets the priority of the given rule.

1.6. 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!

1.7. xsSetRuleMinInterval¶

Returning Type: void

Prototype: void xsSetRuleMinInterval(string ruleName, int interval)

Parameters:

string ruleName: The name of the rule to set the min interval of
int interval: The new min interval of the rule

Sets the min interval of the given rule.

1.8. 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.9. xsSetRuleMaxInterval¶

Returning Type: void

Prototype: void xsSetRuleMaxInterval(string ruleName, int interval)

Parameters:

string ruleName: The name of the rule to set the max interval of
int interval: The new max interval of the rule

Sets the max interval of the given rule.

1.10. 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.11. 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.12. 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.13. 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

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. xsVectorSetX¶

Returning Type: vector

Prototype: vector xsVectorSetX(vector v, float x)

Parameters:

vector v: The vector to modify the X coordinate of
float 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.5. xsVectorSetY¶

Returning Type: vector

Prototype: vector xsVectorSetY(vector v, float y)

Parameters:

vector v: The vector to modify the Y coordinate of
float 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.6. xsVectorSetZ¶

Returning Type: vector

Prototype: vector xsVectorSetZ(vector v, float z)

Parameters:

vector v: The vector to modify the Z coordinate of
float 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!

2.7. xsVectorSet¶

Returning Type: vector

Prototype: vector xsVectorSet(float x, float y, float z)

Parameters:

float x: The value to set the X coordinate to
float y: The value to set the Y coordinate to
float z: The value to set the Z coordinate to

Returns a vector with the given X, Y and Z components.

2.8. 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.9. 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.

3. Arrays¶

3.1. 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.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. 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.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. xsArraySetInt¶

Returning Type: bool

Prototype: bool xsArraySetInt(int arrayId, int index, int value)

Parameters:

int arrayId: The ID of the array to set the value in
int index: The index to set the value of
int 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.7. xsArraySetFloat¶

Returning Type: bool

Prototype: bool xsArraySetFloat(int arrayId, int index, float value)

Parameters:

int arrayId: The ID of the array to set the value in
int index: The index to set the value of
float 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.8. xsArraySetBool¶

Returning Type: bool

Prototype: bool xsArraySetBool(int arrayId, int index, bool value)

Parameters:

int arrayId: The ID of the array to set the value in
int index: The index to set the value of
bool 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.9. xsArraySetString¶

Returning Type: bool

Prototype: bool xsArraySetString(int arrayId, int index, string value)

Parameters:

int arrayId: The ID of the array to set the value in
int index: The index to set the value of
string 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.10. xsArraySetVector¶

Returning Type: bool

Prototype: bool xsArraySetVector(int arrayId, int index, vector value)

Parameters:

int arrayId: The ID of the array to set the value in
int index: The index to set the value of
vector 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.

3.11. xsArrayGetInt¶

Returning Type: int

Prototype: int xsArrayGetInt(int arrayId, int index)

Parameters:

int arrayId: The ID of the array to get the value from
int index: The index to get the value of

Gets and returns the value of the given int array at the specified index.

3.12. xsArrayGetFloat¶

Returning Type: float

Prototype: float xsArrayGetFloat(int arrayId, int index)

Parameters:

int arrayId: The ID of the array to get the value from
int index: The index to get the value of

Gets and returns the value of the given float array at the specified index.

3.13. xsArrayGetBool¶

Returning Type: bool

Prototype: bool xsArrayGetBool(int arrayId, int index)

Parameters:

int arrayId: The ID of the array to get the value from
int index: The index to get the value of

Gets and returns the value of the given bool array at the specified index.

3.14. xsArrayGetString¶

Returning Type: string

Prototype: string xsArrayGetString(int arrayId, int index)

Parameters:

int arrayId: The ID of the array to get the value from
int index: The index to get the value of

Gets and returns the value of the given string array at the specified index.

3.15. xsArrayGetVector¶

Returning Type: vector

Prototype: vector xsArrayGetVector(int arrayId, int index)

Parameters:

int arrayId: The ID of the array to get the value from
int index: The index to get the value of

Gets and returns the value of the given vector array at the specified index.

3.16. xsArrayResizeInt¶

Returning Type: bool

Prototype: bool xsArrayResizeInt(int arrayId, int newSize)

Parameters:

int arrayId: The ID of the array to resize
int newSize: The new size of the array

Resizes the the given int array to the specified size and returns 1.

3.17. xsArrayResizeFloat¶

Returning Type: bool

Prototype: bool xsArrayResizeFloat(int arrayId, int newSize)

Parameters:

int arrayId: The ID of the array to resize
int newSize: The new size of the array

Resizes the the given float array to the specified size and returns 1.

3.18. xsArrayResizeBool¶

Returning Type: bool

Prototype: bool xsArrayResizeBool(int arrayId, int newSize)

Parameters:

int arrayId: The ID of the array to resize
int newSize: The new size of the array

Resizes the the given bool array to the specified size and returns 1.

3.19. xsArrayResizeString¶

Returning Type: bool

Prototype: bool xsArrayResizeString(int arrayId, int newSize)

Parameters:

int arrayId: The ID of the array to resize
int newSize: The new size of the array

Resizes the the given string array to the specified size and returns 1.

3.20. xsArrayResizeVector¶

Returning Type: bool

Prototype: bool xsArrayResizeVector(int arrayId, int newSize)

Parameters:

int arrayId: The ID of the array to resize
int newSize: The new size of the array

Resizes the the given vector array to the specified size and returns 1.

3.21. 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.

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. 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.3. pow¶

Returning Type: float

Prototype: float pow(float x, float y)

Parameters:

float x: The base value
float y: The exponent to raise the base value to

Returns x raised to the power y (x**y).

4.4. 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.5. 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.6. 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.7. 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.8. 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.9. 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.10. 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 of
float 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.11. 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.12. exp¶

Returning Type: float

Prototype: float exp(float x)

Parameters:

float x: The value to find the exp of

Returns \(e^x\)

4.13. 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.14. 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.15. bitCastToFloat¶

Returning Type: float

Prototype: float bitCastToFloat(int number)

Parameters:

int number: The value to reinterpret/bit_cast to float

Reinterprets/Bit casts the given int value to float. Equivalent to std::mem::transmute::<i32, f32>(number)

4.16. bitCastToInt¶

Returning Type: int

Prototype: int bitCastToInt(float number)

Parameters:

float number: The value to reinterpret/bit_cast to int

Reinterprets/Bit casts the given float value to int. Equivalent to std::mem::transmute::<f32, i32>(number)

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

4.18. ln¶

Returning Type: float

Prototype: float ln(float x)

Parameters:

float x: The value to find the natural log of

Returns the natural log

4.19. log2¶

Returning Type: float

Prototype: float log2(float x)

Parameters:

float x: The value to find the log base 2 of

Returns the log base 2

4.20. log10¶

Returning Type: float

Prototype: float log10(float x)

Parameters:

float x: The value to find the log base 10 of

Returns the log base 10

4.21. round¶

Returning Type: float

Prototype: float round(float x, int places)

Parameters:

float x: The value to round
(Optional) int places: The number of decimal places to round to. Capped between 0-8, defaults to 2.

Returns the rounded value

4.22. radians¶

Returning Type: float

Prototype: float radians(float x)

Parameters:

float x: The value to convert to radians

Returns \(\cfrac{\pi}{180} x\)

4.23. degrees¶

Returning Type: float

Prototype: float degrees(float x)

Parameters:

float x: The value to convert to degrees

Returns \(\cfrac{180}{\pi} x\)

4.24. dist¶

Returning Type: float

Prototype: float dist(vector v1, vector v2)

Parameters:

vector v1: The first vector
vector v2: The second vector

Returns the distance (norm-2) between the two vectors

4.25. bitAnd¶

Returning Type: int

Prototype: int bitAnd(int x, int y)

Parameters:

int x: The first number
int y: The second number

Returns x & y

4.26. bitOr¶

Returning Type: int

Prototype: int bitOr(int x, int y)

Parameters:

int x: The first number
int y: The second number

Returns x | y

4.27. bitXor¶

Returning Type: int

Prototype: int bitXor(int x, int y)

Parameters:

int x: The first number
int y: The second number

Returns x ^ y

4.28. bitLsh¶

Returning Type: int

Prototype: int bitLsh(int x, int y)

Parameters:

int x: The first number
int y: The second number

Returns x << y

4.29. bitRsh¶

Returning Type: int

Prototype: int bitRsh(int x, int y)

Parameters:

int x: The first number
int y: The second number

Returns x >> y

4.30. bitNot¶

Returning Type: int

Prototype: int bitNot(int x)

Parameters:

int x: The number to get the 1's compliment for

Returns ~x

5. Randomization¶

5.1. xsGetRandomNumber¶

Returning Type: int

Prototype: int xsGetRandomNumber()

Returns a random number between 0 and 32767.

5.2. 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.3. 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.

6. Techs¶

6.1. xsResearchTechnology¶

Returning Type: bool

Prototype: bool xsResearchTechnology(int techId, bool force, bool techAvailable, int playerId)

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 argument techAvailable must be set to false
bool techAvailable: This flag determines if it is required to check if a tech is available before researching it
int playerId: The player to research the technology for

Returns a boolean based on whether the technology was researched or not.

6.2. xsGetTechName¶

Returning Type: string

Prototype: string xsGetTechName(int techId, int playerId, bool internalName)

Parameters:

int techId: The tech to get the name for
int 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.

6.3. xsGetTechState¶

Returning Type: int

Prototype: int xsGetTechState(int techId, int playerId)

Parameters:

int techId: The tech to get the state for
int playerId: The player to get the tech's state for

Returns one of the cTechState constants based on the tech's status

6.4. xsGetTechAttribute¶

Returning Type: int

Prototype: int xsGetTechAttribute(int playerId, int techId, int techAttribute, int indexOrCostType)

Parameters:

int playerId: The player to get the tech's attribute for
int techId: The tech to get the attribute for
int techAttribute: The tech attribute to get. See the cTech constants
int indexOrCostType: The train location index when getting research location specific attributes or a resource ID when getting costs

Gets the specific tech attribute for the supplied tech for the given player.

6.5. xsSetTechName¶

Returning Type: void

Prototype: void xsSetTechName(int techId, int playerId, string description)

Parameters:

int techId: The tech to set the name for
int playerId: The player to set the tech name for
string description: The name to set to

Sets the tech name for the supplied tech for the given player.

6.6. xsSetTechDescription¶

Returning Type: void

Prototype: void xsSetTechDescription(int techId, int playerId, string description)

Parameters:

int techId: The tech to set the description for
int playerId: The player to set the tech description for
string description: The description to set to

Sets the tech description for the supplied tech for the given player.

6.7. xsInitiateResearch¶

Returning Type: bool

Prototype: bool xsInitiateResearch(int buildingId, int techId)

Parameters:

int buildingId: The building to initiate the research at
int techId: The tech to research

Same as the editor effect. Starts researching a technology at a specific building. The tech must be available/the player must have sufficient resources to research the tech. The resources are deducted from the player's stockpile on research.

6.8. xsHasResearchedLocalTechnology¶

Returning Type: bool

Prototype: bool xsHasResearchedLocalTechnology(int buildingId, int localTechId)

Parameters:

int buildingId: The building to check local techs at
int localTechId: The local tech to check

Checks if a local tech has been researched at the given building.

6.9. xsResearchLocalTechnology¶

Returning Type: bool

Prototype: bool xsResearchLocalTechnology(int buildingId, int localTechId)

Parameters:

int buildingId: The building to research a local tech at
int localTechId: The local tech to research

Researches the given local tech at the specified building if it is available. Same as the editor effect.

7. Player¶

7.1. xsEffectAmount¶

Returning Type: void

Prototype: void xsEffectAmount(int effectId, int objectOrTechnologyId, int attributeOrOperation, float value, int playerId, int trainLocationIndex)

Parameters:

int effectId: The ID of the effect to use. See the Effect Type and Technology Attribute constants
int objectOrTechnologyId: The ID of the object, unit, or technology to effect
int attributeOrOperation: The attribute to modify or the operation to perform, See the Effect Operation constants
float value: The value of the effect
(Optional) int playerId: The player to apply the effect to. If unspecified, applies to all players except Gaia.
(Optional) int trainLocationIndex: Specifies the train location entry mod when setting train location related attributes on techs and objects. When not set, defaults to using the train location entry mod value on the object itself

Change the specified attribute of the specified object or technology by the value for the specified player. Note that values for certain attributes such as sound events require to be passed after being converted using bitCastToFloat.

7.2. xsGetPlayerUnitIds¶

Returning Type: int

Prototype: int xsGetPlayerUnitIds(int playerId, int objectOrClassId, int arrayId)

Parameters:

int playerId: The player to get the unit IDs for
int 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

7.3. xsGetHandicapMultiplier¶

Returning Type: float

Prototype: float xsGetHandicapMultiplier(int playerId)

Parameters:

int playerId: The player to get the handicap for

Returns the handicap multiplier for the given player (a float between 1 and 2)

7.4. xsGetWorldPlayerId¶

Returning Type: int

Prototype: int xsGetWorldPlayerId(int scxPlayerId)

Parameters:

int scxPlayerId: The player to get the world index (lobby slot) for

Returns the lobby slot corresponding to the player number (usually the same as color) in the scenario.

7.5. xsGetPlayerCivilization¶

Returning Type: int

Prototype: int xsGetPlayerCivilization(int playerId)

Parameters:

int playerId: 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

7.6. xsGetPlayerInGame¶

Returning Type: bool

Prototype: bool xsGetPlayerInGame(int playerId)

Parameters:

int playerId: Check if this player is still alive

Returns true if the player given is still alive, and false otherwise.

7.7. xsGetPlayerNumberOfTechs¶

Returning Type: int

Prototype: int xsGetPlayerNumberOfTechs(int playerId)

Parameters:

int playerId: The player whose technology count is being requested.

Returns the number of technologies available to the player in the entire game.

7.8. xsPlayerAttribute¶

Returning Type: float

Prototype: float xsPlayerAttribute(int playerId, int resourceId)

Parameters:

int playerId: 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.

7.9. xsSetPlayerAttribute¶

Returning Type: void

Prototype: void xsSetPlayerAttribute(int playerId, int resourceId, float value)

Parameters:

int playerId: The player to set the resource of (0 for Gaia)
int resourceId: The ID of the resource to set the amount of
float value: The amount to set the resource to

Sets the amount of the specified resource of the given player to the provided value.

7.10. xsGetPlayerName¶

Returning Type: string

Prototype: string xsGetPlayerName(int playerId)

Parameters:

int playerId: The lobby index of the player

Returns the given player's name.

7.11. xsGetPlayerType¶

Returning Type: int

Prototype: int xsGetPlayerType(int playerId)

Parameters:

int playerId: The player to get the type for

Returns the type of player. Refer to the Constant Reference for all the different player types

7.12. xsGetDiplomacy¶

Returning Type: int

Prototype: int xsGetDiplomacy(int sourcePlayerId, int targetPlayerId)

Parameters:

int sourcePlayerId: The player to get the stance for
int targetPlayerId: The player to get the stance towards

Returns the source player's stance towards the target player

7.13. xsSetDiplomacy¶

Returning Type: bool

Prototype: bool xsSetDiplomacy(int sourcePlayerId, int targetPlayerId, int diploStance, bool mirror)

Parameters:

int sourcePlayerId: The player to set the stance for
int targetPlayerId: The player to set the stance towards
int diploStance: The stance to set
(Optional) bool mirror: If true, make the target player set their stance towards the source player to the same.

Sets the diplomacy of source player towards the target player

7.14. xsGetDifficulty¶

Returning Type: int

Prototype: int xsGetDifficulty()

Returns the difficulty setting for the game. Refer to the Constant Reference for all the different difficulty IDs

7.15. xsDeclareVictory¶

Returning Type: void

Prototype: void xsDeclareVictory(int playerId, bool victory)

Parameters:

int playerId: The player to make win
(Optional) bool victory: If unset, defeat the player instead

Makes a player win or lose the game

7.16. xsGetPlayerCivName¶

Returning Type: string

Prototype: string xsGetPlayerCivName(int playerId, bool localized)

Parameters:

int playerId: The player to get the civ name for
(Optional) bool localized: If true, localize the civ name

Gets the given player's civ name

7.17. xsSetPlayerCivName¶

Returning Type: bool

Prototype: bool xsSetPlayerCivName(int playerId, string name)

Parameters:

int playerId: The player to set the civ name for
string name: The civ name to set to

Sets the given player's civ name to the specified value.

7.18. xsSetPlayerName¶

Returning Type: bool

Prototype: bool xsSetPlayerName(int playerId, string name)

Parameters:

int playerId: The player to set the name for
string name: The name to set to

Sets the given player's name for the remainder of this game to the specified value

7.19. xsSetPlayerColor¶

Returning Type: bool

Prototype: bool xsSetPlayerColor(int playerId, int colorId)

Parameters:

int playerId: The player to set the color for
int colorId: The color to set to

Sets the given player's color to the specified value

7.20. xsSetChatToPlayer¶

Returning Type: void

Prototype: void xsSetChatToPlayer(int targetPlayer, bool enabled)

Parameters:

int targetPlayer: The player to set the chat setting for
bool enabled: The value to set the chat setting to

Sets the local player's chat setting towards the given player. To be used along with diplomacy-related effects

8. Tasks¶

8.1. 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 constants
float 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.

8.2. xsResetTaskAmount¶

Returning Type: void

Prototype: void xsResetTaskAmount()

Resets all the values of the global XS task struct to their defaults. See also xsTask.

8.3. xsGetObjectTaskCount¶

Returning Type: int

Prototype: int xsGetObjectTaskCount(int objectId, int playerId)

Parameters:

int objectId: The ID of the object to get the number of tasks for
int playerId: The player whose object to get the number of tasks for

Returns the number of tasks the specific object for the given player has

8.4. xsGetUnitTaskCount¶

Returning Type: int

Prototype: int xsGetUnitTaskCount(int unitId)

Parameters:

int unitId: The ID of the object to get the number of tasks for

Returns the number of tasks the given unit has

8.5. xsObjectTaskAmount¶

Returning Type: bool

Prototype: bool xsObjectTaskAmount(int objectId, int playerId, int taskId)

Parameters:

int objectId: The ID of the object to get the task for
int playerId: The player whose object to get the task for
int taskId: The ID (index) of the task to get

Copies the provided task of the specific object from the given player into XS' global task struct

8.6. xsUnitTaskAmount¶

Returning Type: bool

Prototype: bool xsUnitTaskAmount(int unitId, int taskId)

Parameters:

int unitId: The ID of the unit to get the task for
int taskId: The ID (index) of the task to get

Copies the provided task of the specific unit into XS' global task struct

8.7. xsGetTaskAmount¶

Returning Type: float

Prototype: float xsGetTaskAmount(int taskFieldId)

Parameters:

int taskFieldId: The task field to ge the value for. Refer to the Constant Reference for all the different task field IDs

Returns the given task field from XS' global task struct.

8.8. xsModifyObjectTasks¶

Returning Type: bool

Prototype: bool xsModifyObjectTasks(int objectId, int playerId, int taskId, bool edit)

Parameters:

int objectId: The ID of the object to modify the task for
int playerId: The player whose object to modify the task for
int taskId: The index to insert the task at
(Optional) bool edit: If true, edit the task at the given index instead of inserting (ignored with negative indices)

A copy of the global XS task struct is inserted at the provided index in the task list of the specified object for the given player.

ID N will insert the task at index N
When edit = true, edit an existing task instead of inserting one.
ID -(N+1) will remove the task at index N

8.9. xsModifyUnitTasks¶

Returning Type: bool

Prototype: bool xsModifyUnitTasks(int unitId, int taskId, bool edit)

Parameters:

int unitId: The ID of the unit on the map to modify the task for
int taskId: The index to insert the task at
(Optional) bool edit: If true, edit the task at the given index instead of inserting (ignored with negative indices)

A copy of the global XS task struct is inserted at the provided index in the task list of the specified unit.

ID N will insert the task at index N
When edit = true, edit an existing task instead of inserting one.
ID -(N+1) will remove the task at index N

8.10. xsTask¶

Deprecated: True

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 to
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 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)

8.11. xsRemoveTask¶

Deprecated: True

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)

9. Units And Objects¶

9.1. xsCreateUnit¶

Returning Type: int

Prototype: int xsCreateUnit(int objectId, int playerId, vector location, bool foundation, bool playCreatedSound, bool checkCollision)

Parameters:

int objectId: The ID of the object to create
int playerId: The player to create the unit for
vector location: The location to create the unit at
(Optional) bool foundation: If true, create a foundation (ignored for non buildings)
(Optional) bool playCreatedSound: If false, don't play the unit creation sound
(Optional) bool checkCollision: If false, don't check for collision before creating the unit

Creates a unit on the map and returns its ID, or -1 if creation failed

9.2. xsRemoveUnit¶

Returning Type: bool

Prototype: bool xsRemoveUnit(int unitId)

Parameters:

int unitId: The unit to remove

Removes the given unit from the map

9.3. 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 for
int objectId: The object to get the attribute for
int attribute: The attribute to get
int damageClass: For use with armor/attack attributes - specifies which armor/attack class to get. Also specifies the train location entry mod when getting train location related attributes. When not set, defaults to using the train location entry mod value on the unit itself

Returns the attribute value for an object. Note that values for certain attributes such as sound events must be converted using bitCastToInt after being returned.

9.4. xsGetUnitAttribute¶

Returning Type: float

Prototype: float xsGetUnitAttribute(int unitId, int attribute, int damageClassOrEntryMod)

Parameters:

int unitId: The unit to get the attribute for.
int attribute: The attribute to get
int damageClassOrEntryMod: For use with armor/attack attributes - specifies which armor/attack class to get. Also specifies the train location entry mod when getting train location related attributes. When not set, defaults to using the train location entry mod value on the unit itself

Returns the attribute value for a specific unit on the map. Note that values for certain attributes such as sound events must be converted using bitCastToInt after being returned.

9.5. 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.

9.6. 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.

9.7. 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.

9.8. xsSetUnitPosition¶

Returning Type: bool

Prototype: bool xsSetUnitPosition(int unitId, vector position, bool checkCollision)

Parameters:

int unitId: The unit to set the position for
vector position: The position to set
(Optional) bool checkCollision: If false, don't check for collision before moving the unit

Sets the given unit's position.

9.9. 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

9.10. xsGetObjectName¶

Returning Type: string

Prototype: string xsGetObjectName(int objectId, int playerId, bool internalName)

Parameters:

int objectId: The object to get the name for
int 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.

9.11. 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

9.12. 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

9.13. 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

9.14. 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

9.15. xsIsObjectAvailable¶

Returning Type: bool

Prototype: bool xsIsObjectAvailable(int objectId, int playerId)

Parameters:

int objectId: The object to check the availability for
int playerId: The player to get the object's availability for

Returns true if this object can currently be trained or built.

9.16. 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

9.17. xsSetUnitHitpoints¶

Returning Type: bool

Prototype: bool xsSetUnitHitpoints(int unitId, float value)

Parameters:

int unitId: The unit to set the HP for
float value: The value to set the HP to

Sets the given unit's HP

9.18. 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

9.19. xsSetUnitBuildPoints¶

Returning Type: bool

Prototype: bool xsSetUnitBuildPoints(int unitId, float value)

Parameters:

int unitId: The unit to set the build points for
float value: The value to set the build points to

Sets the given unit's Build Points

9.20. 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

9.21. 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

9.22. xsGetObjectCopyId¶

Returning Type: int

Prototype: int xsGetObjectCopyId(int playerId, int objectId)

Parameters:

int playerId: The player to get the object's copy ID for
int objectId: The object to get the copy ID for

Returns the given object's copy ID in data for the specified player

9.23. 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

9.24. xsGetObjectClass¶

Returning Type: int

Prototype: int xsGetObjectClass(int playerId, int objectId)

Parameters:

int playerId: The player to get the object's class for
int objectId: The object to get the class for

Returns the given object's class for the specified player. See cClass constants

9.25. 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

9.26. xsGetObjectType¶

Returning Type: int

Prototype: int xsGetObjectType(int playerId, int objectId)

Parameters:

int playerId: The player to get the object's type for
int objectId: The object to get the type for

Returns the given object's type for the specified player. See cObjectType constants

9.27. 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.

9.28. 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.

9.29. xsSetUnitAttributeHeld¶

Returning Type: bool

Prototype: bool xsSetUnitAttributeHeld(int unitId, float value, int attributeId)

Parameters:

int unitId: The unit to set the resource held for
float 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.

9.30. 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

9.31. xsSetUnitCharge¶

Returning Type: bool

Prototype: bool xsSetUnitCharge(int unitId, float value)

Parameters:

int unitId: The unit to set the charge for
float value: The value to set the charge to

Sets the given unit's charge

9.32. xsGetGarrisonedInUnitId¶

Returning Type: int

Prototype: int xsGetGarrisonedInUnitId(int unitId)

Parameters:

int unitId: The unit to get the garrisoned in

Returns the ID of the unit in which this unit is garrisoned in

9.33. xsGetGarrisonedUnitIds¶

Returning Type: int

Prototype: int xsGetGarrisonedUnitIds(int unitId)

Parameters:

int unitId: The unit to get the garrisoned objects for

Returns an int array which contains the IDs of all the units garrisoned inside this unit

9.34. xsGetObjectCount¶

Returning Type: int

Prototype: int xsGetObjectCount(int playerId, int objectOrClassId)

Parameters:

int playerId: The player to get the object count for
int 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

9.35. xsGetObjectCountTotal¶

Returning Type: int

Prototype: int xsGetObjectCountTotal(int playerId, int objectOrClassId)

Parameters:

int playerId: The player to get the object count for
int 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

9.36. 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 for
int objectOrClassId: The ID of the object or class to check actions for
int 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 this Interface Kind (look in the A.G.E.), eg: 3 - villagers, 4 - most military units. Can be used as an alternative to targetType. 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.

9.37. xsIsObjectValid¶

Returning Type: bool

Prototype: bool xsIsObjectValid(int objectId, int playerId)

Parameters:

int objectId: The object ID to check
int playerId: The player to check the ID for

Checks if the supplied object ID is valid for the given player (e.g. Gaia only units)

9.38. xsGetPlayerNumberOfObjects¶

Returning Type: int

Prototype: int xsGetPlayerNumberOfObjects(int playerId)

Parameters:

int playerId: The player to get the number of data objects for

Returns the number of data objects for this player

9.39. xsTrainObject¶

Returning Type: bool

Prototype: bool xsTrainObject(int buildingId, int objectId, int count)

Parameters:

int buildingId: The building to train the objects at
int objectId: The ID of the object to train
int count: The number of objects to queue

Queues the given number of objects at the specified building. The object must be available at the building and the player must have sufficient resources to queue all the units. If resources are insufficient to cover all of the units, only units which can be afforded are queued. Resources are deducted from the player for this. Note: The base ID of upgraded units must be used, i.e. to train an Arbalest at the Archery Range, the objectId specified needs to be of the Archer itself. Same as the editor effect.

9.40. xsSetUnitGatherPoint¶

Returning Type: bool

Prototype: bool xsSetUnitGatherPoint(int buildingId, vector position, int unitId)

Parameters:

int buildingId: The building to set the gather point of
vector position: The position at which the gather point should be set
(Optional) int unitId: If specified, set the gather point on this unit. Takes priority over position

Sets the gather point of the given building to the specified location/unit

9.41. xsGetUnitGatherPoint¶

Returning Type: vector

Prototype: vector xsGetUnitGatherPoint(int buildingId)

Parameters:

int buildingId: The building to get the gather point for

Gets the gather point of the specified building. If the gather point is set on an object, the Z value of the vector contains the unit ID. In that case, the X and Y values should be ignored.

9.42. xsGetUnitCaption¶

Returning Type: string

Prototype: string xsGetUnitCaption(int unitId)

Parameters:

int unitId: The unit to get the caption for

Gets the specified unit's caption string.

9.43. xsSetUnitCaption¶

Returning Type: bool

Prototype: bool xsSetUnitCaption(int unitId, string caption)

Parameters:

int unitId: The unit to set the caption for.
string caption: The caption string to set to

Sets the specified unit's caption to the given string.

9.44. xsSetUnitName¶

Returning Type: bool

Prototype: bool xsSetUnitName(int unitId, string name)

Parameters:

int unitId: The unit to set the name for
string name: The name to set to

Sets the given unit's name.

9.45. xsGetUnitCivName¶

Returning Type: string

Prototype: string xsGetUnitCivName(int unitId, bool localized)

Parameters:

int unitId: The unit to get the civ name for
(Optional) bool localized: If true, localize the civ name

Gets the given unit's civ name.

9.46. xsSetUnitCivName¶

Returning Type: bool

Prototype: bool xsSetUnitCivName(int unitId, string name)

Parameters:

int unitId: The unit to set the civ name for
string name: The name to set as the civ name

Sets the given unit's civ name to the specified value.

9.47. xsGetUnitPlayerName¶

Returning Type: string

Prototype: string xsGetUnitPlayerName(int unitId)

Parameters:

int unitId: The unit to get the player name for

Gets the given unit's player name.

9.48. xsSetUnitPlayerName¶

Returning Type: bool

Prototype: bool xsSetUnitPlayerName(int unitId, string name)

Parameters:

int unitId: The unit to set the player name for
string name: The name to set the player name to

Sets the given unit's player name to the specified value.

9.49. xsSetObjectDescription¶

Returning Type: bool

Prototype: bool xsSetObjectDescription(int playerId, int objectId, string description)

Parameters:

int playerId: The player to set the object description for
int objectId: The ID of the object to set the description for
string description: The description to set

Sets the given object's description to the specified value for the provided player.

9.50. xsGetUnitProperty¶

Returning Type: float

Prototype: float xsGetUnitProperty(int unitId, int property, int typeOrPlayer)

Parameters:

int unitId: The unit to get the property for
int property: The property to get. See cUnit Property Constants
(Optional) int typeOrPlayer: Resource ID when getting attributes held or player when getting unit visibility

Gets the specified property for the given unit.

9.51. xsSetUnitProperty¶

Returning Type: bool

Prototype: bool xsSetUnitProperty(int unitId, int property, float value, int typeOrForce)

Parameters:

int unitId: The unit to set the property for
int property: The property to set. See cUnit Property Constants
float value: The value to set the property to
(Optional) int typeOrForce: Resource ID when setting attributes held or force when setting garrisoned in ID or unit visibility

Sets the specified property for the given unit to the provided value.

9.52. xsSetUnitOwner¶

Returning Type: bool

Prototype: bool xsSetUnitOwner(int unitId, int playerId, bool flashObject)

Parameters:

int unitId: The unit to set the owner for
int playerId: The new owner
(Optional) bool flashObject: If false, do not flash the object on ownership change

Changes the owner of the given unit to the specified player. Same as the editor effect.

9.53. xsFlashUnit¶

Returning Type: bool

Prototype: bool xsFlashUnit(int unitId, int playerId, int soundName)

Parameters:

int unitId: The unit to flash
(Optional) int playerId: If set, flash only for this player. Otherwise flash for all players (Default: -1)
(Optional) int soundName: Defaults to "?capture_complete"

Flashes the given unit. Same as the editor effect.

9.54. xsStopUnit¶

Returning Type: bool

Prototype: bool xsStopUnit(int unitId)

Parameters:

int unitId: The unit to stop

Stops the unit. Same as the editor effect.

9.55. xsBuildUnit¶

Returning Type: bool

Prototype: bool xsBuildUnit(int unitIds, int objectId, vector location1, vector location2, bool isShiftQueue, bool isFormationCommand)

Parameters:

int unitIds: The units to task
int objectId: The object to build
vector location1: The location to build at
(Optional) vector location2: When building a wall, the second location to finish the wall at. (Default: cInvalidVector)
(Optional) bool isShiftQueue: If true, shift queue the units
(Optional) bool isFormationCommand: If true, issue a formation command to the units

Tasks the selected units to build the given object at the specified location. The target location must be visible, the building must be available to the selected units, and the player must have sufficient resources to construct the building. Resources are deducted upon building. Same as the editor effect

9.56. xsTaskUnits¶

Returning Type: bool

Prototype: bool xsTaskUnits(int unitIds, int actionType, vector location, int locationUnitId, bool isShiftQueue, bool isFormationCommand, bool shouldPlayUnloadSound, int patrolPoints)

Parameters:

int unitIds: The units to task
int actionType: The action to issue. See cActionType Constants
(Optional) vector location: The location at which to task the units
(Optional) int locationUnitId: The unit to task the selected units to
(Optional) bool isShiftQueue: If true, shift queue the units
(Optional) bool isFormationCommand: If true, issue a formation command to the units
(Optional) bool shouldPlayUnloadSound: If true, play the unload sound when ungarrisoning units
(Optional) int patrolPoints: Array of vectors. When tasking units to patrol, use this if multiple patrol points are desired. isShiftQueue must be set to false when using this.

Tasks the selected units to perform the given action. Same as the editor effect.

10. Map¶

10.1. 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.

10.2. xsGetMapID¶

Returning Type: int

Prototype: int xsGetMapID()

Returns the AI map type.

10.3. xsGetMapHeight¶

Returning Type: int

Prototype: int xsGetMapHeight()

Returns the Height of the map.

10.4. xsGetMapWidth¶

Returning Type: int

Prototype: int xsGetMapWidth()

Returns the Width of the map.

10.5. xsGetColorMood¶

Returning Type: int

Prototype: int xsGetColorMood()

Returns the current color mood of the map. Refer to the Constant Reference for all the different color mood IDs

10.6. xsSetColorMood¶

Returning Type: bool

Prototype: bool xsSetColorMood(int colorMood, int interval)

Parameters:

int colorMood: The color mood to set
(Optional) int interval: The transition duration in seconds

Sets the color mood of the map with a transition time. Refer to the Constant Reference for all the different color mood IDs

10.7. xsGetMapSeed¶

Returning Type: int

Prototype: int xsGetMapSeed()

Gets the current RMS seed or -1 in the editor.

10.8. 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. Note: This only works in a custom scenario

10.9. xsSetTriggerVariable¶

Returning Type: void

Prototype: void xsSetTriggerVariable(int variableId, int value)

Parameters:

int variableId: The ID of the variable to set the value of
int value: The value to set the variable to

Sets the value of the variable of the given variable ID to the provided value. Note: This only works in a custom scenario

10.10. xsGetMapTileAttribute¶

Returning Type: int

Prototype: int xsGetMapTileAttribute(int x, int y, int attributeId)

Parameters:

int x: The X value of the tile to get the attribute of
int y: The Y value fo the tile to get the attribute of
int attributeId: The attribute to get. See cTile constants

Gets the specified attribute for the given tile.

11. Game Info¶

11.1. xsGetNumPlayers¶

Returning Type: int

Prototype: int xsGetNumPlayers()

Returns the number of players in the game

11.2. xsGetTime¶

Returning Type: int

Prototype: int xsGetTime()

Returns the current game time - 1 in seconds

11.3. xsGetGameTime¶

Returning Type: int

Prototype: int xsGetGameTime()

Returns the current game time in seconds

11.4. xsGetWorldTime¶

Returning Type: int

Prototype: int xsGetWorldTime()

Returns the current game time in milliseconds

11.5. xsGetTurn¶

Returning Type: int

Prototype: int xsGetTurn()

Returns the current game tick (called turn). Note: ticks may differ in games and replays

11.6. 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.

11.7. 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.

11.8. 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

11.9. 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

11.10. 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

11.11. xsGetVictoryCondition¶

Returning Type: int

Prototype: int xsGetVictoryCondition()

Returns one of these constants: cStandardVictory cWonderVictory cRelicVictory cKingOfTheHillVictory

11.12. xsGetVictoryConditionForSecondaryGameMode¶

Returning Type: int

Prototype: int xsGetVictoryConditionForSecondaryGameMode()

Returns one of these constants: cStandardVictory cWonderVictory cRelicVictory cKingOfTheHillVictory

11.13. xsGetCivName¶

Returning Type: string

Prototype: string xsGetCivName(int civId, bool localized)

Parameters:

int civId: The
(Optional) bool localized: If true, localize the civ name

Gets the given civ's name

12. Ui¶

12.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

12.2. xsGetLocale¶

Returning Type: int

Prototype: int xsGetLocale()

Gets the locale of the current player. See the cLocale constants. Note: this function returns a unique value for every player, and should only be used for strings/chat/UI related functionality, otherwise it will cause a desync.

12.3. xsGetString¶

Returning Type: string

Prototype: string xsGetString(int stringId, bool localized)

Parameters:

int stringId: The string ID to get
(Optional) bool localized: If true, localize the returned string based on the current langauge of the player. Note: Using this parameter will make this function possibly return a unique value for different players, and should only be used for strings/chat/UI related functionality, otherwise it will cause a desync.

Gets the string associated with a given string ID

12.4. xsGetPlayerAttributeName¶

Returning Type: string

Prototype: string xsGetPlayerAttributeName(int stringId, bool localized)

Parameters:

int stringId: The resource ID to get the editor name for
(Optional) bool localized: If true, localize the returned string based on the current langauge of the player. Note: Using this parameter will make this function possibly return a unique value for different players, and should only be used for strings/chat/UI related functionality, otherwise it will cause a desync.

12.5. xsGetObjectAttributeName¶

Returning Type: string

Prototype: string xsGetObjectAttributeName(int attributeId, bool localized)

Parameters:

int attributeId: The ID of the attribute to get the name for
(Optional) bool localized: If true, localize the returned string based on the current langauge of the player. Note: Using this parameter will make this function possibly return a unique value for different players, and should only be used for strings/chat/UI related functionality, otherwise it will cause a desync.

12.6. xsGetDamageClassName¶

Returning Type: string

Prototype: string xsGetDamageClassName(int damageClassId, bool localized)

Parameters:

int damageClassId: The ID of the damage class to get the name for
(Optional) bool localized: If true, localize the returned string based on the current langauge of the player. Note: Using this parameter will make this function possibly return a unique value for different players, and should only be used for strings/chat/UI related functionality, otherwise it will cause a desync.

12.7. xsPlaySound¶

Returning Type: bool

Prototype: bool xsPlaySound(string eventOrSoundFileName, int playerId, vector position, float angle, int unitId, bool global)

Parameters:

string eventOrSoundFileName: The sound event name to fire for the given unitId or the sound file name to play
(Optional) int playerId: If set to -1, play for all players. Otherwise play only for the specified player.
(Optional) vector position: If set, play a local sound at this position.
(Optional) float angle: If set, play a directional sound from the specified position.
(Optional) int unitId: If set, play the sound from this unit.
(Optional) bool global: If set, play the sound on the whole map.

12.8. xsDisplayInstructions¶

Returning Type: bool

Prototype: bool xsDisplayInstructions(string msg, int time, int sourcePlayer, int iconObjectId, int panelPosition, bool useTagColorForIcon, bool playNotificationSound, string soundFilename, int playerId)

Parameters:

string msg: The message to show
int time: The time to show the instructions for in seconds
int sourcePlayer: The player to use for the icon's civ and colour
(Optional) int iconObjectId: If set, shows the icon of this object on the instruction panel
(Optional) int panelPosition: The location to show the instructions panel in. Default: cPanelTop. See the cPanel constants
(Optional) bool useTagColorForIcon: If set, uses the <TAG> color used in msg for the icon as well.
(Optional) bool playNotificationSound: If unset, do not play the instruction notification sound.
(Optional) string soundFilename: If playSound is enabled, plays this sound file.
(Optional) int playerId: If set to -1, show for all players. Otherwise show only for the specified player.

Same as the Display Instructions editor effect.

12.9. xsClearInstructions¶

Returning Type: bool

Prototype: bool xsClearInstructions(int panelPosition, int playerId)

Parameters:

(Optional) int panelPosition: The location to clear the instructions panel in. Default: cPanelTop. See the cPanel constants
(Optional) int playerId: If set to -1, clear for all players. Otherwise clear only for the specified player.

Same as the Clear Instructions editor effect.

12.10. xsDisplayTimer¶

Returning Type: bool

Prototype: bool xsDisplayTimer(int timerId, string msg, int time, int timerUnit, bool resetTimer, int playerId)

Parameters:

int timerId: The timer ID to use to show the instructions for in seconds
string msg: The message to show. You may use or %d to substitute a formatted timer value
int time: The timeout for the timer
(Optional) int timerUnit: The unit for the timer. Default: cTimerUnitSeconds, see the cTimerUnit constants
(Optional) bool resetTimer: If unset, duplicate the timer. Note: Do not unset this unless you know what you're doing.
(Optional) int playerId: If set to -1, show for all players. Otherwise show only for the specified player.

Same as the Display Timer editor effect.

12.11. xsClearTimer¶

Returning Type: bool

Prototype: bool xsClearTimer(int timerId, int playerId)

Parameters:

int timerId: The timer ID to clear
(Optional) int playerId: If set to -1, clear for all players. Otherwise clear only for the specified player.

Same as the Clear Timer editor effect.

12.12. xsUnsyncGetTimerTimeRemaining¶

Returning Type: float

Prototype: float xsUnsyncGetTimerTimeRemaining(int timerId, int timerUnit, int playerId)

Parameters:

int timerId: The timer ID to clear
(Optional) int timerUnit: The unit for the timer. Default: cTimerUnitSeconds, see the cTimerUnit constants
(Optional) int playerId: If set to -1, clear for all players. Otherwise clear only for the specified player.

Gets the time remaining for this timer in the specified unit. Note: If a playerId other than -1 is used, this can possibly return different values for different players and will cause a desync! Use with caution!

12.13. xsSendChat¶

Returning Type: bool

Prototype: bool xsSendChat(string msg, int playerId, bool silent)

Parameters:

string msg: The msg to send
(Optional) int playerId: If set to -1, send for all players. Otherwise send only for the specified player.
(Optional) bool silent: If set, do not play the chat notification sound.

Gets the time remaining for this timer in the specified unit. Note: If a playerId other than -1 is used, it can possibly return different values for different players and will cause a desync! Use with caution!

12.14. xsUnsyncGetLocalPlayerId¶

Returning Type: int

Prototype: int xsUnsyncGetLocalPlayerId()

Gets the ID of the local player. The local player is the ID of the current player, and it is different for every player. Do not use this for anything other than chat/UI things, as it will cause a desync!

12.15. xsGetPlayerColorTag¶

Returning Type: string

Prototype: string xsGetPlayerColorTag(int playerId)

Parameters:

int playerId: The player to get the colour prefix () for

Gets the colour prefix (e.g. ) for a given player. See the cColor constants

12.16. xsSetViewPosition¶

Returning Type: bool

Prototype: bool xsSetViewPosition(int playerId, vector position, int duration)

Parameters:

int playerId: The player to set the view position for. Can be set to -1 to apply to all players
vector position: The position to set the view to
(Optional) int duration: If set, scroll to the destination in this amount of time

Sets the given player's camera to the specified position. Same as the editor effect.

12.17. xsUnsyncGetViewPosition¶

Returning Type: vector

Prototype: vector xsUnsyncGetViewPosition(int playerId)

Parameters:

(Optional) int playerId: When specified, only returns a valid vector if the local player matches this

Gets the local player's view position. Note that this is an unsync function and cannot be used raw in MP.

12.18. xsSetZoom¶

Returning Type: bool

Prototype: bool xsSetZoom(int playerId, float zoom, float duration)

Parameters:

int playerId: The player to set the zoom for. Can be set to -1 to apply to all players
float zoom: The zoom level to set to. Clamped between 0.75 (Fully zoomed out) and 1.25 (Fully zoomed in)
(Optional) float duration: If specified, change the zoom to the target value in this amount of time.

Sets the given player's zoom to the specified value.

12.19. xsUnsyncGetZoom¶

Returning Type: float

Prototype: float xsUnsyncGetZoom(int playerId)

Parameters:

(Optional) int playerId: When specified, only returns a valid value if the local player matches this

Gets the local player's zoom. Note that this is an unsync function and cannot be used raw in MP.

12.20. xsUnsyncGetPlayerSelectedUnitIds¶

Returning Type: int

Prototype: int xsUnsyncGetPlayerSelectedUnitIds(int arrayId, int playerId)

Parameters:

(Optional) int arrayId: The array to use
(Optional) int playerId: When specified, only returns a valid value if the local player matches this

Returns an int array with the currently selected unit IDs for the local player. Note that this is an unsync function and cannot be used raw in MP.

12.21. xsUnsyncIsUnitVisible¶

Returning Type: bool

Prototype: bool xsUnsyncIsUnitVisible(int unitId, bool allowInFog, int playerId)

Parameters:

int unitId: The unit to check visibility for
(Optional) bool allowInFog: If true, allow check to pass even if the unit is only seen in the fog and not in the LoS.
(Optional) int playerId: When specified, only returns a valid value if the local player matches this

Checks if the specified unit is visible to the local player. Note that this is an unsync function and cannot be used raw in MP.

13. File Io¶

13.1. xsCreateFile¶

Returning Type: bool

Prototype: bool xsCreateFile(bool append)

Parameters:

(Optional) bool append: Default: true. If set to false, 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.

13.2. 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 .xsdatfile 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

13.3. 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

13.4. 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

13.5. 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

13.6. 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.

13.7. 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

13.8. 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

13.9. 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

13.10. 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

13.11. 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.

13.12. 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 to false 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

13.13. xsCloseFile¶

Returning Type: bool

Prototype: bool xsCloseFile()

Close the currently opened or created file. Returns true if the file was successfully closed

13.14. xsGetFilePosition¶

Returning Type: int

Prototype: int xsGetFilePosition()

Gets the byte (0-indexed) of the file that the next read function will start reading from.

13.15. xsGetDataTypeSize¶

Returning Type: int

Prototype: int xsGetDataTypeSize(int type)

Parameters:

int type: One of the cOffsetXXX constants may be used as a parameter

Returns the number of bytes used to store a given type value.

13.16. xsGetFileSize¶

Returning Type: int

Prototype: int xsGetFileSize()

Gets the size (in bytes) of the currently open file

14. Ai Scripting¶

14.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

14.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

14.3. xsSetGoal¶

Returning Type: void

Prototype: void xsSetGoal(int id, int value)

Parameters:

int id: The goal id/number to get for the current AI
int value: The value to set the goal id/number to

Sets the goal id/number of the current AI

14.4. xsSetStrategicNumber¶

Returning Type: void

Prototype: void xsSetStrategicNumber(int id, int value)

Parameters:

int id: The SN to get for the current AI
int value: The value to set the SN to

Sets the SN of the current AI

14.5. xsGetAiSignal¶

Returning Type: int

Prototype: int xsGetAiSignal(int signalId, bool useLegacyAi)

Parameters:

int signalId: The signal to get the value of
(Optional) bool useLegacyAi: If true, use the legacy signal

Gets the given AI signal value.

14.6. xsSetAiSignal¶

Returning Type: void

Prototype: void xsSetAiSignal(int signalId, int value, bool useLegacyAi)

Parameters:

int signalId: The signal to set the value of
int value: The value to set to
(Optional) bool useLegacyAi: If true, use the legacy signal

Sets the given AI signal value.

14.7. xsGetAiScriptGoal¶

Returning Type: bool

Prototype: bool xsGetAiScriptGoal(int goalId)

Parameters:

int goalId: The goal to check

Checks if the given AI goal is set

14.8. xsSetAiScriptGoal¶

Returning Type: bool

Prototype: bool xsSetAiScriptGoal(int goalId, bool value)

Parameters:

int goalId: The goal to set
bool value: The value to set the goal to

Sets the given AI goal to the specified value

15. Misc¶

15.1. xsDumpArrays¶

Returning Type: void

Prototype: void xsDumpArrays()

This function is supposed to blogs out all XS arrays. Currently, it does absolutely nothing.

15.2. xsGetContextPlayer¶

Returning Type: int

Prototype: int xsGetContextPlayer()

Returns the current context player ID.

15.3. 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.

15.4. 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.

15.5. 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.

15.6. 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 the xsGetMapName(true) function and checking the extension. To use with an AI, set the runtime name to "Expert" and pass the player number as the arg
string functionName: This is the name of a user defined function that takes a single integer argument
int functionArgument: This is an integer argument that is passed to the function given to the argument functionName 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

16. Strings¶

16.1. ord¶

Returning Type: int

Prototype: int ord(string character)

Parameters:

string character: The character to get the ASCII ord value for

Returns the ASCII ord value for the given character. Same as Python's ord

16.2. chr¶

Returning Type: string

Prototype: string chr(int code)

Parameters:

int code: The ASCII code to get the character for.

Returns the ASCII character for the given code. Same as Python's chr

16.3. strLen¶

Returning Type: int

Prototype: int strLen(string str)

Parameters:

string str: The string to get the length for

Returns the length of the given string

16.4. strCharAt¶

Returning Type: string

Prototype: string strCharAt(string str, int index)

Parameters:

string str: The string to index
int index: The index to get. Can be in the range [-length, length)

Returns the str[index] as in Python or "" if the index is out of bounds.

16.5. strSubstring¶

Returning Type: string

Prototype: string strSubstring(string str, int start, int end)

Parameters:

string str: The string to substring
int start: The start index. Can be in the range [-length, length)
int end: The end index. Can be in the range [-length, length)

Returns the str[start:end] as in Python or "" if the indices are out of bounds.

16.6. strContains¶

Returning Type: bool

Prototype: bool strContains(string str, string substring)

Parameters:

string str: The string to check
string substring: The sub string to check

Checks if the given substring is contained in the provided string.

16.7. strStartsWith¶

Returning Type: bool

Prototype: bool strStartsWith(string str, string prefix)

Parameters:

string str: The string to check
string prefix: The prefix to check

Checks if the given string starts with the provided prefix.

16.8. strEndsWith¶

Returning Type: bool

Prototype: bool strEndsWith(string str, string suffix)

Parameters:

string str: The string to check
string suffix: The suffix to check

Checks if the given string ends with the provided suffix.

16.9. strRemovePrefix¶

Returning Type: string

Prototype: string strRemovePrefix(string str, string prefix)

Parameters:

string str: The string to remove the prefix from
string prefix: The prefix to remove

Removes the prefix from the given string if present and returns a new string. Returns the original string otherwise.

16.10. strRemoveSuffix¶

Returning Type: string

Prototype: string strRemoveSuffix(string str, string suffix)

Parameters:

string str: The string to remove the suffix from
string suffix: The suffix to remove

Removes the suffix from the given string if present and returns a new string. Returns the original string otherwise.

16.11. strIndexOf¶

Returning Type: int

Prototype: int strIndexOf(string str, string substring, int fromIndex)

Parameters:

string str: The string to check in
string substring: The substring to find the index of
(Optional) int fromIndex: If set, check starting from this index

Finds the index of the given substring in the provided string. Returns -1 if not found

16.12. strLastIndexOf¶

Returning Type: int

Prototype: int strLastIndexOf(string str, string substring, int fromIndex)

Parameters:

string str: The string to check in
string substring: The substring to find the index of
(Optional) int fromIndex: If set, check backwards starting from this index

Finds the index of the given substring in the provided string backwards. Returns -1 if not found

16.13. strReplace¶

Returning Type: string

Prototype: string strReplace(string str, string target, string replacement, int max)

Parameters:

string str: The string to replace in
string target: The substring to replace
string replacement: The replacement for the target
(Optional) int max: If specified, only replace a max of these instances of the target string

Replaces the occurrences of the target in the given string with the replacement and returns it as a new string.

16.14. strInsert¶

Returning Type: string

Prototype: string strInsert(string str, int index, string target)

Parameters:

string str: The string to insert into
int index: The index to insert at
string target: The substring to insert

Inserts the given substring at the provided index in the specified string and returns a new string.

16.15. strRemove¶

Returning Type: string

Prototype: string strRemove(string str, int index, int length)

Parameters:

string str: The string to remove from
int index: The index to remove from
int length: The number of characters to remove

Removes the specified number of characters at the provided index in the given string and returns a new string.

16.16. strSplit¶

Returning Type: int

Prototype: int strSplit(string str, string delimiter, int max)

Parameters:

string str: The string to split
(Optional) string delimiter: The string to split by. If unspecified, split at all characters.
int max: The maximum number of splits to make.

Returns an int ID for an array of strings.

16.17. strJoin¶

Returning Type: string

Prototype: string strJoin(int arrayId, string delimiter)

Parameters:

int arrayId: An int ID for an array of strings
string delimiter: The string to join the array with

Returns a joined string of the provided array interspaced with the given delimiter.

16.18. strTrim¶

Returning Type: string

Prototype: string strTrim(string str)

Parameters:

string str: The string to trim

Removes whitespaces on both sides of the given string and returns a new string.

16.19. strTrimStart¶

Returning Type: string

Prototype: string strTrimStart(string str)

Parameters:

string str: The string to trim

Removes whitespaces at the start of the given string and returns a new string.

16.20. strTrimEnd¶

Returning Type: string

Prototype: string strTrimEnd(string str)

Parameters:

string str: The string to trim

Removes whitespaces at the end of the given string and returns a new string.

16.21. strToUpper¶

Returning Type: string

Prototype: string strToUpper(string str)

Parameters:

string str: The string to convert to uppercase

Returns a new string that is the given string converted to uppercase. Note that only ASCII characters are affected.

16.22. strToLower¶

Returning Type: string

Prototype: string strToLower(string str)

Parameters:

string str: The string to convert to lowercase

Returns a new string that is the given string converted to uppercase. Note that only ASCII characters are affected.

16.23. strReverse¶

Returning Type: string

Prototype: string strReverse(string str)

Parameters:

string str: The string to reverse

Returns a new string that is the original string backwards.

16.24. strToInt¶

Returning Type: int

Prototype: int strToInt(string str, int base, int defaultValue)

Parameters:

string str: The string to parse as an int
(Optional) int base: Defaults to 10
(Optional) int defaultValue: Defaults to -1

Returns the string parsed as an int and returns the default value if it fails

16.25. strToFloat¶

Returning Type: float

Prototype: float strToFloat(string str, float defaultValue)

Parameters:

string str: The string to parse as a float
(Optional) float defaultValue: Defaults to -1.0

Returns the string parsed as a float and returns the default value if it fails

16.26. hex¶

Returning Type: int

Prototype: int hex(string str, int defaultValue)

Parameters:

string str: The hex string to parse. Digits may be separated by '
(Optional) int defaultValue: Defaults to -1

Returns the signed 32-bit base-10 value for the given hex string and returns the default value if it fails

16.27. bin¶

Returning Type: int

Prototype: int bin(string str, int defaultValue)

Parameters:

string str: The bin string to parse. Digits may be separated by '
int defaultValue: Defaults to -1

Returns the signed 32-bit base-10 value for the given binary string and returns the default value if it fails

16.28. fstr¶

Returning Type: string

Prototype: string fstr(string str)

Parameters:

string str: The string to format

Formats the given string like a Python f-string. Note that Expressions are not allowed, and it is limited to variable names only.

Example:

xsChatData(fstr("{colourTag}{player}: {msg}")); // assuming that colourTag, player, and msg are valid variables here.

Similar to Python, you may use {{ and }} to escape the brackets themselves when passing a string to fstr when interpolation is not desired.

The strings passed to fstr do not need to be literal strings. This allows creating multi-language template strings in language files that can be fetched via xsGetString and then passed to fstr for interpretation.

The variable names used inside the {} must be valid identifiers and in scope, or the {} will be left unmodified in the output.