GRAW2 Mission scripting...

[Wolfsong]

Chapter 1: Introduction and XML Basics

Those who scripted for GRAW1 may wonder if they need to read this document and the answer is mostly likely yes. The base elements in GRAW2 are a little different from those found in GRAW1, and some elements and children have also changed names and attributes or been replaced by combined elements, so even those with scripting experience from the first game should look through this document to get those updates and changes. You may skip the rest of chapter 1 though as it’s the exact same intro as I did for GRAW1.

Intro
To begin with you may wonder what you need to script for GRAW2. The answer is simply nothing more then the game itself and a text editor of your choice. Many text editors have color syntaxes for different programming languages, but it’s not essential to be able to script. NotePad works just as well as for example XML Marker, which you can find for free here: http://symbolclick.com/download.htm

Now then, before we go into all the different triggers, events, elements and other stuff that looks cryptic when you first try to script a mission for GRAW2, let’s take a look at a basic example of how a part of it works and also give a little introduction to XML. We’ll only look into the mission.xml file for now.

Many things in mission.xml refer to entries found in world.xml, which is created by the map editor. Those are the “game names” set to each objects by the designer that places them into the world inside the map editor, all other names we’ll give things in the mission.xml is only used internally by that file.

This document will not cover making the map itself or understanding the map editor. Everything will require that you have already built the map and made it so the player gets inserted somehow.
 
XML
Ok then, what is XML? To quote www.xml.com, this is the technical term:

XML is a markup language for documents containing structured information. Structured information contains both content (words, pictures, etc.) and some indication of what role that content plays (for example, content in a section heading has a different meaning from content in a footnote, which means something different than content in a figure caption or content in a database table, etc.).

Almost all documents have some structure. A markup language is a mechanism to identify structures in a document. The XML specification defines a standard way to add markup to documents. Unlike HTML, XML specifies neither semantics nor a tag set. In fact XML is really a meta-language for describing markup languages. In other words, XML provides a facility to define tags and the structural relationships between them. Since there's no predefined tag set, there can't be any preconceived semantics. All of the semantics of an XML document will either be defined by the applications that process them or by stylesheets.

Okay, I guess that didn’t help very much. But I’ll try to at least give you the basics of how XML, or Extensible Markup Language, is structured. Its syntax is very similar to that of HTML, which is where XML originated. Like HTML, XML is built in hierarchies of nested elements. The main difference is that in XML the people making the engine, in our case Grin, can create their own element tags, which means that they can create their own elements to be used in the XML files we’ll be scripting in.

An XML element typically consists of two tags, a start tag and an end tag, which can surround other elements that are then called child elements. The start tag consists of a name surrounded by angle brackets, like “”. The end tag consists of the same name with angle brackets, but with a forward slash preceding the name, like “”. To set this end tag is what programmers refer to as “closing your tags”. The elements attributes are everything that appears in the start tag after the name, but before the closing angle bracket. First comes the name of the attribute, followed by the value it is given. The value must ALWAYS be quoted, and each attribute name should only appear once in any element. The elements content is everything that appears between the start tag and the end tag, which in GRAW2 scripting is always in the form of child elements.

An element without content has a special syntax to make it shorter to write. Instead of writing a start tag followed immediately by an end tag, the forward slash is inserted at the end of the start tag, before it’s closing angle bracket, like “”. If this element has attributes, those are written as normal after the initial name.

Note: Everything in XML is also case sensitive. So if there is an element called “name”, you can’t call it by writing “Name”.
 
The basic syntax for an XML element looks like this:

 

Above you can see an element called “name”. It has an attribute called “attribute1”, which is given the value “value1”. This element also has content in form of a child element which has no content of its own and therefore is written with the special short syntax provided for that case. As you can see, the child element is tabbed in as to easier get an overview of the code hierarchy. The child element is called “content” and also has an attribute called “attribute1” given the value “value1”. Finally there is an end tag for the “name” element, telling the script that it has no more content.

Note: The two attributes with the same name has NO connection between them at all. Attributes are specific to each element they are given to, and which attributes that can be given to an element is defined by the creators of the engine that will read you script.

