Dragon Age Toolset Wiki - User contributions [en]

Map tutorial

2009-10-08T15:27:09Z

Codepoetzz: /* Converting XLS files into GDA files */

Map objects are a way to allow the player to travel from area to area without having to follow a rigid path from one exit to the next. They're useful for representing large expanses of wide-open countryside, for example, or a city with various districts that the player can travel between freely but is too large to conveniently fit in a single area. Maps allow a world to be large without having to detail every little irrelevant place in it.

If you start by creating a new map resource within the designer toolkit, you'll quickly find that there is only a very limited pre-defined list of map images that are available for use. That's because map layouts are defined in a 2DA ("two-dimensional array"), a binary table of data that is used by the toolset to provide definitions but that is not itself editable from it. You may have encountered references to 2DAs when working with other objects. For example, the list of variables that an object's scripts can refer to is stored in a 2DA. This tutorial is going to assume that you've never worked with 2DAs themselves before. In a sense, this tutorial is as much a 2DA tutorial as it is a map tutorial.

== Terminology ==

This tutorial makes use of a number of different three-letter acronyms and specific terms that may be troublesome to keep track of at first. Before we dive straight in, here's a cheat sheet that may prove useful:

*2DA - "two-dimensional array", the table of data we'll be editing. Note that a 2DA can be stored in a human-readable or machine-readable format, each of which has their own names. "2DA" is used to refer to the table as an abstract concept.
*XLS - the file extension for an Excel spreadsheet.
*Worksheet - tabbed panes within an Excel spreadsheet. Each Excel spreadsheet can contain multiple worksheets and each worksheet can represent one 2DA, so one spreadsheet can contain multiple 2DAs.

[[Image:Worksheet tabs.png|frame|center|Worksheet tabs along the bottom of an Excel spreadsheet]]

*GDA - The file extension for a binary file usable by the game. 2DAs that have been processed by the resource exporter will be stored in this form.
*TGA - Targa graphics file extension. TGA graphic files are used to define the underlying appearance of the map itself.
*M2DA - "Multiple 2DA". Previous BioWare games have made use of 2DAs, but the 2DAs used in Dragon Age use this new format instead. It allows several different 2DAs to be combined together and treated as a single 2DA by the game, which is very useful for adding new content to an existing 2DA.

== The worldmaps.xls spreadsheet ==

See also [[worldmaps.xls]].

If we're creating maps for a brand new module we could in theory start with a blank Excel spreadsheet and build the required 2DAs from scratch. It's much easier, however, to start with an existing copy of the relevant spreadsheet from another module and replace the values within it with our own.

The spreadsheet that contains all the 2DAs relevant to world maps is <code>worldmaps.xls</code>. Open it in Excel and you'll find that it contains, among other worksheets, the "worldmaps" worksheet.

[[Image:Worldmaps worksheet.png|frame|center|The redaction will be removed when the game ships !!Note: mere moments after these screenshots were taken a NameStrRef column was added to allow localized map names. These screenshots will have to be redone anyway!!]]

This is the core 2DA that defines what maps are available in the Designer Toolset's "Map" dropdown menu.

First, some standard features that all 2DA worksheets will have:
*The first row of the worksheet contains the labels of the columns. Don't change the names of columns or the game won't be able to recognize them.
*The second row contains a keyword describing the data type of that column. Again, don't change this or the game will become confused by what it's seeing.
*The first column contains ID numbers. Each row needs to have a unique ID number.

In the case of the worldmaps worksheet there are four columns that contain the data defining the map layout.
* Label - The name that this map layout will be known by in the Designer Toolkit's dropdown menu. It's not seen by the player.
* MAP - The filename of the .tga that defines the map's appearance, without the .tga extension.
* TargetWpTable - The names of 2DAs that contains information about what waypoints the player appears at within areas accessible from the map. This is discussed in greater detail below.
* TripsCounterTable - A table showing which trips should have random encounters. We won't be going into detail about this in this tutorial.

We'll need to add a new row to this table to describe the map area that we want to use in the toolset. For this example we have a map of a region named "Epona's Realm", in a file named <code>epona.tga</code>. We'll need to assign a unique number ID, which we'll arbitrarily set to 700 (using a high number like this makes it less likely to interfere with other people's additions in the future.). We'll call the target waypoint table "target_wps_epona" to fit with the naming convention of the other maps.

[[Image:Worldmaps worksheet with epona added.png]]

In our hypothetical game module we've got three different cities that the player can reach via the world map; Dunland, Agrabia, and Serepta. They'll be represented by the areas dunland_main, agrabia_main, and serepta_main. The next thing we might want to do do is create a 2DA that defines which waypoints you wind up in when you travel to each of these areas from each of the possible origin points. This isn't strictly necessary but can be used to make travel around the worldmap seem more realistic by having the player arrive at different waypoints depending on which direction they're arriving in an area from.

Again, a convenient starting place is an existing 2DA. This 2DA is another worksheet in <code>worldmaps.xls</code> that shows the target waypoints for a group of areas accessible from a city map in the game's single-player campaign:

[[Image:Worldmaps worksheet target_wps example.png]]

All of the source areas are listed in the second column, and then each column after that corresponds to a destination area for that source. Every source needs a destination column, so there should always be a number of columns equal to the number of sources plus two (the "ID" and "SourceLocation" columns). In this example, if you're in the "markets" area and then use the map to go to the "elven_alienage" area, you'll be placed at the waypoint "wmw_alienage_from_market". Since you can never travel from an area to that same area via the map the diagonal entries are left blank.

To repurpose this 2DA for Epona's Realm, first copy the worksheet and then rename it to "target_wps_epona". We'll only need three rows and three destination columns so delete the extras.

The geometry of these three cities is quite simple, they lie in an east-west row with Serepta to the west, Agrabia in the center, and Dunland to the east. We'll place waypoints in the eastern and western ends of agrabia_main's area layout to represent the player arriving from each of those directions.

So, the final version of the target_wps_epona worksheet will look like:

[[Image:Worldmaps worksheet target_wps_epona.png]]

== Using M2DAs to extend the game ==

There's one remaining complication to be addressed now. When you generate <code>worldmaps.GDA</code> it will include our new map ID 700, but it also includes the old maps with the IDs 1-5. Since the file is in the override directory, these rows override the existing maps with those ID numbers in the single player campaign. This isn't a problem right now since the data is identical but it could be a problem in the future; if BioWare releases an update that needs to change those original five maps, or if some other modder wants to add some maps of his own, only one version will "win" and the result could be a mess.

This can be overcome by splitting up a 2DA into different files that all get loaded by the game and are combined into one 2DA internally. These multi-part 2DA files are known as M2DAs, which stands for "multiple 2DA". The identity of M2DA files is kept track of via their "prefix", a string of text that all M2DAs being with. In the case of the worldmaps 2DA, the prefix is "worldmaps" (ie, the <code>worldmaps.GDA</code> file has the "worldmaps" prefix and no suffix, so it belongs to the "worldmaps" 2DA).

What we'll do now is split out the data relating to our "Epona's Realm" map into a separate M2DA file named <code>worldmaps_epona.GDA</code>. Simply rename the worksheet to "worldmaps_epona" and delete the first five rows of data entirely, leaving us with this:

[[Image:Worldmaps_epona worksheet.png]]

Now when the game encounters this 2DA in the override directory it will keep the data from the original worldmaps 2DA in memory and add the data from worldmaps_epona to it. If in the future some other modder builds on top of your work they can add further worldmap M2DAs, and if a patch comes out that updates the contents of the original 2DA your mod will incorporate it without needing to be updated.

== Converting XLS files into GDA files ==

The game can't use Excel files directly, the 2DAs must first be converted into a "binarized" form. This is done by a command-line utility called <code>ResourceBuilder.exe</code>. Command-line utilities are not very user-friendly, however, so a more convenient "wrapper" is included in the form of another spreadsheet named <code>2daExporter.xls</code>. <code>2daExporter.xls</code> uses macros to run <code>ResourceBuilder.exe</code> with the appropriate command-line options. You'll need to provide <code>2daExporter.xls</code> with the following parameters:

* ResourceBuild Path: The path to <code>ResourceBuilder.exe</code>, which is installed by default in your Dragon Age directory under tools\ResourceBuild
* 2DA Path: The source path of the XLS files to be exported.
* Override Path: The path to the directory that the completed GDA files should be exported to. This doesn't have to be your actual override directory, you can move the files there manually after creating them if you prefer.

Note that <code>2daExporter.xls</code>' macro can have trouble with paths that have spaces in them, so you may need to move your XLS files to a path without any. Likewise, you may not be able to send the output files directly directly to the override directory if there are spaces in its path.

Here's how we've set up <code>2daExporter.xls</code> for converting our example:

[[Image:2da exporter for worldmap tutorial.png]]

To convert worldmaps.xls into binary form, select it and click the "Export Selected" button. A command-line window should pop up briefly while ResourceBuilder runs and then the finished GDA files will be placed in the directory listed in "Override Path."

If you can't get <code>2daExporter.xls</code> working, just run <code>ExcelProcessor</code> instead. You can learn more about <code>ExcelProcessor</code> by reading the [[2DA]] section.

Note that there will be a separate GDA file for each worksheet in the XLS file, named after the worksheets in the XLS file. We only need to use two of them; <code>worldmaps_epona.GDA</code> and <code>target_wps_epona.GDA</code>. Copy these files into your game's override directory along with <code>epona.tga</code> and "Epona's Realm" will become available in the toolset's dropdown menu.

== Creating a map and adding pins ==

Now we can at last see the map as an option in the drop-down menus of the toolset. Create a map and set the "Map" property to Epona's Realm, and the map should appear.

[[Image:Worldmaps selecting Epona.png]]

There's not much to the map itself - its only configurable properties are Parent Map, Tag, and Map. To make the map useful beyond simply displaying a graphic we'll need to add map pins (icons representing destinations). You can also add "trails", which are a series of icons that you can make appear between different pins to mark the player's passage, but these are of lesser importance and can be left for later or omitted entirely.

