Scenario Editor

From Ashes of the Singularity - Official Wiki
Jump to navigation Jump to search

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. The best advice for seeing what is possible is to look through the \Assets\Campaign\ and \Scenario\ directories and see what the xml files are doing. 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.

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 Ascendancy Wars screen, etc) and global settings like enabling/disabling creeps and hiding terrain, using a <Mission> tag.

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

 

Commands

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

See the main Commands entry for details.

  • 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

The UI for Ashes is defined in XML, it is as moddable as the rest of the game. But we just want to make one small change, we want the game to show us the coordinates. Fortunately there is already a field for that in the UI, it’s just marked hidden. You will find the following toward the end of AshesGameView.xml:

Changing the XML to show locations
Changing the XML to show locations

To have the coordinates be displayed in game, change this to Hidden=”0”. 0 typically means False and 1 means True so by setting it to 0 we are setting it to “Not Hidden”. You may also want to reduce the FontSize, 20 tends to be fairly large but that is up to you.

This will help you get the exact coordinates when you are playing with your map to figure out where you want to place resources, starting locations for player, where you want events or trigger or where you want to spawn new units.

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.