That is it for the basics in XML, which I hope will help you understand the rest of this document better.

[Wolfsong]

Chapter 2: Base XML Elements in GRAW2

There are a few basic elements that Grin has created for GRAW2 to build the main structure in the mission.xml. To begin with there are only four different base elements you’ll be using, “trigger”, “player_trigger”, “briefing” and “event”.

Triggers
“trigger” is the base element used to create triggers that check if their given conditions are “true” and if so runs a defined event. They always have content which mainly consists of an element type called “condition”. There can be an unlimited amount of “condition” elements inside a “trigger”, but all of them have to be checked as true for the trigger to successfully run. These conditions have to be given a value for their “type” attribute, and depending on which type of condition it is there will be other attributes that needs to be set, which is covered in chapter 5. The last line of content inside a “trigger” is always an element called “event”, which has an attribute called “name” that hold the name of the event to run if all the conditions above are true.

The “trigger” element itself also has attributes. The first is “name”, which is required. This name is very important as it’s used to activate, and sometimes deactivate, the trigger inside the mission script and as such it’s required to be unique for each trigger. The second attribute is “interval“, which needs to be given a time in seconds for how often the trigger should check if its conditions are true after it has been activated.

Next comes a few optional attribute of which the first is called “preserved”. This attribute defines if the trigger should stay active after it has executed its event, and so it requires the value “true” if you want the trigger to run more then once. It will default to “false” which will deactivate the trigger automatically once its given event is called to execute. The next attribute is called “once” and should be defined as “true” if the trigger should be able to successfully execute more then once, otherwise this defaults to “false”.

The last optional attribute is “ping_pong”, which is basically the same as “once” but with the exception that after it has successfully executed with all its conditions being true, it will next wait until all its conditions are false which will make the next successful call to its events. After that it will once again check for all conditions to be true and so on until it’s deactivated. Every time the check is done for the conditions to be false a different event will be called, which requires the user to use two “event” elements in the trigger when setting “ping_pong” to “true”. Finally, don’t forget to close your tags.

An example of the “trigger” element:

 
 
 

Player Triggers
“player_trigger” is the base element used to create a special type of trigger that activates for each individual player. In other words it will activate at different times for different players even if they are on the same team while playing in multi player. It can also never be activated by an AI soldier even if he’s part of the player team. This trigger type is used in the original content to display area names to players when they move around the map to help with additional orientation and communication inside the team.

This trigger type can have a few different types of contents. First is uses a “condition” content, which I’ll specify in chapter 7. But besides that it has three optional special child elements called “on_enter”, “on_exit” and “on_inside”, which will run for example when the player enters exits or stays inside the zone, if the given conditions are found to be true. These can be given a few different sub functions defined by their “name” attribute, which will be covered in chapter 7.

The “player_trigger” element also has its own attributes. The first is “name”, which just like for normal triggers has to be unique and is required as it’s used to activate and deactivate each “player_trigger”. The next is “player_type”, which specifies which type of player that can activate the trigger. This attribute can be used in team versus team multi player modes to make the “player_trigger” only usable by one side. See beginning of chapter 5 for details on acceptable “player_type” versions.

An example of the “player_trigger” element:

 
 

Briefings
 “briefing” is the base element used to define what is shown during the missions briefing in game modes using the briefing screen. It can be given child elements to define which map to display, where to place markers or text on the map, which movie to run in the NarCom window, which strings to use as briefing text, as well as the maximum number of members in the campaign team including AI soldiers. This is quite straight forward but we’ll cover it more in detail in chapter 8.

An example of the “briefing” element:

 
 
 
 

Events
“event” is the base element used to create the bulk of the script which actually drive the mission forward. The “event” element has an attribute called “name”, which is very important. This name is only used inside mission.xml, but it’s what you will use to execute or stop that event when the script is running, and as such it’s required to be unique for each event. Always use a name that describes what the purpose of the event is to make it easier on yourself.

There is also optional attributes. The first is called “type”, which is used to define if the event should only be able to run once by giving it the value “once”, and if not used it will default to make the event run unlimited times. The second is “breakable”, which defines if the event can be stopped once it’s executed and still not reached the end tag. The default value for “breakable” is “true” if it’s not used.

