Dragon Age Toolset Wiki - User contributions [en]

Scripting tutorial

2009-11-08T23:55:05Z

Hydra1448: /* Passing execution to other event handlers */

The final piece of the puzzle in our little tutorial game is getting the <code>MONSTERS_SLAIN</code> flag set on our plot so that when the hero succeeds in his quest, the quest giver will know about it. This is done via scripting.

Scripting is a programming language with a syntax similar to C. This tutorial assumes a small amount of programming knowlege but hopefully it will be possible even for one with no experience to pick up the basics here.

== Dragon Age's event-driven model ==

In Dragon Age scripts are primarily event-driven. An "event" is a package of information in a special format that gets passed around in the game to trigger behaviour. They are generated by other scripts or the game engine and are passed to an object's event-handling script.

Events have a type, a target object, a time delay and a package of parameters (arbitrary number of ints, objects, floats and strings).

As an example, the "<code>[[EVENT_TYPE_ATTACK_IMPACT]]</code>" event is sent by the game engine whenever an attack hits a target. It contains the identities of the attacker and the target, whether the attack was a critical hit, and the amount of damage that the attack did. It is sent to an event-handling script attached to the attacker, which takes the information it contains and handles it in whatever way is appropriate (reducing the target's hit points, usually).

For our purposes right now we're not going to need to generate any events of our own. We have set all of the hut monsters to be members of team 1, and the game has a built-in feature that will generate an event when all of the members of a particular team of creatures has been killed. Our new script will respond to that event by setting the plot flag so that when the hut monsters are all defeated, the plot will change to indicate the quest objective has been accomplished.

An enormous list of events for all occasions can be found at the [[event]] page. The one we're going to want our script to look for is <code>[[EVENT_TYPE_TEAM_DESTROYED]]</code>, which is sent when the last member of a team of creatures is destroyed. The event contains the team number within it.

== Creating a basic event-handling script ==

Start by creating a new script resource. We'll call our script "<code>hut_monsters_slain</code>".

In most cases when a script is run the scripting engine will start with a function named "<code>main</code>". So for most scripts you'll want to start with this very basic beginning:

<pre>
void main()
{

}
</pre>

The code that will perform our tasks will be inserted between the { and } brackets. <code>main</code> doesn't return any results directly, so the function's return type is "<code>[[void]]</code>", and it takes no parameters, so the parameter list is an empty ().

=== Event type constants ===

Next we're going to need to make sure the script will know what we're talking about when we make references to events. The tag that tells us the type of each event is is actually represented internally by a number, but since it would be impossible for a programmer to keep track of all the different event numbers without making hard-to-find mistakes Dragon Age has instead used named constants to represent them in a more human-readable name.

Those constants are defined in the script <code>events_h</code>. The "<code>_h</code>" suffix stands for "header", which is a special class of script that contains only various definitions meant to be included in other scripts and doesn't do anything on its own.

To include the header file, add this line to the top of our script:

<pre>#include "events_h"</pre>

All <code>#include</code> commands should be at the top of your script before anything else, but if there's more than one it shouldn't matter what order they are in.

To see whether our script now knows what <code>[[EVENT_TYPE_TEAM_DESTROYED]]</code> means you can use the constant browser on the right edge of the script editor to check if it's listed. The browser defaults to showing a list of all defined functions (the "f()" button), to set it to show all defined constants click on the "C" button.

[[Image:Scripting constant browser.png]]

Even without any included files the list of defined constants is going to be quite long, and for scripts with many include files it can be very difficult to find any particular constant - especially if you aren't sure exactly what its name is. To find constants more easily, type any part of its name into the filter field at the top.

[[Image:Scripting constant browser filtered.png]]

To insert the constant into the script at the location where the cursor is currently located, simply double-click on the constant in the constant browser. This avoids any risk of making a typo.

=== Extracting information about the current event ===

When an event is sent to a script the script's <code>main</code> function will be run, but it won't know anything about the event that caused it to be run without some explicit instructions.

First, you will need to retrieve the package of data that is the event. We'll define a variable named <code>ev</code> that will hold this package, and set it to the "<code>event</code>" data type. To retrieve the current event and stick it into that variable, we'll use the engine-defined function <code>[[GetCurrentEvent]]</code>.

The first line of the main function will therefore be:
<code>event ev = GetCurrentEvent();</code>

Every event will have an event type. As described above, this event type is represented internally by an integer. We'll create an integer variable named <code>nEventType</code> to hold it, and use the <code>GetEventType</code> function to extract it from <code>ev</code>. The next line will be:

<code>int nEventType = [[GetEventType]](ev);</code>

The rest of the information packaged with the event depends on exactly what kind of event it is, so the rest of the code we write will be event-specific. To make sure only the correct code is run we'll use a <code>switch</code> statement. We're only looking for one particular event so we could just as easily have used an <code>if</code> statement but a <code>switch</code> is more extendable for future use.

<pre>
switch(nEventType)
{
case EVENT_TYPE_TEAM_DESTROYED:
{
//our event-specific code goes here
break;
}
}
</pre>

We know from the documentation for the <code>[[EVENT_TYPE_TEAM_DESTROYED]]</code> event, that it comes with a single piece of information; the team number. It's an integer, so we can extract it with the <code>[[GetEventInteger]]</code> function. <code>[[GetEventInteger]]</code> takes two parameters, the event object (which we've stored in the variable <code>ev</code>) and the index of the integer we want, in this case 0 (this is listed in the documentation).

