Dragon Age Toolset Wiki - User contributions [en]

Map tutorial

2009-11-28T05:05:56Z

Arixsus: Restructured my previous editions to the tutorial. moved creating a custom maps in photoshop tutorial section to the bottom, and created a tutorial on how to add them into worldmaps.xls

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

==Custom Maps==

=== Creating maps in photoshop to use in-game ===

Here are some tutorials that can be used to make yourself a map in photoshop.

[http://www.jezelf.co.uk/tutorials_map01.htm Basic Map tutorial] - required as it is the basic stepping stone to make any map [Difficulty = Basic]

[[File:Map01_thumb.jpg‎]]

[http://www.jezelf.co.uk/tutorials_map02.htm Paper style/aged Map tutorial ] Style #1 [Difficulty = Beginner]

[[File:Map02_thumb.jpg]]

[http://www.jezelf.co.uk/tutorials_map04.htm Colored 2D Map Tutorial ] Style #2 [Difficulty = Beginner/Intermediate]

[[File:Map04_thumb.jpg‎]]

[http://www.jezelf.co.uk/tutorials_map05.htm Pseudo 3D Map Tutorial ] Style #3 [Difficulty = Intermeditate/Advanced]

[[File:Map05_thumb.jpg‎]]

Be sure to save the map as a .tga so the 2da will read it

''
All map making tutorials above are done by Jeremy Elford and [http://www.jezelf.co.uk/index.html www.Jezelf.co.uk]''

'''Other Valuable Map Making Resources'''

[http://www.profantasy.com/ Cartographer 3 + Addons -$] Simple easy to use map maker for those who don't have photoshop or the skills/knowledge to work it.

[http://cartographersguild.com/ Cartographers Guild Map Making Community -Free] Great website if you are seeking other tutorials, inspiration, help, possibility of hiring someone to make you a map, and more!

[http://www.youtube.com/ZombieNirvana#p/u/18/KO4XZfaSAoA Youtube Tut series by ZombieNirvana -Free] Great Series of tutorials on youtube

=== Putting your map into the toolset ===

Now that we've created our own map, we need to find away for the game to see it. In the previous parts of this tutorial we covered .xls files that contain 2da data. For this part we are going to modify the 2da so that it will use our newly created map instead of the one that shipped with Dragon Age.

Step 1:

Browse to your Dragon Age folder > tools > Source > 2DA and find the worldmaps.xls

[[File:Step_1.jpg]]

Step 2:

Create a folder, somewhere on your hard drive, such as "C:\Dragon_Age\test_mod\" (do not allow any of the folders to have space)

[[File:Step_2_map.jpg]]

Step 3:

Go back to your window with the Dragon Age>Tools>source>2da and copy the worldmaps.xls to your newly created folder.

Step 4:

open up your copied over worldmaps.xls and it should be on the first tab. You will notice that there are multiple tabs on the bottom, which make up the 2da.

Step 5:

After you have opened up the .xls you will see

1 Wide Open World 396061 Worldmap target_wps_wow 1012 enc_trips_sp
[[File:Step_3_map.jpg]]

Step 6:

This step is rather simple, in Column D Row 4, you will notice that it says world map. This is the part of the .2da that point's to the image file. After you've taken a sec to get the feel of how it works, replace the "worldmap" txt with the name of the image file you are going to use, but leave out the file extension. As you can see in the image of step5 I have replaced "worldmap" with "Genalor_DA_BL_MAP" leaving out the .tga extension.

Step 7:

Download [http://combustiblestudios.comze.com/files/converter.rar Converter.rar] this .rar contains the convert.bat and excelprocessor.exe needed to convert your newly changed worldmaps.xls into a GDA for you to use in your mod.

Step 8:

Once downloaded extract it to your folder that you copied and edited your worldmaps.xls in. When it is finished copying over, right click the covert.bat and select edit. It should pop up a window using notepad.exe that should look like this.
[[File:Step 4 map.jpg]]

Step 9:

You will see in the opened Covert.bat that will say

<Pre>
C:\Combustable_Studios\Dragon_Age_Files\XLS\test_mod\ExcelProcessor.exe worldmaps.xls -outdir=C:\Combustable_Studios\Dragon_Age_Files\XLS\test_mod\convert\
</pre>

For this part you want to change
<pre>C:\Combustable_Studios\Dragon_Age_Files\XLS\test_mod\ExcelProcessor.exe</pre>

to

<pre>Your Directory where the stuff you need to convert is located\Excelprocessor.exe</pre>

and

<pre>-Outdir=C:\Combustable_Studios\Dragon_Age_Files\XLS\test_mod\convert\</pre>

to

<pre>-Outdir=Your Directory where the stuff you need to convert is located\convert\</pre>

After you have changed those batch to point to your folder and file save and close it. Once it is saved and has been close run it, if all goes well it should create a folder called convert and it will contain the following GDA's.

<pre>
Location_states.GDA
Map_pin_images.GDA
State_image_suffixes.GDA
target_wps_climax_denerim.GDA
target_wps_denerim.GDA
target_wps_fade.GDA
target_wps_underground.GDA
target_wps_wow.GDA
terrain_types.GDA
worldmaps.GDA
</pre>

step 10: Copy those files then navigate to your BioWare\Dragon Age\AddIns\mod_name\core\override and paste them into the folder. Then go get your .tga map you created in what ever program you used and place it into that folder to.

After step 10 you may jump back up to Creating a map and adding pins tutorial, and where your map will have replaced the original world map.

"Once you get a feel with what you are doing you may be able to do more, but I would not recommend such a thing for those who are new to this kinda stuff"--[[User:Arixsus|-Arixsus]] 05:05, 28 November 2009 (UTC)

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

Map tutorial

2009-11-28T05:01:41Z

Arixsus:

File:Step 4 map.jpg

2009-11-28T04:35:12Z

Arixsus: Step 4 of placing your map into worldmaps.xls

Step 4 of placing your map into worldmaps.xls

File:Step 3 map.jpg

2009-11-28T04:12:59Z

Arixsus: Step 2 of placing your map into worldmaps.xls

Step 2 of placing your map into worldmaps.xls

File:Step 2 map.jpg

2009-11-28T04:11:01Z

Arixsus: Step 2 of placing your map into worldmaps.xls

Step 2 of placing your map into worldmaps.xls

File:Step 1.jpg

2009-11-28T04:08:47Z

Arixsus: Step 1 of placing your map into worldmaps.xls

Step 1 of placing your map into worldmaps.xls

Map tutorial

2009-11-28T03:47:16Z

Arixsus: /* Creating maps in photoshop to use in-game */ _cleaning up

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 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 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 maps in photoshop to use in-game ==

Here are some tutorials that can be used to make yourself a map in photoshop.

[http://www.jezelf.co.uk/tutorials_map01.htm Basic Map tutorial] - required as it is the basic stepping stone to make any map [Difficulty = Basic]

[[File:Map01_thumb.jpg‎]]

[http://www.jezelf.co.uk/tutorials_map02.htm Paper style/aged Map tutorial ] Style #1 [Difficulty = Beginner]

[[File:Map02_thumb.jpg]]

[http://www.jezelf.co.uk/tutorials_map04.htm Colored 2D Map Tutorial ] Style #2 [Difficulty = Beginner/Intermediate]

[[File:Map04_thumb.jpg‎]]

[http://www.jezelf.co.uk/tutorials_map05.htm Pseudo 3D Map Tutorial ] Style #3 [Difficulty = Intermeditate/Advanced]

[[File:Map05_thumb.jpg‎]]

''
All map making tutorials above are done by Jeremy Elford and [http://www.jezelf.co.uk/index.html www.Jezelf.co.uk]''

'''Other Valuable Map Making Resources'''

[http://www.profantasy.com/ Cartographer 3 + Addons -$] Simple easy to use map maker for those who don't have photoshop or the skills/knowledge to work it.

[http://cartographersguild.com/ Cartographers Guild Map Making Community -Free] Great website if you are seeking other tutorials, inspiration, help, possibility of hiring someone to make you a map, and more!

[http://www.youtube.com/ZombieNirvana#p/u/18/KO4XZfaSAoA Youtube Tut series by ZombieNirvana -Free] Great Series of tutorials on youtube

== 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-11-28T03:46:43Z

Arixsus: /* Creating maps in photoshop to use in-game */

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 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 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 maps in photoshop to use in-game ==

----

Here are some tutorials that can be used to make yourself a map in photoshop.

[http://www.jezelf.co.uk/tutorials_map01.htm Basic Map tutorial] - required as it is the basic stepping stone to make any map [Difficulty = Basic]

[[File:Map01_thumb.jpg‎]]

[http://www.jezelf.co.uk/tutorials_map02.htm Paper style/aged Map tutorial ] Style #1 [Difficulty = Beginner]

[[File:Map02_thumb.jpg]]

[http://www.jezelf.co.uk/tutorials_map04.htm Colored 2D Map Tutorial ] Style #2 [Difficulty = Beginner/Intermediate]

[[File:Map04_thumb.jpg‎]]

[http://www.jezelf.co.uk/tutorials_map05.htm Pseudo 3D Map Tutorial ] Style #3 [Difficulty = Intermeditate/Advanced]

[[File:Map05_thumb.jpg‎]]

''
All map making tutorials above are done by Jeremy Elford and [http://www.jezelf.co.uk/index.html www.Jezelf.co.uk]''

'''Other Valuable Map Making Resources'''

[http://www.profantasy.com/ Cartographer 3 + Addons -$] Simple easy to use map maker for those who don't have photoshop or the skills/knowledge to work it.

[http://cartographersguild.com/ Cartographers Guild Map Making Community -Free] Great website if you are seeking other tutorials, inspiration, help, possibility of hiring someone to make you a map, and more!

[http://www.youtube.com/ZombieNirvana#p/u/18/KO4XZfaSAoA Youtube Tut series by ZombieNirvana -Free] Great Series of tutorials on youtube

== 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-11-28T03:44:50Z

Arixsus:

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 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 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 maps in photoshop to use in-game ==

----

Here are some tutorials that can be used to make yourself a map in photoshop.

[http://www.jezelf.co.uk/tutorials_map01.htm Basic Map tutorial] - required as it is the basic stepping stone to make any map [Difficulty = Basic]

[[File:Map01_thumb.jpg‎]]

[http://www.jezelf.co.uk/tutorials_map02.htm Paper style/aged Map tutorial ] Style #1 [Difficulty = Beginner]

[[File:Map02_thumb.jpg]]

[http://www.jezelf.co.uk/tutorials_map04.htm Colored 2D Map Tutorial ] Style #2 [Difficulty = Beginner/Intermediate]

[[File:Map04_thumb.jpg‎]]

[http://www.jezelf.co.uk/tutorials_map05.htm Pseudo 3D Map Tutorial ] Style #3 [Difficulty = Intermeditate/Advanced]

[[File:Map05_thumb.jpg‎]]

''
All map making tutorials above are done courtesy of Jeremy Elford and [http://www.jezelf.co.uk/index.html www.Jezelf.co.uk]''

'''Other Valuable Map Making Resources'''

[http://www.profantasy.com/ Cartographer 3 + Addons -$] Simple easy to use map maker for those who don't have photoshop or the skills/knowledge to work it.

[http://cartographersguild.com/ Cartographers Guild Map Making Community -Free] Great website if you are seeking other tutorials, inspiration, help, possibility of hiring someone to make you a map, and more!

[http://www.youtube.com/ZombieNirvana#p/u/18/KO4XZfaSAoA Youtube Tut series by ZombieNirvana -Free] Great Series of tutorials on youtube

== 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]]

Talk:Main Page

2009-11-27T08:43:25Z

Arixsus: Create a new single developers page within the wiki to properly list addon's underdevelopment, and the teams developing them? -Discussion

== Add a new topic by creating a new header like this one ==

And then write your comment below it. Sign your comment with four tildes, like so: <nowiki>~~~~</nowiki>. It is automatically substituted with your user name and a link to your user page.

:To respond to someone else's comment, use a colon at the beginning of your response to indent it.

::Two colons indent twice, and so forth.

== Can we add a link to the Level Editor tutorial to the list of tutorials on the main page? ==

I don't know how to do it myself, but it seems like the Level Editor tutorial belongs before the Area tutorial in that list on the main page.

== Tutorials ==
I moved the placeable tutorial to second on the list, because it doesn't work unless you already created a module in the area tutorial.
[[User:Proleric1|Proleric1]] 12:41, 25 October 2009 (UTC)

== Events ==
The list of events is actually here:
http://social.bioware.com/wiki/datoolset/index.php/Category:Event_types [[User:Proleric1|Proleric1]] 07:59, 15 October 2009 (UTC)

== NDA ==
I suspect that the NDA no longer applies to the Wiki, since the latter does not touch on the three topics that Chris Priestly asked us not to discuss in his e-mail of 13-Jul-2009.
[[User:Proleric1|Proleric1]] 09:42, 25 July 2009 (UTC)
:Surely no NDA applies now, as the wiki is in the public domain? [[User:Proleric1|Proleric1]] 07:47, 15 October 2009 (UTC)
::Probably not. I'll ask around to make sure, though. [[User:BryanDerksen|BryanDerksen]] 19:44, 15 October 2009 (UTC)
::I've been asked to ask you to hold off on talking about the wiki until next week, to help spread the "buzz" out a bit. Right now everyone's talking about character creator, we don't want to distract from that. The folks who busted their humps on CC need their due. [[User:BryanDerksen|BryanDerksen]] 15:07, 16 October 2009 (UTC)
::Heh. I see Sunjammer just posted about the wiki on the forum, directing people here. Oh well. :) [[User:BryanDerksen|BryanDerksen]] 15:41, 16 October 2009 (UTC)

== Toolset download location ==

Someone should probably post a link to the location of the toolset here and/or in the installation page, to go with the instructions. It's a bit slow on the various EA/Bioware servers right now to just search around for them, and there's no direct link on Google for the obvious searches yet.

Edit: That link would be:
[http://social.bioware.com/toolset.php#downloads]

According to a post by Scott Meadows,Senior Programmer in the forums, it is still not available for general download, as of 9:48pm PST. No ETA was given.

--[[User:RyanFenton|RyanFenton]] 20:45, 3 November 2009 (UTC)

:It is available now.
[[User:Rabidgerbal|Rabidgerbal]] 23:20, 6 November 2009 (UTC)

::Thanks, slipped my mind in the midst of all the troubleshooting. :) [[User:BryanDerksen|BryanDerksen]] 23:41, 6 November 2009 (UTC)

== Camp ==

How do I add stuff to the camp area? [[User:Apocalypsefu|Apocalypsefu]] 04:45, 11 November 2009 (UTC)

: [[How-tos#Insert_content_into_an_existing_area]] has a summary of how you can create an addin that adds new content to existing areas. [[User:BryanDerksen|BryanDerksen]] 01:42, 14 November 2009 (UTC)

==Ten Minute Tutorials==
I think we should create a category and or easily accessible launch page where people can contribute quick 10 minute tutorials on a variety of subjects [[User:Allan Smith|Allan Smith]] 01:54, 13 November 2009 (UTC)

==Help for the timid==
We should also put up something on the main page that helps timid editors know that it is okay to make new articles, and possibly give some guidance on naming conventions and how to get their articles included or linked from the main page (or really guidance on where they should be linked from [[User:Allan Smith|Allan Smith]] 01:54, 13 November 2009 (UTC)

:I'll come up with a page tomorrow, I should have some spare time then. :) [[User:BryanDerksen|BryanDerksen]] 01:43, 14 November 2009 (UTC)

==Added an Item Reskinning Tutorial==
See [[Tutorial: Reskinning an Item]]. Perhaps someone could add it to the list of tutorials on the main page, if appropriate?
[[User:Avantoreon|Avantoreon]] 00:38, 17 November 2009 (UTC)

== Google ==

The Wiki isn't accessible unless you have a Bioware social account; are there exceptions for Googlebot? I understand wanting to protect the contents but being searchable is a great way to be found. --[[User:Talonius|Talonius]] 04:30, 17 November 2009 (UTC)

== 2DA ID reservation page ==

Is there any way a page can be added to the wiki so that modders that use it can reserve ranges for their content? I would do it, but I feel that it needs to be accessible from the main page of the wiki so that its existence is well known. [[User:Ladydesire|Ladydesire]] 01:34, 19 November 2009 (UTC)

: I've just redone the main page to have a lot fewer links on it, which I think will actually help a new user find things more easily. I'm thinking that putting it on [[script]] would be better now, since that's the "portal" page that deals with things where row IDs are likely to come up. I'll put it there for now, anyway. Thoughts? [[User:BryanDerksen|BryanDerksen]] 22:46, 23 November 2009 (UTC)

:There, I've whipped up a stub page at [[2DA ranges in use]]. Is that the sort of thing you were thinking of? [[User:BryanDerksen|BryanDerksen]] 22:53, 23 November 2009 (UTC)

== Adding to main game ==

Is it possible to add "addin" content to the main game (Single Player)? I would like to add a new town to an existing forest in the main game without going through Other Campaign.

:Does [[How-tos#Insert_content_into_an_existing_area]] cover what you had in mind? [[User:BryanDerksen|BryanDerksen]] 22:58, 23 November 2009 (UTC)

== Custom Animations? ==

Is it possible to create custom animations with the toolset? As in, animate the characters any way you wish for cutscenes, like a werewolf thriller remake for example? I haven't taken a good look in the toolset quite yet, and only a brief look at the wiki, but it looks as though I would be limited to a set group of named pre-made animations. [[User:Interitus3841|Interitus3841]] 13:29, 23 November 2009 (UTC)

: The toolset doesn't have animation-creation tools in it, though the [[blend tree editor]] is used to combine existing animations. Currently there aren't any tools available that I know of for converting animations created with other tools such as Poser to the [[ANI]] format used by Dragon Age, but I'm sure eventually someone will come up with something. [[User:BryanDerksen|BryanDerksen]] 22:58, 23 November 2009 (UTC)

== Create a new single developers page within the wiki to properly list addon's underdevelopment, and the teams developing them? ==

Title basically sums it up. I feel like Social.Bioware.com itself isn't as organized as it should be, and its quiet hard to sift through. I figure if all us developers get together we could maintain a single page that would list addon's and the team doing them in a table sort of way, linking our social.bioware.com page, and our websites all in one little easy to use area.

Tutorials

2009-11-27T08:36:28Z

Arixsus: /* External Tutorials */

In the course of these tutorials we'll go through all the steps needed to create a basic adventure.

{{sidebox|
*Boxes like this contain a checklist of important steps.
*They're intended as a reminder and as a navigational aid.
}}

*[[Introductory tutorial]] - An overview of the toolset as a whole
*[[Module tutorial]] - how to create a module to work in.

This set of tutorials forms a series, each building on or filling in omissions by the last:
*[[Level Editor Tutorial]]
*[[Placeable tutorial]]
*[[Area tutorial]]
*[[Item tutorial]]
*[[Creature tutorial]]
*[[Conversation tutorial]]
*[[Scripting tutorial]]

Once you've become familiar with the basics introduced on those tutorials you might have a better grounding for:
*[[Cutscene tutorial]]
*[[Map tutorial]] (which also introduces you to [[2DA]] editing)

== Demo module ==

The toolset currently ships with a simple demo module pre-loaded into its database.

*[[Demo module]] - how to export and run the demo module.

== Other Tutorials ==
*[[Tutorial: Reskinning an Item]]
*[[Adding a Location to the Single Player Campaign Tutorial]]
*[[Backgrounds tutorial]]

== External Tutorials ==
*[http://dragonagemodding.wordpress.com Beyond Ferelden] has many in-depth tutorials by jwvanderbeck.

*[http://www.youtube.com/watch?v=TwQNRBFLhrE Playable Area and Conversation] video tutorial by [http://social.bioware.com/64020/ st4rdog].
*[http://www.youtube.com/watch?v=CaHldJcUTz8 Simple Conversation Cameras] video tutorial by [http://social.bioware.com/64020/ st4rdog].
*[http://www.youtube.com/watch?v=QOQJ2heQto4 Cutscene and Trigger] video tutorial by [http://social.bioware.com/64020/ st4rdog].
*[http://www.youtube.com/watch?v=szWKgj2ZuXo Custom Level and Room Building] video tutorial by [http://social.bioware.com/64020/ st4rdog].
*[http://www.youtube.com/watch?v=DKJ7F14n8o8 Downloading and Installing the Toolset] video tutorial by [http://social.bioware.com/74287/ DragonAge22].
*[http://www.youtube.com/watch?v=iMPBsulv9xI Creating a Room] video tutorial by [http://social.bioware.com/74287/ DragonAge22].
*[http://www.youtube.com/watch?v=g3kx2CaarHo How to Make an Interior Level with Lighting] video tutorial by [http://social.bioware.com/group/60/ Darkworld Development Team].
*[http://www.youtube.com/watch?v=O6TeZeE1Lc8 Making a Room] video tutorial by BigDrip681.
*[http://social.bioware.com/5339/blog/576/ Custom Player Items In Single Player] by [http://social.bioware.com/5339/ weriK].
*[http://social.bioware.com/5339/blog/651/ The Secret Behind Item Statistics] by [http://social.bioware.com/5339/ weriK].
*[http://social.bioware.com/project/923/ Guide for installing/uninstalling Mods] Beginner Guide to get started with using Mods by [http://social.bioware.com/237411/ Alexspeed].
*[http://www.jezelf.co.uk/tutorials.htm Photoshop Map making tutorials] Credits to Jason Elford, brought to DAT wiki by [http://social.bioware.com/48156/ Arixsus]

[[Category:Tutorials| ]]

Map tutorial

2009-11-27T08:32:57Z

Arixsus: Added photoshop map making tutorials, and resources to the map making tutorial section.

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 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 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 maps in photoshop to use in-game ===

----

Here are some tutorials that can be used to make yourself a map in photoshop.

[http://www.jezelf.co.uk/tutorials_map01.htm Basic Map tutorial] - required as it is the basic stepping stone to make any map [Difficulty = Basic]

[[File:Map01_thumb.jpg‎]]

[http://www.jezelf.co.uk/tutorials_map02.htm Paper style/aged Map tutorial ] Style #1 [Difficulty = Beginner]

[[File:Map02_thumb.jpg]]

[http://www.jezelf.co.uk/tutorials_map04.htm Colored 2D Map Tutorial ] Style #2 [Difficulty = Beginner/Intermediate]

[[File:Map04_thumb.jpg‎]]

[http://www.jezelf.co.uk/tutorials_map05.htm Pseudo 3D Map Tutorial ] Style #3 [Difficulty = Intermeditate/Advanced]

[[File:Map05_thumb.jpg‎]]

''
All map making tutorials above are done courtesy of Jeremy Elford and [http://www.jezelf.co.uk/index.html www.Jezelf.co.uk]''

'''Other Valuable Map Making Resources'''

[http://www.profantasy.com/ Cartographer 3 + Addons -$] Simple easy to use map maker for those who don't have photoshop or the skills/knowledge to work it.

[http://cartographersguild.com/ Cartographers Guild Map Making Community -Free] Great website if you are seeking other tutorials, inspiration, help, possibility of hiring someone to make you a map, and more!

[http://www.youtube.com/ZombieNirvana#p/u/18/KO4XZfaSAoA Youtube Tut series by ZombieNirvana -Free] Great Series of tutorials on youtube

== 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]]

File:Map05 thumb.jpg

2009-11-27T08:19:40Z

Arixsus: Map_05_thumbnail for map making tut

Map_05_thumbnail for map making tut

File:Map04 thumb.jpg

2009-11-27T08:17:24Z

Arixsus: Map_04_thumbnail for map making tut

Map_04_thumbnail for map making tut

File:Map02 thumb.jpg

2009-11-27T08:14:21Z

Arixsus: Map_02_thumbnail for map making tut

Map_02_thumbnail for map making tut

File:Map01 thumb.jpg

2009-11-27T08:13:23Z

Arixsus: Map_01_thumbnail for map making tut

Map_01_thumbnail for map making tut