The event content only consists of one element type, simply called “element”. It sounds simple, but it can be set to a lot of different type by setting its first attribute “type”. All of these types and all their special attributes and are covered in chapter 6, but for now it’s good to know that most of them at least have no contents of their own. It’s always a good thing to list the elements in the order you want them to execute, so that it’s easier to read the script, although it’s not needed as executing order is set by an attribute that all event content elements have, called “start_time”. This attribute is usually declared last of the attributes for each element and set in seconds delay that this specific element should have in executing after the event itself has been called. I’ll show this in examples in later chapters. And then again at the end, don’t forget to close your tags.

An example of the “event” element:

 
 

Very important to know about before starting to script a mission is the special “event” named “start_game”. You have to have this event and it’s executed automatically when the map is loaded. Here you can define which different insertions the mission has for example. The next special event is called “start_mission” and it’s executed when the team leader hits the launch mission button, at the same time as the events specified for the selected insertion (which I’ll cover later). This event is not needed as the insertion event can be used to start your script execution chain, but elements that are common to all insertion options should be included in the “start_mission” event instead to repetitive code and keep it cleaner. There is also a special event called “start_round”, which is executed for each player in multi player once they first join a new round.
 
With knowledge about the base elements used inside each GRAW2 mission.xml, we’ll move on with a simple scripting example next.

[Wolfsong]

Chapter 3: Human Activated Locations

With the basics covered, let’s finally get into some scripting. I think we should begin by looking at something that you’ll use quite often in missions, triggers that activates when member of the player team enters a location. They are a fairly simple setup and not very complicated to use, so a good place to start. I’ll try to add a much descriptive text as I can in this chapter as it’s our first look at actual mission scripting in GRAW2.

Our goal in this chapter is to create a location that will act as a trigger, which checks if a member of the player team is inside it, and if so that condition will return the value true and the trigger will call an event that will execute and activate a hostile group which will attack the player. A quite simple and common setup to be found in most mission scripts, and something you should know by heart after a while.

Here is the script that we’ll need:

     player_type=”campaign_team” amount=”1”/>
 



 



 

At first you may think it looks complicated, but I’ll explain it all step by step and gradually let you do more and more of the thinking as the chapters goes.

World.xml
For this script to work we’ll first need to place a few objects in the map editor, which then will be saved into the world.xml. Those things are a location, which I named “enemy_area01” in the map editor, and a human group of any hostile kind you want to use, which I named “enemy_group01”. Save it and the world.xml will be updated.
 
Location Trigger
Next we’ll need to do some scripting in mission.xml. Let’s begin with defining the trigger and its child condition so that the game knows what location and what group to look for, how many members of the group that has to be inside the location for it to return that the condition is true, and also how often it should do this check after the trigger has been activated.

That part of the script looks like this:

     player_type=”campaign_team” amount=”1”/>
 

First we have the element type “trigger” itself, as described in chapter 2 it’s what we have to use to make the game check if a set condition is true so we know that our “event” should be executed.

Next is the required attribute, “name”, where you set the name used to refer to this trigger inside the mission.xml. Use something descriptive so you remember what the purpose of the trigger is in the script. I’ll call it “enemy_area01_trigger”.

After that we need to set the “interval” for how often our check should be made after the trigger is activated (which we’ll cover later). This is set in seconds, and let’s says that it’s an important check, so let’s set it to “0.3”.

Note: The interval value depends on the size off the area and how important it is that the area detects the player as soon as possible when he/she enters. If the area is small and the interval is large, the player may pass through the area before the check is run, and then it won’t detect the player’s presence. On the other hand if the interval is set to a small number it will run more frequently and take up more processing power which could be useful in other areas. So it’s a balance act to optimize the needed interval time for each trigger.

Next we need to a “condition” child element. It should be of the type we want the trigger to use when deciding if its given event should be called to execute. So we’ll set its “type” attribute to “UnitInLocation”, as we want to check for the presence of units inside the location we created in the map editor. This specific type has a required attribute called “location”, which we have to set to the name we gave the location inside the map editor when we defined it, that is now stored inside the world.xml, so the script knows which defined location to check inside.