We also know that the team number we gave the hut monsters is 1, so we want to update the plot only when we receive an event indicating that team number 1 has been destroyed. We can do this with an <code>if</code> statement:

<pre>
if (GetEventInteger(ev,0) == 1)
{
//code to update the plot here
}
</pre>

== Interacting with plots ==

To interact with a plot's flags you'll need to have some way for the script to know where the plot flags are and what they're named. This is done in a similar manner to how we told the script what the event types were named; by including the plot file in the script.

Plots are not the same as regular scripts, though, so when including them they are distinguished from regular scripts through the use of a <code>plt_</code> prefix in their name. The plot we wish to interact with is called <code>clear_the_hut</code>, so at the top of the script file you'll need to put the line:

<code>#include "plt_clear_the_hut"</code>

Now your script will have access to the plot's flags and will be able to read or change them. You'll find that several new constants have been defined; <code>PLT_CLEAR_THE_HUT</code> contains the plot object, and the integer constants <code>MONSTERS_SLAIN</code>, <code>QUEST_ACCEPTED</code> and <code>REWARD_RECEIVED</code> identify the flags within the plot.

Changing the state of the flags is done with the <code>WR_SetPlotFlag</code> function that is defined in the include file <code>wrappers_h</code> (<code>wrappers_h</code> contains a variety of utility functions that handle operations requiring low-level access to the game. Add <code>#include "wrappers_h"</code> to the top of your script). In our case, we want to set the plot flag <code>MONSTERS_SLAIN</code>. The <code>WR_SetPlotFlag</code> function takes three parameters; the plot identifier, the flag identifier, and the state we want to set it to:

<pre>
WR_SetPlotFlag(PLT_CLEAR_THE_HUT, MONSTERS_SLAIN, TRUE);
</pre>

== Associating an event script with an object ==

The script is almost complete now, but until we've linked it up to some object in the game that can receive events it will never actually be run.

Most objects in the game will have a field named "Script" shown in the object inspector. According to the documentation for the <code>EVENT_TYPE_TEAM_DESTROYED</code> event it is sent to the area object the team is in, so we'll want to open the hut_interior area now and go to its Script entry. The default event script for areas is <code>area_core</code>, which handles basic area events in a default way.

This is where you'll want to put the <code>hut_monsters_slain</code> script. Click on the ellipsis ([[Image:ellipsis.png]]) button and select the new script. It will replace <code>area_core</code>, and now when there are events sent to this area our new script will be triggered and handle them.

=== Passing execution to other event handlers ===

There is just one problem remaining to be resolved now. As mentioned above, the <code>area_core</code> script normally handles a variety of events that are sent to areas. Now that we've replaced the default event handler with our custom script, and our script only responds to one specific event, there's nothing responding to the rest of the events coming into the area any more. Our custom script has preempted and therefore effectively disabled all the default area event processing by not responding to every possible area event.

We don't want to re-implement all that default event handling in our own script, for a variety of reasons; it's a lot of work, we could make mistakes, and it would be difficult to update the default event handling across all of our areas in the future. Fortunately there's an easy way to tell Dragon Age to use another script to handle events; namely, the <code>[[HandleEvent]]</code> function. It takes two parameters, the event object to be handled and an identifier for the script that should handle it.

A set of constants defining identifiers for the common default scripts is in the <code>global_objects_h</code> header file, but we won't need to include that because <code>wrappers_h</code> includes it already. So all we need to do is insert the following line after our switch statement:

<pre>
HandleEvent(ev, RESOURCE_SCRIPT_AREA_CORE);
</pre>

(The RESOURCE_SCRIPT_AREA_CORE constant is defined in global_objects_h, which we don't need to include explicitly in this case because it's already included in wrappers_h.)

With this addition, whenever any event is sent to the hut_interior area, first our script will run and process the event, and then it will send it on to <code>area_core</code> to handle the default area processing normally done when no custom event handling script is being used.

The final text of our script, then, is:

<pre>
#include "events_h"
#include "plt_clear_The_hut"
#include "wrappers_h"

void main()
{
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);

switch(nEventType)
{
case EVENT_TYPE_TEAM_DESTROYED:
{
if(GetEventInteger(ev,0) == 1)
{
WR_SetPlotFlag(PLT_CLEAR_THE_HUT, MONSTERS_SLAIN, TRUE);
}
break;
}
}
HandleEvent(ev, RESOURCE_SCRIPT_AREA_CORE);
}
</pre>

