Modders Guide: Difference between revisions

From Ashes of the Singularity - Official Wiki
Jump to navigation Jump to search
No edit summary
m (Add comment about My Games/Ashes of the Singularity - Escalation/Mods.ini)
(45 intermediate revisions by 3 users not shown)
Line 1: Line 1:


Ashes is a large scale RTS where you wage war with huge armies over massive areas. You fight for regions to get resources, you fight to protect the areas you control and you fight to destroy your enemy’s armies and infrastructure. In the end you win by destroying their Nexas or controlling enough of the map to win via victory points.
Ashes of the Singularity gives you access to a powerful strategy game engine to create your own scenarios, objects and worlds. The designers have had a lot of fun creating scenarios for the game, and you will have access to the same features they had to create your own.


There is a lot to do in Ashes. But it was also built from the ground up to be mod friendly. Modders have access to the gameplay elements to change and tweak as they desire. This document will introduce some of what is possible, and we will make a map and a mod to take advantage of this.
There is a lot to do in Ashes. But it was also built from the ground up to be mod friendly. Modders have access to the gameplay elements to change and tweak as they desire. This document will introduce some of what is possible, and we will make a map and a mod to take advantage of this.


This is not always going to be a managed and curated editor with limited options. You can mod the game the same way the developers make changes to the game. Editors are nice because they typically keep you from doing “bad” things. But they also keep you from doing incredibly good things. An editor only allows you to do the things the developer setup for you to change. With direct access to the files you can do things the developer never expected. Sometimes that turns out horribly (okay, a lot of the time that turns out horribly), but sometimes it turns out brilliantly. We believe power trumps ease of use.[[File:]]
This is not always going to be a managed and curated editor with limited options. You can mod the game the same way the developers make changes to the game. Editors are nice because they typically keep you from doing “bad” things. But they also keep you from doing incredibly good things. An editor only allows you to do the things the developer set up for you to change. With direct access to the files you can do things the developer never expected. Sometimes that turns out horribly (okay, a lot of the time that turns out horribly), but sometimes it turns out brilliantly. We believe power trumps ease of use.
 
== The Map Editor ==
 
(see [[Map_Editor|the full Map Editor article]] for more)


= The Map Editor =
[[File:ModGuide 1.png|thumb|right|200px|Creating a new map]]To enable the [[Map_Editor|Map Editor]] add the “-modding” (without the quotes) to the Launch Options for the game (in Steam, right-click the game, go to Properties, click Set Launch Options in the General tab). That will add a Map Editor button to the main menu of the game. From there you can decide if you want to modify an existing map, or create a new one. If you create a new one the menu to the right is presented.
<div align="center">
----
</div>
[[File:ModGuide 1.png|right|300px|ModGuide 1.png]]To enable the Map Editor add the “-modding” (without the quotes) to the Launch Options for the game. That will add a Map Editor button to the main menu of the game. From there you can decide if you want to modify an existing map, or create a new one. If you create a new one the menu to the right is presented.


For your first map I’d select a smaller map size. You probably assume that you will run out of space quickly on small maps, you would be wrong. Ashes small maps are what other games would call huge. The large ones are ridiculous and will take a lot of time to design. Practice on some small ones first.
For your first map I’d select a smaller map size. You probably assume that you will run out of space quickly on small maps, you would be wrong. Ashes small maps are what other games would call huge. The large ones are ridiculous and will take a lot of time to design. Practice on some small ones first.


I selected Terran (grassland) terrain and default lighting. As you will see in the demo I change to Frozen terrain later, it’s easy to do so don’t worry too much about your selection here.
[[File:ModGuide 2.png|thumb|left|600px|A new, blank map]]
 
&nbsp;
 
&nbsp;
 
&nbsp;


The following is the default map that you are given. It starts with 2 player Nexas’s (Nexi?), a Turinium Generator and one other region. But we have lots of things we can add.
&nbsp;


[[File:ModGuide 2.png|RTENOTITLE]]
&nbsp;


The most useful functions in the above editor are:
&nbsp;
 
&nbsp;


*'''File'''- This is where you can edit the MapProperties.xml file, go to the folder where the map information is stored or exit the Map Editor. If you want to change the victory point limits for your map then use this option to modify the MapProperties.xml file and regenerate the map.
&nbsp;
*'''Show/Hide Help'''- This displays some useful information for using the Map Editor. I have it set to display help in the above screenshot.
*'''Toggle Display Mode'''- This changes how you are viewing the map. In the above screenshot I’m not looking at modeled terrain. It’s often easier to layout the map in this mode. But you can switch over to realistic terrain if you want to see exactly what your map would look like to the player.
*'''Enable Symmetry'''- Enable this if you want your terrain painting to be symmetrical. If it is set you can choose to make is symmetrically mirrored or use a radial symmetry for multiple equal positions.
*'''Terran/Desert/Frozen'''- If you would like to switch your world type while building you can do it here.
*'''Brush Size'''- When painting terrain or cosmetics this is the brush size you would like to use.
*'''Edit Terrain'''- Ashes has 5 base terrains:
**'''Plain'''- Normal ground
**'''Plateau'''- Higher ground that the player can still move and build on. Height is an advantage for many units so plateaus generally make for good defensive positions. Most maps start with the Nexas on a plateau for this reason.
**'''Hill'''- Hills connect Plains and Plateaus. Use them to determine where players can access one elevation from the other.
**'''Mountain'''- Mountains are impassable by anything except flying units. Use them to block parts of the map.
**'''Basin'''- Basins are also impassible to anything except for flying units. But units with long enough range can fire across basins.


