Scenario Editor

Scripting – Creating Scenarios

Scripting allows you a huge amount of control over what exactly happens on the map you are creating. You can restrict what buildings and units the players can use, set up Triggers to lock or unlock them, spawn units or buildings for the players or their enemies. You can send units to attack specific targets and send dialog popups to the player. Everything you need to make your own custom Scenarios.

All of this is stored in XML, not code, so you don’t need any special programming tools or experience to use it. Though, it may be confusing at first and take a while to wrap your head around it. The best advice for seeing what is possible is to look through the \Assets\Campaign\ and \Scenario\ directories and seeing how the existing missions are made. Some examples are also included below.

There are three main elements in Ashes scripting: missions, players and triggers. Missions are the definition or the scenario. Players defines the players that are going to be used in the scenario. Triggers are where all the magic happens. Triggers have a lot of elements and options. There's a lot of terminology to learn for scripting, and not all of them are listed on this page but links are provided throughout to give you the full set of required terms.

Note that all triggers and arguments are case-sensitive.

Mission Definition

First, you set up all the menu-related items (what icons/art to use in the Campaign screen, etc) and global settings like enabling/disabling creeps and hiding terrain.

Player Definition

To do much of anything, you'll need to define players next. This is done with individual <Player> tags that enable or disable their AI, sets faction, team, and color, etc.

You'll likely refer to these players later in the script by number, where 0 is the first player defined, 1 is the next, and so on.

Triggers

Triggers are what control anything you want to happen while the scenario is being played, from spawning starting base to calling waves of attacking enemies or giving players objectives. There are several types of triggers which activate off of different events.

Trigger Types

These are the types of triggers you can use in a script, and any specific arguments they support.

• Area - Fires when the human player moves a unit into the area.

• Build - Fires when a human player builds structures or units.

• Destruction - Fires when something specific dies.

• Difficulty - Fires at the beginning of a scenario if the given difficulty was chosen

• NamedCreate - Fires when a specific unit or building is spawned via a script.

• Research - Fires when a player researches a Quantum Upgrade

• Timer - Fires after a delay.

• Var - Fires if a variable meets given criteria

• ZoneCapture - Fires when a region is captured, is also used for destroying players since their nexus turns into a Turinium Generator.

 

Commands

These are the commands you can put within a trigger to create gameplay effects.

For detailed information about how to use this, read the main Commands entry.

• ActivateTrigger - Activate another trigger (also can be used to activate the trigger it is called from, making a repeating trigger).
• AreaIndicator - This places a visible indicator on the map to help the player know where they should go to.
• AttackAttackMove - Order an army to move to a specific area, engaging enemies along the way.
• AttackUnit - Order an army to attack a specific script-spawned unit
• Camera - Move the player's view to a specific area.
• CaptureNearestNext - Order an army to capture the nearest neutral or enemy-controlled region
• CaptureNearest - Order an army to clear its order queue and capture the nearest neutral or enemy-controlled region (note: ordered unit will stop moving if region is captured before it gets there)
• ChangeAIDifficulty - Change an AI player's difficulty setting
• ChangeAIPersonality - Change an AI player's personality
• DestroyBuilding - Destroys a specific script-spawned building.
• DestroyUnit - Destroys a specific script-spawned unit.
• Dialog - This creates a popup that can convey information or story to the player. Use with <Entry> tags.
• Entry - The actual text that will be displayed. Use only within <Dialog> tags.
• EndMission - Use to force a win or loss of the scenario.
• GrantStuff - Give a player free resources
• GrantTech - Give a player a free Quantum Upgrade
• HidePanel - Hide UI panels
• LetterBox - disable commands and go to a cinematic, letterbox view
• MoveUnit - Move an army to a location without stopping to fight
• Objective - Use this to set objective notifications for the player (so they know what to do).
• Restrict - To block the player from being able to access objects in the game.
• Reveal - Reveal the fog of war over a location
• SpawnBuilding - Places a building on the map.
• SpawnUnit - Places a unit on the map.
• Var - Set or modify a variable. Tip: Set any variable you want to use to 0 in the initial setup trigger to avoid unpredictable results. All values must be integers.

Position Coordinates

To view map coordinates, ensure you have opted into to a modding build under steam betas which allows you to open the developer tools. Open up the the map in a skirmish and press the ` or HOME key, then select DebugPlayerPanel and Enable Show Mouse Position.

Trigger Examples

A single trigger can do any combination of the above options. It can popup some text, spawn some units, set an objective give the player some resources and unlock some new building options. It is up to you how you want to combine and use them. Let’s take a look at some examples.

Send an army to attack

An attack trigger

The above trigger is inactive, meaning it needs another trigger to call it before it will activate. Once it does it will spawn 16 units into an army and send them to attack the defined map position. This is a relatively simple trigger, but a common one. With this alone you can create scenarios that spawn waves to attack the player, grant reinforcements to the player or create surprise ambushes.

Reward the player for capturing an area

A region capture trigger

The above trigger occurs when the player captures the region at the specified position. Notice that the trigger starts inactive, so it would need to be enabled by an earlier trigger before it could occur.

This trigger does the following:

• Checks the Cap_C_Obj objective in the player’s objective list.
• It disables the Cap_B_Ind Area Indicator by setting it’s duration to 0.
• It pops up some dialog for the player.
• It enables the player’s ability to build Metal Extractors.
• It spawns a free Engineer for the player.
• It moves the camera to look at the captured region.
• It adds a new objective for the player (Mex_Built_Obj).
• It gives the player 500 Metal.
• It makes the Cap_C_Trigger trigger active.

This is a great example of the kind of combinations that can be done with the trigger system. This is a reward to the player for capturing the region. But it could as easily have triggered an escalation for the enemy forces.

 

Commenting Out Code

Commenting out code is very useful to disable certain lines but without deleting them so you can easily place them back on. This is also useful for leaving notes so you remember what you are trying to do or just making it neater and easier to navigate. To comment out a section, add "" to the end of what you want commented out.

Fixing Issues

Many things in the Scenario code can cause issues that result a crash or prevent it from working. Here's a list of some common issues that you may encounter and how to fix them.

• Consistent Crash - Often happening at the start of a scenario, if you have a crash that happens every time it is likely the result of trying to spawn a unit or building with an incorrect name. For example, if the game is trying to spawn PHC_Smarty_System" it will find this building name doesn't exist and result in a crash, due to the internal reference name actually being PHC_Smarties. It's vital you get the correct internal reference names, and not all of them match their in-game display
• Empty Campaign Screen - If the campaign screen is empty with no campaigns or scenario missions listed, this means there is a grammar error in one of the scripts which has broken it and made it unable to be ran. You will have to identity the mistake and fix it. For example, having a Trigger without the > on the end or missing a quotation mark can cause this error. Identifying the issue can be time consuming, so it is recommended you make updates in small increments so you know where in the script the cause would be. One strategy to find these mistakes is to comment out entire sections of the script and see if the problem persists. If you have commented out a large portion of the script and then the missions are now showing up, you have narrowed down the cause and you can comment more and more specific sections to location the issue.