[[Category:Scripts]]
[[Category:Tutorials]]

Module tutorial

2009-11-06T22:23:24Z

Hydra1448: /* Naming conventions */

This simple demo module is intended to show off a variety of methods that will be commonly used in real stand-alone modules. The documentation here on this website will walk you through the major steps required to set it all up, but the module itself also has documentation embedded within it in the form of comments; it is intended to be explored in the designer toolkit and dissected to see how things tick.

One thing that this demo doesn't demonstrate is the art of writing. As such the 'plot' of the adventure is somewhat nonsensical.

This tutorial also assumes that you've read many of the other basic tutorials elsewhere on this site and are familiar with the basic functioning of the toolkit. Links will be provided directing you to more specific information if needed.

== Organization ==

There are two major groups of resources that are used when creating a Dragon Age module; designer resources and art resources. Designer resources are housed in a database whereas art resources take the form of conventional files on your file system.

For your art resources the most convenient approach it is probably to create a directory tree with subdirectories sorting your art resources by what regions of the game they appear in. The directory tree should be someplace easily accessible and with full read/write priviledges - somewhere in your "My Documents" folder is a good place to put them.

In our example we're going to have three areas:
*A swampy outdoor area with a small tavern in it
*The tavern's interior
*An outdoor roadway

=== Naming conventions ===

For the most part the names you give your resources will matter only to you, there are very few situations where the toolset pays attention to the specific form that a resource name takes. So provided you're working on your own, any naming convention that suits your particular style will suffice.

Dragon Age is a large and complex game to create content for, however, so establishing ''some'' form of naming convention and adhering to it from the outset is important to ensure you don't lose track of things later on. A consistent naming system is very useful for debugging and if you later choose to collaborate with other builders it allows you to find your way around other peoples' work without needing to know it intimately.

The convention used in the main Single Player campaign of Dragon Age is as follows:

*Three-letter prefix indicating which large-scale area of the game the resource begins to (particular origin story, prelude, etc)
*three-digit number unique to a particular area, generally starting with 100 and incrementing in hundreds for major areas. Accessory areas are given numbers within the block of one hundred that their 'parent' area belongs to. "global" resources are often given the number 000.
*two-letter code indicating what general type of resource it is (for example "ar" for area, "pl" for placeable). A major exception here is event scripts, which have exactly the same name as the resource they're the script for. Dialogue files are also generally named exactly the same as their owner resource.
*An underscore.
*The remainder of the name is free-form and human-readable, a descriptive term to remind you at a glance what the resource is.