Tip: You can use the same area in unlimited amounts of conditions, all looking for different groups, vehicles or amounts.
 
Next, as we want to check against the player team, we’ll use an optional attribute called “player_type”, which we give the value “campaign_team” that is the global variable for any member of the player team (all the different optional attributes and possible global attributes they use are listed in chapter 5).

As a last optional attribute the condition requires one of the many comparing attributes that this element uses to determine if the condition is true or false. Let’s use the simplest one called “amount”, which uses an exact value to compare against the current amount of members from the given group that are inside the given location. We will give this attribute the value “1” as we want the trigger to activate the given even once the first member of the player team enters the location. We could also give the attribute the value “all” if we wanted the condition to require the entire group to be inside the location for it to return true when checked. Another way we could use this condition type is to require that no member of the given group is inside the location to return true when checked, and then we would set it to “0”.

Note: Don’t set it to a bigger integer than the group has members or it won’t be able to ever return true when checked, which then makes the trigger using the condition unable to ever run successfully.

As the last part of the trigger we need to tell it which event to call if the above condition is checked to be true. For this we use an element called “event” (which is NOT the same “event” we use as a base element). It has only one required attribute called “name”, which we give the name of the event to call if the triggers conditions are true. Let’s call this “show_enemy_group01” which describes what it will do, and we’ll create that next.

Finally don’t forget to close the tags.

Enemy Activation Event
Now we’ll create the event that is called by the trigger and does the actual work of activating the enemy group. It’s a normal base “event”, which will never execute if no trigger or other event tells it to do so.

That part of the script looks like this:

 

First we create the “event” and set its “name” attribute. Set it to the same name as used for the trigger to call if it’s condition where true, “show_enemy_group01”.

Next we’ll add an “element” that is going to perform the action we where looking for, so set its “type” attribute to “ActivateGroup”. This element type can only do one thing; spawn in groups defined in world.xml to the game world and tell that group to start its behavior set in the map editor. For this it requires that we set its “group_id” attribute to the name of the group we want to show, which is the same as the name we gave the group when we created it in the map editor, “enemy_group01”.

Then close the “event” tag and it’s done.

Trigger Activation Event
Finally we need to activate every trigger we want to start performing their checks. There is a specific “element” type, which can only activate triggers, but as we learned in chapter 2, “element” only work inside an “event”. Which event to use depends on when during the mission that the area should be activated? In this example, let’s say that the area is close to when the player is inserted at the beginning of the mission and therefore we’ll activate it inside the special event named “start_mission”, which was covered at the end of chapter 2.

Note: The element can be used inside any event in this mission.xml.

That part of the script looks like this:

 

First add a child element of the type “element” inside the event tags. The “type” of element we need now is called “StartTrigger” which can only activate any given trigger. This element type also requires an attribute called “name”, where we must enter the name we gave to our trigger when we defined it.

Now let’s just close our tags and where done. We have now created a script that will detect is a member of the player team is inside a given location and if so, activates an enemy group.

Alternative Location Conditions
If you want to create the same script but let a non-player group or a vehicle activate the trigger, it’s just as easy but with one different attribute in the condition element.

Player version (as described in this chapter):

   player_type=”campaign_team” amount=”1”/>

AI Group version:

   group_id=”group_01” amount=”1”/>

Vehicle version:

   vehicle_id=”tank_01” amount=”1”/>

As you can see the only difference is the use of the attribute “group_id” or “vehicle_id” instead of the attribute “player_type”. Great, now we know how to set those up as well.

Next we’ll take a look at using objectives before we get in deep with all the condition and element types available in GRAW2.

[Wolfsong]

Chapter 4: Objective UI

Ok. Now you should know a little more about how the syntax works, so I won’t describe everything at the same level as in the previous chapter but will of course explain anything new and the function of the script itself.

