.xs scripting for is a new functionality added to Age of Empires II: Definitive Edition, available with the November 2020 update. It adds another layer of scripting functionality to the existing trigger system in the scenario editorand in random map scripts.
This is official reference for RMS/Trigger functions accessible in AoE2. For a more in-depth guide, including a reference for beginners in programming, as well as the usage of Rules and other XS features, please check out The UGC Guide for XS created by the community!
Summary:
- Make sure function names are unique. (e.g. having multiple functions called Function() will cause a conflict)
- Make sure the function returns the defined type (e.g. bool Function() should return a boolean expression)
- If you wrote a function inside of the Scenario Editor, it will be compiled into an .xs file called default0.xs. These functions will be called automatically for that specific Script Call.
- You must place your .xs scripts in resources\_common\xs
- You can find the Constants.xs file with all constants (like for instance cAttributeStone) and effects (SetAttribute)that can be used within some functions in \resources_common\xs
- When entering the Script Name inside the Editor, you do not need to include the final .xs extension.
- You can define as many functions as you want inside an .xs file.
- To call functions in the Editor, you only need to pass in the function name (e.g. if you had a function called doesPlayerHaveFood() you will only need to write doesPlayerHaveFood in the Script Call textbox.)
Scenario Editor Functions
Function Name | Purpose | Example |
---|---|---|
xsTriggerVariable | Returns the value of the desired Trigger Variable. Syntax: xsTriggerVariable(long triggerVariableId) | // Returns the value of Trigger Variable 0. int getTriggerVariable() { |
xsSetTriggerVariable | Sets a trigger variable to the desired value. Syntax: xsSetTriggerVariable(long triggerVariableId, long value) | // Set Trigger Variable 0 to 100. void setTriggerVariable() { |
xsEffectAmount | Allows you to modify a unit or building with research-style type effects. Set playerId to -1 to apply the change to all players. Syntax: xsEffectAmount(long effect, long itemName, long type, float value, long playerId) | // Modify players starting resources, in this case, set starting stone to 50. void setDefaultStone() { |
xsResearchTechnology | Allows you to research a technology for a specific player. This can be done forcefully without any condition checking. You can also check to research the technology if it’s available. This function will return true if research was successful or false if it was not. Syntax: xsResearchTechnology(long techID, bool force, bool techAvailable, long playerID) | // Research Loom for player 2. void researchLoom() { |
xsGetPlayerNumberOfTechs | Returns the number of technologies a player can research. Syntax: xsGetPlayerNumberOfTechs(long playerID) | // Get the number of technologies from player 3. int getPlayerThreeNumTechs() { |
Random Map Script Functions
Function Name | Purpose | Example |
---|---|---|
xsEffectAmount | Allows you to modify a unit or building with research-style type effects. Set playerId to -1 to apply the change to all players. Syntax: xsEffectAmount(long effect, long itemName, long type, float value, long playerId) | // Modify players starting resources, in this case, set starting stone to 50. void setDefaultStone() { |
Shared Functions
Function Name | Purpose | Example |
---|---|---|
xsChatData | Sends a chat with the desired message/variable. This is useful for testing. Syntax: xsChatData(const char* text, long value) | // Chat player 1’s food. void chatFood() |
xsPlayerAttribute | Returns the value of the desired player attribute. Syntax: xsPlayerAttribute(long playerId, long attribute) | // Get the food amount of player 1. int getPlayerOneFood() |
xsSetPlayerAttribute | Sets the desired player attribute to the value specified. Syntax: xsSetPlayerAttribute(long playerId, long attribute, float value) | // Set player 1 food to 100. void setPlayerOneFood() |
xsGetNumPlayers | Returns the number of players in a match (Excluding Gaia) E.g. if there is 2 players in a match, only 2 is returned. Syntax: xsGetNumPlayers() | // Get the number of players. void getNumberOfPlayers() |
xsGetPlayerCivilization | Returns the civilization ID of a specific player. Syntax: xsGetPlayerCivilization(long playerID) | // Get the civilization ID of player 1 void getPlayerOneCiv() |
xsGetPlayerInGame | Returns true if the specific player is in the game still, if the specified player has been defeated, resigned or dropped from the match, it will return false. Syntax: xsGetPlayerInGame(long playerID) | // Check if player 4 is still in the match. bool isPlayerFourInGame() |
xsGetGameTime | Returns the elapsed game time (in seconds). Syntax: int xsGetGameTime() | // Get the game time. void getGameTime() |
xsGetVictoryPlayer | Returns the player ID of who will win using relics, wonder, monastery or monuments. Syntax: int xsGetVictoryPlayer() | // Get the winning player ID void getWinningPlayer() |
xsGetRandomNumber() | Generate a random number. Syntax: int xsGetRandomNumber() | // Get a random number void rand() |
xsGetRandomNumberLH | Generate a random number using between low and high. Syntax: int xsGetRandomNumberLH(int low, int high) | // Generate a random number between 5 – 10. void randLH() |
xsGetRandomNumberMax(int max) | Generate a random number using a maximum value. Syntax: int xsGetRandomNumberMax(int max) | // Generate a random number with a maximum value of 3. void randMax() |
Read/Write Functions
Function Name | Purpose | Example |
---|---|---|
xsCreateFile | Opens a file with the .xsdat extension for writing to. Returns true if the file was successfully opened to write to. Setting append to false will result in a new file being written and the old one being lost. The file name will use the name of the scenario and random map. Files can only be a maximum of 1 megabyte. Each file is unique to each players profile. bool xsCreateFile(bool append) | // Create a brand new xs data file. void main() |
xsOpenFile | Opens a .xsdat file for reading only. Will return true if file was successfully opened for reading. bool xsOpenFile(string filename) | // Open a file for reading bool load() |
xsWriteString | Writes a string to the file that has been opened using xsCreateFile. Returns true if the write was successful. bool xsWriteString(string data) | // Write a string to the xs data file. bool save() |
xsWriteInt | Writes a integer to the file that has been opened using xsCreateFile. Returns true if the write was successful. bool xsWriteInt(int data) | // Write a integer to the xs data file. bool save() |
xsWriteFloat | Writes a floatto the file that has been opened using xsCreateFile. Returns true if the write was successful. bool xsWriteFloat(float data) | // Write a floatto the xs data file. bool save() |
xsWriteVector | Writes a vector to the file that has been opened using xsCreateFile. Returns true if the write was successful. bool xsWriteVector(vector data) | // Write a vector to the xs data file. bool save() |
xsReadString | Reads a string from the currently opened file at the current file position. Returns a string if successfully read. string xsReadString() | // Read a string from the xs data file extern string text = “”; bool load() |
xsReadInt | Reads a integer from the currently opened file at the current file position. Returns a int if successfully read. int xsReadInt() | // Read a int from the xs data file extern int value = 0; bool load() |
xsReadFloat | Reads a float from the currently opened file at the current file position. Returns a float if successfully read. float xsReadFloat() | // Read a float from the xs data file extern float value = 0; bool load() |
xsReadVector | Reads a vector from the currently opened file at the current file position. Returns a vector if successfully read. vector xsReadVector() | // Read a vector from the xs data file extern vector vectordata = vector(0.0, 0.0, 0.0); bool load() |
xsSetFilePosition | Sets the current position in file directly for the currently opened file. Returns true if it was successful. bool xsSetFilePosition(int pos) | // Set the file position (buffer) to the beginning void parse() |
xsOffsetFilePosition | Jump forward or backward from the current file position by using the desired data type. Returns true if it was successful. Supported data types are: cOffsetString (assumes current position is at a string) cOffsetInterger cOffsetFloat cOffsetVector bool xsOffsetFilePosition(int dataType, bool forward) | // Skip reading an integer void load() |
xsCloseFile | Closing the currently opened file (either by xsCreateFile or xsOpenFile) Returns true if a file was successfully closed. | // Close the currently opened file. void load() |
How to write functions which accept parameters:
If you want to write a function which accepts parameters (e.g. you want to chat the amount of food a player has) you must initialize your parameter variables.
Example on how a function written inside the editor looks:
To use an XS script in a Random Map Script, do the following:
- At the top of your RMS file (before <PLAYER_SETUP>) add #includeXS scriptname.xs
- “scriptname.xs” is the name of the file located in your resources\_common\xs folder. You can put the file name in quotation marks if it contains spaces. Paths relative to the “xs” folder are allowed.
- In the XS file, create a void main() function definition. All of its content will be executed upon loading the Random map script. You can use all general functions and RMS-specific functions (described at the top of this document).