Designer resources will have a three-letter extension, much like a regular file system file, but this is not editable and does not frequently come up.

Resources in the designer toolkit can also be placed into folders, again much like a regular file system. Unlike most file systems, though, you don't need to explicitly create a folder in order to put a resource into it. Just edit the resource's "folder" property and if the folder didn't have anything in it before it'll be created automatically. Folders that don't have any resources in them are removed automatically.

Here's a preview of what we're going to put into the demo module, to illustrate how this naming convention looks in practice. We'll be using the four-letter prefix "demo" instead of the usual three-letter one for clarity.

[[screenshot of demo resource palette]]

== Setting up character generation in a new module ==

The most basic steps of creating a new module are described in "[[creating a module]]". A Dragon Age module, when first created, lacks many very basic components such as the ability to generate a character or an area to start in.

Note that you can actually start creating areas and testing content before you set up character creation if you prefer, the game will provide a player with a simple (and very weak!) default character if character generation isn't performed. You can also override the default starting area and waypoint every time you export for testing purposes, using the "Export Options" found under the "Tools" menu, so you can skip directly to the area you're working on without needing to write debugging scripts.

We're going to follow the flow of the finished game for now, though, so after creating the module the first thing we'll want to do is create a module script that triggers character generation.

Once you've created the initial empty module you'll need to create a module script. We call it "demo_module". The event that we'll want to handle character generation in is EVENT_TYPE_MODULE_START, which is sent to the module script only once when the game is first started up.

To call the default character generation system, simply have this event call the following functions:

<pre>
PreloadCharGen();
StartCharGen(GetHero(),0);
</pre>

PreloadCharGen causes the game to load up various resources that will be used in character generation, and StartCharGen causes the game to show the character generation GUI to the player.

== Creating our areas ==

This module will be very simple, consisting of only three areas - only two of which will have any signficiant amount of detail. They will be named:

* demo100ar_wilderness
* demo200ar_tavern
* demo300ar_road

Three level layouts ([[LVL]] files) are included with the module for use in these areas; ost101d (a swampy wasteland with a small wooden structure), hrt002d (a small tavern interior), and lgt600d (a section of roadway). The naming convention for level layouts used internally at BioWare is specific to the single player campaign, the meaning of these filenames is not relevant to this basic tutorial.

The area editor (and the game itself) cannot use a LVL file directly, it must be compiled into a more efficient form for use. Open up each LVL file in the level editor and, under tools, select "Post to local" to compile the level and export it to an appropriate directory where the game and toolset will be able to find it.

Once you've done this you can select the layout in the area editor's "Area Layout" property field.

== Placing area transitions and setting up the world map ==

See the [[Area tutorial]] for details on how to link areas up with level transitions. The transition from demo100ar_wilderness to demo200_tavern is straightforward and is basically the same as what's shown in that tutorial.

The transition between demo100ar_wilderness and demo300ar_road, however, is going to be handled via the world [[map]] instead. The demo's map is a resource named demo000mp_world.

To create an area transition that sends the player to the world map, set the PLC_AT_DEST_AREA_TAG to the string "world_map". The placeable_core script recognizes this string as a special override that triggers a map transition by sending the module script an EVENT_TYPE_BEGIN_TRAVEL event.

Note that you can have multiple world maps in a module, but under the default code you can't directly specify which one an area transition will send the player to. Instead, you will need to call the script function WR_SetWorldMapPrimary to specify which world map is the currently active "primary" one. In this demo the code that performs this is also in the EVENT_TYPE_MODULE_START event of the module script, since we only have one map and it only needs to be set as primary once. If you have multiple maps in your module you'll need to call this function again later from some other scripted event to change it.

Here, then, is the complete code for the demo module's EVENT_TYPE_MODULE_START event:

<pre>
case EVENT_TYPE_MODULE_START:
{
object oMapId = GetObjectByTag("demo000mp_world");
WR_SetWorldMapPrimary(oMapId);

PreloadCharGen();
StartCharGen(GetHero(),0);
break;
}

</pre>