Our goal in this chapter is to create an objective with headline, descriptive text and a waypoint marker in the HUD. We want to update the objective during the mission and finally declare the objective completed. Important to understand is that nothing that we create in this chapter will have anything to do with what the actual objective is, in other words, what activates it, what is required to update it, or what is required to complete it? Nor will the script in this chapter work by itself. All we’re going to do is create the parts that the player can see during the mission, the HUD and map elements. For the objective to actually do anything and drive the mission forward, you’ll need to use triggers and other events based on your mission design. All available trigger conditions will be covered in detail in chapter 5.

We really wouldn’t need to enclose each of the elements covered in this chapter inside their own events, but we’ll do that anyhow to show that they are used in different parts of the script. In your mission you can, and probably will, use them inside any event you want, combined with other elements.

Here is the script that we’ll need to reach the goal of this chapter:

     headline_id=”mx_obj1_head” txt_id=”mx_obj1_txt”
   waypoint_id=”mx_obj1_wp” waypoint=”10171 -9296 106”/>



     headline_id=”mx_obj1_head” txt_id=”mx_obj1_txt2”
   waypoint_id=”mx_obj1_wp” waypoint=”10171 -9296 106”/>



 

To do this we need nothing from the world.xml, but we need to have the coordinates to where we want the waypoint marker to appear. One way of getting this is to use the panel inside the map editor, activated by pressing “/” or your numeric keypad, and moving your camera to around the area where you want it to be placed and then writing down the coordinates seen in the lower right corner. Another way is to place a prop where you want it to be, name it something like “objective_marker_pos”, save your file and them open the world.xml in you XML editor and do a search for “objective_marker_pos”. Then you’ll find its coordinates listed next to it’s entry in there, copy them to somewhere safe and then back in the map editor, delete the prop.
 
Add Objective Event
The first thing we need is an event that adds the objective for the player to see.

That part of the script looks like this:

     headline_id=”mx_obj1_head” txt_id=”mx_obj1_txt”
   waypoint_id=”mx_obj1_wp” waypoint=”10171 -9296 106”/>

For this we create a simple event and give it a name that is descriptive so we later can easily find it in our script. This you know by now so let’s concentrate on the content element.

We only need one element to initiate an objective for the player and it’s of the type “objective”. This element type has many attributes that are optional to use depending on what you want to do with the objective itself.

First we’ll set the attributes that “objective” always requires, which is “id” and “state”. “id” is the name that we’ll use inside the script to add, update and remove the objective, lets call this “obj1”. In “state” we determine what’s going to happen to the objective GUI, and as we now want to add it as a new objective, set it to “add”.

Then we want to tell the game which strings to use as objective headline and objective description. This is done by setting the attributes “headline_id” and “txt_id”, which require you to enter the name of string variables created in the strings.xml connected with your mission, which you don’t have to use. There is another option to enter headline and description to an objective, that doesn’t require a strings.xml file. Instead of using “headline_id” you simply use the attribute “headline” and enter the text you want inside the quotation marks. The same thing can be done for the description, when “txt” is used instead of “txt_id”. The strings.xml files are used to allow for multi language support.

That was it for the objective part. Now we need to set the attributes for the waypoint marker. The first of those is “waypoint_id”, which works the same as the other string attributes, but holds the string that will be visible under the waypoint in the HUD. This attribute also accepts text written directly between the quotation marks, if that text isn’t matching the name of a string variable in the strings.xml. The second attribute needed is “waypoint”, which requires the coordinates of where the waypoint should appear in the game world that we got earlier somehow. These are entered as three floats in the order “x”, “y” and “z”. Now all that is left is closing all tags.
 
Update Objective Event
Now the player can see the objective in the list, read the description and see the waypoint on the map and in the HUD. But during this objective the description will change when a given trigger condition is set. This could also be used to move the waypoint marker by simply adding new coordinates for it, but we’ll leave it this time.

That part of the script looks like this:

     headline_id=”mx_obj1_head” txt_id=”mx_obj1_txt2”
   waypoint_id=”mx_obj1_wp” waypoint=”10171 -9296 106”/>

