Scenario Editor: Difference between revisions

From Ashes of the Singularity - Official Wiki
Jump to navigation Jump to search
No edit summary
 
(33 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Scripting – Creating Scenarios ==
{{DISPLAYTITLE:<span style="position: absolute; clip: rect(1px 1px 1px 1px); clip: rect(1px, 1px, 1px, 1px);">{{FULLPAGENAME}}</span>}}
 
{{HeaderTemplate
|welcome=Scenario Editor
}}
{{SectionTemplate
|h=h3
|title=Scripting – Creating Scenarios
|content=}}
[[Scripting|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|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 popups to the player. Everything you need to make your own custom Scenarios.
[[Scripting|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|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 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.
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_(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.
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. 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.
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 [[Missions_(scripting)|<Mission> tag]].
{{SectionTemplate
|h=h4
|title=Mission Definition
|content=
}}
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. [[Missions (scripting)|Click here]] to see the full list of what can be configured in mission scripting.


=== Player Definition ===


{{SectionTemplate
|h=h4
|title=Player Definition
|content=
}}
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.
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.
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 ===


{{SectionTemplate
|h=h4
|title=Triggers
|content=
}}
[[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.
[[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 ===


{{SectionTemplate
|h=h5
|title=Trigger Types
|content=
}}
These are the types of triggers you can use in a script, and any specific arguments they support.
These are the types of triggers you can use in a script, and any specific arguments they support.


Line 43: Line 65:
*'''[[Var_Trigger|Var]]''' - Fires if a variable meets given criteria  
*'''[[Var_Trigger|Var]]''' - Fires if a variable meets given criteria  


*'''[[ZoneCapture_Trigger|ZoneCapture]]''' - Fires when a region is captured.  
*'''[[ZoneCapture_Trigger|ZoneCapture]]''' - Fires when a region is captured, is also used for destroying players since their nexus turns into a Turinium Generator.  


&nbsp;
=== Commands ===


{{SectionTemplate
|h=h4
|title=Commands
|content=
}}
These are the [[Script_Commands|commands]] you can put within a trigger to create gameplay effects.
These are the [[Script_Commands|commands]] you can put within a trigger to create gameplay effects.


See the [[Script_Commands|main Commands entry]] for details.
For detailed information about how to use this, read the [[Script_Commands|main Commands entry]].


*'''[[ActivateTrigger|ActivateTrigger]]''' - Activate another trigger (also can be used to activate the trigger it is called from, making a repeating trigger).  
*'''[[ActivateTrigger|ActivateTrigger]]''' - Activate another trigger (also can be used to activate the trigger it is called from, making a repeating trigger).  
Line 79: Line 103:
*'''[[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.''
*'''[[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.''


== 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|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]]''':
[[File:ModGuide 28.png|center|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.
{{SectionTemplate
|h=h3
|title=Position Coordinates
|content=
}}
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 ==


{{SectionTemplate
|h=h3
|title=Trigger Examples
|content=
}}
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.


=== Send an army to attack ===


{{SectionTemplate
|h=h4
|title=Send an army to attack
|content=
}}
[[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.
[[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.


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


{{SectionTemplate
|h=h4
|title=Reward the player for capturing an area
|content=
}}
[[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.
[[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.


Line 115: Line 149:
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;


&nbsp;
{{SectionTemplate
|h=h3
|title=Commenting Out Code
|content=
}}
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. I need to use an image to show which characters are used to comment out.
[[File:Capture.jpg|thumb|left]]


&nbsp;


&nbsp;
{{SectionTemplate
|h=h3
|title=Fixing Issues
|content=
}}
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.


&nbsp;
*'''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.


&nbsp;
[[Category:Modding]]

Latest revision as of 10:17, 5 October 2021

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. Click here to see the full list of what can be configured in mission scripting.


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
  • 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. I need to use an image to show which characters are used to comment 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.