Although the default placeable_core script has code in it to recognize that the "world_map" string should lead to a world transition and generates an EVENT_TYPE_BEGIN_TRAVEL event, the default module_core script doesn't actually do anything with this event. This is because the map transition code used in Dragon Age's single player world map transitions is rather complex and has to handle many special cases that depend on plot elements specific to the single player campaign, so BioWare never implemented a basic default - it would have had to be overridden completely anyway.

Fortunately it's quite easy to add one, though there's a slight hitch; the area transition code needs to be split over two different events.

* In EVENT_TYPE_BEGIN_TRAVEL you'll be able to get the target area and waypoint tags from the event object, and then call the <pre>WorldMapStartTravelling</pre> function to cause the map to start animating the map trail path the player is following.

* While the map trail animation is playing, the EVENT_TYPE_WORLDMAP_PRETRANSITION event is called. This is the event where you'll want to call the <pre>UT_DoAreaTransition</pre> function to start the loading process of the destination area. The area will load at the same time that the map trail animation is playing, making the transition seem more seamless for the player. Note, however, that EVENT_TYPE_WORLDMAP_PRETRANSITION's event object ''doesn't'' contain the destination area and waypoint tags as members; you'll need to use local variables in the module's variable table to preserve these strings and pass them on from EVENT_TYPE_BEGIN_TRAVEL.

The basic code to handle map travel, then, is:

<pre>
////////////////////////////////////////////////////////////////////////
// Sent by: The engine
// When: the player clicks on a destination in the world map
////////////////////////////////////////////////////////////////////////
case EVENT_TYPE_BEGIN_TRAVEL:
{
string sSource = GetEventString(ev, 0); //area tag source location
string sTarget = GetEventString(ev, 1); // area tag target location
string sWPOverride = GetEventString(ev, 2); // waypoint tag override
if (sSource != sTarget)
{
//store target area's tag to a local module variable
SetLocalString(GetModule(), "WM_STORED_AREA", sTarget);
//store target waypoint tag
SetLocalString(GetModule(), "WM_STORED_WP", sWPOverride);
//initiate the map's travelling animation. The engine will
//send EVENT_TYPE_WORLDMAP_PRETRANSITION once it's started.
WorldMapStartTravelling();
}
}

////////////////////////////////////////////////////////////////////////
// Sent by: The engine
// When: the world map has begun its "travelling" animation
////////////////////////////////////////////////////////////////////////
case EVENT_TYPE_WORLDMAP_PRETRANSITION:
{
//retrieve the target area tag we stored in EVENT_TYPE_BEGIN_TRAVEL
string sArea = GetLocalString(GetModule(), "WM_STORED_AREA");
//retrieve the target waypoint tag
string sWP = GetLocalString(GetModule(), "WM_STORED_WP");
//execute the area transition to that target.
UT_DoAreaTransition(sArea, sWP);
break;
}
</pre>

We'll need to come back to the module script later on to add some plot-specific code, but for now this is all that's needed to enable a basic adventure to stand on its own.

== Introductory cutscene ==

After the player has finished character generation we play an introductory cutscene for him before the game starts.

The cutscene itself is quite simple, consisting of a few camera movements and an actor (substituted by the player) playing a walking animation. See [[cutscene tutorial]] for how to create a cutscene.

To make it play when the game begins we need to call it at the appropriate time with the CS_LoadCutscene function. The appropriate time has to be after the area that the cutscene is located in as loaded, otherwise the cutscene won't be able to play. The event that's best suited for this is EVENT_TYPE_AREALOAD_SPECIAL, which is called on an area's event script after the area has loaded but before any of the other game systems (AI and so forth) have been enabled. So in this case we want to insert the function call into the area script for the starting area, demo100ar_wilderness. We only want the cutscene to play the first time we enter this area so we've wrapped the function call in a plot flag check;

<pre>
case EVENT_TYPE_AREALOAD_SPECIAL:
{
if (!WR_GetPlotFlag(PLT_DEMO000PL_MAIN, DEMO_INTRO_COMPLETE))
{
CS_LoadCutscene(R"demo100ct_intro.cut");
WR_SetPlotFlag(PLT_DEMO000PL_MAIN, DEMO_INTRO_COMPLETE,TRUE); //sets the plot flag to ensure we don't repeat the intro cutscene.
}
break;
}
</pre>