*'''Edit Buildings'''- Use this to place the following on the map:
&nbsp;
**'''Player Seed'''- A players starting location.
**'''Relay'''- The heart of a region. Surround it with Metal and Radioactive deposits to decide what that region offers.
**'''Turinium Generator'''- This is a special type of power generator that can provide victory points. Provided maps don’t put resources in Generator regions, but you are modding, so do whatever you like.
**'''Metal Deposit'''- If players control regions with these, they provide Metal for the player.
**'''Radioactive Deposit'''- If players control regions with these, they provide Radioactives for the player.


*'''Edit Cosmetic'''- To place the cosmetic details on the map, like trees on terran planets.
&nbsp;
*'''Build Quality/Erosion/Terrain Synth'''- Increasing these will increase the amount of time and memory required to generate the terrain. I recommend keeping them low until you are ready to make the final version of the map. We generate at terrain quality 4 for our final maps.
*'''Rebuild Terrain'''- This regenerates the map with any changes you have made so you can see how they look.


[[File:ModGuide 3.png]]
&nbsp;


In this design the teal is plateau, red is mountains, blue is basins, yellow is hills and the green is plains.
&nbsp;


The player Nexas’s are in the upper right and the lower left. The point of this map was to create a single channel for the players to battle through. The upper part is biased for the player on the left, giving him a plateau to fire down at enemy units driving by the area below and the reverse for the southern part of the map.
&nbsp;


There are three Turinium Generators, one in the center of the map and one on each of the two plateaus overlooking the plains pass. The goal is to make one Turinium Generator easy for each player to grab so they need to battle over the one in the center (since victory points are awarded to the player who holds the majority of generators).
== Moddable Game Files (added in Escalation 2.2) ==


[[File:ModGuide 4.png]]
Just as with the Map Editor, to enable the game modifications add the “-modding” (without the quotes) to the Launch Options for the game (in Steam, right-click the game, go to Properties, click Set Launch Options in the General tab). That will add a Modifications&nbsp;button to the main menu of the game. You will not be able to play multiplayer if you are using Mods.


Rebuilding the terrain and toggling to map display mode gives us a look at what the map will look like. I like the pass, the mountains and the basin. But the rest looks a little bare. So I need to add more details to make that area more interesting. I often forget how big the Ashes maps are, so when I toggle to the real map they don’t seem as full as I imagined.
The game supports modding the directories Modders would be most interested in. These are:


[[File:ModGuide 5.png]]
*'''GameCore'''- The home of the most critical files, definitions for all the games units, buildings, weapons, orbital abilties, etc. This directory isn't additive, you make changes by replacing the file you want to change with a new one. For example, if you want to modify the hit poitns on the Zeus your mod will need to include a new UnitTemplates.csv file with the hit point value for the Zeus changed.
*'''Maps'''- For adding new maps with the mod.
*'''Scenario'''- For adding new scenarios with the&nbsp;mod. It is possible to modify existing scenarios with mods (by using the same name as that scenario file) but adding new scnearios with new names will be more common.
*'''UI'''- So a modder can add new art refered to by the Scenario file.
*'''UIText'''- For adding or changing existing text. Files placed here are additive (they don't need to replace an existing file). If you want to change a text string from the base game just include that string in your new text file and it will overwrite it.  


In this update I’ve added more opportunities for the defending player. The overlooking plateaus can only be accessed from the Nexas region so they get to attack in the central channel as well as attacking units forced to come by the plateau wall on their way to the Nexas.
To create a mod add a directory in your My Games/Ashes of the Singularity - Escalation/Mods/ directory with the name of the mod you would like to use.


[[File:]]
[[File:ModDir.png|RTENOTITLE]]


I’ve also switched it over to the Frozen terrain. I think its brutal hostility fits the maps focus better. I put the build quality up to 4 and increased the erosion levels so it looks great. It took a lot more time to generate (btw: don’t attempt to use high build levels on the largest possible maps unless you have a lot of memory) but it looks great.
In the above example the name of the Mod is BalanceMod. There is an index.ashesmod file that is a text file that contains the details about the mod. When you start the game it will create a generic one for you but the format is as follows:
<blockquote>[AshesMod]<br/> Name=Balance Mod<br/> Author=Rob Brink<br/> Description=This is a Balance mod that also includes the Weehawken Scenario.<br/> Version=1.1.10</blockquote>
This is purely informational, its what is displayed by the mod on the mod screen.


This map is a lot of fun to play, but may favor aircraft to strongly (since they can bypass all of these defense and attack anywhere. In a later section we will talk about creating scripts where we could do things like disable aircraft so the players are forced to slug it out.
'''[[File:ModScreen.png|right|300px|ModScreen.png]]Note:''' Ashes can’t use a file if it is locked. If you have a file open with Excel and try to start Ashes, the game will likely crash. Close the file before starting Ashes.


&nbsp;
To use a mod go into the Modification screen from the main menu. You will see all of your Mods here and you can enable or disable them, and change the order they load in. &nbsp;This can also be changed by editing the&nbsp;My Games/Ashes of the Singularity - Escalation/Mods.ini file.


= CSV and XML files – The Swarm Mod =
=== Notable Files for Modding ===
<div align="center">
----
</div>
Most of the data that drives Ashes is stored in CSV and XML files, and there are a lot of them.


[[File:]]
The following files are simple to mod and can effect major changes to gameplay.


You can find these in the in the place the game is installed under the ..\Ashes of the Singularity\Assets\ directories. Modifying files in a games directory isn’t for the faint of heart, so you will want to remember a few things:
All files are found in the Ashes \Assets\ directory.


#If you modify any of these files you can always get back to the original by verifying your game cache in Steam (which will revert all your files to the original game files).  
*'''\GameCore\[[BuildingTemplates.csv|BuildingTemplates.csv]]''' - Controls build time, cost, armor, HP, and more for all buildings.  
#Conversely, if you verify your cache in steam you will lose any local changes you have made.  
*'''\GameCore\[[UnitTemplates.csv|UnitTemplates.csv]]''' - Controls build time, cost, armor, HP, and more for all units.  
#Game updates may overwrite any changes you have made locally, so make a backup of your changes.  
*'''\GameCore\ModuleTemplates\[[WeaponModuleTemplates.csv|WeaponModuleTemplates.csv]]''' - Controls rate of fire, range, targeting priority, damage, and everything else for all weapons.  
#We plan to add a modding directory that will overwrite the game files, so you don’t have to modify the game files directly. But at the time that this guide is being written that functionality doesn’t exist. It won’t change what you can do, but it will make the process easier and cleaner.  
#You cannot play multiplayer with modded games (that wouldn’t be fair or fun for the other player). So if you want to play multiplayer you will need to revert your changes. If you have forgotten about some of the changes you can use reverify your files to get them back to default.
#You can modify the assets in Ashes but in general you cannot add new ones. This is because the UI wouldn’t should them in the build menus. So if you had a new unit you wanted to build at a factory it wouldn’t be displayed in the units the factory could produce. You could make a new unit to have the player start with, to reward the player with after he completes a trigger (more about those later), etc.  


'''Note:''' Ashes can’t use a file if it is locked. If you have a file open with Excel and try to start Ashes, the game will crash. Close the file before starting Ashes.
=== [[File:ModGuide 7.png|right|300px|ModGuide 7.png]]File Mod Example ===


There are a lot of files, with a lot of fields that can be tweaked and changed. For this demo we are going to mess with my favorite file, '''UnitTemplates.csv'''.
There are a lot of files, with a lot of fields that can be tweaked and changed. For this demo we are going to mess with my favorite file, '''[[UnitTemplates.csv|UnitTemplates.csv]]'''.


[[File:]]
[[File:ModGuide 8.png|thumb|right|200px|UnitTemplates.csv]]


In this screenshot I’ve opened UnitTemplates.csv with Excel, because it makes it easier for me to work with, but Excel isn’t required. Notepad could be used to modify the file. If you use Excel remember to save it as a csv file.
In this screenshot I’ve opened [[UnitTemplates.csv|UnitTemplates.csv]] with Excel, because it makes it easier for me to work with, but Excel isn’t required. Notepad could be used to modify the file. If you use Excel remember to save it as a csv file.


There are a lot of fields that can be modified. In this screenshot we can see:
There are a lot of fields that can be modified. In this screenshot we can see:


*Max HP’s
*Max HPs
*Max Energy  
*Max Energy  
*Energy Per Second  
*Energy Per Second  
Line 111: Line 100:
*Construction Time  
*Construction Time  


Some of these fields aren’t named the same as they are in game. Names change during the course of development, and we didn’t want to go back and change all these definitions to match each time they do. Because of that you may have to experiment a bit to see how things match. For example, PHC_T1_Light is the Brute, and Cost Data is actually the Radioactive cost of the unit. You can checkout the translation tables in ..\Ashes of the Singularity\Assets\UIText\ directory to see how raw assets relate to in game assets.
Some of these fields aren’t named the same as they are in game. Names change during the course of development, and we didn’t want to go back and change all these definitions to match each time they do. Because of that you may have to experiment a bit to see how things match. For example, PHC_T1_Light is the Brute, and Cost Data is actually the Radioactive cost of the unit. You can check out the translation tables in ..\Ashes of the Singularity\Assets\UIText\ directory to see how raw assets relate to in game assets.


Using this file alone, and just the things in this screenshot (there are many more fields in Unittemplates.csv) we can dramatically alter the balance and design of the game. Let’s use the above to create a new game variant I call the '''Swarm Mod'''.
Using this file alone, and just the things in this screenshot (there are many more fields in UnitTemplates.csv) we can dramatically alter the balance and design of the game. Let’s use the above to create a new game variant I call the '''Swarm Mod'''.


I love the scale of Ashes, I love large battles. So this mod is going to make even larger battles possible and we are going to get into them fast. To do that I’m going to make the following changes:
I love the scale of Ashes, I love large battles. So this mod is going to make even larger battles possible and we are going to get into them fast. To do that I’m going to make the following changes:


[[File:]]
[[File:ModGuide 9.png|thumb|right|200px|UnitTemplates.csv, modded]]


I’ve reduce the Metal, Radioactive, Logistics and Construction time costs by 90%. I’ve reduce the Logistics costs of T1 units to 0 (so you can have as many as you want). With these changes factories should produce 10 units in the time it took to produce 1 before. As long as you can keep feeding the (dramatically reduced) resource costs, units should come out of factories in an endless stream, like a tower defense game on steroids.
I’ve reduce the [[Metal|Metal]], [[Radioactives|Radioactives]], [[Logistics|Logistics]] and [[Construction_time|Construction time]] costs by 90%. I’ve reduce the Logistics costs of T1 units to 0 (so you can have as many as you want). With these changes factories should produce 10 units in the time it took to produce 1 before. As long as you can keep feeding the (dramatically reduced) resource costs, units should come out of factories in an endless stream, like a tower defense game on steroids.


There are a lot of ways to tweak this concept. I could have kept the Metal and Radioactive costs the same and then the player would be strongly incented to claim and upgrade regions to keep his factories fed. I could have just halved the costs rather than dropping them by 90%. I could have increased the resource gathering rates of upgraded metal and radioactive mines rather than lowering costs to incent players to invest in their regions.
There are a lot of ways to tweak this concept. I could have kept the Metal and Radioactive costs the same and then the player would be strongly incented to claim and upgrade regions to keep his factories fed. I could have just halved the costs rather than dropping them by 90%. I could have increased the resource gathering rates of upgraded metal and radioactive mines rather than lowering costs to incent players to invest in their regions.
Line 125: Line 114:
But for this we are going crazy. Everything gets very cheap. Massive armies can be built from the start of the game. Those poor creeps won’t know what hit them. And be prepared to be sieged by thousands of units.
But for this we are going crazy. Everything gets very cheap. Massive armies can be built from the start of the game. Those poor creeps won’t know what hit them. And be prepared to be sieged by thousands of units.


[[File:]]
[[File:ModGuide 10.png|thumb|right|200px|Swarms of frigates!]]


This is 5 minutes into the game. I only have 2 factories putting out an endless stream of Brutes. I make an army out of them and in the time it takes to do that there are a bunch more waiting to be added. So I find that it works just as well to set the rally point of the factory to where I want to attack, so that my river of death flows out to destroy it.
This is 5 minutes into the game. I only have 2 factories putting out an endless stream of Brutes. I make an army out of them and in the time it takes to do that there are a bunch more waiting to be added. So I find that it works just as well to set the rally point of the factory to where I want to attack, so that my river of death flows out to destroy it.


[[File:]]
[[File:ModGuide 11.png|thumb|right|200px|Pew! Pew pew!]]


The AI has adapted to the new lower costs and is meeting my endless streams with its own. Unlike me it has opted to go with some cheaply produced dreadnoughts. The game lasts for 45 minutes, and there is a battle waging between my endless armies and his at this chokepoint for nearly all of it. It isn’t until I win more minor battles on some of outskirt regions (to take the resources which even at 90% off still become critical) and I send a strike force around to take out his factories that I cause his production chain to falter and begin to break through.
The AI has adapted to the new lower costs and is meeting my endless streams with its own. Unlike me it has opted to go with some cheaply produced dreadnoughts. The game lasts for 45 minutes, and there is a battle waging between my endless armies and his at this chokepoint for nearly all of it. It isn’t until I win more minor battles on some of outskirt regions (to take the resources which even at 90% off still become critical) and I send a strike force around to take out his factories that I cause his production chain to falter and begin to break through.


[[File:]]
[[File:ModGuide 12.png|thumb|right|200px|Pewpewpew!]]


I had to adjust away from my typical Artemis (long range missile ships) to Nemesis (which are really good against enemy dreadnoughts) to be able to begin killing them faster than he could produce them. I also needed to invest heavily in anti-air Apollos to counter the AI’s strike fleets of aircraft that nearly cost me the game.
I had to adjust away from my typical [[Artemis|Artemis]] (long range missile ships) to Nemesis (which are really good against enemy dreadnoughts) to be able to begin killing them faster than he could produce them. I also needed to invest heavily in anti-air [[Apollo|Apollos]] to counter the AI’s strike fleets of [[Aircraft|aircraft]] that nearly cost me the game.


Once the lines were broken I turned the biggest Ashes armada I had ever controlled against his Nexas. There were a lot of dreadnoughts fighting their way up that hill, and the explosions, missile trails and laser blasts cut through and won me the game.
Once the lines were broken I turned the biggest Ashes armada I had ever controlled against his Nexus. There were a lot of [[Dreadnoughts|dreadnoughts]] fighting their way up that hill, and the explosions, missile trails and laser blasts cut through and won me the game.


Overall it is amazing how much game play can change with these changes. If I were to do it again I might keep the reduced cost overall, but maybe just 50% off rather than 90%. I liked the larger armies, but it was a crazy experience more like fighting a fire than playing chess.
Overall it is amazing how much game play can change with these changes. If I were to do it again I might keep the reduced cost overall, but maybe just 50% off rather than 90%. I liked the larger armies, but it was a crazy experience more like fighting a fire than playing chess.
Line 143: Line 132:
If you decide to modify the csv files with a text editor (Notepad++ is my text editor of choice) you can do everything I was doing in Excel, it just isn’t formatted into columns to be easy to read. Instead it is raw text like the following:
If you decide to modify the csv files with a text editor (Notepad++ is my text editor of choice) you can do everything I was doing in Excel, it just isn’t formatted into columns to be easy to read. Instead it is raw text like the following:


[[File:]]
[[File:ModGuide 13.png|thumb|right|200px|A .csv file in Notepad++]]


Modifying the files this way works, you just need to count the amount of fields, remembering that commas separate the fields (CSV stands for Comma Separated Values) to get to the right values.
Modifying the files this way works, you just need to count the amount of fields, remembering that commas separate the fields (CSV stands for Comma Separated Values) to get to the right values.


&nbsp;
=== Adding a new Map to a Mod ===
 
= Scripting – Creating Scenarios =
<div align="center">
----
</div>
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, setup 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 ..\Ashes of the Singularity\Assets\MapScripts\, \Campaign\ and \Scenario\ directories and see what the xml files are doing. But I’ve included some of the functionality below with examples.
 
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 is where all the magic happens. Triggers have a lot of elements and options.
 
The following isn’t a complete list of scripting options in Ashes. But represents the most useful to get you up and creating your own scenarios right away. Note that all triggers and arguments are case-sensative.
 
'''Mission'''- Mission is the starting definition for this scenario.
 
[[File:]]
 
*'''Title'''- Title of the mission
*'''Description'''- Description of the mission
*'''Map'''- What map this mission uses
*'''Image'''- The image that is displayed when this mission is selected
*'''ImageFade'''- The image that is displayed when this mission isn’t selected
*'''ImageBig'''- The close up image of the planet
*'''ImageRadius'''- How big the image is
*'''PlanetPosition'''- Where the planet is displayed in the ascendancy war screen
*'''EnableCreeps'''- Are creeps enabled in this map?
*'''HideTerrain'''- Should the world start revealed or not?
 
'''Player'''- this area defines all the players that will be used in the Scenario.
 
[[File:]]
 
*'''Name'''- Name of the player.
*'''Faction'''- Faction the player belongs to (Substrate or PHC).
*'''Team'''- What team the player belongs to.
*'''Color'''- What is the team color for the player.
*'''AIType'''- Set to “Player” if this is player controlled.
*'''Difficulty'''- 1 for Beginner up to 7 for Insane.
*'''NoSeed'''- Set this to 1 to disable a Nexas for the player.
*'''NoEngineer'''- Set this to 1 if the player isn’t going to start with an Engineer.
*'''StartLocation'''- What start location the player uses.
 
'''Trigger'''- This is something that happens while the scenario is being played.
 
[[File:]]
 
*'''Name'''- Name of the trigger.
*'''Owner'''- Which player is this trigger for.
*'''Inactive'''- If this trigger is inactive, to activate use the ActivateTrigger option from another Trigger.
*'''OtherTrigger'''- Name of another trigger that must have fired before this one will activate. Use this to set multiple conditions on a trigger occurring.
*'''NotOtherTrigger'''- Inverse of OtherTrigger. If the other trigger has fired this trigger won’t fire. Us this to create branching options in your scenario.
*'''Type'''- What type of trigger is it. The following types are supported: <ul style="list-style-type:circle;">
</ul>
</ul>
 
</ul>
 
</ul>
 
</ul>
 
</ul>
 
*'''ZoneCapture'''- Fires when a region is captured.
**
***'''Position'''- Map coordinates of the generator/nexas.
***'''Owner'''- Player who must capture this region to fire the trigger.
 
 
 
&nbsp;
 
&nbsp;
 
&nbsp;
 
&nbsp;
 
*
**'''Timer'''- Fires after a delay.
***'''Timer-''' Time in seconds after this gets triggered that it takes place.
 


It is also possible to add a custom map to a Mod. &nbsp;The in-game map editor will always create a map in the default \Assets\Maps\<mapname> directory. &nbsp;To include that map in your mod, once created you'll need to move the entire map directory into your <ModName>\Maps directory. &nbsp;Once the map is in the mod directory and the game is restarted, the Map Editor will be able to edit the map directly from the mod directory.


&nbsp;
=== Current Limitations (Ashes 2.2) ===
 
&nbsp;
 
&nbsp;


&nbsp;
The Ashes developers are working to expand Modding support, however there are a few significant limtations to the existing modification support.


*
The following files from the Ashes \Assets\ directory are currently NOT modifiable.
**'''Build'''- Fires when a human player builds structures.
**'''Destruction'''- Fires when something specific dies.
***'''Target'''- Name of the script-spawned unit or building.
***'''IsBuilding'''- If this is a building (if not it refers to a unit).  


*'''\Units\''': Contains the models and textures for all the units in the game.
*'''\Buildings\''': Contains the models and textures for all the buildings in the game.
*'''\Formation\[[FlockerTemplates.csv|FlockerTemplates.csv]]''': Controls the Max Acceleration, Max Velocity, and other movement related parameters.
*'''\Physics\[[RigidBodyTemplates.csv|RigidBodyTemplates.csv]]''': Controls the physics collision dimensions and mass.


=== Safe Mode ===


&nbsp;
If your Ashes instalation with Mods gets into a state where the game fails to load. It is possible to still load the game via safe mode. &nbsp;Safe mode will not load any mods, but will still present the user interface for enabling and disabling mods. &nbsp;You can open the interface, disable the offending Mod, and restart Ashes in the normal mode.


&nbsp;
To start safe mode, select the option from the launch menu in steam, or add "-safe" to the command line arguments.


&nbsp;
== Scripting – Creating Scenarios ==


&nbsp;
[[Scripting|Scripting]] allows you a huge amount of control over what exactly happens on the map you are creating. You can [[Restrict|restrict]] what [[Buildings|buildings]] and [[Units|units]] the players can use, set up [[Triggers|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|dialog]] popups to the player. Everything you need to make your own custom [[Scenarios|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.
**'''Research'''- Fires when a Quantum upgrade is researched.  
***'''Player'''- playerID of who can fire this trigger.  
***'''Target'''- Tech name that causes this trigger to fire.  


There are three main elements in Ashes scripting: [[Missions_(scripting)|missions]], [[Player_(scripting)|players]] and [[Triggers|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.


&nbsp;
=== Mission Definition ===


&nbsp;
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 [[Missions_(scripting)|<Mission> tag]].


&nbsp;
=== Player Definition ===


&nbsp;
To do much of anything, you'll need to define [[Player_(scripting)|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.
**'''NamedCreate'''- Fires when a specific unit or building is spawned via a script.
***'''Target'''- Name of the script-spawned unit or building.
***'''IsBuilding'''- If this is a building (if not it refers to a unit).  


=== Triggers ===


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


&nbsp;
=== Trigger Types ===


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


&nbsp;
*'''[[Area_Trigger|Area]]''' - Fires when the human player moves a unit into the area.


&nbsp;
*'''[[Build_Trigger|Build]]''' - Fires when a human player builds structures or units.


*
*'''[[Destruction_Trigger|Destruction]]''' - Fires when something specific dies.  
**'''Area'''- Fires when the human player moves a unit into the area.
***'''Center'''- Map coordinates of the center of the area.
***'''Size'''- Size of the area.
***'''Template'''- Template name of the unit that can trigger this.  


*'''[[Difficulty_Trigger|Difficulty]]''' - Fires at the beginning of a scenario if the given difficulty was chosen


*'''[[NamedCreate_Trigger|NamedCreate]]''' - Fires when a specific unit or building is spawned via a script.


&nbsp;
*'''[[Research_Trigger|Research]]''' - Fires when a player researches a Quantum Upgrade


&nbsp;
*'''[[Timer_Trigger|Timer]]''' - Fires after a delay.


&nbsp;
*'''[[Var_Trigger|Var]]''' - Fires if a variable meets given criteria


&nbsp;
*'''[[ZoneCapture_Trigger|ZoneCapture]]''' - Fires when a region is captured.


&nbsp;
&nbsp;


'''ActivateTrigger'''- To activate another trigger, so you can create a series of triggers that have to be completed in order.
=== Commands ===
 
[[File:]]
 
*'''Target'''- This is the name of another trigger that will be set from Inactive to Active.
 
'''AreaIndicator'''- This places a visible indicator on the map to help the player know where they should go to.
 
[[File:]]
 
*'''Name'''- The name of the area.
*'''Position'''- The center of the area.
*'''Color'''- The color the area indicator is.
*'''Size'''- How big the area indicator will be.
*'''Duration'''- How long the area indicator should last, -1 means that it lasts forever.
 
'''AttackAttackMove'''- Order an army to move to a specific area.
 
[[File:]]
 
*'''Name'''- The name of the army that will be given the order.
*'''Time'''- How long after the trigger occurs that the game will wait before issuing this order.
*'''Position'''- Where the army is ordered to move to.
 
'''Camera'''- Move the players view to a specific area.
 
[[File:]]
 
*'''Position'''- Where the camera will be looking.
*'''RTP'''- The engineers tell me this is Rho/Theta/Phi for the camera angle settings. Since I’m pretty sure they made those words up we should just think of it as the Distance, Rotation and Pitch of the camera.
*'''Speed'''- Speed that the players view is switched to the new camera location.
 
'''Dialog'''- This creates a popup that can convey information or story to the player.
 
[[File:]]
 
'''Entry'''- The actual text that will be displayed.
 
*'''Icon'''- The icon used with the text popup.
*'''Text'''- The actual text that is displayed.
 
'''EndMission'''- Use to force a win or loss of the scenario.
 
[[File:]]
 
*'''Victory'''- Set to 0 to lose the scenario or 1 to win.
*'''String'''- The text that is displayed.
 
'''GrantStuff'''- Use this to give the player free resources when a trigger occurs.
 
[[File:]]
 
*'''Metal'''- The amount of metal being granted.
*'''Quanta'''- The amount of quanta being granted.
*'''Radioactives'''- The amount of radioactives being granted.
*'''Tech'''- The amount of research being granted.
*'''Turinium'''- The amount of victory points being granted.
 
'''Objective'''- Use this to set objective notifications for the player (so they know what to do).
 
[[File:]]
 
*'''Name'''- The name of the objective, use this name when checking or hiding it.
*'''Hide'''- If this objective should be hidden or not, usually this means the objective is complete.
*'''String'''- What the objective displays on the screen.
*'''SetCheck'''- If the objective checkbox is checked or not.
 
'''Restrict'''- To block the player from being able to access objects in the game.
 
[[File:]]
 
*'''Type'''- Unit, Building, Research or Orbital. Whatever type of object that is being restricted.
*'''ID'''- The name of the object being restricted.
*'''Enable'''- Set this to 1 to enable the object. You can use this to restrict something early in the scenario and then enable it later on (for example: when the player accomplishes an objective or after a set amount of time).


'''SpawnBuilding'''- Places a building on the map.
These are the [[Script_Commands|commands]] you can put within a trigger to create gameplay effects.


[[File:]]
See the [[Script_Commands|main Commands entry]] for details.


*'''Name'''- The name you assign to the building.  
*'''[[ActivateTrigger|ActivateTrigger]]''' - Activate another trigger (also can be used to activate the trigger it is called from, making a repeating trigger).
*'''Template'''- The name of the building type being created.  
*'''[[AreaIndicator|AreaIndicator]]''' - This places a visible indicator on the map to help the player know where they should go to.
*'''Player'''- The player who will own the building.  
*'''[[AttackAttackMove|AttackAttackMove]]''' - Order an army to move to a specific area, engaging enemies along the way.
*'''Position'''- Where the building will be placed.  
*'''[[AttackUnit|AttackUnit]]''' - Order an army to attack a specific script-spawned unit
*'''[[Camera|Camera]]''' - Move the player's view to a specific area.
*'''[[CaptureNearestNext|CaptureNearestNext]]''' - Order an army to capture the nearest neutral or enemy-controlled region
*'''[[CaptureNearest|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|ChangeAIDifficulty]]''' - Change an AI player's difficulty setting
*'''[[ChangeAIPersonality|ChangeAIPersonality]]''' - Change an AI player's personality
*'''[[DestroyBuilding|DestroyBuilding]]''' - Destroys a specific script-spawned building.  
*'''[[DestroyUnit|DestroyUnit]]''' - Destroys a specific script-spawned unit.
*'''[[Dialog|Dialog]]''' - This creates a popup that can convey information or story to the player. Use with <Entry> tags.
*'''[[Entry|Entry]]''' - The actual text that will be displayed. Use only within <Dialog> tags.
*'''[[EndMission|EndMission]]''' - Use to force a win or loss of the scenario.
*'''[[GrantStuff|GrantStuff]]''' - Give a player free resources
*'''[[GrantTech|GrantTech]]''' - Give a player a free Quantum Upgrade
*'''[[HidePanel|HidePanel]]''' - Hide UI panels
*'''[[LetterBox|LetterBox]]''' - disable commands and go to a cinematic, letterbox view
*'''[[MoveUnit|MoveUnit]]''' - Move an army to a location without stopping to fight
*'''[[Objective|Objective]]''' - Use this to set objective notifications for the player (so they know what to do).
*'''[[Restrict|Restrict]]''' - To block the player from being able to access objects in the game.  
*'''[[Reveal|Reveal]]''' - Reveal the fog of war over a location
*'''[[SpawnBuilding|SpawnBuilding]]''' - Places a building on the map.  
*'''[[SpawnUnit|SpawnUnit]]''' - Places a unit on the map.
*'''[[Var_Command|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.''


'''SpawnUnit'''- Places a unit on the map.
== Position Coordinates ==


[[File:]]
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|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|AshesGameView.xml]]''':


*'''Name'''- The name you assign to the unit.  
[[File:ModGuide 28.png|center|Changing the XML to show locations]]
*'''Parent'''- The army the unit will belong to (used to make it easier to issue moves).
*'''Template'''- The type of unit being created.
*'''Player'''- The player that will own the unit.
*'''Position'''- Where the unit will be created.


== How do you find out the position coordinates? ==
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.
 
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''':
 
[[File:]]
 
&nbsp;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.
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.


== Putting it together ==
== 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.
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.
Line 414: Line 253:
=== Send an army to attack ===
=== Send an army to attack ===


[[File:]]
[[File:ModGuide 29.png|frame|center|An attack trigger]]<br/> 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.
 
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.
 
&nbsp;


=== Reward the player for capturing an area ===
=== Reward the player for capturing an area ===


[[File:]]
[[File:ModGuide 30.png|frame|center|A region capture trigger]]<br/> 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.
 
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:
This trigger does the following:
Line 440: Line 273:
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.
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.


&nbsp;
[[Category:Modding]]
 
= In Conclusion =
 
Ashes of the Singularity gives you access to a powerful strategy game engine to create your own scenarios, objects and worlds. The designers have had a lot of fun creating scenarios for the game, and you will have access to the same features they had to create your own.

Revision as of 14:17, 15 March 2017

Ashes of the Singularity gives you access to a powerful strategy game engine to create your own scenarios, objects and worlds. The designers have had a lot of fun creating scenarios for the game, and you will have access to the same features they had to create your own.

There is a lot to do in Ashes. But it was also built from the ground up to be mod friendly. Modders have access to the gameplay elements to change and tweak as they desire. This document will introduce some of what is possible, and we will make a map and a mod to take advantage of this.

This is not always going to be a managed and curated editor with limited options. You can mod the game the same way the developers make changes to the game. Editors are nice because they typically keep you from doing “bad” things. But they also keep you from doing incredibly good things. An editor only allows you to do the things the developer set up for you to change. With direct access to the files you can do things the developer never expected. Sometimes that turns out horribly (okay, a lot of the time that turns out horribly), but sometimes it turns out brilliantly. We believe power trumps ease of use.

The Map Editor

(see the full Map Editor article for more)

Creating a new map

To enable the Map Editor add the “-modding” (without the quotes) to the Launch Options for the game (in Steam, right-click the game, go to Properties, click Set Launch Options in the General tab). That will add a Map Editor button to the main menu of the game. From there you can decide if you want to modify an existing map, or create a new one. If you create a new one the menu to the right is presented.

For your first map I’d select a smaller map size. You probably assume that you will run out of space quickly on small maps, you would be wrong. Ashes small maps are what other games would call huge. The large ones are ridiculous and will take a lot of time to design. Practice on some small ones first.

A new, blank map

 

 

 

 

 

 

 

 

 

 

 

 

 

Moddable Game Files (added in Escalation 2.2)

Just as with the Map Editor, to enable the game modifications add the “-modding” (without the quotes) to the Launch Options for the game (in Steam, right-click the game, go to Properties, click Set Launch Options in the General tab). That will add a Modifications button to the main menu of the game. You will not be able to play multiplayer if you are using Mods.

The game supports modding the directories Modders would be most interested in. These are:

  • GameCore- The home of the most critical files, definitions for all the games units, buildings, weapons, orbital abilties, etc. This directory isn't additive, you make changes by replacing the file you want to change with a new one. For example, if you want to modify the hit poitns on the Zeus your mod will need to include a new UnitTemplates.csv file with the hit point value for the Zeus changed.
  • Maps- For adding new maps with the mod.
  • Scenario- For adding new scenarios with the mod. It is possible to modify existing scenarios with mods (by using the same name as that scenario file) but adding new scnearios with new names will be more common.
  • UI- So a modder can add new art refered to by the Scenario file.
  • UIText- For adding or changing existing text. Files placed here are additive (they don't need to replace an existing file). If you want to change a text string from the base game just include that string in your new text file and it will overwrite it.

To create a mod add a directory in your My Games/Ashes of the Singularity - Escalation/Mods/ directory with the name of the mod you would like to use.

RTENOTITLE

In the above example the name of the Mod is BalanceMod. There is an index.ashesmod file that is a text file that contains the details about the mod. When you start the game it will create a generic one for you but the format is as follows:

[AshesMod]
Name=Balance Mod
Author=Rob Brink
Description=This is a Balance mod that also includes the Weehawken Scenario.
Version=1.1.10

This is purely informational, its what is displayed by the mod on the mod screen.

ModScreen.png
ModScreen.png

Note: Ashes can’t use a file if it is locked. If you have a file open with Excel and try to start Ashes, the game will likely crash. Close the file before starting Ashes.

To use a mod go into the Modification screen from the main menu. You will see all of your Mods here and you can enable or disable them, and change the order they load in.  This can also be changed by editing the My Games/Ashes of the Singularity - Escalation/Mods.ini file.

Notable Files for Modding

The following files are simple to mod and can effect major changes to gameplay.

All files are found in the Ashes \Assets\ directory.

  • \GameCore\BuildingTemplates.csv - Controls build time, cost, armor, HP, and more for all buildings.
  • \GameCore\UnitTemplates.csv - Controls build time, cost, armor, HP, and more for all units.
  • \GameCore\ModuleTemplates\WeaponModuleTemplates.csv - Controls rate of fire, range, targeting priority, damage, and everything else for all weapons.

ModGuide 7.png
ModGuide 7.png
File Mod Example

There are a lot of files, with a lot of fields that can be tweaked and changed. For this demo we are going to mess with my favorite file, UnitTemplates.csv.

UnitTemplates.csv

In this screenshot I’ve opened UnitTemplates.csv with Excel, because it makes it easier for me to work with, but Excel isn’t required. Notepad could be used to modify the file. If you use Excel remember to save it as a csv file.

There are a lot of fields that can be modified. In this screenshot we can see:

  • Max HPs
  • Max Energy
  • Energy Per Second
  • Armor
  • Heal Rate
  • Max Shields
  • Shield Regen Rate
  • Radar Radius
  • Cost Metal
  • Cost Data
  • Cost Energy
  • Cost Logistics
  • Construction Time

Some of these fields aren’t named the same as they are in game. Names change during the course of development, and we didn’t want to go back and change all these definitions to match each time they do. Because of that you may have to experiment a bit to see how things match. For example, PHC_T1_Light is the Brute, and Cost Data is actually the Radioactive cost of the unit. You can check out the translation tables in ..\Ashes of the Singularity\Assets\UIText\ directory to see how raw assets relate to in game assets.

Using this file alone, and just the things in this screenshot (there are many more fields in UnitTemplates.csv) we can dramatically alter the balance and design of the game. Let’s use the above to create a new game variant I call the Swarm Mod.

I love the scale of Ashes, I love large battles. So this mod is going to make even larger battles possible and we are going to get into them fast. To do that I’m going to make the following changes:

UnitTemplates.csv, modded

I’ve reduce the Metal, Radioactives, Logistics and Construction time costs by 90%. I’ve reduce the Logistics costs of T1 units to 0 (so you can have as many as you want). With these changes factories should produce 10 units in the time it took to produce 1 before. As long as you can keep feeding the (dramatically reduced) resource costs, units should come out of factories in an endless stream, like a tower defense game on steroids.

There are a lot of ways to tweak this concept. I could have kept the Metal and Radioactive costs the same and then the player would be strongly incented to claim and upgrade regions to keep his factories fed. I could have just halved the costs rather than dropping them by 90%. I could have increased the resource gathering rates of upgraded metal and radioactive mines rather than lowering costs to incent players to invest in their regions.

But for this we are going crazy. Everything gets very cheap. Massive armies can be built from the start of the game. Those poor creeps won’t know what hit them. And be prepared to be sieged by thousands of units.

Swarms of frigates!

This is 5 minutes into the game. I only have 2 factories putting out an endless stream of Brutes. I make an army out of them and in the time it takes to do that there are a bunch more waiting to be added. So I find that it works just as well to set the rally point of the factory to where I want to attack, so that my river of death flows out to destroy it.

Pew! Pew pew!

The AI has adapted to the new lower costs and is meeting my endless streams with its own. Unlike me it has opted to go with some cheaply produced dreadnoughts. The game lasts for 45 minutes, and there is a battle waging between my endless armies and his at this chokepoint for nearly all of it. It isn’t until I win more minor battles on some of outskirt regions (to take the resources which even at 90% off still become critical) and I send a strike force around to take out his factories that I cause his production chain to falter and begin to break through.

Pewpewpew!

I had to adjust away from my typical Artemis (long range missile ships) to Nemesis (which are really good against enemy dreadnoughts) to be able to begin killing them faster than he could produce them. I also needed to invest heavily in anti-air Apollos to counter the AI’s strike fleets of aircraft that nearly cost me the game.

Once the lines were broken I turned the biggest Ashes armada I had ever controlled against his Nexus. There were a lot of dreadnoughts fighting their way up that hill, and the explosions, missile trails and laser blasts cut through and won me the game.

Overall it is amazing how much game play can change with these changes. If I were to do it again I might keep the reduced cost overall, but maybe just 50% off rather than 90%. I liked the larger armies, but it was a crazy experience more like fighting a fire than playing chess.

If you decide to modify the csv files with a text editor (Notepad++ is my text editor of choice) you can do everything I was doing in Excel, it just isn’t formatted into columns to be easy to read. Instead it is raw text like the following:

A .csv file in Notepad++

Modifying the files this way works, you just need to count the amount of fields, remembering that commas separate the fields (CSV stands for Comma Separated Values) to get to the right values.

Adding a new Map to a Mod

It is also possible to add a custom map to a Mod.  The in-game map editor will always create a map in the default \Assets\Maps\<mapname> directory.  To include that map in your mod, once created you'll need to move the entire map directory into your <ModName>\Maps directory.  Once the map is in the mod directory and the game is restarted, the Map Editor will be able to edit the map directly from the mod directory.

Current Limitations (Ashes 2.2)

The Ashes developers are working to expand Modding support, however there are a few significant limtations to the existing modification support.

The following files from the Ashes \Assets\ directory are currently NOT modifiable.

  • \Units\: Contains the models and textures for all the units in the game.
  • \Buildings\: Contains the models and textures for all the buildings in the game.
  • \Formation\FlockerTemplates.csv: Controls the Max Acceleration, Max Velocity, and other movement related parameters.
  • \Physics\RigidBodyTemplates.csv: Controls the physics collision dimensions and mass.

Safe Mode

If your Ashes instalation with Mods gets into a state where the game fails to load. It is possible to still load the game via safe mode.  Safe mode will not load any mods, but will still present the user interface for enabling and disabling mods.  You can open the interface, disable the offending Mod, and restart Ashes in the normal mode.

To start safe mode, select the option from the launch menu in steam, or add "-safe" to the command line arguments.

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.