To insert a pin, right-click on the map and select "insert pin" from the drop-down menu. The pointer will turn into a crosshair that you can click anywhere on the map to place a pin (pins can also be dragged around after creation so don't worry if you miss slightly). The pin will be added to the tree view to the left of the map and, when selected, you can view its properties in the object inspector.

[[Image:Worldmaps placing a pin.png]]

The most important properties to set here are:
* AreaTag - tells the game which area to take the player to when he clicks on this pin. Our Dunland pin will have this set to dunland_main.
* Initial State - tells the game whether to display the pin and whether to make it clickable; you will often want to have pins on the map that only become available to the player at some point later in the game. We'll set Dunland to "grayed out" right now, since we'll want the player to know about its existence but not be able to go there right away.
* Name - This name is shown to the player.
*Pin Type - A list of icons that can be used for the pin. The list of appearances available can be added to in <code>worldmaps.xls</code>, you may have noticed the <code>map_pin_images</code> worksheet when you were editing it earlier.

Other properties you may wish to set include "Tooltip" (a longer description that will be shown to the player if he hovers the mouse pointer over the pin) and "Waypoint Override", which designates which waypoint in the pin's target area to send the player to when he clicks on it. This waypoint overrides the one set in target_wps_epona but has less fine-grained control available; it can be useful for testing purposes.

The "TerrainType" property is used to determine which group of random encounters to draw from. Setting up random encounters is a more advanced topic that we won't cover in this tutorial.

[[Image:Worldmaps pins placed.png]]

== Showing the player the map ==

Once you've got a map built for your module you'll need to tell the game how to use it. There are a number of wrapper functions in wrappers_h that you'll find useful for this:

<pre>void WR_SetWorldMapPrimary(object oMapId)</pre>

This function tells the game what the current default "world map" is. You'll want to set this to your default world map as part of the initial setup of your module, and if you have multiple different maps you'll need to call this function again later in the game to switch which one is active (for example in a plot script that triggers when the player completes a certain task or moves to a certain area).

<pre>void WR_SetWorldMapSecondary(object oMapId)</pre>

!!Need to find out more about this one.!!

<pre>void WR_SetWorldMapLocationStatus(object oLocation, int nStatusId, int bSuppressActiveFlash = FALSE)</pre>

oLocation is a map pin, nStatusId is an integer identifier for one of the status states (such as active, grayed out, destroyed), and the optional bSuppressActiveFlash flag tells the game to omit the visual highlighting that is usually shown around map pins that have had their status changed since the last time the player looked at the map.

<pre>void WR_SetWorldMapPlayerLocation(object oMap, object oLocation)</pre>

This marks the player's current location on the map.

=== Sending the player to the world map via an area transition ===

To set up an area transition placeable (such as a door) to send the player to the world map when an area transition is performed, set the placeable's PLC_AT_DEST_AREA_TAG variable to the string "world_map". This is a special string that's used to signal the placeable_core script's area-transition-handling code that it needs to show a map instead. When the placeable is triggered it will send an EVENT_TYPE_TRANSITION_TO_WORLD_MAP event to the module's event script.

The default module_core script doesn't handle this event so you'll need to add your own module event script to override this behavior. The module's event script should call the following core script functions:

<pre>
SetWorldMapGuiStatus(WM_GUI_STATUS_USE);
OpenPrimaryWorldMap();
</pre>

This displays the map to the player.

== Activating and deactivating map pins ==

This can be done via scripting.

First get the world map pin object:
<pre>
object oVillage = GetObjectByTag(WML_WOW_VILLAGE);
</pre>

Then call the following to activate the pin:
<pre>
WR_SetWorldMapLocationStatus(oVillage, WM_LOCATION_ACTIVE);
</pre>

Area transitions using the default area transition core script can also automatically enable certain map pins when the player travels through them. The names of these pins are set in the area transition's variables.

== Handling the player's map usage ==

If the proper destination areas and waypoints have been set in the map pins (and optionally the target_wps 2DA) the player's movement from one location to another should be handled automatically. However, the game does provide some hooks that allows further customization or non-standard actions to be performed.

When a player clicks on a map pin, the EVENT_TYPE_BEGIN_TRAVEL event is sent to the module script.

This event has the following parameters:

* string sSource = GetEventString(ev, 0); // area tag for the source location (the area the player's leaving)
* string sTarget = GetEventString(ev, 1); // area tag for the target location (the area the player's travelling to)
* string sWPOverride = GetEventString(ev, 2); // the tag for the target waypoint override (the waypoint in the destination area that the player will appear at)
* int nSourceTerrain = GetEventInteger(ev, 0); //The terrain type of the source location
* int nTargetTerrain = GetEventInteger(ev, 1); //The terrain type of the target location - these two parameters are used in the main campaign's code for determining what sort of random encounters to generate, but that's handled entirely in scripting so you can use them for other purposes or ignore them completely if you prefer.
* int nWorldMap = GetEventInteger(ev, 2);
* object oSourceLocation = GetEventObject(ev, 0); // the map pin object representing the source location.

In the main Dragon Age campaign's module script, a large amount of complex code is triggered by the EVENT_TYPE_BEGIN_TRAVEL event. This code takes into account a lot of special-case situations that are relevant only to the particular plot and structure of the Dragon Age main campaign. But it is important to note one thing that is ''not'' done in the EVENT_TYPE_BEGIN_TRAVEL event; the actual call to UT_DoAreaTransition().

Instead, once you have finished doing whatever special-case coding and random encounter tests you choose to implement, you will need to store the destination that you're sending the player to in the module's variable table. Then call the WorldMapStartTravelling(); function to begin the map trail animation (the WorldMapStartTravelling function has optional parameters to insert a random encounter partway through the trip and to override the map pin the trail starts at).

The engine will send the EVENT_TYPE_WORLDMAP_PRETRANSITION event as it begins the map trail animation. This is where you want to call UT_DoAreaTransition(); the level will begin loading in the background as the map trail animation plays.

The following code is the most basic amount that you should need to put in your module script in order to implement area transitions via the world map:

<pre>
case EVENT_TYPE_BEGIN_TRAVEL:
{
string sTarget = GetEventString(ev, 1); // area tag target location
string sWPOverride = GetEventString(ev, 2); // waypoint tag override
//if you want to do any special-case code or random encounter handling, insert it here
SetLocalString(GetModule(), "WM_STORED_AREA", sTarget); //store target area's tag to a local module variable
SetLocalString(GetModule(), "WM_STORED_WP", sWPOverride); //store target waypoint tag
WorldMapStartTravelling(); //initiate the map's travelling animation. The engine will send EVENT_TYPE_WORLDMAP_PRETRANSITION once it's started.
}

case EVENT_TYPE_WORLDMAP_PRETRANSITION:
{
string sArea = GetLocalString(GetModule(), "WM_STORED_AREA"); //retrieve the target area tag stored in EVENT_TYPE_BEGIN_TRAVEL
string sWP = GetLocalString(GetModule(), "WM_STORED_WP"); //retrieve the target waypoint tag
UT_DoAreaTransition(sArea, sWP); //execute the area transition to that target.
break;
}
</pre>

There is also a EVENT_TYPE_WORLDMAP_POSTTRANSITION event. In the Dragon Age main campaign it is used only to trigger certain cutscenes that play as a result of world travel.

=== Other map-related events ===

The EVENT_TYPE_WORLD_MAP_CLOSED is sent to the module script when the world map is closed. It has only one parameter, an integer flag that indicates whether the map was closed due to cancel being selected or due to the player traveling to a new destination.

[[Category:Maps]]
[[Category:Tutorials]]

Map tutorial

2009-10-08T02:13:28Z

Codepoetzz: /* Converting XLS files into GDA files */

Map objects are a way to allow the player to travel from area to area without having to follow a rigid path from one exit to the next. They're useful for representing large expanses of wide-open countryside, for example, or a city with various districts that the player can travel between freely but is too large to conveniently fit in a single area. Maps allow a world to be large without having to detail every little irrelevant place in it.

If you start by creating a new map resource within the designer toolkit, you'll quickly find that there is only a very limited pre-defined list of map images that are available for use. That's because map layouts are defined in a 2DA ("two-dimensional array"), a binary table of data that is used by the toolset to provide definitions but that is not itself editable from it. You may have encountered references to 2DAs when working with other objects. For example, the list of variables that an object's scripts can refer to is stored in a 2DA. This tutorial is going to assume that you've never worked with 2DAs themselves before. In a sense, this tutorial is as much a 2DA tutorial as it is a map tutorial.

== Terminology ==

This tutorial makes use of a number of different three-letter acronyms and specific terms that may be troublesome to keep track of at first. Before we dive straight in, here's a cheat sheet that may prove useful:

*2DA - "two-dimensional array", the table of data we'll be editing. Note that a 2DA can be stored in a human-readable or machine-readable format, each of which has their own names. "2DA" is used to refer to the table as an abstract concept.
*XLS - the file extension for an Excel spreadsheet.
*Worksheet - tabbed panes within an Excel spreadsheet. Each Excel spreadsheet can contain multiple worksheets and each worksheet can represent one 2DA, so one spreadsheet can contain multiple 2DAs.

[[Image:Worksheet tabs.png|frame|center|Worksheet tabs along the bottom of an Excel spreadsheet]]

*GDA - The file extension for a binary file usable by the game. 2DAs that have been processed by the resource exporter will be stored in this form.
*TGA - Targa graphics file extension. TGA graphic files are used to define the underlying appearance of the map itself.
*M2DA - "Multiple 2DA". Previous BioWare games have made use of 2DAs, but the 2DAs used in Dragon Age use this new format instead. It allows several different 2DAs to be combined together and treated as a single 2DA by the game, which is very useful for adding new content to an existing 2DA.

== The worldmaps.xls spreadsheet ==

See also [[worldmaps.xls]].

If we're creating maps for a brand new module we could in theory start with a blank Excel spreadsheet and build the required 2DAs from scratch. It's much easier, however, to start with an existing copy of the relevant spreadsheet from another module and replace the values within it with our own.

The spreadsheet that contains all the 2DAs relevant to world maps is <code>worldmaps.xls</code>. Open it in Excel and you'll find that it contains, among other worksheets, the "worldmaps" worksheet.

[[Image:Worldmaps worksheet.png|frame|center|The redaction will be removed when the game ships !!Note: mere moments after these screenshots were taken a NameStrRef column was added to allow localized map names. These screenshots will have to be redone anyway!!]]

This is the core 2DA that defines what maps are available in the Designer Toolset's "Map" dropdown menu.

First, some standard features that all 2DA worksheets will have:
*The first row of the worksheet contains the labels of the columns. Don't change the names of columns or the game won't be able to recognize them.
*The second row contains a keyword describing the data type of that column. Again, don't change this or the game will become confused by what it's seeing.
*The first column contains ID numbers. Each row needs to have a unique ID number.

In the case of the worldmaps worksheet there are four columns that contain the data defining the map layout.
* Label - The name that this map layout will be known by in the Designer Toolkit's dropdown menu. It's not seen by the player.
* MAP - The filename of the .tga that defines the map's appearance, without the .tga extension.
* TargetWpTable - The names of 2DAs that contains information about what waypoints the player appears at within areas accessible from the map. This is discussed in greater detail below.
* TripsCounterTable - A table showing which trips should have random encounters. We won't be going into detail about this in this tutorial.

We'll need to add a new row to this table to describe the map area that we want to use in the toolset. For this example we have a map of a region named "Epona's Realm", in a file named <code>epona.tga</code>. We'll need to assign a unique number ID, which we'll arbitrarily set to 700 (using a high number like this makes it less likely to interfere with other people's additions in the future.). We'll call the target waypoint table "target_wps_epona" to fit with the naming convention of the other maps.

[[Image:Worldmaps worksheet with epona added.png]]

In our hypothetical game module we've got three different cities that the player can reach via the world map; Dunland, Agrabia, and Serepta. They'll be represented by the areas dunland_main, agrabia_main, and serepta_main. The next thing we might want to do do is create a 2DA that defines which waypoints you wind up in when you travel to each of these areas from each of the possible origin points. This isn't strictly necessary but can be used to make travel around the worldmap seem more realistic by having the player arrive at different waypoints depending on which direction they're arriving in an area from.

Again, a convenient starting place is an existing 2DA. This 2DA is another worksheet in <code>worldmaps.xls</code> that shows the target waypoints for a group of areas accessible from a city map in the game's single-player campaign:

[[Image:Worldmaps worksheet target_wps example.png]]

All of the source areas are listed in the second column, and then each column after that corresponds to a destination area for that source. Every source needs a destination column, so there should always be a number of columns equal to the number of sources plus two (the "ID" and "SourceLocation" columns). In this example, if you're in the "markets" area and then use the map to go to the "elven_alienage" area, you'll be placed at the waypoint "wmw_alienage_from_market". Since you can never travel from an area to that same area via the map the diagonal entries are left blank.

To repurpose this 2DA for Epona's Realm, first copy the worksheet and then rename it to "target_wps_epona". We'll only need three rows and three destination columns so delete the extras.

The geometry of these three cities is quite simple, they lie in an east-west row with Serepta to the west, Agrabia in the center, and Dunland to the east. We'll place waypoints in the eastern and western ends of agrabia_main's area layout to represent the player arriving from each of those directions.

So, the final version of the target_wps_epona worksheet will look like:

[[Image:Worldmaps worksheet target_wps_epona.png]]

== Using M2DAs to extend the game ==

There's one remaining complication to be addressed now. When you generate <code>worldmaps.GDA</code> it will include our new map ID 700, but it also includes the old maps with the IDs 1-5. Since the file is in the override directory, these rows override the existing maps with those ID numbers in the single player campaign. This isn't a problem right now since the data is identical but it could be a problem in the future; if BioWare releases an update that needs to change those original five maps, or if some other modder wants to add some maps of his own, only one version will "win" and the result could be a mess.

This can be overcome by splitting up a 2DA into different files that all get loaded by the game and are combined into one 2DA internally. These multi-part 2DA files are known as M2DAs, which stands for "multiple 2DA". The identity of M2DA files is kept track of via their "prefix", a string of text that all M2DAs being with. In the case of the worldmaps 2DA, the prefix is "worldmaps" (ie, the <code>worldmaps.GDA</code> file has the "worldmaps" prefix and no suffix, so it belongs to the "worldmaps" 2DA).

What we'll do now is split out the data relating to our "Epona's Realm" map into a separate M2DA file named <code>worldmaps_epona.GDA</code>. Simply rename the worksheet to "worldmaps_epona" and delete the first five rows of data entirely, leaving us with this:

[[Image:Worldmaps_epona worksheet.png]]

Now when the game encounters this 2DA in the override directory it will keep the data from the original worldmaps 2DA in memory and add the data from worldmaps_epona to it. If in the future some other modder builds on top of your work they can add further worldmap M2DAs, and if a patch comes out that updates the contents of the original 2DA your mod will incorporate it without needing to be updated.

== Converting XLS files into GDA files ==

The game can't use Excel files directly, the 2DAs must first be converted into a "binarized" form. This is done by a command-line utility called <code>ResourceBuilder.exe</code>. Command-line utilities are not very user-friendly, however, so a more convenient "wrapper" is included in the form of another spreadsheet named <code>2daExporter.xls</code>. <code>2daExporter.xls</code> uses macros to run <code>ResourceBuilder.exe</code> with the appropriate command-line options. You'll need to provide <code>2daExporter.xls</code> with the following parameters:

* ResourceBuild Path: The path to <code>ResourceBuilder.exe</code>, which is installed by default in your Dragon Age directory under tools\ResourceBuild
* 2DA Path: The source path of the XLS files to be exported.
* Override Path: The path to the directory that the completed GDA files should be exported to. This doesn't have to be your actual override directory, you can move the files there manually after creating them if you prefer.

Note that <code>2daExporter.xls</code>' macro can have trouble with paths that have spaces in them, so you may need to move your XLS files to a path without any. Likewise, you may not be able to send the output files directly directly to the override directory if there are spaces in its path.

Here's how we've set up <code>2daExporter.xls</code> for converting our example:

[[Image:2da exporter for worldmap tutorial.png]]

To convert worldmaps.xls into binary form, select it and click the "Export Selected" button. A command-line window should pop up briefly while ResourceBuilder runs and then the finished GDA files will be placed in the directory listed in "Override Path."

If you can't get <code>2daExporter.xls</code> working, just run <code>ExcelProcessor</code> instead. You can learn more about <code>ExcelProcessor</code> by reading the [[2DA]] section.

Note that there will be a separate GDA file for each worksheet in the XLS file, named after the worksheets in the XLS file. We only need to use two of them; <code>worldmaps.GDA</code> and <code>target_wps_epona.GDA</code>. Copy these files into your game's override directory along with <code>epona.tga</code> and "Epona's Realm" will become available in the toolset's dropdown menu.

== Creating a map and adding pins ==

Now we can at last see the map as an option in the drop-down menus of the toolset. Create a map and set the "Map" property to Epona's Realm, and the map should appear.

[[Image:Worldmaps selecting Epona.png]]

There's not much to the map itself - its only configurable properties are Parent Map, Tag, and Map. To make the map useful beyond simply displaying a graphic we'll need to add map pins (icons representing destinations). You can also add "trails", which are a series of icons that you can make appear between different pins to mark the player's passage, but these are of lesser importance and can be left for later or omitted entirely.

To insert a pin, right-click on the map and select "insert pin" from the drop-down menu. The pointer will turn into a crosshair that you can click anywhere on the map to place a pin (pins can also be dragged around after creation so don't worry if you miss slightly). The pin will be added to the tree view to the left of the map and, when selected, you can view its properties in the object inspector.

[[Image:Worldmaps placing a pin.png]]

The most important properties to set here are:
* AreaTag - tells the game which area to take the player to when he clicks on this pin. Our Dunland pin will have this set to dunland_main.
* Initial State - tells the game whether to display the pin and whether to make it clickable; you will often want to have pins on the map that only become available to the player at some point later in the game. We'll set Dunland to "grayed out" right now, since we'll want the player to know about its existence but not be able to go there right away.
* Name - This name is shown to the player.
*Pin Type - A list of icons that can be used for the pin. The list of appearances available can be added to in <code>worldmaps.xls</code>, you may have noticed the <code>map_pin_images</code> worksheet when you were editing it earlier.

Other properties you may wish to set include "Tooltip" (a longer description that will be shown to the player if he hovers the mouse pointer over the pin) and "Waypoint Override", which designates which waypoint in the pin's target area to send the player to when he clicks on it. This waypoint overrides the one set in target_wps_epona but has less fine-grained control available; it can be useful for testing purposes.

The "TerrainType" property is used to determine which group of random encounters to draw from. Setting up random encounters is a more advanced topic that we won't cover in this tutorial.

[[Image:Worldmaps pins placed.png]]

== Showing the player the map ==

Once you've got a map built for your module you'll need to tell the game how to use it. There are a number of wrapper functions in wrappers_h that you'll find useful for this:

<pre>void WR_SetWorldMapPrimary(object oMapId)</pre>

This function tells the game what the current default "world map" is. You'll want to set this to your default world map as part of the initial setup of your module, and if you have multiple different maps you'll need to call this function again later in the game to switch which one is active (for example in a plot script that triggers when the player completes a certain task or moves to a certain area).

<pre>void WR_SetWorldMapSecondary(object oMapId)</pre>

!!Need to find out more about this one.!!

<pre>void WR_SetWorldMapLocationStatus(object oLocation, int nStatusId, int bSuppressActiveFlash = FALSE)</pre>

oLocation is a map pin, nStatusId is an integer identifier for one of the status states (such as active, grayed out, destroyed), and the optional bSuppressActiveFlash flag tells the game to omit the visual highlighting that is usually shown around map pins that have had their status changed since the last time the player looked at the map.

<pre>void WR_SetWorldMapPlayerLocation(object oMap, object oLocation)</pre>

This marks the player's current location on the map.

=== Sending the player to the world map via an area transition ===

To set up an area transition placeable (such as a door) to send the player to the world map when an area transition is performed, set the placeable's PLC_AT_DEST_AREA_TAG variable to the string "world_map". This is a special string that's used to signal the placeable_core script's area-transition-handling code that it needs to show a map instead. When the placeable is triggered it will send an EVENT_TYPE_TRANSITION_TO_WORLD_MAP event to the module's event script.

The default module_core script doesn't handle this event so you'll need to add your own module event script to override this behavior. The module's event script should call the following core script functions:

<pre>
SetWorldMapGuiStatus(WM_GUI_STATUS_USE);
OpenPrimaryWorldMap();
</pre>

This displays the map to the player.

== Activating and deactivating map pins ==

This can be done via scripting.

First get the world map pin object:
<pre>
object oVillage = GetObjectByTag(WML_WOW_VILLAGE);
</pre>

Then call the following to activate the pin:
<pre>
WR_SetWorldMapLocationStatus(oVillage, WM_LOCATION_ACTIVE);
</pre>

Area transitions using the default area transition core script can also automatically enable certain map pins when the player travels through them. The names of these pins are set in the area transition's variables.

== Handling the player's map usage ==

If the proper destination areas and waypoints have been set in the map pins (and optionally the target_wps 2DA) the player's movement from one location to another should be handled automatically. However, the game does provide some hooks that allows further customization or non-standard actions to be performed.

When a player clicks on a map pin, the EVENT_TYPE_BEGIN_TRAVEL event is sent to the module script.

This event has the following parameters:

* string sSource = GetEventString(ev, 0); // area tag for the source location (the area the player's leaving)
* string sTarget = GetEventString(ev, 1); // area tag for the target location (the area the player's travelling to)
* string sWPOverride = GetEventString(ev, 2); // the tag for the target waypoint override (the waypoint in the destination area that the player will appear at)
* int nSourceTerrain = GetEventInteger(ev, 0); //The terrain type of the source location
* int nTargetTerrain = GetEventInteger(ev, 1); //The terrain type of the target location - these two parameters are used in the main campaign's code for determining what sort of random encounters to generate, but that's handled entirely in scripting so you can use them for other purposes or ignore them completely if you prefer.
* int nWorldMap = GetEventInteger(ev, 2);
* object oSourceLocation = GetEventObject(ev, 0); // the map pin object representing the source location.

In the main Dragon Age campaign's module script, a large amount of complex code is triggered by the EVENT_TYPE_BEGIN_TRAVEL event. This code takes into account a lot of special-case situations that are relevant only to the particular plot and structure of the Dragon Age main campaign. But it is important to note one thing that is ''not'' done in the EVENT_TYPE_BEGIN_TRAVEL event; the actual call to UT_DoAreaTransition().

Instead, once you have finished doing whatever special-case coding and random encounter tests you choose to implement, you will need to store the destination that you're sending the player to in the module's variable table. Then call the WorldMapStartTravelling(); function to begin the map trail animation (the WorldMapStartTravelling function has optional parameters to insert a random encounter partway through the trip and to override the map pin the trail starts at).

The engine will send the EVENT_TYPE_WORLDMAP_PRETRANSITION event as it begins the map trail animation. This is where you want to call UT_DoAreaTransition(); the level will begin loading in the background as the map trail animation plays.

The following code is the most basic amount that you should need to put in your module script in order to implement area transitions via the world map:

<pre>
case EVENT_TYPE_BEGIN_TRAVEL:
{
string sTarget = GetEventString(ev, 1); // area tag target location
string sWPOverride = GetEventString(ev, 2); // waypoint tag override
//if you want to do any special-case code or random encounter handling, insert it here
SetLocalString(GetModule(), "WM_STORED_AREA", sTarget); //store target area's tag to a local module variable
SetLocalString(GetModule(), "WM_STORED_WP", sWPOverride); //store target waypoint tag
WorldMapStartTravelling(); //initiate the map's travelling animation. The engine will send EVENT_TYPE_WORLDMAP_PRETRANSITION once it's started.
}

case EVENT_TYPE_WORLDMAP_PRETRANSITION:
{
string sArea = GetLocalString(GetModule(), "WM_STORED_AREA"); //retrieve the target area tag stored in EVENT_TYPE_BEGIN_TRAVEL
string sWP = GetLocalString(GetModule(), "WM_STORED_WP"); //retrieve the target waypoint tag
UT_DoAreaTransition(sArea, sWP); //execute the area transition to that target.
break;
}
</pre>

There is also a EVENT_TYPE_WORLDMAP_POSTTRANSITION event. In the Dragon Age main campaign it is used only to trigger certain cutscenes that play as a result of world travel.

=== Other map-related events ===

The EVENT_TYPE_WORLD_MAP_CLOSED is sent to the module script when the world map is closed. It has only one parameter, an integer flag that indicates whether the map was closed due to cancel being selected or due to the player traveling to a new destination.

[[Category:Maps]]
[[Category:Tutorials]]

Map tutorial

2009-10-08T02:12:25Z

Codepoetzz: /* Converting XLS files into GDA files */

Map objects are a way to allow the player to travel from area to area without having to follow a rigid path from one exit to the next. They're useful for representing large expanses of wide-open countryside, for example, or a city with various districts that the player can travel between freely but is too large to conveniently fit in a single area. Maps allow a world to be large without having to detail every little irrelevant place in it.

If you start by creating a new map resource within the designer toolkit, you'll quickly find that there is only a very limited pre-defined list of map images that are available for use. That's because map layouts are defined in a 2DA ("two-dimensional array"), a binary table of data that is used by the toolset to provide definitions but that is not itself editable from it. You may have encountered references to 2DAs when working with other objects. For example, the list of variables that an object's scripts can refer to is stored in a 2DA. This tutorial is going to assume that you've never worked with 2DAs themselves before. In a sense, this tutorial is as much a 2DA tutorial as it is a map tutorial.

== Terminology ==

This tutorial makes use of a number of different three-letter acronyms and specific terms that may be troublesome to keep track of at first. Before we dive straight in, here's a cheat sheet that may prove useful:

*2DA - "two-dimensional array", the table of data we'll be editing. Note that a 2DA can be stored in a human-readable or machine-readable format, each of which has their own names. "2DA" is used to refer to the table as an abstract concept.
*XLS - the file extension for an Excel spreadsheet.
*Worksheet - tabbed panes within an Excel spreadsheet. Each Excel spreadsheet can contain multiple worksheets and each worksheet can represent one 2DA, so one spreadsheet can contain multiple 2DAs.

[[Image:Worksheet tabs.png|frame|center|Worksheet tabs along the bottom of an Excel spreadsheet]]

*GDA - The file extension for a binary file usable by the game. 2DAs that have been processed by the resource exporter will be stored in this form.
*TGA - Targa graphics file extension. TGA graphic files are used to define the underlying appearance of the map itself.
*M2DA - "Multiple 2DA". Previous BioWare games have made use of 2DAs, but the 2DAs used in Dragon Age use this new format instead. It allows several different 2DAs to be combined together and treated as a single 2DA by the game, which is very useful for adding new content to an existing 2DA.

== The worldmaps.xls spreadsheet ==

See also [[worldmaps.xls]].

If we're creating maps for a brand new module we could in theory start with a blank Excel spreadsheet and build the required 2DAs from scratch. It's much easier, however, to start with an existing copy of the relevant spreadsheet from another module and replace the values within it with our own.

The spreadsheet that contains all the 2DAs relevant to world maps is <code>worldmaps.xls</code>. Open it in Excel and you'll find that it contains, among other worksheets, the "worldmaps" worksheet.

[[Image:Worldmaps worksheet.png|frame|center|The redaction will be removed when the game ships !!Note: mere moments after these screenshots were taken a NameStrRef column was added to allow localized map names. These screenshots will have to be redone anyway!!]]

This is the core 2DA that defines what maps are available in the Designer Toolset's "Map" dropdown menu.

First, some standard features that all 2DA worksheets will have:
*The first row of the worksheet contains the labels of the columns. Don't change the names of columns or the game won't be able to recognize them.
*The second row contains a keyword describing the data type of that column. Again, don't change this or the game will become confused by what it's seeing.
*The first column contains ID numbers. Each row needs to have a unique ID number.

In the case of the worldmaps worksheet there are four columns that contain the data defining the map layout.
* Label - The name that this map layout will be known by in the Designer Toolkit's dropdown menu. It's not seen by the player.
* MAP - The filename of the .tga that defines the map's appearance, without the .tga extension.
* TargetWpTable - The names of 2DAs that contains information about what waypoints the player appears at within areas accessible from the map. This is discussed in greater detail below.
* TripsCounterTable - A table showing which trips should have random encounters. We won't be going into detail about this in this tutorial.

We'll need to add a new row to this table to describe the map area that we want to use in the toolset. For this example we have a map of a region named "Epona's Realm", in a file named <code>epona.tga</code>. We'll need to assign a unique number ID, which we'll arbitrarily set to 700 (using a high number like this makes it less likely to interfere with other people's additions in the future.). We'll call the target waypoint table "target_wps_epona" to fit with the naming convention of the other maps.

[[Image:Worldmaps worksheet with epona added.png]]

In our hypothetical game module we've got three different cities that the player can reach via the world map; Dunland, Agrabia, and Serepta. They'll be represented by the areas dunland_main, agrabia_main, and serepta_main. The next thing we might want to do do is create a 2DA that defines which waypoints you wind up in when you travel to each of these areas from each of the possible origin points. This isn't strictly necessary but can be used to make travel around the worldmap seem more realistic by having the player arrive at different waypoints depending on which direction they're arriving in an area from.

Again, a convenient starting place is an existing 2DA. This 2DA is another worksheet in <code>worldmaps.xls</code> that shows the target waypoints for a group of areas accessible from a city map in the game's single-player campaign:

[[Image:Worldmaps worksheet target_wps example.png]]

All of the source areas are listed in the second column, and then each column after that corresponds to a destination area for that source. Every source needs a destination column, so there should always be a number of columns equal to the number of sources plus two (the "ID" and "SourceLocation" columns). In this example, if you're in the "markets" area and then use the map to go to the "elven_alienage" area, you'll be placed at the waypoint "wmw_alienage_from_market". Since you can never travel from an area to that same area via the map the diagonal entries are left blank.

To repurpose this 2DA for Epona's Realm, first copy the worksheet and then rename it to "target_wps_epona". We'll only need three rows and three destination columns so delete the extras.

The geometry of these three cities is quite simple, they lie in an east-west row with Serepta to the west, Agrabia in the center, and Dunland to the east. We'll place waypoints in the eastern and western ends of agrabia_main's area layout to represent the player arriving from each of those directions.

So, the final version of the target_wps_epona worksheet will look like:

[[Image:Worldmaps worksheet target_wps_epona.png]]

== Using M2DAs to extend the game ==

There's one remaining complication to be addressed now. When you generate <code>worldmaps.GDA</code> it will include our new map ID 700, but it also includes the old maps with the IDs 1-5. Since the file is in the override directory, these rows override the existing maps with those ID numbers in the single player campaign. This isn't a problem right now since the data is identical but it could be a problem in the future; if BioWare releases an update that needs to change those original five maps, or if some other modder wants to add some maps of his own, only one version will "win" and the result could be a mess.

This can be overcome by splitting up a 2DA into different files that all get loaded by the game and are combined into one 2DA internally. These multi-part 2DA files are known as M2DAs, which stands for "multiple 2DA". The identity of M2DA files is kept track of via their "prefix", a string of text that all M2DAs being with. In the case of the worldmaps 2DA, the prefix is "worldmaps" (ie, the <code>worldmaps.GDA</code> file has the "worldmaps" prefix and no suffix, so it belongs to the "worldmaps" 2DA).

What we'll do now is split out the data relating to our "Epona's Realm" map into a separate M2DA file named <code>worldmaps_epona.GDA</code>. Simply rename the worksheet to "worldmaps_epona" and delete the first five rows of data entirely, leaving us with this:

[[Image:Worldmaps_epona worksheet.png]]

Now when the game encounters this 2DA in the override directory it will keep the data from the original worldmaps 2DA in memory and add the data from worldmaps_epona to it. If in the future some other modder builds on top of your work they can add further worldmap M2DAs, and if a patch comes out that updates the contents of the original 2DA your mod will incorporate it without needing to be updated.

== Converting XLS files into GDA files ==

The game can't use Excel files directly, the 2DAs must first be converted into a "binarized" form. This is done by a command-line utility called <code>ResourceBuilder.exe</code>. Command-line utilities are not very user-friendly, however, so a more convenient "wrapper" is included in the form of another spreadsheet named <code>2daExporter.xls</code>. <code>2daExporter.xls</code> uses macros to run <code>ResourceBuilder.exe</code> with the appropriate command-line options. You'll need to provide <code>2daExporter.xls</code> with the following parameters:

* ResourceBuild Path: The path to <code>ResourceBuilder.exe</code>, which is installed by default in your Dragon Age directory under tools\ResourceBuild
* 2DA Path: The source path of the XLS files to be exported.
* Override Path: The path to the directory that the completed GDA files should be exported to. This doesn't have to be your actual override directory, you can move the files there manually after creating them if you prefer.

Note that <code>2daExporter.xls</code>' macro can have trouble with paths that have spaces in them, so you may need to move your XLS files to a path without any. Likewise, you may not be able to send the output files directly directly to the override directory if there are spaces in its path.

Here's how we've set up <code>2daExporter.xls</code> for converting our example:

[[Image:2da exporter for worldmap tutorial.png]]

To convert worldmaps.xls into binary form, select it and click the "Export Selected" button. A command-line window should pop up briefly while ResourceBuilder runs and then the finished GDA files will be placed in the directory listed in "Override Path."

If you can't get <code>2daExporter.xls</code> working, just run <code>ExcelProcessor</code> instead. You can learn more about <code>ExcelProcessor</code> by reading the 2DA section.

Note that there will be a separate GDA file for each worksheet in the XLS file, named after the worksheets in the XLS file. We only need to use two of them; <code>worldmaps.GDA</code> and <code>target_wps_epona.GDA</code>. Copy these files into your game's override directory along with <code>epona.tga</code> and "Epona's Realm" will become available in the toolset's dropdown menu.

== Creating a map and adding pins ==

Now we can at last see the map as an option in the drop-down menus of the toolset. Create a map and set the "Map" property to Epona's Realm, and the map should appear.

[[Image:Worldmaps selecting Epona.png]]

There's not much to the map itself - its only configurable properties are Parent Map, Tag, and Map. To make the map useful beyond simply displaying a graphic we'll need to add map pins (icons representing destinations). You can also add "trails", which are a series of icons that you can make appear between different pins to mark the player's passage, but these are of lesser importance and can be left for later or omitted entirely.

To insert a pin, right-click on the map and select "insert pin" from the drop-down menu. The pointer will turn into a crosshair that you can click anywhere on the map to place a pin (pins can also be dragged around after creation so don't worry if you miss slightly). The pin will be added to the tree view to the left of the map and, when selected, you can view its properties in the object inspector.

[[Image:Worldmaps placing a pin.png]]

The most important properties to set here are:
* AreaTag - tells the game which area to take the player to when he clicks on this pin. Our Dunland pin will have this set to dunland_main.
* Initial State - tells the game whether to display the pin and whether to make it clickable; you will often want to have pins on the map that only become available to the player at some point later in the game. We'll set Dunland to "grayed out" right now, since we'll want the player to know about its existence but not be able to go there right away.
* Name - This name is shown to the player.
*Pin Type - A list of icons that can be used for the pin. The list of appearances available can be added to in <code>worldmaps.xls</code>, you may have noticed the <code>map_pin_images</code> worksheet when you were editing it earlier.

Other properties you may wish to set include "Tooltip" (a longer description that will be shown to the player if he hovers the mouse pointer over the pin) and "Waypoint Override", which designates which waypoint in the pin's target area to send the player to when he clicks on it. This waypoint overrides the one set in target_wps_epona but has less fine-grained control available; it can be useful for testing purposes.

The "TerrainType" property is used to determine which group of random encounters to draw from. Setting up random encounters is a more advanced topic that we won't cover in this tutorial.

[[Image:Worldmaps pins placed.png]]

== Showing the player the map ==

Once you've got a map built for your module you'll need to tell the game how to use it. There are a number of wrapper functions in wrappers_h that you'll find useful for this:

<pre>void WR_SetWorldMapPrimary(object oMapId)</pre>

This function tells the game what the current default "world map" is. You'll want to set this to your default world map as part of the initial setup of your module, and if you have multiple different maps you'll need to call this function again later in the game to switch which one is active (for example in a plot script that triggers when the player completes a certain task or moves to a certain area).

<pre>void WR_SetWorldMapSecondary(object oMapId)</pre>

!!Need to find out more about this one.!!

<pre>void WR_SetWorldMapLocationStatus(object oLocation, int nStatusId, int bSuppressActiveFlash = FALSE)</pre>

oLocation is a map pin, nStatusId is an integer identifier for one of the status states (such as active, grayed out, destroyed), and the optional bSuppressActiveFlash flag tells the game to omit the visual highlighting that is usually shown around map pins that have had their status changed since the last time the player looked at the map.

<pre>void WR_SetWorldMapPlayerLocation(object oMap, object oLocation)</pre>

This marks the player's current location on the map.

=== Sending the player to the world map via an area transition ===

To set up an area transition placeable (such as a door) to send the player to the world map when an area transition is performed, set the placeable's PLC_AT_DEST_AREA_TAG variable to the string "world_map". This is a special string that's used to signal the placeable_core script's area-transition-handling code that it needs to show a map instead. When the placeable is triggered it will send an EVENT_TYPE_TRANSITION_TO_WORLD_MAP event to the module's event script.

The default module_core script doesn't handle this event so you'll need to add your own module event script to override this behavior. The module's event script should call the following core script functions:

<pre>
SetWorldMapGuiStatus(WM_GUI_STATUS_USE);
OpenPrimaryWorldMap();
</pre>

This displays the map to the player.

== Activating and deactivating map pins ==

This can be done via scripting.

First get the world map pin object:
<pre>
object oVillage = GetObjectByTag(WML_WOW_VILLAGE);
</pre>

Then call the following to activate the pin:
<pre>
WR_SetWorldMapLocationStatus(oVillage, WM_LOCATION_ACTIVE);
</pre>

Area transitions using the default area transition core script can also automatically enable certain map pins when the player travels through them. The names of these pins are set in the area transition's variables.

== Handling the player's map usage ==

If the proper destination areas and waypoints have been set in the map pins (and optionally the target_wps 2DA) the player's movement from one location to another should be handled automatically. However, the game does provide some hooks that allows further customization or non-standard actions to be performed.

When a player clicks on a map pin, the EVENT_TYPE_BEGIN_TRAVEL event is sent to the module script.

This event has the following parameters:

* string sSource = GetEventString(ev, 0); // area tag for the source location (the area the player's leaving)
* string sTarget = GetEventString(ev, 1); // area tag for the target location (the area the player's travelling to)
* string sWPOverride = GetEventString(ev, 2); // the tag for the target waypoint override (the waypoint in the destination area that the player will appear at)
* int nSourceTerrain = GetEventInteger(ev, 0); //The terrain type of the source location
* int nTargetTerrain = GetEventInteger(ev, 1); //The terrain type of the target location - these two parameters are used in the main campaign's code for determining what sort of random encounters to generate, but that's handled entirely in scripting so you can use them for other purposes or ignore them completely if you prefer.
* int nWorldMap = GetEventInteger(ev, 2);
* object oSourceLocation = GetEventObject(ev, 0); // the map pin object representing the source location.

In the main Dragon Age campaign's module script, a large amount of complex code is triggered by the EVENT_TYPE_BEGIN_TRAVEL event. This code takes into account a lot of special-case situations that are relevant only to the particular plot and structure of the Dragon Age main campaign. But it is important to note one thing that is ''not'' done in the EVENT_TYPE_BEGIN_TRAVEL event; the actual call to UT_DoAreaTransition().

Instead, once you have finished doing whatever special-case coding and random encounter tests you choose to implement, you will need to store the destination that you're sending the player to in the module's variable table. Then call the WorldMapStartTravelling(); function to begin the map trail animation (the WorldMapStartTravelling function has optional parameters to insert a random encounter partway through the trip and to override the map pin the trail starts at).

The engine will send the EVENT_TYPE_WORLDMAP_PRETRANSITION event as it begins the map trail animation. This is where you want to call UT_DoAreaTransition(); the level will begin loading in the background as the map trail animation plays.

The following code is the most basic amount that you should need to put in your module script in order to implement area transitions via the world map:

<pre>
case EVENT_TYPE_BEGIN_TRAVEL:
{
string sTarget = GetEventString(ev, 1); // area tag target location
string sWPOverride = GetEventString(ev, 2); // waypoint tag override
//if you want to do any special-case code or random encounter handling, insert it here
SetLocalString(GetModule(), "WM_STORED_AREA", sTarget); //store target area's tag to a local module variable
SetLocalString(GetModule(), "WM_STORED_WP", sWPOverride); //store target waypoint tag
WorldMapStartTravelling(); //initiate the map's travelling animation. The engine will send EVENT_TYPE_WORLDMAP_PRETRANSITION once it's started.
}

case EVENT_TYPE_WORLDMAP_PRETRANSITION:
{
string sArea = GetLocalString(GetModule(), "WM_STORED_AREA"); //retrieve the target area tag stored in EVENT_TYPE_BEGIN_TRAVEL
string sWP = GetLocalString(GetModule(), "WM_STORED_WP"); //retrieve the target waypoint tag
UT_DoAreaTransition(sArea, sWP); //execute the area transition to that target.
break;
}
</pre>

There is also a EVENT_TYPE_WORLDMAP_POSTTRANSITION event. In the Dragon Age main campaign it is used only to trigger certain cutscenes that play as a result of world travel.

=== Other map-related events ===

The EVENT_TYPE_WORLD_MAP_CLOSED is sent to the module script when the world map is closed. It has only one parameter, an integer flag that indicates whether the map was closed due to cancel being selected or due to the player traveling to a new destination.

[[Category:Maps]]
[[Category:Tutorials]]

VFX Tutorial

2009-10-05T20:34:34Z

Codepoetzz: /* Adding an emitter */

PDF Version Part 1 [[File:VFX_Tut_p1.pdf]]

PDF Version Part 2 [[File:VFX_Tut_p2.pdf]]

PDF Version Part 3 [[File:VFX_Tut_p3.pdf]]

----

== VFX Tutorial Part 1 ==

This tutorial is to get you started in creating your own visual effects to be used in the DA toolset. Tutorial #1 will cover the basics of creating, editing, and implementing the visual effect.

=== Creating a new visual effect ===

To create a new VFX, right click on the palette window and select “NEW > VFX”

[[File:new VFX.jpg|250px]]

The VFX Editor will open up showing a square grid and a “Select VFX” window in the middle. For this tutorial we will be doing a Placeable effect, so select “Placeable” and click “OK”.

On the top left, you should see a little globe called “VFXRoot” and in the Object Inspector you should see the properties of VFXRoot.
At this point, save your work by selecting “File > Save As” or clicking the Save Icon in the upper left. You will be prompted for a file name. I like to keep all of my VFX files in one place so in My Documents/Bioware/Dragon Age folder I created a VFX folder to save my files.

For this tutorial we will be creating a bonfire type of effect and to stay with Dragon Age [[naming convention]], we will use a 3 letter prefix, underscore, and then the file name. Name the file “fxp_bonfire_jp”
The “fxp” is for “Visual Effect Placeable” (all VFX files start with fx*) “bonfire” tells me what the effect is, and the “jp” on the end lets me know that it is my effect and not someone else’s, you can add whatever suffix you want. Click “Save” when done.

You can close the toolset at any time and return to this tutorial. You can open your effect again later by selecting “File > Open” and navigate to and select the file you just saved.

=== VFX root properties ===

[[File:t1_root_obj_inspector.jpg|250px]]

'''VFXRoot Properties:'''
I’ll just cover the ones that we will be using.

'''Name:''' This is the resource name and is what will be used when we Post to Local. Change it to match the file name.

'''Impact Length:''' Time in seconds for the stating phase of the effect. Example, a Runner starting off from the start line reaching max speed.

'''Duration Length:''' Time in seconds for the duration of the effect. Example, the time it takes the runner to reach the finish line after reaching max speed.

'''Cessation Length:''' Time in seconds for the ending of the effect. Example, the runner slowing down after crossing the finish line.

We are making a bonfire effect, so we want the fire to start off small, grow in size, then burn itself out. So set the Impact Length to 3 seconds, this will start the fire and grown to its max size. Set the Duration Length to 3 seconds. This will allow us plenty of time to vary the coloration of the flames. Set the Cessation time to 3 seconds as well, as the fire burns out.

You may be thinking that 9 seconds is a very short fire. When the effect is set in a script, the duration time is set within the function ApplyEffect*. This duration time causes the duration time of the animation to loop over and over. So for example, if this bon fire effect is applied to an object for 6 min, the duration part of the effect will loop 120 times, 3 second duration * 120 loops = 360 seconds = 6 minutes. Then the Cessation time plays and the effect is done.

After setting these times, you should now see a time line something like this, More on this in part 2.

[[File:T1_time_line.jpg|640px]]

=== Adding an emitter ===

Next we need an emitter. Right click on the window and select “Insert > Insert Emitter”. You should get a pulsating white capsule in the center of the grid and a “NewEmitter” object added to the list on the left.

[[File:T1_emitter.jpg|640px]]

Select the NewEmitter object and you will see the properties in the Object inspector window.

[[File:T1_op_properties.jpg|250px]]

'''Properties Window:'''

'''Name:''' Change the name of the emitter to “Base” this will be the main base of the fire. Naming the emitter will help sort them out when building an effect with several emitters.

'''Material Library:''' This is the library that we will be selecting our particle material from. The DA Effect Libraries start with the prefix fx_*Click on the Material Library box to open the resource window. Select the fx_firelibrary and click OK.

'''Material Object:''' This is the martial that we will use from the above selected Library. For this select “FireFlipbook”.
Before we continue, save your work and let’s talk about Flipbooks.

A flipbook is a particle that consists of columns and rows of varying images. The animation is created by the effect rapidly flipping through each image, much like a cartoon animation. At this point you should see 4 columns of flickering flames. Note that not all particles are in flipbook form, some are a static image. A simple way to see if the particle is a flipbook, and to see how many columns and rows there are is to set the Birth Rate to 1. Click on the “Emission” tab in the Object Properties and change the top parameter “Birth Rate” to 1. You should now see an image that consists of 4 rows and 4 columns of small flame images. This is a single particle, 4x4 flipbook. Set the Birth Rate back to 10, and return to the “Properties” tab of the Object Inspector, more on Birth Rate later.

[[File:T1_flip.jpg]]

'''Flipbook Type:''' Select “ContactSheet”.

'''Flipbook Random Start Frame:''' This selects a random frame within the flipbook to start with on each emission. Set this to TRUE. This will help give us diversity and make the flame look more “real”.

'''Flipbook Rows:''' This is how many Rows there are in the flipbook, set this number to 4.

'''Flipbook Columns:''' This is the number of Columns in the flipbook, set this to 4 also.

'''Flipbook Frames per Second:''' The particle image has 4 rows and 4 colunms, there are 16 total images to flip through. This value should be a factor of Rows and Columns, so 4 x 4 = 16. Set this value to at least 16 flips per second.

You should now see a single column of what nearly looks like fire.
Right now the flames flicker a bit too slow for me, so set the Flipbook Frames per Second to 32. This makes the flames flicker twice as fast because it is now flipping through all 16 images twice per second instead of once.
Save your work.

[[File:T1_fire.jpg]]

'''Age Map:'''

[[File:T1_agemap.jpg]]

In the Object Inspector click the “Age Map” Tab.

Here we can manipulate the color and the scale of the effect.

Color values are in percentage of 0 to 100% on a scale of 0 to 1, so 50% Blue would be 0.5.

Most normal fires aren’t white, so set Color B (blue) to 0. Your flame should now be yellow. Set Color G (green) to 0.4. We now have a orangey-red color.

Color A (alph) is the flames color intensity setting this to 0.5, the fire is half as intense. Set it where you like.

The scale X and Y values can be any number from 0 to infinity. Setting the scale to 1 is the particles normal size. Because the particle image is a 2d image, there is no Z scale. Changing Scale X will affect the X (width) direction of the flame and Scale Y will affect the Y (Height) direction of the particle. For now we will leave them alone.

The corresponding multipliers simply multiply the values in the general section. For example, if you set Color G back to 1, then set Green Color Multiplier to 0.4 you will have the same result. 1 * 0.4 = 0.4

There is a notable difference between the 2 however, the General settings affect the particles over the lifetime of each particle while the Multipliers affect all the particles over the length of the animation. This will be explored further in Part 2. Go ahead and play with the color settings until you have it the way you want it, and then save your work.

'''Emissions'''

[[File:T1_emissions.jpg]]

Now click on the “Emission” tab these settings control the particle emissions.

'''Birth Rate:''' This is how many particle emit per second. The default is 10, which works out for the fire pretty good. However the flicker is pretty static. So we will change that in a minute.

'''Birth Rate +/-:''' This setting will cause the particle Birth Rate to randomly vary by a positive number or a negative number. If we set this value to 1, the Birth Rate then will vary between 9 and 11 particles per second. Since a 10 Birth Rate seems to be a good number for the most particles per second, set the +/- value to 2, and change the Birth Rate to 8. This will make the max 10 and the min 6 particles per second.

'''Initial Speed:''' This is how fast the particles travel when emitted from the emitter. Changing this value appears to change how long the particles last. However this is not the case, they simple move further before the particle life has expired.

'''Initial Speed +/-:''' This setting works the same as the Birth Rate +/- setting but instead affects the Initial Speed. Set this value to 0.5 which will now give the particles a varying speed between 0.5 and 1.5.

'''Life Expectancy (s):''' This is how long each particle last, in seconds, before vanishing.

'''Life Expectancy +/-''': Again is a random variance to the value set in Life Expectancy. Set this value to 0.5, making the particle last longer and shorter as the fire burns.

'''Scale Range:''' This adds a random variance to the size of the particle much like the other +/- settings. Set this to 0. 6. You should now see the flame vary in size as it emits from the base emitter.

Play with these settings a bit to get familiar with them. In the end you should have a raging fire animation. When you are happy, save your work.

[[File:T1_fire_1.jpg]]

'''Getting the effect in game:''' Right click on the Root and select “Post to Local”. You'll find the new VFX under the model palette. It can be placed directly in the level editor or the cutscene editor but not the area editor. You can also add the effect dynamically to an area using a script.

'''Notes:''' Because an effect is Art work, at present will not be included with a Builder to Builder Create and must be sent separately. Scripting examples to come later once there is a client to test for accuracy.

[[File:T1_ptl.jpg]]

So now you have a raging fire. In part 2 of this tutorial, we will make this fire dance and sing. Part 2 will introduce using the time line settings to very coloration, scale, size and other more advanced settings as well as explore some of the settings introduce here a bit deeper. Keep the bonfire effect you created with this tutorial, we will need it in the second part. The bonfire effect can also be downloaded from the social site.

== VFX Tutorial Part 2 ==

In tutorial #1 we created a good bone fire as a base and up until now we only changed the values directly in the properties on the effect. As we can see this works well for simple effects. Changing the values in this manor alters the effect over its entire life time.
We have seen how to change the color and scale of the effect by changing the values in the properties age map. This is great for a basic flame but we want to add more life to it by making the flame vary in color and size over the length of the effect. To start, Set all the Values back to default as shown in the 2 pictures below.
Note: This tutorial assumes you have read Tutorial #1 or are familiar with the basics of the VFX editor.

[[File:T2_agemap_01.jpg]][[File:T2_emission_01.jpg]]

Setting any of these values directly will affect the visual over the entire length of the effect. Instead we want to vary these values so the flame will change from reds, yellows, and orange. We also want to change its size during the impact, duration, and cessation phases of the effect. To do this, we will use the time line to set colors and scale so they change over the course of the effect.

Before we continue, we need to make a small change. Select the Root of the effect and in the Object Inspector, change the Impact time to 5 sec and the Cessation time to 8 sec. The 5 sec impact will allow us enough time to see the changes in the flame as it grows and the longer cessation time is for the smoke we will be adding later on.

[[File:T2_root_01.png]]

Select the “Base” object, at the top right corner there is a drop down window, select “Color” from the list. Note, when using the time lines, make sure you have the correct emitter object selected. In this case it is the Base emitter. You should then see a time line like the one below.

[[File:T2_color_01.jpg|680px]]

Notice at the top of the time line is reads “Particle Lifetime”. This means that the changes we make here will affect each partial over the lifetime of each particle. The lifetime of the particle is directly related to the “Lifetime” value setting in the Emissions Tab, which currently is set to 1 sec.

=== Parts of the Time line ===

[[File:T2_timeparts_01.jpg|680px]]

'''Control Point:''' The round dots allow you move the value up, down, left, or right within the time line.

'''Value Rang:''' The left side of the time line shows the value range. At this current control point, the value is 1, which is the current value for all 4 colors in the Age map.

'''Current Value:''' The dotted line shows the current value any place on the time line. Currently it is set to 1 over the entire length of the particle lifetime. When a control point is added, the line between the 2 control points will become solid.

'''Visible:''' This box shows which time lines are visible, the dotted or solid line. You can select or unselect these time lines. Currently all 4 are selected and visible. All 4 also are set at the same value so you only see one control point as all 4 are stacked from top to bottom, Color A being the one on top.

Click inside the time line and you will get a vertical bar. Drag the bar to the far right until the end of the timeline is reached. This bar represents that point in time and I will refer to this bar as the Point bar. Clicking anywhere on the time line will move the point bar to that point in time.

[[File:T1_v_bar.jpg]]

Right click on the time line and select “Add Control Point”. This adds a node at the point in which the point bar and the time line intersects. Also note that the Colors in the age map turn red, this indicates that the values are now controlled by the time line and can vary in value depending on the point in time. Also note that this adds a Control Point to each time line that is visible, so all 4 colors get an added node.
Before we continue, save your work. Next turn the Loop Animation Off by clicking on it at the top right so it is no longer highlighted.

[[File:T2_timeparts_02.jpg]]

There are 2 ways that we can set the values on the time line, directly in the value box of the Age Map, or by dragging the control points on the time line. To see how it affects the animation, first make sure the point bar is to the far right at 100. Change the value Color B to 0 directly in the Age Map properties, just as we did in Tutorial 1. You should now see a blue line starting at 1 and dropping to 0 at the end of the time line. By changing the value on the Age Map, you affect the control point that intersects with the Point Bar. The Flame should now be white at the bottom and Yellow at the top.

[[File:T2_cb.jpg|680px]]

To see what happens to each particle, go to the Emission tab and change the birth rate to 1. You will see the particle start from the emitter as white, and then gradually change to yellow. Set the Birth rate back to 10 and return to the Age Map.

Now move the point bar to the far left on 0. Notice that the value in Color B on the Age Map is again 1. Change this to 0 also and the left most control point will drop to 0 and you time line should now look like this.

[[File:T2_cb_2.jpg|680px]]

The small box in the lower right corner in the above image indicates which time lines are visible. Right now all 4 colors are visible on the time line. Next we will affect the green color by dragging the control points instead of changing the value directly in the Age Map. However the green time line in underneath the Alpha time line. So to make it visible, click the check mark to unselect the Alpha Color. The Alpha line goes away and we can now see the Green time line. Also uncheck the Red and Blue color time lines so only the Green is visible.

Next Click and hold on the far left (0) control point of the Green time line and drag it down a bit, about half way between 1 and 0, you should see the flame change colors as you drag it down. Grab the right most control point and drag it down to 0. You should now have a flame that is brighter red at the bottom and darker at the top.

[[File:T2_cg.jpg|680px]]

Now we are going to add 2 more control points to the Green time line. Move the Point Bar to 5 on the Particle Lifetime line, right click and select “Add Control Point”. Now move the Point Bar to 10 on the timeline and add a second control point. Grab the first control point we just added, the one at 5, and drag it up to about 0.7. This will create a bright flicker at the base of the fire.

[[File:T2_cg_2.jpg|680px]]

Now we just need to fade out the top of the flame a bit so the bottom is more intense than the top. Uncheck the green timeline and check the Color A (Alpha). Color A is a transparency color and can be use to alter the intensity of the particle. Grab the Right most control point and drag it down to about 40% (0.4). You will see that the top is less visible than the bottom of the flame. Save your work.

=== Changing its size ===

Right now the flame is a single column that is the same size at the top as it is at the base, this is not very realistic so we will remedy that by changing the scale of the particle.

In the drop down menu at the top right, select “Scale”. Again you will see a time line labeled “Particle Lifetime” a Control point, and a box showing the “Scale Y” and “Scale X” time lines. As we did before, move the Point Bar to the far right at 100 and right click and select “Add Control Point”. Now uncheck the Scale X time line so only the Scale Y line is visible. Move the Left control point to about 1.5 and the right control point to about 1.75. Check the Scale X timeline to make it visible and move the left control point to about 1.5 and the right control point to 0.5. This will widen the base and stretch the top to a point much like a real fire.

[[File:T2_scale.jpg|680px]]

Now the fun begins. Up until now we have been changing values over the lifetime of the particles. Now we will start changing values over the Impact, Duration, and Cessation time of the effect, but first save your work.

Select the “Emissions” Tab in the Object Properties. In the drop down menu, select “Birth Rate”. This time you will see a bit different looking time line. At the top you will see 3 sections, Impact which starts at 0 and ends at 5000, Duration starting at 5001 and ending at 8000, and the Cessation which starts at 8001 and ends at 1600. These times correlate to the 5 sec Impact, 3 second Duration, and the 8 second Cessation times specified in the VFX root.

'''TIP:''' You can Zoom Extents by double clicking inside the time graph, or zoom in/out by using the mouse scroll wheel.

When an effect is used in game, the Impact time plays, then the Duration time is looped for the length of the applied effect, then the Cessation time plays. For example, if the fire effect is applied to a wood pile for 3 min, the Impact time plays then the 2 second duration is looped for 3 min then the cessation time plays. With this in mind, we want the fire to build up to the a full blown fire, then taper off and go out.

In the Birth Rate time line, add 3 more control points, one at the Duration start, one at the duration end, and one at about 12000. Starting from the left move the left most control point to 0, move the second Control Point to 10, the third Control Point to 10 and the fourth to 0.

[[File:T2_br_2.jpg|680px]]

Notice that the flame stops burning like it was before. This is because now the total effect length is a factor. Slide the Point Bar back and forth on the time line, you can see what happens to the fire at any point in time. Now to view the animation of the effect, you must click the Play button in the upper right corner. The Point Bar will scroll across the time line and the results can be viewed in the effect window.

The fire should now start out slow and build up then taper off and go out at around 12 seconds. You can click on the Loop Animation if you want and the effect will continue to loop until paused by the Pause Animation button or by clicking in the time line.

Now select Life in the drop down menu. Right now each point in time the flame last 1 second. We want to change this so the flame when first starting out or ending doesn’t last that long. Keep the tip I gave above in mind, and make the Life time line look like the one in the picture. The Control Point times from left to right are 0, 1, 1.4, 1, 0 then save your work.

[[File:T2_life.jpg|680px]]

'''Let’s Dance:'''

Right now we have our fire looking pretty good, but there is one element still missing, the wavering and dancing of a real fire. On the Emission table item 12 and 13 are “Spawn Spread X (Deg)” and “Spawn Spread Y (Deg)”. These settings affect the spread of the particles in the X and Y directions, that is the particles can emit in varying directions in degrees from the emitter. Set both of these to 20 degrees.

Now our fire dances. Note that these settings could be set using the time line “Spawn Spread” as well, feel free to play with that if you wish.

We can get a better Idea of what our effect will look like in game by adding a reference model. Right click on the Root and select “Insert > Insert Reference Model”. In the Resource window Name field we can filter the list to make it easier to find what we are looking for, so enter *fire* and press enter. Now your resource list will only show those items with the word fire in it.

[[File:T2_resource.jpg]]

Choose the resource “plc_firepit_01_1”. Turn Bounding box Off by clicking it at the top to un-highlight it. This gets rid of the yellow square around the objects. Turn the Collision Plane on by clicking on it to highlight it. This will simulate a stone floor at the walk mesh level.

Now play you animation. You can also select the Base object and click anywhere in the time line, for example if you place the Point Bar anyplace in the Duration time you can watch your fire burn at it’s full potential.

'''Challenge:''' Replace the plc_firepit_01_1 with the plc_bonfire01_1 reference model. Scale your fire up, and increase it’s life time to engulf the wood pile in flames.
Don’t forget to save your work.

[[File:T2_fin.jpg|680px]]

This concludes Part 2 of the tutorial. In Part 3 we will be adding smoke and lighting to the flame and make the flickering flame reflect off of surrounding objects.

== VFX Tutorial Part 3 ==

This tutorial assumes you have read Tutorial #1 and #2 and are now familiar with using the time lines to adjust values over time. You can down load the final effect from Tutorial #2 from the social site if you need it to continue with Tutorial #3.

'''Where there’s smoke:'''

Our fire is missing 2 more elements to be complete, smoke and lighting.

First we will add the smoke.
Right click on the effect Root and select “Insert > Insert Emitter”. You will see a second emitter appear on top of the first one.
Select the new emitter and in the Object Inspector properties, change its name to Smoke. For Material Library, select fx_smoke_vol. For Material Object select fx_smoke_vol_blend.

In the First tutorial we talked about the Flipbook Type: Contact Sheet. For this effect we will be using the Flipbook Type: Volume. This works similar to the Contact Sheet type except that the Flipbook Rows is the number of layers, usually 2 or 4. The Flipbook Columns should always be 1 and the Frame per second is a factor of the 2, i.e. Rows x Columns. Set these to 2, 1, and 2 respectively.

In the Age map, set the colors R, G, B to 0.5 and Color A to 0.7. Our smoke should now look more like smoke, but we have a ways to go yet.
Smoke usually bellows upwards and spreads out as it rises. We can simulate this with a combination of the Scale and Scale Multiplier time lines.
Select the smoke emitter and the Scale time line from the top right drop down menu. We want the smoke to grow in size both in the X and Y directions, but more so in the X direction.

[[File:T3_scale.jpg]]

Both X and Y should start at 1 and X should end around 5.5 and Y should end around 3.5 over the life of the particle. This will give us a funnel shape.

Now select the Scale Multiplier time line. We can use this line to make the smoke grow in proportion to the flame during it’s impact, duration, and cessation times.

Start out at a 0 multiplier and raise it to 1 at the start and during the duration time, then taper it back down to 0 during the Cessation time. Notice that at around 12000, the flame is gone and we are only left with smoke for the last 4 seconds of the effect.

[[File:T3_scale_mult.jpg]]

Now we need to change a few of the Emissions. Set the Birth rate to 3, Life Expectancy to 2.5 and Life Expectancy +/- to 0.5. If you recall from previous tutorials the +/- will give us a variance on how long the particle last. As we did with the flame, we want the smoke to also waver from left to right and forward and back, set the Spawn Spread X (Deg) and Spawn Spread Y (Deg) to 10.

'''Changing Position:'''

By now you may have noticed that when you play the effect in full, the smoke stays at ground level. Smoke naturally rises from the top of the flame, not from the base. This is OK during the Impact and cessation phase as the fire is small and near the ground level. However, we need the smoke to rise to the top of the flame during the Duration phase. To do this we will use the position time line to make the smoke rise, and lower as the flame grows.

With the smoke emitter selected, select the Position Time Line. Unselect the X and Y position time lines so only the Z line is visible. Add a control point at the start and end of the Duration time. Also add a control point at around 12000 and one at the end of the effect time.

Raise the control points at the start and end of the duration to about 1.2, so it looks like the pic below.

[[File:T3_position.jpg]]

Now when you play the effect, the smoke should rise and lower with the flame. Feel free to play with any of these settings to get the look you like best.

'''Fade it out:'''

If you zoom out and look at the Animation as a whole you will notice that the smoke just suddenly disappears at the top, looks a bit odd. Instead we will fade it out so this isn’t seen.

Select the Smoke emitter and then select the Color time line. Uncheck all the colors except the Alpha color. Add 2 or 3 control points towards the end of the time line and tapper the alpha down to 0 at the end of the particle life time. This makes the smoke fade out naturally. Save your work.

[[File:T3_colora.jpg]]

'''Light My Fire:'''

Before we continue, let’s put our fire into a game scene. Select the VFX Root and in the Object Inspector, under “Layout Settings”. You can select a area and see what your effect will look like in game. In Layout, select the area resource. Your effect should be near the upper right corner.

[[File:T3_arena.jpg]]

Play the VFX a few times, notice there is no light given off by the fire.

Right click the VFX root and select Insert > Insert Light. A new light object will be inserted on top of the fire emitter. It’s right where we need it to be, by default.

[[File:T3_light_2.jpg]]

Light Properties:
Affects Characters: Set this to true. This setting specifies if the light should reflect off nearby creatures and characters.
Affects Level: same as above but it applies to the surrounding terrain.
Name: Name your light, I called mine “Flicker”

First we need to give the light some color, a good yellowish – red should do. Set Color G to 0.5 and Color B 0. To make the fire flicker, we will change the intensity of the color to coincide with the flame.

Select the Flame object and then select the “Color Intensity” time line from the drop down list. Add several control points and adjust the intensity up and down so it climaxes during the duration, similar to the image shown.

[[File:T3_intens.jpg]]

Be sure to drop the intensity to 0 at around 12000 as this is where the flame goes out.

TIP: You can manually slide the time bar left and right on the time line to get a visual check of the intensity control points.

Now we have a nice bon fire complete with smoke and lighting.

[[File:T3_flame.jpg]]

'''Challenge:''' Using the Material Library “fx_distortionmatlib” add a third emitter and give your fire distortion.

This concludes the basic VFX Tutorials, Thanks for reading.
Author: Jassper

[[Category:Tutorials]]
[[Category:VFX]]

Placeable tutorial

2009-10-03T23:28:49Z

Codepoetzz: /* Field Notes */

In Dragon Age, "[[placeable]]s" are objects that a player can interact with or are objects simply added to the area to create greater detail. They are added to areas simply by dropping them into the area landscape. Once placed, they can easily be moved into position or rotated on their axis to achieve the look you want.

In general, placeables can serve a wide variety of functions. They can render popup text. They can be destroyed or bashed or hold inventory or treasure within. They can be holders of conversations. In this tutorial we'll mainly stick to the basics, but placeables are an important part of any area design.

== Creating A Placeable ==

Similar to creating anything within the toolset, go to File > New > Placeable or right click in the Palette Window to access the New Placeable option.

[[Image:New resource.png|thumb|New resource menu]]

The first step is naming the placeable. We'll need a door for the tutorial so lets start with a door that will serve as an area transition. Name the placeable "transition_door". Luckily and unluckily, the default object is a door. The lucky part is that it is a door. The unlucky part is that this is a non-area transition door. There are two types of doors, ones that open and allow for an area transition and ones that simply open. For the upcoming [[area tutorial]] we need a door that will allow the player to move from outside the hut to inside the hut.

Doors that allow transitions are all grouped under the Appearance beginning with "Area Transition". Change the appearance to be "Area Transition, Ferelden, Small". The placeable has the exact same appearance it had but now it will be able to function as an area transition. For more detail on doors, please see [[door]]s. They are a bit unique within the placeable world so it is important to understand how the two types function as well as some of the finer options that are available.

As you can see, placeables are straightforward and easy to create. Let's build one more for our module before moving along with the tutorial. Again create a new placeable and let's name it "statue". Any good exterior can always use a statue. For this lets set the appearance to "Statue, Giant" and rename the placeable "Huge Statue". By default, the placeable is "Interactive" so let's toggle that setting to false. You can either use the drop down menu OR just double click on TRUE to toggle the state. Now our statue is ready to be placed. It is basically an addition to the landscape. It won't be something you can interact with but it can add detail to your area and to your story.

While we are in the tutorial, let's quickly cover checking in and checking out resources which is a new concept for Dragon Age. For a more detailed summary, please see [[Resource palette]]. Briefly in Dragon Age, resources are stored within databases. When you work on a module and alter any existing work or create new work, you are creating an instance of the object (be it a placeable, item, creature, area etc.). There are a number of benefits for this that are beyond the scope of this tutorial but when you edit something, it has to be "checked out" (or never checked in) with you working on an instance.

For example, select your new statue and right click and you will see that many common tasks are NOT available because it has not been "checked in" to the database. For example, you can't rename or delete the placeable. In order to rename the placeable, we'll need to check in the placeable. Right click and select check in. Check the box for no comment or enter a comment and hit ok. At this point, the resource has been written to the database. Once the object is "checked in" you can adjust the name or delete it if you so choose (assuming it doesn't have other dependent resources).

== Placing / Adjusting your Placeable ==

That is a brief overview of how to create your first placeables. Now let's cover putting them into your module. To place a placeable, simply bring up an area (which we will make in the [[Area Tutorial]]) and highlight the placeable and left-click within the region.

To adjust the position or orientation of the object, you'll need to use the Camera and Movement Toolbar:

[[Image:Camera and movement toolbar labeled.png]]

To adjust the x,y,z position either activate the Local Coordinates button [[Image:IconLocalCoordinates.png]] or use the keyboard shortcut 'q'. With this activated, you can mouse over any axis (notice the change to the yellow highlight) and the object will move only in the selected dimension.

To adjust the rotational orientation, highlight the 3 Axis Rotation button [[Image:Icon3AxisRotation.png]] or use the keyboard shortcut 'e'. In a similar fashion, you can easily selected and adjust the rotational orientation of the placeable.

(For much more detail regarding 3D controls please see the [[3D control]] page).

Of course, you can use the Object Inspector to type in exact numbers for any of these parameters you choose. Simply ensure the object is selected within the area viewer and type in your changes.

== Field Notes ==

*'''Character''': Mapping a character to a placeable is done for VO when a placeable owns a conversation.

[[Category:Placeables]]
[[Category:Tutorials]]

Placeable tutorial

2009-10-03T23:27:36Z

Codepoetzz: /* Placing / Adjusting your Placeable */

In Dragon Age, "[[placeable]]s" are objects that a player can interact with or are objects simply added to the area to create greater detail. They are added to areas simply by dropping them into the area landscape. Once placed, they can easily be moved into position or rotated on their axis to achieve the look you want.

In general, placeables can serve a wide variety of functions. They can render popup text. They can be destroyed or bashed or hold inventory or treasure within. They can be holders of conversations. In this tutorial we'll mainly stick to the basics, but placeables are an important part of any area design.

== Creating A Placeable ==

Similar to creating anything within the toolset, go to File > New > Placeable or right click in the Palette Window to access the New Placeable option.

[[Image:New resource.png|thumb|New resource menu]]

The first step is naming the placeable. We'll need a door for the tutorial so lets start with a door that will serve as an area transition. Name the placeable "transition_door". Luckily and unluckily, the default object is a door. The lucky part is that it is a door. The unlucky part is that this is a non-area transition door. There are two types of doors, ones that open and allow for an area transition and ones that simply open. For the upcoming [[area tutorial]] we need a door that will allow the player to move from outside the hut to inside the hut.

Doors that allow transitions are all grouped under the Appearance beginning with "Area Transition". Change the appearance to be "Area Transition, Ferelden, Small". The placeable has the exact same appearance it had but now it will be able to function as an area transition. For more detail on doors, please see [[door]]s. They are a bit unique within the placeable world so it is important to understand how the two types function as well as some of the finer options that are available.

As you can see, placeables are straightforward and easy to create. Let's build one more for our module before moving along with the tutorial. Again create a new placeable and let's name it "statue". Any good exterior can always use a statue. For this lets set the appearance to "Statue, Giant" and rename the placeable "Huge Statue". By default, the placeable is "Interactive" so let's toggle that setting to false. You can either use the drop down menu OR just double click on TRUE to toggle the state. Now our statue is ready to be placed. It is basically an addition to the landscape. It won't be something you can interact with but it can add detail to your area and to your story.

While we are in the tutorial, let's quickly cover checking in and checking out resources which is a new concept for Dragon Age. For a more detailed summary, please see [[Resource palette]]. Briefly in Dragon Age, resources are stored within databases. When you work on a module and alter any existing work or create new work, you are creating an instance of the object (be it a placeable, item, creature, area etc.). There are a number of benefits for this that are beyond the scope of this tutorial but when you edit something, it has to be "checked out" (or never checked in) with you working on an instance.

For example, select your new statue and right click and you will see that many common tasks are NOT available because it has not been "checked in" to the database. For example, you can't rename or delete the placeable. In order to rename the placeable, we'll need to check in the placeable. Right click and select check in. Check the box for no comment or enter a comment and hit ok. At this point, the resource has been written to the database. Once the object is "checked in" you can adjust the name or delete it if you so choose (assuming it doesn't have other dependent resources).

== Placing / Adjusting your Placeable ==

That is a brief overview of how to create your first placeables. Now let's cover putting them into your module. To place a placeable, simply bring up an area (which we will make in the [[Area Tutorial]]) and highlight the placeable and left-click within the region.

To adjust the position or orientation of the object, you'll need to use the Camera and Movement Toolbar:

[[Image:Camera and movement toolbar labeled.png]]

To adjust the x,y,z position either activate the Local Coordinates button [[Image:IconLocalCoordinates.png]] or use the keyboard shortcut 'q'. With this activated, you can mouse over any axis (notice the change to the yellow highlight) and the object will move only in the selected dimension.

To adjust the rotational orientation, highlight the 3 Axis Rotation button [[Image:Icon3AxisRotation.png]] or use the keyboard shortcut 'e'. In a similar fashion, you can easily selected and adjust the rotational orientation of the placeable.

(For much more detail regarding 3D controls please see the [[3D control]] page).

Of course, you can use the Object Inspector to type in exact numbers for any of these parameters you choose. Simply ensure the object is selected within the area viewer and type in your changes.

== Field Notes ==

Character: Mapping a character to a placeable is done for VO when a placeable owns a conversation.

[[Category:Placeables]]
[[Category:Tutorials]]

Area tutorial

2009-10-03T23:07:46Z

Codepoetzz: /* Grouping */

Once you have created a new module (see [[creating a module]]), the first thing you will likely want to do is create one or more areas where your adventure is going to be set.

== Creating the area ==

[[Image:New resource.png|thumb|New resource menu]]

There are several ways to reach the "new area" command; you can right-click on the resource palette window, or select "new" from the file menu.

<br clear="all" />

Areas are represented with the [[Image:IconArea.png]] icon. When you select it you'll be presented with a "Create New Resource" window:

[[Image:Create new resource.png|center|]]

{{sidebox|
* Resref names should be useful to the designer
* Set the "area layout" property to assign terrain to an area
* "Resource Name" and "Tag" are only seen by developers
* "Name" may be seen by players
}}

Most of the fields are already filled in with good defaults for the module you're working with. You'll need to supply a "ResRef Name", which is the name by which the resource will be known internally to the toolset. (This is the "Name" field on the "Create New Resource" dialog box.) You'll probably want to use a name that will remind you, the module designer, of the purpose or important features of the area. Changing a resource's name is difficult to do later. We're going to call the first area of the tutorial "hut_exterior".

After creating the area you'll be presented with a completely blank area editor. There will be no environment or objects of any kind. To specify what environment you'll be placing objects into, open the object inspector and select the "Area Layout" property. There will be an ellipsis button ([[Image:ellipsis.png]]) in the property's data field that will bring up a resource selection window where you can select an environment to use for this area. The environment we wish to select is in the area layout file "ost101d.arl". Once we select it, the area layout appears in the main area window.

The resource's internal resource name is hut_exterior but the player will not see this when he's playing the game. To give the area a name meaningful to the player we'll set the "Name" field to "Deep in the Swamp". All of the other defaults are fine for now, we will leave them as is.

[[Image:Area tutorial 1.png|thumb|600px|center]]

== Area Basics ==
{{sidebox|
* See [[3D control]] for camera and movement controls
* You can double-click on an object in the area's object list to zoom in to it.
}}

Moving the view around inside the area layout can be somewhat non-intuitive and frustrating at first. The toolset has a number of different control schemes it can be set to; see [[3D control]] for a summary of the various options. By default, you can:

* zoom in and out by using the mouse wheel
* rotate the camera around the target it's focused on by holding the middle button down or by holding down the Ctrl key and the right mouse button while moving the mouse
* translate the camera by holding down the Ctrl key and the left mouse button while moving the mouse

To see where you are a bit better, it is helpful to deactivate real lighting or turn on full brightness. Above the area viewer, the sun-like button should be toggled so that it isn't highlighted; see [[Area]] for a more complete summary of various options within the Area Editor.

Before we move along to placing a starting location, it is important to touch upon Pathfinding points. All BioWare areas include walkmesh or pathfinding information. To view pathfinding information for your area, goto View, then Environment, and then toggle Pathfinding Points on. The green dots represent areas where characters can walk. Note, in this map, the area that is walkable is quite small compared to the entire area. When placing your starting location, you should ensure it is in a walkable portion of the area.

== Setting the start point ==

{{sidebox|
* Create a waypoint to mark where the player starts the game
}}

This is going to be the starting area for the adventure, so we're going to want to define a spot within the area where the player will first appear. This is done by setting a [[waypoint]]. Waypoints are very simple objects that mark locations in an area that other objects in the game can refer to; they are not normally visible to the player. To create a waypoint, right-click somewhere in the area and select "Insert Waypoint" from the resulting menu. A waypoint will appear at the location of your mouse pointer and follow it around along the area's floor; move it to the approximate place you want to have the player appear and left-click to place it. By default the waypoint is named "Waypoint".

The waypoint will be automatically selected, indicated by a yellow wireframe box surrounding it. You'll also see the waypoint listed in the area's object list, to the left of the display window. If you lose track of the waypoint later a good way to find it again is to right-click on the waypoint in the list and select "Zoom to Object" in the resulting menu or double click on its tag to center the object in the display window. The waypoint's properties will be shown in the object inspector. We want to change the waypoint's name to something more informative, in this case to "start". More importantly for the game itself, though, we'll also want to change the waypoint's tag to "start" (it defaults to blank). An object's tag is how scripts and other resources will refer to the waypoint. Since this particular waypoint is never going to be visible to the player it's likely that the waypoint's name will never be seen at all.

The player will also start out facing in the same direction that the waypoint is facing (indicated by the arrow-shaped base of the waypoint object). If we don't want the player to start out facing in the default direction, we'll want to rotate the waypoint to point in a new direction. To rotate an object, use the toolbar to switch from standard selection mode ([[Image:Standard selection mode.png]]) to 3-axis rotation mode ([[Image:3 axis rotation mode.png]]).
When you select the waypoint in this mode you'll see a set of circles around the waypoint's base with various orientations; clicking and holding the mouse button on one of them will allow you to rotate the waypoint around its center.

[[Image:Waypoint rotation.png|center]]

Now that we have an area and a waypoint to start at, we can now tell the module that this is where the player is to appear. Reopen the "Manage Modules" window (available via a command under the File menu), select your module, and click the "Properties" button. This opens the module's properties. For the "Starting Area" property, click on the ellipsis button ([[Image:ellipsis.png]]) and select the starting area from the areas available in the module; since we've only put one area in so far "hut_exterior" will be the only available option. Once the area has been selected we can then select the starting waypoint from the waypoints currently placed in the area. Again, we've only put in one so this will be easy. You can also set the player to appear ath the origin of the map (coordinates 0,0,0), but this is generally a poor choice and available only as a default in case there are no waypoints defined yet.

== Area transitions via doors ==

Adventures almost always have more than one area in them, so we'll create a second area to demonstrate travel between the two. The area "hut_interior" will use area layout ost102d, which is a cosy little room that represents the interior of the small hut present in the hut_exterior area.

{{sidebox|
* [[Door]]s are special placeables
* Doors can attach to "hooks" pre-built into the area layout
* Area transition doors use a different "appearance" than within-area doors
}}

Next we will need to create some doors. We'll create a default door placeable using the "New Placable" command, reached in a similar way as the "New Area" command explained earlier (placeables will be covered in another tutorial, but the core game resources will come with a variety of default doors usable in many situations like this) and place it in the area near the empty doorframe built into the hut's exterior. For an area transition, use one of the "Area Transition" appearances for the door. To place the door, click on it in the palette; the mouse cursor will turn into a crosshair; then click in the area viewer near the doorframe.

As a side note, if you accidentally use one of the standard door appearances it won't work as an area transition: the door will simply swing open when clicked on instead. Each standard door appearance has a matching area transition door appearance in the resource database so this can be an easy mistake to make, but it's also easily correctable - just go back to the door's placeable resource and swap in the correct appearance, and all copies of that door in use throughout your game will be updated.

You may notice that when the door you placed in the area is selected a small blue sphere will appear at one edge in addition to the yellow wireframe bounding box. This is the door's "hook". Area layouts come with hidden "hooks" pre-installed to place doors on, and doors have matching hooks of their own. If you click on the blue sphere it will turn red, and all of the compatible door hooks built into the area's layout will appear. The following image illustrates this:

[[Image:Door with door hook selected.png|400px|center|thumb|Drag the red sphere near to the blue sphere to automatically position the door]]

To hook a door up with its frame, simply click and drag the door's hook to a location very close to the matching frame hook. You don't need to get the positioning exact; if the two hooks are close enough together when you release the mouse button they'll automatically snap together. The door will be positioned and reoriented to fit correctly into the frame.

Note that door hooks are only there to make it easy to get exact matches on frames and walls that need a snug fit, to ensure that Artists and Designers don't have to spend a lot of time putting it in place. Doors will function just as well off of hooks as on them.

{{sidebox|
* Area transition effect is defined in the door's "Variables" property
}}

Next, we'll tell the game engine that the door is an area transition door and that when the player clicks on it he will be transported to another area of the game. This is done by setting two of the door's [[variable]]s. Select the door (either in the area's object palette or directly in the main display window) and right-click on it, selecting "properties" from the resulting menu. This will open the door's properties in the Object Inspector window. Select the "Variables" property and click on the ellipsis ([[Image:ellipsis.png]]) button. This will open up the variable browser for that particular instance of the door object.

There are two key variables in this list that we'll need to set:

*PLC_AT_DEST_AREA_TAG - tag of the destination area
*PLC_AT_DEST_TAG - tag of the destination waypoint within the destination area

Once we've set these the door will become an area transition door, and when the player interacts with it they'll be transported to the target area.

The destination area is "hut_interior". We'll create a waypoint just inside the hut's interior door, tagged "hut_door_interior", to serve as the place where the player appears.

Here is how the exterior door's variables should look:

[[Image:Area tutorial door variables.png|frame|center|Area transition door's variables]]

And here is the interior door, with the destination waypoint:

[[Image:Area tutorial interior door.png|frame|center|Interior door with destination waypoint]]

The interior door is set up in the same manner, with a destination area of "hut_exterior" and a matching destination waypoint of "hut_door_exterior".

{{sidebox|
* Use invisible area transition "doors" when the transition is already built into the area layout art
}}

If you want to create an area transition that doesn't look like a door, or is otherwise already represented by the level art, you can use an invisible 'door' instead. Appearances for these invisible placeables are named "Area Transition, Invisible". Set its variables the same way as was done for the visible door.

[[Image:Area Transition, Invisible.png|frame|center|Invisible area transition]]

The player won't see this 'door' in the game, but when he moves the mouse pointer over it it will change to signify that an area transition lies there and it can be right-clicked to be activated just like a visible door.

== Area transitions via triggers ==

{{sidebox|
* Triggers use variables with a different prefix for setting their area transition effect
}}

Finally, you can also create an area transition that triggers automatically when the player walks into a predefined area. This is done using [[trigger]]s. ([[Image:IconTrigger.png]]) You'll first have to create a trigger resource, much like how you had to create a placeable door earlier, but trigger resources are much simpler and for area transitions you won't need to change any of the defaults. Create a default trigger with "New -> Trigger" (either by right-clicking the resource palette or from the File menu) and give it an informative name such as "trigger_area_transition".

Go back to your area map, select the trigger from the resource palette, and then click on the map to define the corner points of the area the trigger will occupy. Double-click the last vertex to complete the polygon. A trigger can have any number of vertices, and vertices can be moved, added, or deleted after the trigger is created so don't worry if you don't get it exactly right. Note that the blue plane the trigger uses to show the enclosed area will pass through the ground and may not be entirely visible in the toolset, but it extends infinitely upward so the trigger will still take effect if the player enters its boundaries.

To set the trigger's destination, you'll find a familiar pair of variables in the trigger's default variable table:

*TRIGGER_AT_DEST_AREA_TAG - tag of the destination area
*TRIGGER_AT_DEST_TAG - tag of the destination waypoint within the destination area

(Note the prefix "TRIGGER" instead of "PLC")

Below is an example where we've placed both a trigger and an invisible door across a pathway. Note that this is redundant, only one or the other is really needed. For most purposes a placeable area transition is probably best. (''It is worth noting that placeable area transitions prompt a popup asking the player if they want to transition when bumped, but not when clicked upon - effectively acting as either a door or a trigger.'') The waypoint shown is the arrival spot for the player when coming in from the other side; note how it's placed outside the trigger area, allowing the player to immediately back up and retreat through the area transition if he chooses.

[[Image:Area Transition, invisible with trigger.png|center]]

== Grouping Placeables ==

{{sidebox|
* Two or more placeables can be grouped together using Associations.
}}

Often the placeables within an area are related. For example, a firepit placeable probably has an associated sound emitter. The toolset needs to be told that these two objects are related. Place the firepit in your area. Next, place the sound emitter. Right-click on the firepit to bring up the menu and choose "Add Associated object." The cursor changes to a cross-hair. Click on the sound emitter placeable. Now when you drag the firepit placeable around the area, the sound emitter will automatically follow. Use the "Managed Links" menu item if you want to remove an association. Note that associations are uni-directional; you can still move the sound emitter without moving the firepit. Examples of other useful associations: a table and all of the items on top of the table, a table surrounded by chairs, etc.

[[Category:Areas]]
[[Category:Tutorials]]

Area tutorial

2009-10-03T22:54:23Z

Codepoetzz: /* Area transitions via triggers */

Once you have created a new module (see [[creating a module]]), the first thing you will likely want to do is create one or more areas where your adventure is going to be set.

== Creating the area ==

[[Image:New resource.png|thumb|New resource menu]]

There are several ways to reach the "new area" command; you can right-click on the resource palette window, or select "new" from the file menu.

<br clear="all" />

Areas are represented with the [[Image:IconArea.png]] icon. When you select it you'll be presented with a "Create New Resource" window:

[[Image:Create new resource.png|center|]]

{{sidebox|
* Resref names should be useful to the designer
* Set the "area layout" property to assign terrain to an area
* "Resource Name" and "Tag" are only seen by developers
* "Name" may be seen by players
}}

Most of the fields are already filled in with good defaults for the module you're working with. You'll need to supply a "ResRef Name", which is the name by which the resource will be known internally to the toolset. (This is the "Name" field on the "Create New Resource" dialog box.) You'll probably want to use a name that will remind you, the module designer, of the purpose or important features of the area. Changing a resource's name is difficult to do later. We're going to call the first area of the tutorial "hut_exterior".

After creating the area you'll be presented with a completely blank area editor. There will be no environment or objects of any kind. To specify what environment you'll be placing objects into, open the object inspector and select the "Area Layout" property. There will be an ellipsis button ([[Image:ellipsis.png]]) in the property's data field that will bring up a resource selection window where you can select an environment to use for this area. The environment we wish to select is in the area layout file "ost101d.arl". Once we select it, the area layout appears in the main area window.

The resource's internal resource name is hut_exterior but the player will not see this when he's playing the game. To give the area a name meaningful to the player we'll set the "Name" field to "Deep in the Swamp". All of the other defaults are fine for now, we will leave them as is.

[[Image:Area tutorial 1.png|thumb|600px|center]]

== Area Basics ==
{{sidebox|
* See [[3D control]] for camera and movement controls
* You can double-click on an object in the area's object list to zoom in to it.
}}

Moving the view around inside the area layout can be somewhat non-intuitive and frustrating at first. The toolset has a number of different control schemes it can be set to; see [[3D control]] for a summary of the various options. By default, you can:

* zoom in and out by using the mouse wheel
* rotate the camera around the target it's focused on by holding the middle button down or by holding down the Ctrl key and the right mouse button while moving the mouse
* translate the camera by holding down the Ctrl key and the left mouse button while moving the mouse

To see where you are a bit better, it is helpful to deactivate real lighting or turn on full brightness. Above the area viewer, the sun-like button should be toggled so that it isn't highlighted; see [[Area]] for a more complete summary of various options within the Area Editor.

Before we move along to placing a starting location, it is important to touch upon Pathfinding points. All BioWare areas include walkmesh or pathfinding information. To view pathfinding information for your area, goto View, then Environment, and then toggle Pathfinding Points on. The green dots represent areas where characters can walk. Note, in this map, the area that is walkable is quite small compared to the entire area. When placing your starting location, you should ensure it is in a walkable portion of the area.

== Setting the start point ==

{{sidebox|
* Create a waypoint to mark where the player starts the game
}}

This is going to be the starting area for the adventure, so we're going to want to define a spot within the area where the player will first appear. This is done by setting a [[waypoint]]. Waypoints are very simple objects that mark locations in an area that other objects in the game can refer to; they are not normally visible to the player. To create a waypoint, right-click somewhere in the area and select "Insert Waypoint" from the resulting menu. A waypoint will appear at the location of your mouse pointer and follow it around along the area's floor; move it to the approximate place you want to have the player appear and left-click to place it. By default the waypoint is named "Waypoint".

The waypoint will be automatically selected, indicated by a yellow wireframe box surrounding it. You'll also see the waypoint listed in the area's object list, to the left of the display window. If you lose track of the waypoint later a good way to find it again is to right-click on the waypoint in the list and select "Zoom to Object" in the resulting menu or double click on its tag to center the object in the display window. The waypoint's properties will be shown in the object inspector. We want to change the waypoint's name to something more informative, in this case to "start". More importantly for the game itself, though, we'll also want to change the waypoint's tag to "start" (it defaults to blank). An object's tag is how scripts and other resources will refer to the waypoint. Since this particular waypoint is never going to be visible to the player it's likely that the waypoint's name will never be seen at all.

The player will also start out facing in the same direction that the waypoint is facing (indicated by the arrow-shaped base of the waypoint object). If we don't want the player to start out facing in the default direction, we'll want to rotate the waypoint to point in a new direction. To rotate an object, use the toolbar to switch from standard selection mode ([[Image:Standard selection mode.png]]) to 3-axis rotation mode ([[Image:3 axis rotation mode.png]]).
When you select the waypoint in this mode you'll see a set of circles around the waypoint's base with various orientations; clicking and holding the mouse button on one of them will allow you to rotate the waypoint around its center.

[[Image:Waypoint rotation.png|center]]

Now that we have an area and a waypoint to start at, we can now tell the module that this is where the player is to appear. Reopen the "Manage Modules" window (available via a command under the File menu), select your module, and click the "Properties" button. This opens the module's properties. For the "Starting Area" property, click on the ellipsis button ([[Image:ellipsis.png]]) and select the starting area from the areas available in the module; since we've only put one area in so far "hut_exterior" will be the only available option. Once the area has been selected we can then select the starting waypoint from the waypoints currently placed in the area. Again, we've only put in one so this will be easy. You can also set the player to appear ath the origin of the map (coordinates 0,0,0), but this is generally a poor choice and available only as a default in case there are no waypoints defined yet.

== Area transitions via doors ==

Adventures almost always have more than one area in them, so we'll create a second area to demonstrate travel between the two. The area "hut_interior" will use area layout ost102d, which is a cosy little room that represents the interior of the small hut present in the hut_exterior area.

{{sidebox|
* [[Door]]s are special placeables
* Doors can attach to "hooks" pre-built into the area layout
* Area transition doors use a different "appearance" than within-area doors
}}

Next we will need to create some doors. We'll create a default door placeable using the "New Placable" command, reached in a similar way as the "New Area" command explained earlier (placeables will be covered in another tutorial, but the core game resources will come with a variety of default doors usable in many situations like this) and place it in the area near the empty doorframe built into the hut's exterior. For an area transition, use one of the "Area Transition" appearances for the door. To place the door, click on it in the palette; the mouse cursor will turn into a crosshair; then click in the area viewer near the doorframe.

As a side note, if you accidentally use one of the standard door appearances it won't work as an area transition: the door will simply swing open when clicked on instead. Each standard door appearance has a matching area transition door appearance in the resource database so this can be an easy mistake to make, but it's also easily correctable - just go back to the door's placeable resource and swap in the correct appearance, and all copies of that door in use throughout your game will be updated.

You may notice that when the door you placed in the area is selected a small blue sphere will appear at one edge in addition to the yellow wireframe bounding box. This is the door's "hook". Area layouts come with hidden "hooks" pre-installed to place doors on, and doors have matching hooks of their own. If you click on the blue sphere it will turn red, and all of the compatible door hooks built into the area's layout will appear. The following image illustrates this:

[[Image:Door with door hook selected.png|400px|center|thumb|Drag the red sphere near to the blue sphere to automatically position the door]]

To hook a door up with its frame, simply click and drag the door's hook to a location very close to the matching frame hook. You don't need to get the positioning exact; if the two hooks are close enough together when you release the mouse button they'll automatically snap together. The door will be positioned and reoriented to fit correctly into the frame.

Note that door hooks are only there to make it easy to get exact matches on frames and walls that need a snug fit, to ensure that Artists and Designers don't have to spend a lot of time putting it in place. Doors will function just as well off of hooks as on them.

{{sidebox|
* Area transition effect is defined in the door's "Variables" property
}}

Next, we'll tell the game engine that the door is an area transition door and that when the player clicks on it he will be transported to another area of the game. This is done by setting two of the door's [[variable]]s. Select the door (either in the area's object palette or directly in the main display window) and right-click on it, selecting "properties" from the resulting menu. This will open the door's properties in the Object Inspector window. Select the "Variables" property and click on the ellipsis ([[Image:ellipsis.png]]) button. This will open up the variable browser for that particular instance of the door object.

There are two key variables in this list that we'll need to set:

*PLC_AT_DEST_AREA_TAG - tag of the destination area
*PLC_AT_DEST_TAG - tag of the destination waypoint within the destination area

Once we've set these the door will become an area transition door, and when the player interacts with it they'll be transported to the target area.

The destination area is "hut_interior". We'll create a waypoint just inside the hut's interior door, tagged "hut_door_interior", to serve as the place where the player appears.

Here is how the exterior door's variables should look:

[[Image:Area tutorial door variables.png|frame|center|Area transition door's variables]]

And here is the interior door, with the destination waypoint:

[[Image:Area tutorial interior door.png|frame|center|Interior door with destination waypoint]]

The interior door is set up in the same manner, with a destination area of "hut_exterior" and a matching destination waypoint of "hut_door_exterior".

{{sidebox|
* Use invisible area transition "doors" when the transition is already built into the area layout art
}}

If you want to create an area transition that doesn't look like a door, or is otherwise already represented by the level art, you can use an invisible 'door' instead. Appearances for these invisible placeables are named "Area Transition, Invisible". Set its variables the same way as was done for the visible door.

[[Image:Area Transition, Invisible.png|frame|center|Invisible area transition]]

The player won't see this 'door' in the game, but when he moves the mouse pointer over it it will change to signify that an area transition lies there and it can be right-clicked to be activated just like a visible door.

== Area transitions via triggers ==

{{sidebox|
* Triggers use variables with a different prefix for setting their area transition effect
}}

Finally, you can also create an area transition that triggers automatically when the player walks into a predefined area. This is done using [[trigger]]s. ([[Image:IconTrigger.png]]) You'll first have to create a trigger resource, much like how you had to create a placeable door earlier, but trigger resources are much simpler and for area transitions you won't need to change any of the defaults. Create a default trigger with "New -> Trigger" (either by right-clicking the resource palette or from the File menu) and give it an informative name such as "trigger_area_transition".

Go back to your area map, select the trigger from the resource palette, and then click on the map to define the corner points of the area the trigger will occupy. Double-click the last vertex to complete the polygon. A trigger can have any number of vertices, and vertices can be moved, added, or deleted after the trigger is created so don't worry if you don't get it exactly right. Note that the blue plane the trigger uses to show the enclosed area will pass through the ground and may not be entirely visible in the toolset, but it extends infinitely upward so the trigger will still take effect if the player enters its boundaries.

To set the trigger's destination, you'll find a familiar pair of variables in the trigger's default variable table:

*TRIGGER_AT_DEST_AREA_TAG - tag of the destination area
*TRIGGER_AT_DEST_TAG - tag of the destination waypoint within the destination area

(Note the prefix "TRIGGER" instead of "PLC")

Below is an example where we've placed both a trigger and an invisible door across a pathway. Note that this is redundant, only one or the other is really needed. For most purposes a placeable area transition is probably best. (''It is worth noting that placeable area transitions prompt a popup asking the player if they want to transition when bumped, but not when clicked upon - effectively acting as either a door or a trigger.'') The waypoint shown is the arrival spot for the player when coming in from the other side; note how it's placed outside the trigger area, allowing the player to immediately back up and retreat through the area transition if he chooses.

[[Image:Area Transition, invisible with trigger.png|center]]

== Grouping ==

{{sidebox|
* Two or more objects can be grouped together using Associations.
}}

[[Category:Areas]]
[[Category:Tutorials]]

Modifying resources

2009-10-03T16:38:01Z

Codepoetzz: /* Modifying Existing Resources */

== Summary ==
After a resource, such as a placeable, has been created and placed in your areas, you might want to customize some of those instances. For example, you can change some of the properties of the placed instances. But if you change the properties of the resource itself (using the palette menus), the placed instances will not be updated to reflect your changes. To push your changes in the palette resource down to the placed instances, use the "Refresh" menu item on the palette menu. Refresh will update all instances in all areas, even if the areas are not open in the toolset.

Modifying resources

2009-10-03T16:37:32Z

Codepoetzz: Describes how to modify resources versus placed instances

== Modifying Existing Resources ==
After a resource, such as a placeable, has been created and placed in your areas, you might want to customize some of those instances. For example, you can change some of the properties of the placed instances. But if you change the properties of the resource itself (using the palette menus), the placed instances will not be updated to reflect your changes. To push your changes in the palette resource down to the placed instances, use the "Refresh" menu item on the palette menu. Refresh will update all instances in all areas, even if the areas are not open in the toolset.

Main Page

2009-10-03T16:30:34Z

Codepoetzz:

__NOTOC__
<big>'''Welcome to the Dragon Age Toolset documentation wiki!'''</big>

The documentation for the toolset is still being worked on so some of the material here may be incomplete or somewhat out-of-date. The contents of this site will eventually be refined and released to the general public; if you wish to contribute toward that (either by adding your own material or by highlighting holes) you are most welcome and your efforts will be incorporated into the finished product. If you see something that needs improvement you can mark it by adding "<nowiki>{{undocumented}}</nowiki>" at the trouble spot.

*For general comments, discussion, suggestions, and questions, click the "[[talk:Main Page|Discussion]]" link at the top of the page.

In the meantime the contents of this wiki are covered by non-disclosure agreements, so please don't spread it around beyond this site and the designated private fora.

{| width="100%"
|-
| valign="top" height="100%" |


{| style="margin:0; background:#f5fffa; border:1px solid #a3bfb1; text-align:left; color:#000; padding:0.2em 0.4em; width:100%; height:100%"
|-
| valign="top"|
<h2 style="margin:0; background:#cef2e0; font-size:150%; font-weight:bold; border:1px solid #a3bfb1; text-align:left; color:#000; padding:0.2em 0.4em;"> Getting started with the toolset </h2>

<h3 style="text-align:center;">[[Installing the toolset]]</h3>
*[[Creating an account]] - how to create an account for this wiki and social.bioware.com
*[[Known issues]] with the current version of the toolset
<h3 style="text-align:center;">[[Overview of the toolset]]</h3>
*[[Comparisons with other toolkits]] - for users who are familiar with other similar toolkits (eg, the Neverwinter Nights tookit) and would like a brief overview of how the Dragon Age toolkit compares.
*[[Shortcuts]] - Assorted toolset shortcuts.
*[[Common Problems]] - Little things that most people will need to know but that are not necessarily obvious.

If you run into a problem that the documentation doesn't cover and that you can't fix, contact toolsetsupport@bioware.com

<h2 style="margin:0; background:#cef2e0; font-size:150%; font-weight:bold; border:1px solid #a3bfb1; text-align:left; color:#000; padding:0.2em 0.4em;"> Tutorials and how-tos </h2>

<h3 style="text-align:center;">[[Creating a module]]</h3>
The initial structure for the game, see subsequent sections for details on how to fill it out.
*[[How-tos]] - short step-by-step guides for accomplishing specific tasks
*'''[[Tutorials]]''' - lengthier documents that are intended to teach the basics of an entire topic area. Some tutorials build on material from previous ones so you may wish to read them sequentially if you're unfamiliar with any of the basics.
**[[Placeable tutorial]]
**[[Area tutorial]]
**[[Item tutorial]]
**[[Creature tutorial]]
**[[Conversation tutorial]]
**[[Scripting tutorial]]
**[[Cutscene tutorial]]
**[[Map tutorial]] (also introduces 2DA editing)
**[[VFX Tutorial]]

<h3 style="text-align:center;">[[Exporting and running a module]]</h3> How to actually run the adventure you've created.

<h2 style="margin:0; background:#cef2e0; font-size:150%; font-weight:bold; border:1px solid #a3bfb1; text-align:left; color:#000; padding:0.2em 0.4em;"> Editing this wiki </h2>

*The [http://meta.wikimedia.org/wiki/Help:Contents Wiki User's Guide] has information on how to edit this wiki.
* [[GeSHI highlighting]] is installed, including "nwscript" and "dascript" tags!
|}

| valign="top" height="100%"|


{| style="margin:0; background:#f5faff; border:1px solid #a3b0bf; text-align:left; color:#000; padding:0.2em 0.4em; width:100%; height:100%"
|-
|
<h2 style="margin:0; background:#cedff2; font-size:150%; font-weight:bold; border:1px solid #a3bfb1; text-align:left; color:#000; padding:0.2em 0.4em;"> Resources </h2>

The Dragon Age toolset has two main classes of resource; designer resources that are stored in a [[database]] and art resources that are stored as files in your filesystem.

<h3 style="text-align:center;">[[Resource list]]</h3>
* The [[resource palette]] details the main interface for selecting designer resources for editing.

*[[Creating new resources]]
*[[Deleting resources]]
*[[Modifying resources]]

*[[String editor]] - A tool that allows quick and easy access to all text that might be presented to the player in the game.

<h3 style="text-align:center;">[[Builder to builder]]</h3>
The mechanisms used by the toolset that allow packages of game resources to be shared between multiple collaborating builders. This is not intended for builder to player packaging, a separate system will be added to the toolset for this at a later time.

<h2 style="margin:0; background:#cedff2; font-size:150%; font-weight:bold; border:1px solid #a3bfb1; text-align:left; color:#000; padding:0.2em 0.4em;"> Scripting and 2DAs </h2>

<h3 style="text-align:center;">[[Script]]ing</h3>
*[[Event]]s - Dragon Age has an event-driven scripting model; this page lists all known events and their functions.
*[[Effect]]s
*[[Ability|Abilities]]
*[[Custom AI]]s
*[[Script error]]s

*[[Treasure system]]

<h3 style="text-align:center;">[[2DA]] files</h3>
2-Dimensional Arrays contain much of the raw data used by the game. They are generated from Microsoft Excel files. If you want to add new basic creature types, new treasure types, and so forth, you'll need to create new 2DA files.

<h2 style="margin:0; background:#cedff2; font-size:150%; font-weight:bold; border:1px solid #a3bfb1; text-align:left; color:#000; padding:0.2em 0.4em;"> Art tools </h2>

Art resources are files saved separately from the database. They need to be processed by the toolset (posted to local) to be visible to the designer tools and usable in-game.

*'''[[Level editor]]''' (note that this is distinct from the [[Area]] editor)
*'''[[Morph]]s''' are generated with the face-morphing tool.
*[[FMOD]] generates sounds.
*[[FaceFX]] handles facial expressions and lip-synching.
*[[Animation blend tree editor]]
*[[Material editor]]
*[[VFX editor]]
**[[VFX list]] lists visual effects in Dragon Age's library.
|}

|-
| colspan="2" |

{| style="margin:0; background: rgb(250, 245, 255); border:1px solid rgb(175, 163, 191); text-align:left; color:#000; padding:0.2em 0.4em; width:100%"
|-
|
<h2 style="margin:0; background: rgb(221, 206, 242); font-size:150%; font-weight:bold; border: 1px solid rgb(175, 163, 191); text-align:left; color:#000; padding:0.2em 0.4em;"> Technical information </h2>

The material in this section is about technical features underlying the toolset, not normally important for routine usage.

*[[File types]] - currently just a list of file format extensions.

*[[Database]] - database schema and other related information.
** [[Database migration]] - instructions for how to update your database when updating your toolset
** [[Database backup and restore]] - How to back up or restore the EUTS database
** [[Database sharing]] - How to share a database between two or more developers

*[[Console]] - a window for entering console commands. Caution, some of these are intended to work with an installed copy of the Dragon Age game and will crash the toolset when used in its current state.

*[[Release notes]]

<h2 style="margin:0; background: rgb(221, 206, 242); font-size:150%; font-weight:bold; border: 1px solid rgb(175, 163, 191); text-align:left; color:#000; padding:0.2em 0.4em;"> Third party tools </h2>

*[[Web Application]] - A sample web application that allows you to search and view scripts, search and view conversations, and translate strings. By Adam Miller.

|}
|}

Cutscene tutorial

2009-10-03T16:01:13Z

Codepoetzz: /* Viewports */

[[Cutscene]]s can be stand-alone cinematic sequences that are triggered by scripts in the course of the game, or they can be inserted into [[conversation]]s in place of the simplified cinematics that conversations can automatically generate.

Our example situation in this tutorial will serve as the beginning of a conversation between the player and two NPCs. The player has just arrived at the campsite where these two NPCs are staying. He walks up to the fire. One of the NPCs is happy to see the player and greets him, but the other is distrustful. The two share a brief exchange to establish this before the interactive part of the conversation begins.

== Creating a new cutscene ==

To create a brand new blank cutscene resource, create a new resource in the usual way:

[[Image:New resource.png]]

The result is opened in the cutscene editor.

[[Image:Cutscene new.png|thumb|center|600px]]

There are two basic sections to the cutscene editor; the viewports (top) and the timeline (bottom).

=== Viewports ===

{{sidebox|
* Viewports can be attached to various cameras to preview what they can see
* Add a "Safe Frame" to camera viewports to ensure the correct aspect ratio
* Set a viewport to "User" to see where cameras are positioned from another perspective
}}

The camera viewports in the cutscene editor work similarly to the viewports in the stage editor. You can set the number and layout of viewports under the "View" menu:

[[Image:Cutscene tutorial viewport layout.png]]

And for each individual viewport you can select which camera it's showing and set other display options by right-clicking on the title bar of the viewport:

[[Image:Cutscene tutorial viewport properties.png]]

When you set a viewport to show the view through one of the cutscene's cameras, it's a good idea to turn on that viewport's "Safe Frame" option as well. This will put a border on the viewport showing what will be visible when the cutscene plays.

Note that when you play the cutscene in the cutscene editor, only the currently selected viewport (the one with the blue title bar) will show the cutscene "live" - the others won't update the view displayed in them until they're selected. To preview the cutscene as the player would see it, then, you should set one of the viewports to "Active Camera" and ensure that this viewport is selected when you play the cutscene in the editor. If the "Active Camera" viewport turns gray, try setting the cutscene property "Enable Level Effects" to false.

=== Timeline ===

{{sidebox|
* There is always exactly one MASTER object in a cutscene.
* Each active object is listed on the timeline, with multiple "tracks" for each.
* All objects have position tracks (divided into X, Y and Z tracks). Some objects have additional built-in tracks.
* Other actions and effects can be added to generic tracks. Objects can have as many generic tracks as you want.
}}

Below the viewport is the timeline. Along the top of the timeline is a time scale; it can be set either to show frames (at 30 frames per second) or milliseconds by changing the "Time Scale" property if the cutscene in the object inspector. A marker indicates what point in the timeline the viewports are currently showing.

Below are a set of rows containing the various actors, cameras, and other objects active in the cutscene. This is where most of the editing is going to take place. Each object will have a number of "tracks", which will contain commands that are sent to the actors at particular times in the course of the cutscene.

[[Image:Cutscene tutorial timeline.png]]

The first object in the track list is the "MASTER" object. This is a special object that every cutscene has exactly one of. The MASTER object is the cutscene equivalent to the root node of a conversation tree, a repository for global settings and effects. For example the MASTER object contains the track that determines which camera is active at any given time. The MASTER object cannot be deleted. By default, a MASTER object appears in the cutscene editor as a small greenish sphere; you can change the MASTER object's appearance in the cutscene option settings.

A new cutscene also has a camera, called Camera 1. This camera can be deleted or renamed if you like; we can add new cameras as needed later on.

Every object has "Position" and "Orientation" tracks that control their locations in space. Cameras also have a FOV (field of view) track.

Objects can have other "generic" tracks added by the editor as needed. These generic tracks contain all the other commands and directions we can give.

== The setting of the cutscene ==

{{sidebox|
* The MASTER object should be moved somewhere near the center of your cutscene.
* You can optionally set a stage for your cutscene, enabling stage-related actions for objects.
}}

Establishing the setting of a cutscene is done in the object inspector in the group of properties labeled "Setting". The most important of these is the "Area" property, which allows you to set the cutscene in an existing [[area]]. We already have a suitable area that was created in an earlier tutorial; the area "great_outdoors".

By default the MASTER object and Camera 1 will be located at the coordinates 0,0,0 in the area. You'll want to move the camera to the appropriate location within the area using standard [[3D control]]s for movement and view management. The MASTER object is invisible when the cutscene is played in-game so it usually doesn't matter where you put it. However, there are some settings that depend on the MASTER object's location - for example, you can set level-of-detail for models so that the model's LOD varies depending on how close it is to the MASTER object - so it's probably a good idea to put MASTER somewhere near the middle of where you'll be having the cutscene's action take place.

You can also set a stage for the cutscene. This is optional, but setting a stage enables "Jump to Stage Place" and "Jump to Stage Camera" actions that could help make setting the cutscene up easier if you already have a good stage defined in the area.

=== Adding objects and creatures ===

{{sidebox|
* Objects already present in the area the cutscene is set in are inactive by default. You need to activate them to control them.
* Other objects can be added from the resource palette as normal.
}}

All of the objects that are normally present in the area (such as creatures and placeables) will be visible in the cutscene editor, but they'll all initially be marked as "inactive". This means that, although they'll be visible in the cutscene when it plays, they won't be controllable; they'll just do whatever ambient activities they would be doing normally. In the case of our campsite area there are two creatures that were placed here in the area editor; the happy camper, named camp_happy, and the angry camper, named camp_angry. We need to seize control of them to make them active participants in the cutscene's activities. To make them active, right-click on them and select "activate objects":

[[Image:Cutscene activate object.png]]

The object will then become an active object in the cutscene, getting its own entry in the timeline that will allow you to control its actions.

[[Image:Cutscene object activated.png]]

We'll activate both of these campers since they'll both be taking part in the cutscene's dialogue.

You can also add objects that aren't normally a part of the area. Simply open the object palette, select the creature or placeable you wish to use in the cutscene, and then click in the viewport to add the object to that location. It will automatically be made active and get an entry in the timeline. The player won't see these objects during regular play, since they're not a part of the area - they're only in the cutscene.

If you want to make an area object disappear during the cutscene you'll need to activate it (allowing you to control it) and then add a track with an action that makes it invisible in the first frame. It will go back to normal again when the cutscene ends and the game resumes, cutscenes are run entirely separate from the main action of the game and have no direct effects on it.

=== Adding the player ===

{{sidebox|
* Use the "Mapping Tag" property on an actor to make the game replace it with another object (such as PLAYER) at run-time.
}}

Normally we don't have to worry about placing the player in an area since the player controls his own movements and actions. But when we're doing a cutscene we can control the player just like any other actor, so we'll need a way to insert the player as an active object. Furthermore, since we'll have no idea what the player is going to look like at any given moment, we'll need to have a way to insert the player as he appears in the game when the cutscene begins.

This is done by inserting a "dummy" virtual actor and then setting the actor's "Mapping Tag" property to the special "PLAYER" tag.

[[Image:Cutscene dummy player.png|thumb|center|600px]]

It doesn't matter what the dummy actor looks like now, it will be replaced with the player's character later on, so we'll just use a default male human model to make it both simple and obvious.

There are ways to tweak the way the cutscene plays based on other characteristics of the player, for example by modifying the position of the camera to account for the player's height or by adding additional dummies to represent followers. We won't go into these more advanced topics in this tutorial.

=== Adding cameras ===

{{sidebox|
* Remember to enable Safe Frame when attaching a viewport to a camera.
* Use an "Active Camera" viewport to preview the cutscene.
* Use a "User" viewport to see camera positions from the outside.
}}

We could film a cutscene entirely from one camera if we liked, either as a single static shot or by moving the camera around to new positions as needed. It's easier and more convenient in most cases just to add several different cameras, however, and use the "Active Camera" track on the MASTER object to switch between them.

For our cutscene we're going to want three different cameras; one camera that's a wide shot showing the player arriving at the campfire, one camera focused on the angry camper, and one focused on the happy camper. We could add more than just these three to make the scene even more dynamic but for simplicity we'll stick to just those for now. We can add more later.

Cameras are added by right-clicking in the viewport and selecting "Insert → Camera".

[[Image:Cutscene insert camera.png]]

You can then position them using standard [[3D control]]s. To make it easier to get the camera set up with the correct view, a good technique is to set one of the viewports to display the camera's feed; you can then reorient and reposition the camera using that viewport's camera controls while getting immediate feedback as to what the camera will see in its new state.

We're also going to rename the three cameras at this point with names intended to remind us of what their purposes are. We'll name them "Arrival Camera", "Happy Camera", and "Angry Camera". We'll want "Arrival Camera" to be active initially, so we may as well use the original camera for this role; it's already set active by default. We'll see how to switch which camera is active later in this tutorial.

We now have all the basic props we need to get the cutscene going.

== Adding an animation to an actor ==

{{sidebox|
* Set the "Pose" property for actors to make them breathe and fidget naturally when not doing other animations.
* Other animations are set by adding "Play Animation" actions to a generic track.
* Animation filenames are often arcane and hard to find.
}}

If you play the cutscene now the first thing you'll probably notice is that the actors are all standing perfectly motionless. Normally someone who's standing still isn't really standing ''perfectly'' still; they breathe, they shift their weight from foot to foot, and so forth. Since almost every actor we use is going to need to do this we don't want to have to spend a lot of effort setting it up, and fortunately we don't have to. Every actor has a "Pose" property in the object inspector. Simply set this pose to "Standing Neutral" and the actors will display this default subtle movement whenever no other animations are being explicitly imposed on them.

[[Image:Cutscene set pose.png]]

Our next task is somewhat less trivial; we want to show the player walking up to the fire. We're going to have to add a walking animation to the player's actor that runs for a short period of time and then stops.

To do this we'll need to add a new track to the actor's timeline. Right-click on the actor's entry in the timeline and select "Add Track" from the resulting menu:

[[Image:Cutscene add track.png]]

The new track will be named "New Track" by default and will start out empty. Actors in cutscenes will sometimes have dozens of tracks directing their actions so we'll want to rename the track to something a little more informative. In this case we'll name it "Walk to fire". To have it actually cause the player's actor to walk to the fire we'll need to add a "[[Play animation]]" action to it. Right-click on the track and select "Add Action" to get the menu to select this.

[[Image:Cutscene add action.png]]

The action will be added starting at the point you're currently viewing in the timeline, so you may wish to move the timeline's time slider back to the beginning before adding this animation. You can reposition an action along the timeline simply by dragging it with the mouse.

Initially the action has no animation associated with it. To set the animation, select the action in the timeline and then in the Object Inspector go to the "Animation" property and click on the ellipsis ([[Image:ellipsis.png]]) button.

Unfortunately this is where things turn a bit arcane since the names of the various animation files are often very unclear and not all will appear in the default list. You may need to resort to trial and error to find one you like, but there are many hundreds of animations available in the game's resources so this could take some time. See [[animation list]] for a list of many of them.

In this case the animation we want, "mh.dg_f_5p" ("male human dialog forward five paces"), doesn't appear in the default list of animations available in the animation picker. You'll need to click the ellipsis button next to the "Custom Animation" field and find it in the complete list of all animation resources.

[[Image:Cutscene finding an animation.png]]

If you try playing the cutscene now you'll see that the player's actor will spend a little over five seconds walking and then come to a natural stop - about as long as we needed. But the actor will be animated in place, his legs taking steps but not actually moving him anywhere. This is where position keys and GAD comes in.

== Moving an actor ==

=== Position and orientation keys ===

{{sidebox|
* Objects be moved over time by setting "key frames" on their position and orientation tracks.
* Intermediate frames are interpolated between key frames.
* You can set the curve type between key frames with the "transition out" property for each key.
}}

Every object in a cutscene has a pre-defined "Position" track with three sub-tracks for its X, Y and Z coordinates. Most objects also have a pre-defined "Orientation" track with three subtracks for roll, pitch, and yaw. These tracks can be used to cause an object to move around within the area over the course of the cutscene.

Movement is handled by setting the position and orientation of objects at specific points in time, called key frames, and then interpolating intermediate positions and orientations. To set a key frame, right-click on the actor's entry in the timeline and select "key position". This will set a key for the current position and orientation at the current time in the timeline. You can set position and orientation keys separately if you like. Since this operation is so common there's a very convenient shortcut for it; "k" inserts a key for the currently selected object's position and orientation, "p" inserts a key for its position, and "o" inserts a key for its orientation. Alternately, select the object and click the key command in the toolbar: [[Image:IconKey.png]]

[[Image:Cutscene key selection.png]]

For our purposes right now all we'll need to do is set a key frame at the beginning of the timeline. Move the pointer to the beginning, select the player actor, and set a key. Small boxes will appear on the position and orientation tracks to mark the key frame.

[[Image:Cutscene key marker.png]]

These markers essentially mean "at this particular point in time, dummy_player will be in this particular place and facing in this particular direction."

To get an actor to move over time you could set two key frames - one at the beginning of the movement, with the actor in his starting position, and one at the end of the movement, with the actor at his end position. You can set how the cutscene engine interpolates between the two positions by setting the "Transition Out" property of the starting keyframe to either Bezier (a smooth curve), Linear (a straight line), or Step (a sudden jump from the starting position to the end position). See the [[curve editor]] page for more detail.

We're not going to actually do this in this case, however; we'll try it at a later point in this tutorial to move a camera around. For this particular actor it would be difficult to manually match the actor's walking action with his motion over the ground. If the animation and the movement don't match the actor's feet will "skate" unrealistically along the surface.

There's an easier way to match an animation such as this one with movement through the scene; a mechanism called GAD.

=== Using GAD ===

{{sidebox|
* GAD is a mechanism by which an animation applies a built-in displacement to the object it's animating.
* You need to set at least one key frame for an object to use GAD, even if you don't otherwise use key frames to move it.
}}

GAD is a displacement that is automatically added to the actor's current position as the animation plays. Each animation has its own GAD information built into it, custom-designed to make the actor move in a manner appropriate to its actions. If we enable it the actor will be moved forward as the animation plays.

Not all animations have GAD associated with them. For example, having an actor wave his hand wouldn't displace him, so there would be no GAD associated with that animation. We only need to worry about GAD in cases like this one where the animation should accompany movement.

To enable GAD select the animation action and set "Play Gad" to true in the object inspector. If no key frames have been defined for the actor the cutscene editor will pop up a warning at this point suggesting that we add position and orientation keys before we add GAD:

[[Image:Cutscene gad warning.png]]

It's important to set at least one set of keys for an object using GAD. The animation's GAD may seem to work correctly without it at first, but unexpected and unpredictable errors could occur later that will send the actor careening off into the distance.

Once we've set a key frame and have set the action's "Play Gad" option to true you'll see that the actor now moves forward as he walks. This is good, but since we started him off in the position he's meant to end in it results in the actor walking straight through the campfire. You'll need to move the actor back so that he starts farther away from the fire.

Note that if you've already set a keyframe as described in the previous section you'll need to re-set it for the actor's new location (or alternately set the "update keys" mode with the [[Image:IconUpdateKeys.png]] tool), otherwise the moment the animation starts the actor will instantly jump back to the place he was where you set the keyframe. Once you set a keyframe for an actor, moving the actor around in the cutscene editor doesn't really change its position unless you re-set the keyframe to the new position. Keyframes and the curves interpolating between them always take precedence.

{{sidebox|
* An animation's "Extend Gad Beyond Action" property makes Gad's displacement persist after the animation ends.
}}

The other GAD properties are set to the most appropriate defaults automatically when you select an animation but one particular property bears mention here in case you run into trouble with it later on; the "Extend Gad Beyond Action" property. In the case of this walking animation it defaults to true. That means that once the animation ends, the displacement that the actor has undergone as a result of it will remain in effect - he will stay in the final position he walked to. If this were set to false, once the animation ended all of the displacement the actor had gained as a result would be undone and he'd instantly jump back to where he started walking from again. If at some point in the future you find your actors doing this, this property is the first place to look for the answer.

There's one final detail we'll tweak here. The walking animation begins with the player starting from a standstill, which is not the impression we want to convey; the player has supposedly been walking for some time before the camera started rolling. We could set the animation to begin playing partway through by changing the animation action's "Start Offset" property, but since this is happening at the beginning of the cutscene's timeline an easier approach is to simply select the animation action and drag it so that it begins a half second before the cutscene does. The cutscene will only begin displaying at the 0 mark and anything that falls before this point in time will never be shown so the initial half second of the actor's walk animation will go unseen.

== Moving a camera ==

The scene now has some of the dynamic action we wanted, showing the player walking up to the campfire and stopping at its edge. But it's still a rather dull introduction and we can do better. Instead of a static camera shot we can set the camera so that it pans across the scene to follow the player's arrival.

Select the Arrival Camera and open up its track list. It has Position and Orientation tracks just like the other actors, and can have keyframes set just the same. With the time marker set to 0, move the Arrival Camera so that its view shows how you want the shot framed at the beginning of the cutscene. In our example we're going to set it so that it shows the player in the center of the frame. With the camera still selected, press "k" to set a key frame for the camera.

[[Image:Cutscene camera start position.png]]

(You may notice that the Field of View (FOV) track also gets a key marker. We won't be changing the camera's FOV so you can ignore that.)

Next move the timeline scrubber to the end of the walking animation at the 5 second mark. The player's actor will now be at the final position where he'll be standing for the conversation. Change the camera's orientation, panning to the right so that all of the actors can be seen in its field of view. In our case the camera's too close to encompass everyone so we'll also move its position to allow it to see them all.

Once you have the shot lined up correctly, press "k" to set a second keyframe.

[[Image:Cutscene camera end position.png]]

You may notice that the User viewports now show a red line tracing out the selected object's trajectory through space (if not, you may need to click the "show trajectories" [[Image:IconShowTrajectory.png]] button in the toolbar). As the first five seconds of the cutscene plays, the Arrival Camera should slide smoothly along the red line and rotate smoothly on its axes to transition from the first keyframe to the second keyframe (If it suddenly jumps from one position to the other instead you may need to click the "default curve mode" tool [[Image:IconDefaultCurveMode.png]] and try setting the keys again, or change the "transition out" property of the keyframe to Bezier).

You can fine-tune the trajectory of the camera by adding additional keyframes between the starting and ending ones. In our case we see that when the time marker is set to the middle of the camera's movement the player slips slightly out of frame.

[[Image:Cutscene camera middle position unadjusted.png]]

We can fix this by changing the camera's position and orientation as needed, and then adding a new keyframe with "k". In this case we'll pull the camera back slightly so that its motion through space becomes a curve instead of a straight line.

[[Image:Cutscene camera middle position adjusted.png]]

We now have a nice, dynamic establishing shot. The scene begins with the player alone and in the center of the camera's shot, and as he walks toward the fire the camera moves and pans around him to show him arriving in the presence of our two campers.

== Switching cameras ==

{{sidebox|
* A track on the MASTER object defines which camera is currently "active."
}}

Once the player arrives he is going to be greeted by the camper who is happy to see him. To give a clear shot of who's doing the talking, we'll want to switch the active camera from Arrival Camera to Happy Camera.

The track where the active camera gets changed is attached to the MASTER object. Move the timeline's time indicator to the point in time where you wish to switch active cameras, in this case 5.5 seconds (giving the scene a half-second view of the player after he's come to a halt). Right-click on the Active Camera track and select Add Action. The only option available for this track is the "Switch Camera" action so go ahead and add one. In the new Switch Camera action's properties set it to switch the active camera to Happy Camera.

Now when the cutscene is played we'll get an establishing shot showing the player walking up to the fire and then switch to a closeup of the happy camper so that he can deliver his greeting.

[[Image:Cutscene switch active camera.png]]

== Adding dialogue ==

{{sidebox|
* Lines of dialog can be inserted from an existing [[conversation]] resource. For convenience, create a new conversation to hold the dialog for a cutscene.
* Caption text, voice over, and facial performance are all included with each line.
* If you edit the conversation later, the changes will be reflected in the cutscene. Remember to generate new VO and FaceFX in the conversation editor.
}}

There are three major components to dialog in Dragon Age; the text of the line being spoken (which is displayed as a caption at the top of the screen), the voice-over for the line being spoken, and the facial performance that makes the virtual actor lip-synch and display appropriate emotions.

There's already got a tool in the toolset that is designed for handling all of these things; the conversation editor. Actors in a cutscene can be given "Speak Line" actions that cause them to deliver lines from an existing dialog, with all three components added together into the actor's performance automatically.

To create the dialog for this cutscene we'll now create a new conversation resource. This conversation is not going to be used in the game directly so we'll be able to ignore many of the more advanced features and settings covered in the conversation tutorial; its only purpose is to serve as a repository of dialog lines for use in this cutscene.

The following screenshot shows our intended conversation. The only things that we need to define for it is the text of the dialog and optionally the emotion settings for RoboBrad to use when generating facial performance. As with our previous conversation we'll generate synthesized placeholder voice-over and generate FaceFX based on that; when we record real voice over later on we can simply update this conversation with it and the cutscene's performance will change to match.

[[Image:Cutscene conversation.png]]

To help keep track of which lines are spoken by which actors you could also optionally set the speaker tag on each line to identify who's doing the talking. This particular conversation has only two speakers so we won't bother with that. The cutscene engine won't need speaker tags, we'll be explicitly telling it who is saying each line. You'll only need to set those things if you wish to preview the conversation before using its lines in the cutscene.

Once you've created your dialogue go back to the cutscene editor and add a new track to the camp_happy actor. Rename it to something informative, such as "Dialogue". Move the timeline marker to the spot where you want the actor to start speaking and add a new "Speak Line" action.

In the Speak Line action's properties, set the "Source Conversation" property to the conversation resource we just created. Then, select the specific line you want the actor to speak in the "Source Line" property (it will have a drop-down menu with all of the lines from the source conversation in it).

That's all you need to do to get the actors to talk. You may wish to add one other detail at this point; head tracking. This is the action that causes actors to turn their heads toward a specific target, usually the person they're talking to or who is talking to them. It's added as its own action, so create another track and add a headtracking action to it with the player as the target. In this case we want the happy camper to turn his head toward the player right before he starts speaking.

== Adding other details ==

{{sidebox|
* Headtracking actions make actors look at other objects in the cutscene.
* You can have more than one action on a track provided they don't overlap.
}}

We've now gone through all the basics, so we'll just finish fleshing out the conversation with a few other details that are done the same way as the examples above.

To add a little more animation to the scene, we add another track for camp_happy with an animation action (mh.dg_hnd_salute_01, a salute) to play during his spoken line. This animation is simpler to deal with than the walking animation because it doesn't displace the actor; there's no need to define position keys or worry about enabling GAD.

We'll set camp_angry's headlook so that she turns toward camp_happy while he's speaking; when we subsequently switch cameras to show her line of dialog she'll already be looking in his direction.

For camp_happy's next line, however, we'll make the headtracking change visible during his shot so the player will see how his attention has switched to camp_angry. Note that we can reuse the existing "Dialogue" and "Headtracking" tracks for this actor; we don't need to create a new track for every single action that an actor performs. So long as the durations of the actions on a track don't overlap they can coexist peacefully.

Finally, after camp_angry's last line we'll set her headtracking to look back toward the player. He's going to get the next word in when we integrate this cutscene into a conversation so this is a good way to indicate that the conversation's focus has gone to the player now.

Once we've finished crafting the cutscene we now know how long its duration needs to be. You can now go to the conversation's properties in the Object Inspector and set the cutscene's duration to the desired length.

The finished timeline of our cutscene:

[[Image:Cutscene finished timeline.png]]

[[Category:Tutorials]]
[[Category:Cutscenes]]