== The main plot file ==

For this demo module, all of the major events relating to the development of the plot are kept track of in the demo000pl_main plot file. This also allows for a centralized place to put scripting that deals with these events.

The plot outline of the demo module is:

#Player encounters the innkeeper outside his inn and speaks with him, receiving the quest to retrieve the innkeeper's sword.
#Player enters the inn. As he approaches the lever that will open the door to the room the sword is in, the bandit that's taken over the inn initiates conversation with the player. This leads to combat.
#Player pulls the lever, blowing up the door to the room the sword is in
#Player retrieves the sword
#Player returns the sword to the innkeeper, who offers to join the party. A new area also opens up on the world map at this point.

We'll cover each of these events in a separate section of this documentation.

You may also note that many of the constants used in the code have been separated out into a "demo_consts_h" script file, even if they are only currently used in one particular place. This is not strictly necessary, and in fact the toolset doesn't recognize the "_h" suffix as having any special significance; whenever you save an _h script the toolset will try to compile it and complain about the lack of a main() or StartingConditional() function (you can ignore this complaint). However, it makes typos much easier to find and debug, and should you need to change a constant later on this approach ensures that you can always catch every instance of it.

== Giving the player an item ==

The first thing that happens if the player talks to the barkeep and accepts the quest is that the barkeep will give him a key. The key is a "plot item", meaning it will be shown in a separate section of the player's inventory and can't be given away or destroyed by the player, but the mechanism used here can give the player non-plot items as well.

The function UT_AddItemToInventory takes a resource variable as its parameter. It causes a new instance of the item to be created and added. If you call it multiple times with the same resource, earlier copies won't be affected - multiple copies of the item will be created. You'll see one way of removing an object from the player's inventory at the end of the quest when the innkeeper takes back his sword.

== Using a trigger to initiate conversation ==

We want the bandit and his loyal patrons to attack the player before the lever can be pulled. A trigger has been placed in such a manner that the player will have to pass through it before reaching the lever; the trick is now to use that trigger to make the things we want to have happen, happen.

When a trigger is entered by any entity the trigger's event script is sent an EVENT_TYPE_ENTER event. Note that this is sent ''every'' time the trigger is entered, by ''any'' entity, so the first thing we'll need to do in the event script is a test to ensure that the triggering entity is the player or one of his party members.

The IsPartyMember function tests to see whether an object is player-controllable, which is true for the player's character and for any creature currently in the player's party. We call it on the event's creator to check if this is the right person; if it's not the event script does nothing.

If we wanted the bandit and patrons to simply charge and attack the player, we'd have the trigger call UT_TeamGoesHostile(BANDIT_TEAM); directly (the bandit and patrons' creature templates are all set to the same team so that we don't need to set each one hostile individually). In this case an unexplained attack would be strange, so instead a conversation has been set up that has the bandit and patrons explain themselves before attacking. So we've set the trigger script to call UT_Talk instead.

Once this has been called, we never want the trigger to fire again for anyone. It is important to note that setting a trigger to "inactive" will ''not'' work; an inactive trigger still fires EVENT_TYPE_ENTER whenever an entity enters it. There are several approaches that can be used here:

*Set the event script to check the trigger's active status and not perform any action if it's inactive
*Use a plot flag to make the code only fire once
*call Safe_Destroy_Object(OBJECT_SELF, 0); to destroy the trigger entirely

Since there will be no circumstances where we'll need the trigger to become active again in the future, destroying the trigger is the simplest and most foolproof way of accomplishing this.

== Using a placeable to call a script ==

The lever placeable has a "use" option that allows the player to flip it from one state to the other. When this happens an EVENT_TYPE_USE event is sent to the placeable's event script. We've added a custom event script to the lever to intercept this event and do something special; demo200pl_security_lever.nss.

Rather than handling all the details of what should happen when the lever is pulled right in this script, though, we've instead put them into the main plot file's script. The custom placeable script serves only to set the appropriate main plot file flag.

[[Category:Tutorials]]