Create a new event and give it a good name. We’ll only need one element as contents again, and once again we’ll set the “type” to “objective”. As we want to update the objective we added earlier, we’ll have to set “id” the same as we did before. Then we’ll set “state” to “update”. Next we’ll use the “headline_id” and “txt_id” again. As we don’t want to change the objective headline, we’ll set the same string for that as before, but we want to change the description, and so we simply set another value to the “txt_id”.

As we don’t want to change the objective waypoint, we’ll set all those value the same again, and finish by checking that all tags are closed.


Completing Objective Event
Finally we want to create the event that declares the objective completed in the list and removes the waypoint.

That part of the script looks like this:

 

Create yet another new event and give it a good name. Once again we’ll only need one element as content with the “type” set to “objective”. Then again tell the game which objective you want to manipulate by setting “id” to the name we gave it when first adding it. Finally to remove the objective and the waypoint, we’ll set “state” to “completed”. The reason both the objective was set as complete and the waypoint was removed is that they have the same “id”. I’ll show next how to do this with separate waypoint controls. But first, close all tags, and we’re done with the goal for this chapter.
 
Separate Waypoint Control
For some objectives you’ll probably want more then one waypoint marker and/or have separate control over it in the script. To get the later you’ll need to have a separate id for just the waypoint marker. This is done by defining the objective and the waypoint in separate elements.

Objective and waypoint with a single id:

     headline_id=”mx_obj1_head” txt_id=”mx_obj1_txt”
   waypoint_id=”mx_obj1_wp” waypoint=”10171 -9296 106”/>

Objective and waypoint with separate ids:

     headline_id=”mx_obj1_head” txt_id=”mx_obj1_txt” />
     waypoint_id=”mx_obj1_wp” waypoint=”10171 -9296 106”/>

If you want to add multiple waypoints for an objective, you simply do it by adding an additional element for each additional waypoint.

Objective with two waypoints:

     headline_id=”mx_obj1_head” txt_id=”mx_obj1_txt” />
     waypoint_id=”mx_obj1_wp” waypoint=”10171 -9296 106”/>
     waypoint_id=”mx_obj1_wp” waypoint=”10500 -8256 -90”/>

When you define everything with separate ids, you also have to remember to remove them all at the end with separate elements.

Strings.xml
The strings.xml file is something that all original missions use to define strings containing the text to be shown during the mission, including the briefing text seen in single player. These files are found in the data/strings catalogue.

Note: The tutorial "GRAW2: The Editor" will cover how to setup a custom strings.xml file in the level folder instead.

Inside it uses very simple XML, with one base element containing all string variable elements.

Example of string.xml contents:

 
 
 

[Wolfsong]

Chapter 5: Trigger Conditions

Now that we are really starting to understand the syntax, we need more trigger conditions to be able to set up different situations in our mission flow.

This chapter will only cover what condition types are available for triggers and what attributes they require. The basic syntax for triggers was covered in chapter 2, and won’t be repeated here.

Player Type Attribute
Some conditions have a special group identification attribute called “player_type”. This attribute is created to make it easier to create checks against the player or players. There are four different values that this attribute accepts, which are “campaign_team”, “team_a”, “team_b” and “team_all”.

campaign_team   (Used for the single player and campaign coop player team.)
team_a   (Used for the ghost team in all other MP modes)
team_b   (Used for the rebel team in all other MP modes)
team_all   (Used for both sides in all other MP modes)

Conditions

Always
- Always returns true.
EvaluateVar
- Variable value condition.
InUse
- Usable object in use condition.
Never
- Always returns false.
PlayersNotPermanentlyDead
- Players permanently dead condition.
PlayersNotSpawnedYet
- Players not yet spawned condition.
ServerSetting
- Server settings condition.
ServerSideVar
- Server settings condition.
SoldiersKilled
- Group members killed condition.
UnitDestroyed
- Destroyed prop or static condition.
UnitHasWeapon
- Unit or group carrying specific weapon condition.
UnitInCombat
- Group members in combat condition.
UnitInLocation
- Players, vehicles or AI in location condition.
UnitInTransport
- Players or AI in vehicle condition.
VehicleDestroyed
- Destroyed vehicle condition.

.
.
.
.
To be continued in the 1.3 Patch.