Dragon Age Toolset Wiki - User contributions [en]

Talk:Follower tutorial

2011-07-21T18:08:38Z

Proleric1: /* Handling followers more robustly */

== Handling followers more robustly ==

Just a few things
* I don't think the described behaviour is a bug in [[UT_HireFollower]](). It's documented that "This function will do nothing for plot followers". It was never intended for use with normal followers, and the code even checks the object tag against the single player campaign's companions. It'll fail to check against your own module's custom followers, though, so it'll do something, but that something isn't always what you want either.

* Plot script gen00pt_party.nss and party_h have some plot-companion handling functions. I wouldn't really give it a short treatment at the bottom under "Advanced Follower Creation" if it's a solid approach. See things like Party_GetFollowerByTag in party_h with an interesting function and comment:
<dascript>
object Party_GetFollowerByTag(string sTag)
{
// We have to retrieve the follower like this. Trying to do it with
// GetObjectByTag proved to mess up lots of stuff. -- yaron.
object [] arParty = GetPartyPoolList();
int i;
int nSize = GetArraySize(arParty);
object oCurrent;
for(i = 0; i < nSize; i++)
{
oCurrent = arParty[i];
if(GetTag(oCurrent) == sTag)
return oCurrent;
}

return UT_GetNearestObjectByTag(GetMainControlled(), sTag, TRUE);
</dascript>

* It's probably worth going through those scripts and adapting them for general tutorial use. That way we can benefit from whatever gotchas have already been solved.

--[[User:FollowTheGourd|FollowTheGourd]] 17:52, 1 January 2011 (UTC)
-------------------
As the author of the "alternative approach" section, my own view is that this should effectively replace that whole section with the monstrous hire script, which really belongs in a how-I-did-it page rather than in a tutorial. However, I am currently up to my armpits in work on my own mod and just don't currently have the bandwidth to undertake the redraft. --[[User:Gaxkang55|Gaxkang55]] 04:10, 8 January 2011 (UTC)
-------------------
I have some sympathy with that. Indeed, I suspect that most of the additions could be integrated into one "best practice" approach. However, I hesitate to carve this up without some informed debate. I'll volunteer to redraft if a few people are willing to join a group discussion first. [[User:Proleric1|Proleric1]] 12:06, 8 January 2011 (UTC)
-------------------
Would be happy to be part of the discussion. Perhaps FollowTheGourd might join the party as well :-) --[[User:Gaxkang55|Gaxkang55]] 08:19, 10 January 2011 (UTC)
-------------------
Just to say I haven't forgotten about this. Too many distractions recently! Will launch the redraft discussion shortly. [[User:Proleric1|Proleric1]] 06:16, 7 February 2011 (UTC)
-------------------
I'm no longer in a position to redraft this. Perhaps someone else would like to have a go. [[User:Proleric1|Proleric1]] 18:08, 21 July 2011 (UTC)

== ==

great tutorial. my only problem is: my companion, Erik has different skills and doesn't seem to follow his autolevel template. --[[User:Mono0x32440|Mono0x32440]] 17:46, 25 February 2010 (UTC)

== Follower's Portrait ==

I cannot figure out how to change the default grey backgrounded portrait for the new followers. It would be nice to have pose and background options.

== Dog equipment slots ==

Mention should be made of the fact that a dog follower needs to have the appropriate equipment slot mask. I will make the addition to the text if no-one has any objections/suggestions in a couple of days. --[[User:Gaxkang55|Gaxkang55]] 09:38, 21 October 2010 (UTC)

I don't think that happened, so I've done it now. [[User:Proleric1|Proleric1]] 10:12, 2 January 2011 (UTC)

Follower tutorial

2011-07-12T06:52:00Z

Proleric1: /* What if there are more than three potential followers? */

== Simple Follower Creation ==

Follow these steps to create a follower that

- Levels up with a default package

- Can be chosen from the party picker

- Can gain XP

This guide assumes you know how to create a creature and are comfortable with basic scripting.

You should only use this simple method if you are sure there will be empty space in the active party when your follower is recruited.

A more comprehensive approach when there are more than three potential party members is discussed in the FAQ below. It's worth taking the time to understand the basics first, though.

=== Create the creature ===

Create a creature to act as your follower. Set its name, appearance, gender, head morph, conversation, inventory etc as you want them to behave in-game.

Set an appropriate '''Tag''' (you'll be using it a lot). I suggest "party_charname".

Make sure you choose a '''Class'''. For most followers this should be Rogue, Warrior or Wizard.

[[File:class.jpg]]

Under Package/Scaling set:

'''General Package Type''' to be '''Party Members'''

'''Package''' to be an appropriate value (probably "Generic - Wizard" or similar)

'''Package AI''' (there should only be one choice)

'''Rank''' to be '''Player'''

[[File:package.jpg]]

Save and export your character as normal.

=== Overlay char_stage ===

In the official campaign, the party picker uses a special area called char_stage. Whether you're extending the official campaign or making a standalone campaign, there is a function that allows you to overlap the offical stage with your own, so that both stages are active simultaneously in game.

In your resource palette, right-click char_stage under the Global folder and select Duplicate to make a copy of the stage with a new resource name, e.g. my_char_stage. In the resource properties, ensure that both Module and Owner Module are set to your module, and the folder of your choice.

[[File:area_palette.jpg]]

Create a new waypoint for your follower to appear on the party picker. This waypoint '''must''' have a tag in the form of "char_" followed by the exact tag of your follower.

[[File:char_stage.jpg]]

In this example the tag of my follower is '''bc_party_miera''' so her waypoint tag must be '''char_bc_party_miera'''

For a standalone module (such as in this example), put your waypoint wherever you please. The illustrated one is directly on top of Morrigan's. For an add-in to the main campaign, you should position your wp appropriately relative to the core party members.

Save and export the area.

Add the following to your module event script:
<dascript>
case EVENT_TYPE_MODULE_GETCHARSTAGE:
{
// Overlay the existing stage with my stage
// "my_char_stage" is the resource name of the overlay area
// "partypicker" is the name of the default GDA
SetPartyPickerStage("my_char_stage", "partypicker");
break;
}
</dascript>

=== Create m2DAs for the Party Picker ===

You will need to create two Excel spreadsheets.

The first should be named (both worksheet and file) '''partypicker_''' with a unique suffix. In this example, my first spreadsheet is named partypicker_fofbc.xls with a worksheet name of partypicker_fofbc - the suffix being the acronym of my module.

Set up your columns as follows:

[[File:partypickerm2da.jpg]]

The '''ID''' for your follower must be '''12 or higher'''. 11 is the highest value used in the base 2DA. 12 is fine for standalone modules, add-ins will probably want to use an arbitrarily high number to avoid potential conflicts.

The '''Label''' should be the follower's name as you wish it to appear on the party picker.

The '''Tag''' must be your follower's tag.

All other values are non-functioning defaults and should be specified as in the image above unless you know explicitly what you're doing.

'''NOTE - ON SELECTION ANIMATIONS'''

Add Animation and Remove Animation are actually Id numbers of different animations, taken from anim_base.gda

Enter and Exit version of animations are generally the best ones to use, altough one can try others. NOT ALL ANIMATIONS WILL WORK, since some require special conditions.
Here are some examples you can use:

819 - talk cursing

629 - reading a book (doesn't work, since it probably requires a book object)

844 - hands behind back (848 and 849 are Enter and Exit versions respectfully)

850 - chest pounding salute

811 - fist pounding

277 - dance

247 - cast area spell

500 - vfx cast

600 - surprised

603 - praying

607 - head bow

609 - standing at attention

651,652 - crouch pray (Enter and exit)

808 - point forward

825 - nodding

840 - hand chop or frustration

905,906 - crouch (Enter, Exit)

919,920 - sit on ground (enter, exit)

965 - kneel down loop

972 - wipe nose

976,977 - squat (Enter, Exit)

986 - wipe eyes

998,999 - hands clasped (Enter, exit)

3029 - inspect nails

3031,3032 - playful (enter, exit)

3054,3056 - slouch (enter, exit)
255 - in-place fly

'''NOTE - ON SELECTION VFX'''

The VFX column is the ID of the vFX effect taken from vFx_base.gda. This one is a bit more tricky, since it also references the BlendTree value from the same file.
Find the ID of the spell effect and look for the BlendTreeName column (should the the 12th columun) and enter BOTH into the respective columns for your character in the partypicker file.

Some examples:

ID --- BLENDTREENAME --- EFFECT

6039 --- fxm_energy_up_p --- Lady of the Forest pillar of light

6040 --- fxm_power_in_p --- Branka - power in

3054 --- fxc_lotf_c --- Lady of the Forest - swirling leaves

3009 --- fxc_succubus_c --- Succubus crust

1549 --- fxa_hly_imp_c --- Holy Impact crust

1076 --- fxa_spi_aur_mht_c --- Spirit - Aura Might crust

The second spreadsheet should be named '''party_picker_''' (note middle underscore). Once again append your unique suffix (in this example party_picker_fofbc.xls with party_picker_fofbc as its worksheet).

Set up your columns and data like so:

[[File:party_pickerm2da.jpg]]

'''ID''' and '''Tag''' should match what you did in the first spreadsheet. Specify INVALID COLUMN for the third column.

If you're familiar with m2DAs, generate them from these files, copy them to your module's override directory, and skip to the next step. Otherwise, read on:

- Go to '''\Program Files\Dragon Age\tools\ResourceBuild\Processors''' (or wherever you installed Dragon Age)

- Copy '''ExcelProcessor.exe''' from that folder to whichever folder has the excel sheets you just created.

- Drag and drop your xls files onto ExcelProcessor. This will create .gda files.

- Copy these .gda files to your module's export directory (probably \Documents\Bioware\Dragon Age\AddIns\yourModule\module\override\toolsetexport). Make sure they are included in your .dazip when the time comes to build your module.

If you are an OpenOffice user and have trouble with ExcelProcessor, you can use [http://social.bioware.com/project/755/ GDApp] to directly create the 2DAs. It rocks!

=== Capture the EVENT_TYPE_PARTYMEMBER_ADDED Event ===

Amusingly enough, the Party Picker does not actually add followers to the party. However it raises an event that allows you to do so. Your module script needs to capture this event and execute some code.

The following example shows what to do with the event. The full script would work as a module script for an add-in (assuming it didn't need to do anything else), but otherwise you'll have to incorporate the event into your own module script.

If you're not sure how to set a module script, go to '''File''' then '''Manage Modules,''' select your module and click '''Properties.'''

<dascript>
#include "utility_h"

void main()
{
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);
switch(nEventType)
{
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0); //Allows the follower to gain XP
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero()))); //Ensures follower appears at PC's location.
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE); //Adds follower to the active party
break;
}

}
}
</dascript>

'''SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE)''' is the key statement to add the follower to the active party. You must have this.

'''SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0)''' is a bug-fix, as followers hired with UT_HireFollower() do not receive XP by default. This statement fixes that, and I consider it best practice to keep it in this event to ensure it is always set. You will not wish to do this if you want a follower that should not gain XP to be on the party picker.

Note that you do not need to intercept the corresponding event for a party member being removed - the party picker handles spawning/despawning, and thus will successfully remove members.

Remember to save and export your module script.

If you're not sure how to set a module script, go to '''File''' then '''Manage Modules,''' select your module and click '''Properties.''' The module script is in the General category, as seen below:

[[File:module_script.jpg]]

You can set this to any script you've created. See [[Scripting tutorial]] and [[Character generation]] for more background and some simple examples of event-handling scripts. In general, you will want to make sure standalone module scripts pass events through to module_core (as in the [[Character generation]] examples) and add-in scripts do not (as in the example above).

=== Create Your Hiring Script ===

Now all that remains is to actually hire the follower :)

Create a script to handle the hiring (which will most likely be fired from a conversation). The script is quite simple:

<dascript>
#include "utility_h"

void main() {

object oFollower = GetObjectByTag("bc_party_miera"); //Use CreateObject() if the creature isn't present in the module yet

UT_HireFollower(oFollower); //Hires the follower

SetPartyPickerGUIStatus(2);

ShowPartyPickerGUI(); //Shows the Party Picker; necessary for the follower to gain XP

}
</dascript>

Make sure you use your own follower's tag and not the example one :)

This script fires the party picker after hiring the follower. That is absolutely necessary via this method, as we have put the XP fix onto an event fired by the party picker. You cannot put the XP fix into this script, it must be called from a later one (the bug is caused by an errant call to an event in player_core, which will be executed AFTER this script).

The easiest way to use this script is directly from conversation, putting it as an action on a line of dialogue where the PC invites the follower to join them. If you're not sure how to associate a script with a dialogue line, see the following image:

[[File:hire_conv.jpg]]

Create your dialogue as normal, select the line you want to fire the script, and click the '''Plots and Scripting''' tab. Use the '''Script''' file chooser in the Action section to browse to the script you created.

If everything worked, you should see something like this:

[[File:picker_success.jpg|thumb|200px|center]]

== Advanced Follower Creation ==

Follow these steps to have full control over the creation of your follower, with options such as:

- Unique level-up template

- Class and specialisation chosen via script

- Any starting state

- Level higher than the PC

- Starts with a specialisation point rather than a specific specialisation

- Set plot flags in the call to the hire script

=== Prepare Creature, char_stage and Party Picker m2DAs ===

Follow the same steps to create your follower creature, char_stage and Party Picker m2DAs as above.

=== Create Party Plot ===

While not necessary, it's very helpful to have plot flags set when a follower is hired or joins/leaves the active party. This makes conversation interjections and the like very easy.

Create a plot with appropriate flags. There's no real need to associate journal text with them:

[[File:follower_plot.jpg]]

See FAQ for an alternative approach to plots when there are more than three potential party members.

=== Add Plot Flags to Party Picker Event Intercept ===

We then update our module script to make use of that plot, like so:

<dascript>
#include "utility_h"
#include "wrappers_h"
#include "plt_bc_create_party" //make sure you include your own plot, not mine

void main()
{
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);
switch(nEventType)
{
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0);
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE);

AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero()))); //Ensures follower appears at PC's location.

if (GetTag(oFollower) == "bc_party_miera") { //You must explicitly test for your follower's tag.
WR_SetPlotFlag(PLT_BC_CREATE_PARTY, PARTY_MIERA_IN_PARTY, TRUE); //Make sure you use your own flags!
}

break;
}

case EVENT_TYPE_PARTYMEMBER_DROPPED:
{
object oFollower = GetEventObject(ev, 0);

if (GetTag(oFollower) == "bc_party_miera") {
WR_SetPlotFlag(PLT_BC_CREATE_PARTY, PARTY_MIERA_IN_PARTY, FALSE); //As above, but set false.
}

}

}
}
</dascript>

=== Create a Level Up Template ===

You can skip this step if you're content to use one of the generic Rogue, Wizard or Warrior templates, but I don't recommend it. Making a template that suits your character is easy and will almost always be better for the player than a generic one that spends points poorly.

Go to \Program Files\Dragon Age\tools\Source\2DA (or wherever you installed Dragon Age).

You should see a number of excel sheets of the form '''ALCharacter.xls''' (such as ALAlistair.xls, ALLeliana.xls, ALRogue_Default.xls etc). Open the one closest to your character (ie Morrigan or Wynne for a wizard, Leliana or Zevran for a rogue). Save a copy as '''ALYourcharacter.xls''' in whatever directory you're using to create your 2DAs, remembering to rename the worksheet '''ALYourcharacter''' (in this example, ALMiera.xls with ALMiera as its worksheet).

It should look something like this:

[[File:ALtable.jpg|thumb|500px|center]]

'''Columns B''' and '''C''' are the talents/spells available to this character. Do not change them.

'''Columns F''' and '''G''' are the skills available to this character. Do not change them.

We will edit the remaining columns like so:

==== Setting Stat Weights ====

The stat weights in '''column J''' determine how the follower will spend their attribute points, in a rough ratio. So if Dexterity is set to 1.5 and Intelligence to 1, you should expect to see 3 points of Dex for every 2 points of Cunning in-game (note Intelligence is the label used in the toolset for Cunning).

Simply change the values in J to reflect how you'd like the character to spend their points. In this example we're creating a wizard, so we're not going to mess around:

[[File:miera_stat_weights.jpg]]

This character will only raise magic. I set the value to 5 rather than something like 1 to provide room underneath for the other stats while still overwhelmingly favouring magic, but in practice I only really ever want that one stat.

In a note left on this column in the existing templates, Bioware's Georg Zoeller writes, "This is the weight of each attribute (row id links into properties.xls.id). 1.0 means 'try to keep this attribute level' (spend 1 point per level). 0.5 means 'try to spend 1 point every two levels' and so on."

The default Mage, Rogue and Warrior templates include '''column L''' labeled "AttInit." Editing these values seems to have no effect on followers set to use these templates.

==== Setting Talent and Skill Priorities ====

'''Columns D''' and '''E''' are the talents/spells that the character will buy, in preference order from top to bottom.

'''Columns H''' and '''I''' are the skills that the character will buy, in preference order from top to bottom.

To change these, just copy the appropriate two cells from columns B&C or F&G over the ones you want to replace.

For example, here we're copying Morrigan's template. Morrigan has Spider Shape high in her preferences, which we do not want.

[[File:AlMori_talent_pref.jpg]]

We decide we'd prefer Flame Blast, so we find it in columns B&C and copy both cells:

[[File:ALMori_copy.jpg]]

Then we select the cells we want to replace in columns D&E and paste over them:

[[File:ALMori_paste.jpg]]

Continue this process until your priorities list for both skills and talents/spells is exactly as you want it. Make sure you have at least as many priorities as the core follower you're copying - points that cannot be spent according to these priorities have a habit of vanishing.

If you used any abilities from a specialisation, make sure you remember to set that specialisation with the function we'll introduce later. The autolevel scripts will add specialisation abilities to a character regardless of whether they have that spec or not.

==== Create a M2DA_base_ m2DA ====

Dragon Age will need to know where to find your autolevel template. We tell it by extending M2DA_base.gda

Create a spreadsheet with the name and worksheet name in the form '''M2DA_base_''' with your unique suffix (in this example, M2DA_base_fofbc.xls with M2DA_base_fofbc as a worksheet).

Set up its columns and data like so (note I used GDApp because Open Office wasn't cooperating for this one!):

[[File:m2da_base_fofbc.jpg]]

The '''ID''' should be very high to avoid conflicts. I've arbitrarily chosen 50,000+ here. Carefully note the ID you've chosen for your character, you will need it later.

Set the '''Label''' and '''Worksheet''' to be the name of your autolevel template worksheet (ALCharactername if you've been following this).

Set the '''PackageIDForAI''' to be 0, it shouldn't be needed for followers.

When you're done, use ExcelProcessor to make GDAs of both spreadsheets and copy them to your module's export folder.

FOR AUTOLEVEL TO WORK AFTER RECRUITING:

Look in packages.xls.
There is a column called LevelupTable. That links to a corresponding AL* table. For instance, row 81 is for Leliana. Her LevelupTable value is 258. If you look that up in 2DA_base, you'll see it links to ALLeliana.
(alternatively, you could try packages_base.gda)

=== Create a New Hire Function Include ===

This section is probably only relevent if you have a specific need to override the functionality of player_core.

Many vital steps of follower addition happen inside an event in player_core. Followers tend to be extremely buggy (no skill tree, for example) if this event does not fire.

However, that event is not very flexible. In order to control it to our requirements, we need to replicate its functionality inside our own script. This is probably much safer than messing with player_core directly!

Create a new script file, naming it something like '''hireCustomFollower_h'''. We will be including this wherever we want to hire a follower.

Paste in the following script:

<dascript>
#include "sys_chargen_h"
#include "wrappers_h"
#include "utility_h"
#include "sys_rewards_h"
#include "approval_h"
#include "sys_autolevelup_h"

/* Jye Nicolson 5-Jan-2010
This function set duplicates the full functionality chain of UT_HireFollower, with the following exceptions:

- Followers can gain XP
- Autolevel status can be set (default off)
- Followers can be set to any starting state (default Available) and will still be properly initalised and added to the party pool
- Autolevel tables for non-core followers can be explicitly set.
- Class and Specialisation can be chosen via script
- Followers without specialisations are granted a spec point by default.

It should only ever be called once each for characters you intend to be full followers.
Much of the protective code handling summoned creatures etc. in player_core is not present here.

Calling the function:

Simple:

hireCustomFollower(oFollower, CLASS_WARRIOR);

Change the class to CLASS_WIZARD or CLASS_ROGUE as appropriate.
This will hire your follower and make them available.
They will auto level up with a default package, and receive a free spec point.

Best Practice:

hireCustomFollower(oFollower, CLASS_WARRIOR, PLT_YOUR_PARTY_PLOT, YOUR_FOLLOWER_JOINED_FLAG, ABILITY_TALENT_HIDDEN_CHAMPION);

Where the plot and flag are those for your module (remember to create the plot and include it on the calling script), and ABILITY_TALENT_HIDDEN etc is the desired spec.

You should also have a custom ALTable set up.
See wiki for details, and remember to edit it in to GetCustomFollowerALTable below or pass it directly as an argument to hireCustomFollower.

Full argument list:

void hireCustomFollower (
object oFollower, //Pass your follower object, mandatory

int nForceClass, //Pass a Class constant here, usually CLASS_ROGUE, CLASS_WARRIOR, CLASS_WIZARD. Mandatory due to a bug.

string sPlot = "", //It's recommended you have a plot flag to be set when the follower joins. Pass the plot constant here. Remember to #include in calling script

int nPlotFlag = "", //And then pass the flag constant. Will be set to TRUE if available.

int nForceSpec = 0, //This is the ID of the Specialisation you want. Note they are NOT classes, but abilities. The full list is:
//ABILITY_SPELL_HIDDEN_ARCANE_WARRIOR, ABILITY_SPELL_HIDDEN_BLOODMAGE, ABILITY_SPELL_HIDDEN_SHAPESHIFTER, ABILITY_SPELL_HIDDEN_SPIRIT_HEALER
//ABILITY_SPELL_HIDDEN_BARD, ABILITY_TALENT_HIDDEN_ASSASSIN, ABILITY_TALENT_HIDDEN_DUELIST, ABILITY_TALENT_HIDDEN_RANGER
//ABILITY_TALENT_HIDDEN_BERSERKER, ABILITY_TALENT_HIDDEN_CHAMPION, ABILITY_TALENT_HIDDEN_REAVER, ABILITY_TALENT_HIDDEN_TEMPLAR
//I recommended forcing a spec, particularly if your ALTable includes abilities from one.

int nALTable = 0, //This is the ID of an ALTable from 2DA_base.GDA or your module's m2DA_base_*.GDA I recommended the latter, but you can edit that into GetCustomFollowerALTable below rather than passing it.

int bInvokePicker = FALSE, //Sets whether the party picker should be opened on hiring. I think it's cleaner to call the picker outside this script, particularly if you have multiple hires at once.

int nInitialState = FOLLOWER_STATE_AVAILABLE, //This sets whether the follower joins the active party or not. Options are:
//FOLLOWER_STATE_ACTIVE (put them in the active party)
//FOLLOWER_STATE_LOCKEDACTIVE (force them into the active party and keep them there, remember to change this later.
//FOLLOWER_STATE_AVAILABLE (make them available on the party picker (if you've set it up for them), but not in the active party)
//Plus some others you're unlikely to need at this time. Defaults to AVAILABLE because having 4+ active followers is screwy.

string sCurrPlot = "", //If you set FOLLOWER_STATE_ACTIVE or FOLLOWER_STATE_LOCKEDACTIVE, the script will check to see if you passed this.
//It is recommended that you have a plot flag set for a given follower being in the active party, this makes conversation interjection etc. much easier.

int nCurrPlotFlag = 0, //This flag will be set if FOLLOWER_STATE_ACTIVE or FOLLOWER_STATE_LOCKEDACTIVE are true
//AND sCurrPlot has a value AND nCurrPlotFlag is > 0.
//ie if you added someone to the active party and have a plot flag to cope with it.

int nAutolevel = 0, //Sets the Autolevel flag on the character sheet. 0 is off, 1 is on, 2 forces it on and removes it so the player can't turn it off.

bFreeSpecPoint = TRUE, //This grants a specialisation point to the follower if they do not have a specialisation.
//It's important to set this false for classes that do not have specs, such as CLASS_DOG.

int nTargetLevel = 0, //If you want a specific level, set this. Generally not worthwhile unless you set it higher than the player, since they'll just get XP from the party picker anyway.

int nMinLevel = 0 //Set this if there's a specific level you don't want the follower to go below. Probably only useful if the PC might be very low level but not necessarily so.

)
*/
/* GetCustomFollowerALTable()
This function is where you put your custom table assignments.

You should explicitly test for the tag of your follower (not mine!) and assign a value to nTable from your m2DA extension to M2DA_base

See wiki for details on how to do this, or ignore it to get the default Warrior/Rogue/Wizard AL tables.

NOTE: you MUST explicitly set a table for non-Warrior/Rogue/Wizards, eg dogs. Use TABLE_AL_DOG for a default Mabari.
*/

int GetCustomFollowerALTable(object oFollower) {
int nTable = _GetTableToUseForAL(oFollower);

if (GetTag(oFollower) == "bc_party_miera") {
nTable = 50143;
}

if (GetTag(oFollower) == "bc_party_jysavin") {
nTable = 50144;
}

if (GetTag(oFollower) == "bc_party_geldual") {
nTable = 50145;
}

if (GetTag(oFollower) == "bc_party_braghon") {
nTable = 50146;
}

return nTable;
}

// This just cleans up the main function a little

int GetCustomFollowerTargetLevel(object oFollower, object oHero, int nPackage, int nMinLevel = 0) {
int nPlayerLevel = GetLevel(oHero);
int nTargetLevel = 0;

if((nPlayerLevel >= 13) || (nPlayerLevel == 1) || (!_UT_GetIsPlotFollower(oFollower))) {
nTargetLevel = nPlayerLevel;
} else {
nTargetLevel = nPlayerLevel + 1;
}

if (nMinLevel == 0) { //If nMinLevel is not specified, checks package 2DA for a value
nMinLevel = GetM2DAInt(TABLE_PACKAGES, "MinLevel", nPackage);
}
if(nMinLevel > 0 && nMinLevel > nTargetLevel) {
nTargetLevel = nMinLevel;
}

return nTargetLevel;

}

// Moving this black box out :) I don't really understand it, but it should function if you have tactics set up in a package.

void InitCustomFollowerTactics(object oFollower, int nPackage) {
int nTableID = GetM2DAInt(TABLE_PACKAGES, "FollowerTacticsTable", nPackage);
if (nTableID != -1)
{
int nRows = GetM2DARows(nTableID);
int nMaxTactics = GetNumTactics(oFollower);

int nTacticsEntry = 1;
int i;
for (i = 1; i <= nRows && nTacticsEntry <= nMaxTactics; ++i)
{
int bAddEntry = FALSE;
int nTargetType = GetM2DAInt(nTableID, "TargetType", i);
int nCondition = GetM2DAInt(nTableID, "Condition", i);
int nCommandType = GetM2DAInt(nTableID, "Command", i);
int nCommandParam = GetM2DAInt(nTableID, "SubCommand", i);

int nUseType = GetM2DAInt(TABLE_COMMAND_TYPES, "UseType", nCommandType);
if (nUseType == 0)
{
bAddEntry = TRUE;
}
else
{
bAddEntry = HasAbility(oFollower, nCommandParam);
}

if (bAddEntry)
{
SetTacticEntry(oFollower, nTacticsEntry, TRUE, nTargetType, nCondition, nCommandType, nCommandParam);
++nTacticsEntry;
}
}
}
}

/* InitCustomFollowerSpec:

This function tries to set the forced Specialisation. If there is none, it checks the package for one.

If there isn't either of those, it grants a free spec point if bFreeSpecPoint is true.

*/

void InitCustomFollowerSpec(object oFollower, int nPackage, int nForceSpec, int bFreeSpecPoint) {
// Find specialization, and optionally add a spec point if none is found.

if (nForceSpec == 0) {

int nSpecAbility = GetM2DAInt(TABLE_PACKAGES, "switch1_class", nPackage); // followers can have only 1 advanced class
if(nSpecAbility > 0)
{
AddAbility(oFollower, nSpecAbility);
} else {
if (bFreeSpecPoint) {
SetCreatureProperty(oFollower, 38, 1.00);
}
}

} else {

AddAbility(oFollower, nForceSpec);

}
}

/* hireCustomFollower() (See doco at top of page)

I strongly suggest you reorder the parameters if you're adding many followers with advanced options.

Feel free to leave them alone if you only want to set class, plot, spec or don't mind long declarations.

Note nForceClass is currently compulsory due to flakiness with GetCreatureCoreClass()
*/

void hireCustomFollower(object oFollower, int nForceClass, string sPlot = "", int nPlotFlag = 0, int nForceSpec = 0,
int nALTable = 0, int bInvokePicker = FALSE, int nInitialState = FOLLOWER_STATE_AVAILABLE, string sCurrPlot = "",
int nCurrPlotFlag = 0, int nAutolevel = 0, int bFreeSpecPoint = TRUE, int nTargetLevel = 0, int nMinLevel = 0)
{

object oHero = GetHero();

/* ################# BEGIN BASIC FOLLOWER JOIN BLOCK ###################

This loosely replicates WR_SetFollowerState.

*/

if (nForceClass == 0) {
nForceClass = GetCreatureCoreClass(oFollower); //This is not working. Hence nForceClass mandatory.
}

SetGroupId(oFollower, GetGroupId(oHero)); //Puts the follower in the pc's Group.
SetEventScript(oFollower, RESOURCE_SCRIPT_PLAYER_CORE); //This makes them act like a player.
SetFollowerState(oFollower, nInitialState); //This sets whether they are available, in the active party etc.

/* ################# END BASIC FOLLOWER JOIN BLOCK ##################### */

/* ################# BEGIN PLAYER_CORE EVENT_TYPE_PARTY_MEMBER_HIRED EMULATION #################
This replicates the EVENT_TYPE_PARTY_MEMBER_HIRED handler from player_core, stripped down for simplicity and allowing our custom options.

*/

Chargen_EnableTacticsPresets(oFollower); //I assume this is important.

SetLocalInt(oFollower, FOLLOWER_SCALED, 1); //This should prevent the follower being rescaled by player_core or what have you

int nPackage = GetPackage(oFollower); //Gets the package, which will be used to find a number of 2DA IDs.
int nPackageClass = GetM2DAInt(TABLE_PACKAGES, "StartingClass", nPackage); //I don't think this is used, even by player_core

// set behavior according to package
int nBehavior = GetM2DAInt(TABLE_PACKAGES, "FollowerBehavior", nPackage);

if(nBehavior >= 0) {
SetAIBehavior(oFollower, nBehavior);
}

Chargen_InitializeCharacter(oFollower); //We initialise the follower and choose race/class.

Chargen_SelectRace(oFollower,GetCreatureRacialType(oFollower));
Chargen_SelectCoreClass(oFollower,nForceClass);

if (nTargetLevel == 0) { //This block picks a target level if not specified

nTargetLevel = GetCustomFollowerTargetLevel(oFollower, oHero, nPackage, nMinLevel);
}

int nXp = RW_GetXPNeededForLevel(Max(nTargetLevel, 1)); //Here is where the XP is calculated and rewarded
RewardXP(oFollower, nXp, FALSE, FALSE);

// -------------------------------------------------------------
// add hidden approval talents - (JN: I don't know how to set these yet, but when I figure it out this should make it work)
// -------------------------------------------------------------
int nIndex = Approval_GetFollowerIndex(oFollower);
Approval_AddFollowerBonusAbility(nIndex, 0);

//Handle Specialisation
InitCustomFollowerSpec(oFollower, nPackage, nForceSpec, bFreeSpecPoint);

// -------------------------------------------------------------
// This spends all available attribute and stat points on the
// creature according to the levelup table. (JN: this replicates AL_DoAutoLevelUp but with our choice of table)
// -------------------------------------------------------------

if (nALTable == 0) {
nALTable = GetCustomFollowerALTable(oFollower);
}

AL_SpendAttributePoints(oFollower, nALTable, FALSE);
AL_SpendSkillPoints(oFollower, nALTable, TRUE);
AL_SpendSpecializationPoints(oFollower, nALTable);
AL_SpendTalentSpellPoints(oFollower, nALTable, TRUE);

// -------------------------------------------------------------------------
// Update various UIs
// -------------------------------------------------------------------------
Chargen_SetNumTactics(oFollower);
SetCanLevelUp(oFollower,Chargen_HasPointsToSpend(oFollower));

// load tactics
InitCustomFollowerTactics(oFollower, nPackage);

/* ################# END PLAYER_CORE EVENT_TYPE_PARTY_MEMBER_HIRED EMULATION ################# */

SetAutoLevelUp(oFollower, nAutolevel); //This is the autolevel flag on the character sheet.

//Set plot flags

if (!((sPlot == "") || (nPlotFlag == 0))) { //Joined Party
WR_SetPlotFlag(sPlot, nPlotFlag, TRUE);
}

if ((nInitialState == FOLLOWER_STATE_ACTIVE) || (nInitialState == FOLLOWER_STATE_LOCKEDACTIVE)) {
if (!((sCurrPlot == "") || (nCurrPlotFlag == 0))) {
WR_SetPlotFlag(sCurrPlot, nCurrPlotFlag, TRUE); //Currently in Party
}
}

// Invoke picker if requested.

if (bInvokePicker) {
SetPartyPickerGUIStatus(2);
ShowPartyPickerGUI();
}
}
</dascript>

Yeah, I know. It can't really be any smaller. Feel free to modify it if you're confident with scripting.
==== Add Your Custom Autolevel Template to GetCustomFollowerALTable() ====
While you can pass the ID you made for your autolevel template to that monster function as an argument, it's better to have them all in one place if you have multiple followers.

GetCustomFollowerALTable() is the first function in our include, and you can add an explicit if test for your follower there to assign the correct table id (the one from your M2DA_base_ m2DA). There is a function very much like it in sys_autolevel_h.nss for the core followers, so we'll copy Bioware's practice.

Let's take a look at the function by itself:

<dascript>
int GetCustomFollowerALTable(object oFollower) {
int nTable = _GetTableToUseForAL(oFollower);

if (GetTag(oFollower) == "bc_party_miera") {
nTable = 50143;
}

if (GetTag(oFollower) == "bc_party_jysavin") {
nTable = 50144;
}

if (GetTag(oFollower) == "bc_party_geldual") {
nTable = 50145;
}

if (GetTag(oFollower) == "bc_party_braghon") {
nTable = 50146;
}

return nTable;

}
</dascript>

So we have a test for each follower tag from my module, matching up to an ID which is assigned to nTable. All you need to do is change a tag from my follower to yours, and my ID to the correct one from your M2DA_base_* m2DA. Then you should delete the rest of the example if statements :)

Save and export the script. Ignore the compiler error about lack of main();

=== Include Function In Your Hire Script and Call It ===

So instead of a hire script that calls UT_HireFollower(), we want one that includes our shiny new function and calls it.

Take a look at the following example:

<dascript>
#include "plt_bc_create_party" //Make sure you include your party handling plot
#include "hireCustomFollower_h" // And include the function script - which will in turn include a bunch of stuff

void main() {

//Initialising my objects, not super-relevant to the example

object oHero = GetHero();
object oMiera = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_miera.utc", GetLocation(oHero));
object oJysavin = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_jysavin.utc", GetLocation(oHero));
object oBraghon = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_braghon.utc", GetLocation(oHero));
object oSpider = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_geldual.utc", GetLocation(oHero));

//Simplest hire call - adds to the party as a wizard. Class is currently compulsory due to a bug.
hireCustomFollower(oMiera, CLASS_WIZARD);

//Add to the party and set joining plot flags
hireCustomFollower(oJysavin, CLASS_WARRIOR, PLT_BC_CREATE_PARTY, PARTY_JYSAVIN_JOINED);

//Add to the party, set plot flags, force a specialisation
hireCustomFollower(oBraghon, CLASS_ROGUE, PLT_BC_CREATE_PARTY, PARTY_BRAGHON_JOINED, ABILITY_TALENT_HIDDEN_ASSASSIN);

//More complex example - Follower added as a unique class (Dog), not granted a specialisation or spec point.
//Note unique classes must have an ALTable passed here or specified in GetCustomFollowerALTable() or they won't work
hireCustomFollower(oSpider, CLASS_DOG, PLT_BC_CREATE_PARTY, PARTY_GELDUAL_JOINED, 0, 0, FALSE, FOLLOWER_STATE_AVAILABLE, "", 0, 0, FALSE);

//Show the party picker to let the player choose from their new companions!
SetPartyPickerGUIStatus(2);
ShowPartyPickerGUI();
}
</dascript>

The example shows several of the more simple ways of invoking the function. Check the comments at the start of the function for a full list of arguments.

I would suggest best practice for most followers would be to call as follows:

'''hireCustomFollower(oFollower, CLASS, PLOT, PLOT_FLAG, SPECIALISATION)'''

This will safely set the follower up as the desired class and specialisation (doubly important if there are spec abilities in their ALTable) while setting your plot flag for them being in the party. hireCustomFollower(oFollower, CLASS, PLOT, PLOT_FLAG, SPECIALISATION, 0, TRUE) will do the same while invoking the Party Picker automatically.

Note that the specialisations are abilities and not classes - you'll find them as ABILITY_HIDDEN_ constants.

If it's all worked, you should find you can now add followers with a lot more flexibility!

[[File:picker_advanced.jpg|thumb|500px|center]]

== Common Follower Problems & FAQ ==

====Why don't my followers gain XP?====
There is a bug in UT_HireFollower. Make a copy of UT_HireFollower in a function of your own, then make the following change:
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, TRUE);
to
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, bPreventLevelup);

====When I choose followers from the Party Picker, they spawn into the area but do not join.====

You need to intercept the EVENT_TYPE_PARTYMEMBER_ADDED event and set the follower to FOLLOWER_STATE_ACTIVE. See Simple Follower Creation earlier in this document.

====My followers don't have skill trees!====

If a follower hasn't been through an initial chargen/autolevel event (via player_core/sys_autolevel_h) then the skill tree doesn't show. You're probably trying to be clever and get around UT_HireFollower without going all the way (see monster function above ^_^).

====My followers don't have a class====

GetCreatureCoreClass() seems flaky under some conditions. It's best to explicitly set the class yourself; this is why class is currently a mandatory argument to hireCustomFollower()

====Dog talents and equipment slots don't work====
Symptoms: dog talents appear on the talents screen but remain greyed out on level up. Warrior talents appear in the quickslots. Equipment slots are for humans, not dogs.

Line 78 of packages_base in packages.xls (Dog) should have the LevelUpTable column set to 257 which is the ALDog table.

The EquipmentLayout 2DA needs a new entry for the follower:

ID=same as partypicker 2DA
Tag=follower tag
AvailableEquipmentSlots=794624
Layout=2
EnableWeaponSets=0

If the creature is not using the appearance "Dog, Party Member", it needs a new appearance line in APR_base. Most of the entries can be copied from the standard appearance (e.g. Wolf), but

MaxScaleLevel=-1
DefaultArmor=
AppearanceRestrictionGroup=1

Otherwise, it won't be able to progress beyond a specified level. The player will receive an unwanted set of armour when the it is hired, and it won't be able to use Marabi crunch items. You may also need to tweak PERSPACE and/or BumpLevel if excessive clipping occurs.

====Isn't there an easier way to do this?====

Possibly. There is a way of recruiting a follower by setting a plot flag. However I don't understand it, and I expect it still doesn't allow custom autolevel templates, full control over specialisations etc. There's still a fair bit of stuff hardcoded for the core followers, I'm not sure putting a custom follower through the same process as Al, Leli et al will have good results.

The next section answers this question, up to a point.

==== What if there are more than three potential followers? ====
This example handles larger numbers of followers, and doesn't force the player to use the party picker unless the party is already full.

The prefix zzz, used throughout, can be replaced with whatever [[Prefixes_in_use | prefix]] you are using for your resources.

If you're making a new campaign, to keep life simple, allocate a unique number to each follower. You could either use a creature variable or a script, e.g.
<pre>
// Party member id (e.g. 1=Alicia, 2=Godwin...)
int zzzPartyMemberID(object oPartyMember)
{
string sPartyMember = GetTag(oPartyMember);

if (sPartyMember == "zzzcr_alicia") return 1;
if (sPartyMember == "zzzcr_godwin") return 2;
if (sPartyMember == "zzzcr_harold") return 3;
if (sPartyMember == "zzzcr_lara" ) return 4;
return 0;
}
</pre>

Make two separate plots, e.g. zzzpt_hired for when a follower is first recruited, and zzzpt_party to flag whether they're currently in the party. Use flag values that correspond to the unique follower id, e.g. ZZZPT_HIRED_GODWIN will be 2.

If you're modifying the official campaign, you won't be able to make this simplification - you'll need a set of plot flags for your new party members, similar to the official ones. The logic of what follows is still correct, it just means that instead of having one set of common code that works for everyone, you have to explicitly script each party member individually using their personal plot flags.

Follower conversation is now very simple. In Godwin's dialogue, the hiring line will be conditional - when ZZZPT_HIRED_GODWIN is clear - and it will set ZZZPT_HIRED_GODWIN. No conversation script is necessary. Instead, in the properties of the plot zzzpt_hired, we add a plot event script, as follows.
<pre>
// PARTY HIRE PLOT SCRIPT
//
// This is called in conversation when a party member is hired for the first time.
// If the party is full, the party picker is displayed, which forces the PARTYMEMBER_ADDED
// module event.
//
// The flag value is never referenced, because the code is common for all party members.

#include "events_h"
#include "global_objects_h"
#include "utility_h"
#include "sys_rewards_h"
#include "log_h"
#include "utility_h"
#include "wrappers_h"
#include "plot_h"

#include "zzz_h" // A header containing the zzzPartyMemberID function
#include "plt_zzzpt_hired"
#include "plt_zzzpt_party"

int StartingConditional()
{
event eParms = GetCurrentEvent();
int nType = GetEventType(eParms); // GET or SET
string strPlot = GetEventString(eParms, 0); // Plot GUID
int nFlag = GetEventInteger(eParms, 1); // Plot flag
object oParty = GetEventCreator(eParms); // Plot table owner
object oFollower = GetEventObject(eParms, 0); // Conversation owner (if any)
int nPlotType = GetEventInteger(eParms, 5); // Plot type

int bIsTutorial = GetM2DAInt(TABLE_PLOT_TYPES, "IsTutorial", nPlotType);
int bIsCodex = GetM2DAInt(TABLE_PLOT_TYPES, "IsCodex", nPlotType);

int nResult = FALSE; // return value for DEFINED GET
object oPC = GetPartyLeader();

plot_GlobalPlotHandler(eParms); // any global plot operations, including debug info

if (nType == EVENT_TYPE_SET_PLOT) // actions -> normal flags only
{
int nValue = GetEventInteger(eParms, 2); // 0=Clear 1=Set
int nOldValue = GetEventInteger(eParms, 3); // Current flag value

if (nValue)
{
if (GetArraySize(GetPartyList(oPC)) < 4)
{
// Code from UT_HireFollower with level up bug fixed
SetAutoLevelUp(oFollower, 2);
SetGroupId(oFollower, GetGroupId(GetHero()));
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, FALSE);
// End of code from UT_HireFollower
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero())));
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), TRUE);
}
else
{
WR_SetFollowerState(oFollower, FOLLOWER_STATE_AVAILABLE, FALSE);
SetEventScript(oFollower, RESOURCE_SCRIPT_PLAYER_CORE);
SendPartyMemberHiredEvent(oFollower, TRUE);
// SetPartyPickerGUIStatus(PP_GUI_STATUS_USE);
// ShowPartyPickerGUI();
}
}
}
else // EVENT_TYPE_GET_PLOT -> defined conditions only
{
switch(nFlag)
{

}
}

plot_OutputDefinedFlag(eParms, nResult);
return nResult;
}
</pre>
We still need to handle the party picker events in our module event script:
<pre>
// PARTY MEMBER ADDED - Allow XP gain. Come here, follow me, flag as party member.
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0);
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero())));
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE);
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), TRUE);
break;
}
// PARTY MEMBER DROPPED - flag as not party member.
case EVENT_TYPE_PARTYMEMBER_DROPPED:
{
object oFollower = GetEventObject(ev, 0);
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), FALSE);
}
</pre>
When we need to refer to a particular follower explicitly, we can still do so - for example, the flag ZZZPT_PARTY_GODWIN will tell use whether Godwin is currently in the party or not.

==== How do I turn off sustained abilities when a follower is dismissed? ====
'''Please note:''' The 1.04 DA:O patch is bugged and removed/broke several features of the toolkit, if you are using it please follow [http://social.bioware.com/forum/1/topic/71/index/3172230/1#3172537 these steps] to re-enable them as one is required for the script below to compile.

There is a potential exploit in what we've done so far. If a follower casts a sustained spell like Flaming Weapons, it affects all party members. When the follower is dismissed, the remaining party members continue to benefit from the spell.

We can prevent this by deactivating modal abilities before opening the party picker. Add these snippets to the module event script:
<pre>
#include "ability_h"
void zDeactivateModalAbilities();
</pre>
and
<pre>
case EVENT_TYPE_PARTYPICKER_INIT:
{
// Deactivate party modal abilities. This ensures that the party no longer benefits
// from spells like Flaming Weapons if the caster is dismissed from the party.
zDeactivateModalAbilities();
break;
}
</pre>
The function looks like this:
<pre>
// Deactivate party's modal abilities

void zDeactivateModalAbilities()
{
object oPC = GetHero();
object [] oFollowerTable = GetPartyList(oPC);
object oFollower;
int nPartySize = GetArraySize(oFollowerTable);
int [] nAbilityTable;
int nAbilityCount;
int nAbility;
int i = -1;
int j;

while (++i < nPartySize)
{
oFollower = oFollowerTable[i];
nAbilityTable = GetAbilityList(oFollower);
nAbilityCount = GetArraySize(nAbilityTable);
j = -1;

while (++j < nAbilityCount)
{
nAbility = nAbilityTable[j];

if (Ability_IsAbilityActive(oFollower, nAbility))
if (Ability_IsModalAbility(nAbility))
Ability_DeactivateModalAbility(oFollower, nAbility);
}
}
}
</pre>
If other ways of dismissing party members are permitted, the same function can be used.

== Advanced Follower Creation: An Alternative Approach ==

While these things are to a large extent a matter of taste, I see no reason to reinvent the wheel when there is a perfectly good wheel at hand. The following describes how to adapt the existing machinery for the recruitment and tracking of your own party members.

First create the setup as described above in Simple Follower Creation, except for the scripts and plot tables. In addition, create the GDA extensions for a level-up table and the M2DA which points to those tables, as described in Advanced Follower Creation above.

Now ...

=== Step 1: Create a party plot table ===

Have a look at the gen00pt_party plot table and create a similar table for your own followers. Don't bother with the Defined Flags for the moment, just the Main Flags will do, ie recruited, in-camp and in-party for each follower. (Critical Note: Do not duplicate the plot table, create one from scratch. This is the case for ALL plot tables because of a show-stopping bug which means a new GUID is not assigned on Duplicate of a plot.)

=== Step 2: Create a party script ===

Duplicate the gen00pt_party script and rename for your module (conventionally plot tables and their plot scripts have the same name). Delete (or comment out) the Defined Flags section at the end and any lines dealing with logging and tutorials. Change names to those of your party members. If you are using gifting, approval or forced inclusion you may wish to retain those sections of code, but additional machinery will be needed for these facilities to work. For approval you can specify a starting level of approval here for each follower if you want it to be other than zero (as per the existing section dealing with Dog). Note that the custom hire function at the head of the script allows you to specify whether or not to invoke the party picker on recruitment. You may not want to do so for the first couple of followers (but see below). You should already have defined all required constants in a separate file for your module, eg <module prefix>_constants_h. If not, do so now and include it, as well as your plot table, at the head of the script. Delete includes that only refer to the main campaign. (If this is all Greek to you, spend a couple of hours examining the set-up of the Demo, which is packaged with the toolset, and go through the introductory tutorials referenced on the main page of this wiki).

Looking at the new party script, notice that the follower-in-camp function is not defined. This is because for some arcane reason it is defined in party_h, and unhappily references the main campaign's plot table. So we will have to create a new function to replace it, change the other function's flag reference (for the sake of neatness), and change the call in the main body of the script. (You may decide later for other reasons to replicate and customise party_h, but that won't interfere with re-creating this function here.)

Our two functions at the head of the script should be:

<dascript>void SetFollowerInParty(object oFollower, string sPlot, int nCampFlag)
{
WR_SetPlotFlag(sPlot, nCampFlag, FALSE);
WR_SetObjectActive(oFollower, TRUE);
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE);
command cJump = CommandJumpToObject(GetPartyLeader());
WR_AddCommand(oFollower, cJump);
}

void SetFollowerInCamp(object oFollower, string sPlot, int nPartyFlag)
{
WR_SetPlotFlag(sPlot, nPartyFlag, FALSE);
WR_SetObjectActive(oFollower, FALSE);
WR_SetFollowerState(oFollower, FOLLOWER_STATE_AVAILABLE, FALSE);
}</dascript>

and the line in the in-camp sections for each follower should now be:

<dascript>SetFollowerInCamp(o<follower>, strPlot, <follower>_IN_PARTY);</dascript>

=== Step 3: Create package GDAs and reference them in you 2DA_base extension ===

Look at the packages_base GDA and create an extension GDA with one line for each follower based on a main campaign follower that is most like your own follower, eg a sword-shield warrior can be a copy of Alistair, a battle mage a copy of Morrigan, etc. You can look at the Excel version of this GDA to more easily see what the fields mean. It is here that you can specify what if any specialisation will be assigned on hire and the level at which this spec point becomes available. (The IDs for each spec are in the 4000-range of ABI_base.)

Most importantly, it is here also that you define the ID of both your level-up table and the AIP table you are about to create.

Now create aip_follower_<follower name> gda tables, again based on a existing tables most like your own followers. No changes should be required to the copies you create.

In the m2da_base_<your module> extension you have already created, add lines for your AIP tables with a package ID referencing the IDs you assigned in your packages extension table.

Carefully check that all IDs in your GDAs are correct and cross-reference properly, and save the GDAs to your override directory.

Desirable but not obligatory (except for non-humanoid characters), is an extension to the Portraits gda. Finally the Equipment Layout gda will need an extension for non-humanoids, who use a different equipment mask.

=== Step 4: Module script addition ===

Modify your own module script to point to the new plot table and your own followers. To see an example of the required code for the two new sections look at the relevant section of module_core, which are for EVENT_TYPE_PARTYMEMBER_ADDED and EVENT_TYPE_PARTYMEMBER_DROPPED.

=== How it works ===

The recruit flag is set in a conversation (usually, but it could be a script) and that event is then processed by the plot script, which among other things sets both the in-camp and in-party flags, and fires up the party picker by default. If the player then selects the follower in the picker, the in-camp flag is unset (or vice versa if the follower is not selected to join). Subsequently, if the character is selected (or unselected) in the picker, the event is picked up by the module script, which sets the relevant plot flag as true, and that plot event is then sent to the plot scipt which sets the other flag as false.

(Note that if the party picker is turned off for a particular follower's recruit event, that follower will be placed in the active party regardless of the number of members, so ONLY do this for a follower who cannot be recruited when there are already 3 possible followers.)

On recruitment, player_core rebuilds the character according to the specifications laid out in the GDAs, so no further scripting is required.

=== Uses ===

To recruit a party member, set the recruit flag from your plot table in the relevant dialogue. Adding or subtracting followers from the active party is automatically tracked via this machinery, and the plot flags can be interrogated in all your scripts and conversations if you need to know who is currently in the party and who is in camp.

Defined flags can be added as you need them to the script and plot table but there is no point having flags that you will not use, so as with all Defined Flags this is an as-you-go decision, but quite easy to do.

Hiring and firing of temporary party members at the start of a campaign (such as Ser Jory, or Jowan, or Soris, etc) can be handled by UT_HireFollower, and the party picker is not invoked (nor is the Party Camp an available destination).

=== Troubleshooting ===

If you haven't done so already, create a simple debugging area for your module where you can dump the player, all followers and a couple of conversation dummies, and set up a dialogue in which you can invoke all required flags and conditions and see if they actually work as expected. (This setup can be used to test many other components as well.) Global machinery such as this can be painful to set up and get right (unless you are of an exceptionally methodical cast of mind), but it is worthwhile to ensure they are absolutely bullet-proof before you develop the specifics of your module.

=== The KISS principle ===

This is an "out-of-the-box" solution, and once set up is quite robust. If you want variants not catered for here, do NOT try to modify what you already have working.

'''Use-case:''' You want a follower (example tag: dairren) to be recruited without a set specialisation and one level higher than the PC.

Go to your packages gda and set the spec field to 0. In the character's plot table (you should have at least one for each follower) create a flag which we will call BLAH_BLAH. In the table's plot scipt insert the following very simple event handler:

<dascript>case BLAH_BLAH:
{
SetCreatureProperty(oDairren, 38, 1.00); //awards the spec point; field from the properties gda
int aLevel = GetLevel(oHero); //some simple arithmetic to find out the XP we need to award
int bLevel = (aLevel+1);
int aPoints = RW_GetXPNeededForLevel(aLevel);
int bPoints = RW_GetXPNeededForLevel(bLevel);
int targetPoints = (bPoints - aPoints);
RewardXP(oDairren, targetPoints, FALSE, TRUE); //award the XP, and we're done
break;
}</dascript>

The flag can be set in the same conversation as the recruit flag, so long as it comes afterwards. This way you not only maintain the integrity of your core machinery, but keep exceptions/variations for particular characters where they belong -- with that character's plot tables and scripts.

[[Category:Tutorials]]
{{Languages}}

Inventory

2011-07-09T06:38:15Z

Proleric1: /* Armor */

A creature or container object can contain one or more [[item]]s in inventory.

If a container is destroyed the contents of its inventory are transferred to a [[Bodybag]].

Each item can have the following properties set:

*Subgroup
*Slot - Sets whether the creature has equipped the item. "Not equipped" leaves the item in the general inventory, "Main" puts the item into the creature's main hand, and "off-hand" puts the item into the creature's off hand.
*Set - Items that are part of a set are meant to be given as a group. !!This is handled in the giving/taking script?!!
*StackSize - how many copies of this item are present in a stack
*Droppable - a checkbox that indicates whether the item is dropped when the creature is killed
*Stealable - a checkbox that indicates whether the item can be stolen from the creature

[[File:Creature inventory.png|center|thumb|400px|A typical creature inventory screen]]

[[Merchant]]s also have an inventory.

See [[Treasure system]] for auto-generated loot.

== Inventory Count - basic syntax ==

How do you know if the user has enough inventory space before adding items?

<dascript>
//Get max inventory size
int iMaxInventorySize = GetMaxInventorySize(GetHero());
object[] oInv = GetItemsInInventory(GetHero(), GET_ITEMS_OPTION_BACKPACK, 0, "", 1);

PrintToLog("Max Inventory size:" + IntToString(iMaxInventorySize));
PrintToLog("Current Inventory count:" + IntToString(GetArraySize(oInv)));
</dascript>

This returned 102 items in my inventory out of a total of 120.

== Inventory Subgroup Codes ==

===Armor===
*351000 - Mage Robe / Clothing
*331000 - Light Armor
*332000 - Medium Armor
*333000 - Heavy Armor
*334000 - Massive Armor

===Glove===
*311000 - Light Gloves
*312000 - Medium Gloves
*311000 - Heavy Gloves
*314000 - Massive Gloves

===Boots===
*321000 - Light Boots
*322000 - Medium Boots
*323000 - Heavy Boots
*324000 - Massive Boots

===Helmets===
*301000 - Light Helmet
*302000 - Medium Helmet
*303000 - Heavy Helmet
*304000 - Massive Helmet
*351500 - Mage Helmet

===Shields===
*343000 - Kite Shield
*342000 - Large Shield
*341000 - Small Shield
*344000 - Tower Shield

===Magic Staff===
*221000 - Staff

===Melee Weapons===
*201000 - Waraxes
*202000 - Battleaxes
*203000 - Daggers
*204000 - Greatswords
*205000 - Longswords
*206000 - Maces
*207000 - Mauls

===Ranged Weapons===
*211000 - Shortbows
*212000 - Longbows
*213000 - Crossbows
*214000 - Ammo

===Other===
*411000 - Amulets
*421000 - Belts
*431000 - Rings

===Special===
*361000 - Collar
*362000 - Warpaint

[[Category:Inventory]]

Follower tutorial

2011-06-22T07:01:09Z

Proleric1: /* What if there are more than three potential followers? */

== Simple Follower Creation ==

Follow these steps to create a follower that

- Levels up with a default package

- Can be chosen from the party picker

- Can gain XP

This guide assumes you know how to create a creature and are comfortable with basic scripting.

You should only use this simple method if you are sure there will be empty space in the active party when your follower is recruited.

A more comprehensive approach when there are more than three potential party members is discussed in the FAQ below. It's worth taking the time to understand the basics first, though.

=== Create the creature ===

Create a creature to act as your follower. Set its name, appearance, gender, head morph, conversation, inventory etc as you want them to behave in-game.

Set an appropriate '''Tag''' (you'll be using it a lot). I suggest "party_charname".

Make sure you choose a '''Class'''. For most followers this should be Rogue, Warrior or Wizard.

[[File:class.jpg]]

Under Package/Scaling set:

'''General Package Type''' to be '''Party Members'''

'''Package''' to be an appropriate value (probably "Generic - Wizard" or similar)

'''Package AI''' (there should only be one choice)

'''Rank''' to be '''Player'''

[[File:package.jpg]]

Save and export your character as normal.

=== Overlay char_stage ===

In the official campaign, the party picker uses a special area called char_stage. Whether you're extending the official campaign or making a standalone campaign, there is a function that allows you to overlap the offical stage with your own, so that both stages are active simultaneously in game.

In your resource palette, right-click char_stage under the Global folder and select Duplicate to make a copy of the stage with a new resource name, e.g. my_char_stage. In the resource properties, ensure that both Module and Owner Module are set to your module, and the folder of your choice.

[[File:area_palette.jpg]]

Create a new waypoint for your follower to appear on the party picker. This waypoint '''must''' have a tag in the form of "char_" followed by the exact tag of your follower.

[[File:char_stage.jpg]]

In this example the tag of my follower is '''bc_party_miera''' so her waypoint tag must be '''char_bc_party_miera'''

For a standalone module (such as in this example), put your waypoint wherever you please. The illustrated one is directly on top of Morrigan's. For an add-in to the main campaign, you should position your wp appropriately relative to the core party members.

Save and export the area.

Add the following to your module event script:
<dascript>
case EVENT_TYPE_MODULE_GETCHARSTAGE:
{
// Overlay the existing stage with my stage
// "my_char_stage" is the resource name of the overlay area
// "partypicker" is the name of the default GDA
SetPartyPickerStage("my_char_stage", "partypicker");
break;
}
</dascript>

=== Create m2DAs for the Party Picker ===

You will need to create two Excel spreadsheets.

The first should be named (both worksheet and file) '''partypicker_''' with a unique suffix. In this example, my first spreadsheet is named partypicker_fofbc.xls with a worksheet name of partypicker_fofbc - the suffix being the acronym of my module.

Set up your columns as follows:

[[File:partypickerm2da.jpg]]

The '''ID''' for your follower must be '''12 or higher'''. 11 is the highest value used in the base 2DA. 12 is fine for standalone modules, add-ins will probably want to use an arbitrarily high number to avoid potential conflicts.

The '''Label''' should be the follower's name as you wish it to appear on the party picker.

The '''Tag''' must be your follower's tag.

All other values are non-functioning defaults and should be specified as in the image above unless you know explicitly what you're doing.

'''NOTE - ON SELECTION ANIMATIONS'''

Add Animation and Remove Animation are actually Id numbers of different animations, taken from anim_base.gda

Enter and Exit version of animations are generally the best ones to use, altough one can try others. NOT ALL ANIMATIONS WILL WORK, since some require special conditions.
Here are some examples you can use:

819 - talk cursing

629 - reading a book (doesn't work, since it probably requires a book object)

844 - hands behind back (848 and 849 are Enter and Exit versions respectfully)

850 - chest pounding salute

811 - fist pounding

277 - dance

247 - cast area spell

500 - vfx cast

600 - surprised

603 - praying

607 - head bow

609 - standing at attention

651,652 - crouch pray (Enter and exit)

808 - point forward

825 - nodding

840 - hand chop or frustration

905,906 - crouch (Enter, Exit)

919,920 - sit on ground (enter, exit)

965 - kneel down loop

972 - wipe nose

976,977 - squat (Enter, Exit)

986 - wipe eyes

998,999 - hands clasped (Enter, exit)

3029 - inspect nails

3031,3032 - playful (enter, exit)

3054,3056 - slouch (enter, exit)
255 - in-place fly

'''NOTE - ON SELECTION VFX'''

The VFX column is the ID of the vFX effect taken from vFx_base.gda. This one is a bit more tricky, since it also references the BlendTree value from the same file.
Find the ID of the spell effect and look for the BlendTreeName column (should the the 12th columun) and enter BOTH into the respective columns for your character in the partypicker file.

Some examples:

ID --- BLENDTREENAME --- EFFECT

6039 --- fxm_energy_up_p --- Lady of the Forest pillar of light

6040 --- fxm_power_in_p --- Branka - power in

3054 --- fxc_lotf_c --- Lady of the Forest - swirling leaves

3009 --- fxc_succubus_c --- Succubus crust

1549 --- fxa_hly_imp_c --- Holy Impact crust

1076 --- fxa_spi_aur_mht_c --- Spirit - Aura Might crust

The second spreadsheet should be named '''party_picker_''' (note middle underscore). Once again append your unique suffix (in this example party_picker_fofbc.xls with party_picker_fofbc as its worksheet).

Set up your columns and data like so:

[[File:party_pickerm2da.jpg]]

'''ID''' and '''Tag''' should match what you did in the first spreadsheet. Specify INVALID COLUMN for the third column.

If you're familiar with m2DAs, generate them from these files, copy them to your module's override directory, and skip to the next step. Otherwise, read on:

- Go to '''\Program Files\Dragon Age\tools\ResourceBuild\Processors''' (or wherever you installed Dragon Age)

- Copy '''ExcelProcessor.exe''' from that folder to whichever folder has the excel sheets you just created.

- Drag and drop your xls files onto ExcelProcessor. This will create .gda files.

- Copy these .gda files to your module's export directory (probably \Documents\Bioware\Dragon Age\AddIns\yourModule\module\override\toolsetexport). Make sure they are included in your .dazip when the time comes to build your module.

If you are an OpenOffice user and have trouble with ExcelProcessor, you can use [http://social.bioware.com/project/755/ GDApp] to directly create the 2DAs. It rocks!

=== Capture the EVENT_TYPE_PARTYMEMBER_ADDED Event ===

Amusingly enough, the Party Picker does not actually add followers to the party. However it raises an event that allows you to do so. Your module script needs to capture this event and execute some code.

The following example shows what to do with the event. The full script would work as a module script for an add-in (assuming it didn't need to do anything else), but otherwise you'll have to incorporate the event into your own module script.

If you're not sure how to set a module script, go to '''File''' then '''Manage Modules,''' select your module and click '''Properties.'''

<dascript>
#include "utility_h"

void main()
{
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);
switch(nEventType)
{
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0); //Allows the follower to gain XP
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero()))); //Ensures follower appears at PC's location.
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE); //Adds follower to the active party
break;
}

}
}
</dascript>

'''SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE)''' is the key statement to add the follower to the active party. You must have this.

'''SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0)''' is a bug-fix, as followers hired with UT_HireFollower() do not receive XP by default. This statement fixes that, and I consider it best practice to keep it in this event to ensure it is always set. You will not wish to do this if you want a follower that should not gain XP to be on the party picker.

Note that you do not need to intercept the corresponding event for a party member being removed - the party picker handles spawning/despawning, and thus will successfully remove members.

Remember to save and export your module script.

If you're not sure how to set a module script, go to '''File''' then '''Manage Modules,''' select your module and click '''Properties.''' The module script is in the General category, as seen below:

[[File:module_script.jpg]]

You can set this to any script you've created. See [[Scripting tutorial]] and [[Character generation]] for more background and some simple examples of event-handling scripts. In general, you will want to make sure standalone module scripts pass events through to module_core (as in the [[Character generation]] examples) and add-in scripts do not (as in the example above).

=== Create Your Hiring Script ===

Now all that remains is to actually hire the follower :)

Create a script to handle the hiring (which will most likely be fired from a conversation). The script is quite simple:

<dascript>
#include "utility_h"

void main() {

object oFollower = GetObjectByTag("bc_party_miera"); //Use CreateObject() if the creature isn't present in the module yet

UT_HireFollower(oFollower); //Hires the follower

SetPartyPickerGUIStatus(2);

ShowPartyPickerGUI(); //Shows the Party Picker; necessary for the follower to gain XP

}
</dascript>

Make sure you use your own follower's tag and not the example one :)

This script fires the party picker after hiring the follower. That is absolutely necessary via this method, as we have put the XP fix onto an event fired by the party picker. You cannot put the XP fix into this script, it must be called from a later one (the bug is caused by an errant call to an event in player_core, which will be executed AFTER this script).

The easiest way to use this script is directly from conversation, putting it as an action on a line of dialogue where the PC invites the follower to join them. If you're not sure how to associate a script with a dialogue line, see the following image:

[[File:hire_conv.jpg]]

Create your dialogue as normal, select the line you want to fire the script, and click the '''Plots and Scripting''' tab. Use the '''Script''' file chooser in the Action section to browse to the script you created.

If everything worked, you should see something like this:

[[File:picker_success.jpg|thumb|200px|center]]

== Advanced Follower Creation ==

Follow these steps to have full control over the creation of your follower, with options such as:

- Unique level-up template

- Class and specialisation chosen via script

- Any starting state

- Level higher than the PC

- Starts with a specialisation point rather than a specific specialisation

- Set plot flags in the call to the hire script

=== Prepare Creature, char_stage and Party Picker m2DAs ===

Follow the same steps to create your follower creature, char_stage and Party Picker m2DAs as above.

=== Create Party Plot ===

While not necessary, it's very helpful to have plot flags set when a follower is hired or joins/leaves the active party. This makes conversation interjections and the like very easy.

Create a plot with appropriate flags. There's no real need to associate journal text with them:

[[File:follower_plot.jpg]]

See FAQ for an alternative approach to plots when there are more than three potential party members.

=== Add Plot Flags to Party Picker Event Intercept ===

We then update our module script to make use of that plot, like so:

<dascript>
#include "utility_h"
#include "wrappers_h"
#include "plt_bc_create_party" //make sure you include your own plot, not mine

void main()
{
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);
switch(nEventType)
{
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0);
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE);

AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero()))); //Ensures follower appears at PC's location.

if (GetTag(oFollower) == "bc_party_miera") { //You must explicitly test for your follower's tag.
WR_SetPlotFlag(PLT_BC_CREATE_PARTY, PARTY_MIERA_IN_PARTY, TRUE); //Make sure you use your own flags!
}

break;
}

case EVENT_TYPE_PARTYMEMBER_DROPPED:
{
object oFollower = GetEventObject(ev, 0);

if (GetTag(oFollower) == "bc_party_miera") {
WR_SetPlotFlag(PLT_BC_CREATE_PARTY, PARTY_MIERA_IN_PARTY, FALSE); //As above, but set false.
}

}

}
}
</dascript>

=== Create a Level Up Template ===

You can skip this step if you're content to use one of the generic Rogue, Wizard or Warrior templates, but I don't recommend it. Making a template that suits your character is easy and will almost always be better for the player than a generic one that spends points poorly.

Go to \Program Files\Dragon Age\tools\Source\2DA (or wherever you installed Dragon Age).

You should see a number of excel sheets of the form '''ALCharacter.xls''' (such as ALAlistair.xls, ALLeliana.xls, ALRogue_Default.xls etc). Open the one closest to your character (ie Morrigan or Wynne for a wizard, Leliana or Zevran for a rogue). Save a copy as '''ALYourcharacter.xls''' in whatever directory you're using to create your 2DAs, remembering to rename the worksheet '''ALYourcharacter''' (in this example, ALMiera.xls with ALMiera as its worksheet).

It should look something like this:

[[File:ALtable.jpg|thumb|500px|center]]

'''Columns B''' and '''C''' are the talents/spells available to this character. Do not change them.

'''Columns F''' and '''G''' are the skills available to this character. Do not change them.

We will edit the remaining columns like so:

==== Setting Stat Weights ====

The stat weights in '''column J''' determine how the follower will spend their attribute points, in a rough ratio. So if Dexterity is set to 1.5 and Intelligence to 1, you should expect to see 3 points of Dex for every 2 points of Cunning in-game (note Intelligence is the label used in the toolset for Cunning).

Simply change the values in J to reflect how you'd like the character to spend their points. In this example we're creating a wizard, so we're not going to mess around:

[[File:miera_stat_weights.jpg]]

This character will only raise magic. I set the value to 5 rather than something like 1 to provide room underneath for the other stats while still overwhelmingly favouring magic, but in practice I only really ever want that one stat.

In a note left on this column in the existing templates, Bioware's Georg Zoeller writes, "This is the weight of each attribute (row id links into properties.xls.id). 1.0 means 'try to keep this attribute level' (spend 1 point per level). 0.5 means 'try to spend 1 point every two levels' and so on."

The default Mage, Rogue and Warrior templates include '''column L''' labeled "AttInit." Editing these values seems to have no effect on followers set to use these templates.

==== Setting Talent and Skill Priorities ====

'''Columns D''' and '''E''' are the talents/spells that the character will buy, in preference order from top to bottom.

'''Columns H''' and '''I''' are the skills that the character will buy, in preference order from top to bottom.

To change these, just copy the appropriate two cells from columns B&C or F&G over the ones you want to replace.

For example, here we're copying Morrigan's template. Morrigan has Spider Shape high in her preferences, which we do not want.

[[File:AlMori_talent_pref.jpg]]

We decide we'd prefer Flame Blast, so we find it in columns B&C and copy both cells:

[[File:ALMori_copy.jpg]]

Then we select the cells we want to replace in columns D&E and paste over them:

[[File:ALMori_paste.jpg]]

Continue this process until your priorities list for both skills and talents/spells is exactly as you want it. Make sure you have at least as many priorities as the core follower you're copying - points that cannot be spent according to these priorities have a habit of vanishing.

If you used any abilities from a specialisation, make sure you remember to set that specialisation with the function we'll introduce later. The autolevel scripts will add specialisation abilities to a character regardless of whether they have that spec or not.

==== Create a M2DA_base_ m2DA ====

Dragon Age will need to know where to find your autolevel template. We tell it by extending M2DA_base.gda

Create a spreadsheet with the name and worksheet name in the form '''M2DA_base_''' with your unique suffix (in this example, M2DA_base_fofbc.xls with M2DA_base_fofbc as a worksheet).

Set up its columns and data like so (note I used GDApp because Open Office wasn't cooperating for this one!):

[[File:m2da_base_fofbc.jpg]]

The '''ID''' should be very high to avoid conflicts. I've arbitrarily chosen 50,000+ here. Carefully note the ID you've chosen for your character, you will need it later.

Set the '''Label''' and '''Worksheet''' to be the name of your autolevel template worksheet (ALCharactername if you've been following this).

Set the '''PackageIDForAI''' to be 0, it shouldn't be needed for followers.

When you're done, use ExcelProcessor to make GDAs of both spreadsheets and copy them to your module's export folder.

FOR AUTOLEVEL TO WORK AFTER RECRUITING:

Look in packages.xls.
There is a column called LevelupTable. That links to a corresponding AL* table. For instance, row 81 is for Leliana. Her LevelupTable value is 258. If you look that up in 2DA_base, you'll see it links to ALLeliana.
(alternatively, you could try packages_base.gda)

=== Create a New Hire Function Include ===

This section is probably only relevent if you have a specific need to override the functionality of player_core.

Many vital steps of follower addition happen inside an event in player_core. Followers tend to be extremely buggy (no skill tree, for example) if this event does not fire.

However, that event is not very flexible. In order to control it to our requirements, we need to replicate its functionality inside our own script. This is probably much safer than messing with player_core directly!

Create a new script file, naming it something like '''hireCustomFollower_h'''. We will be including this wherever we want to hire a follower.

Paste in the following script:

<dascript>
#include "sys_chargen_h"
#include "wrappers_h"
#include "utility_h"
#include "sys_rewards_h"
#include "approval_h"
#include "sys_autolevelup_h"

/* Jye Nicolson 5-Jan-2010
This function set duplicates the full functionality chain of UT_HireFollower, with the following exceptions:

- Followers can gain XP
- Autolevel status can be set (default off)
- Followers can be set to any starting state (default Available) and will still be properly initalised and added to the party pool
- Autolevel tables for non-core followers can be explicitly set.
- Class and Specialisation can be chosen via script
- Followers without specialisations are granted a spec point by default.

It should only ever be called once each for characters you intend to be full followers.
Much of the protective code handling summoned creatures etc. in player_core is not present here.

Calling the function:

Simple:

hireCustomFollower(oFollower, CLASS_WARRIOR);

Change the class to CLASS_WIZARD or CLASS_ROGUE as appropriate.
This will hire your follower and make them available.
They will auto level up with a default package, and receive a free spec point.

Best Practice:

hireCustomFollower(oFollower, CLASS_WARRIOR, PLT_YOUR_PARTY_PLOT, YOUR_FOLLOWER_JOINED_FLAG, ABILITY_TALENT_HIDDEN_CHAMPION);

Where the plot and flag are those for your module (remember to create the plot and include it on the calling script), and ABILITY_TALENT_HIDDEN etc is the desired spec.

You should also have a custom ALTable set up.
See wiki for details, and remember to edit it in to GetCustomFollowerALTable below or pass it directly as an argument to hireCustomFollower.

Full argument list:

void hireCustomFollower (
object oFollower, //Pass your follower object, mandatory

int nForceClass, //Pass a Class constant here, usually CLASS_ROGUE, CLASS_WARRIOR, CLASS_WIZARD. Mandatory due to a bug.

string sPlot = "", //It's recommended you have a plot flag to be set when the follower joins. Pass the plot constant here. Remember to #include in calling script

int nPlotFlag = "", //And then pass the flag constant. Will be set to TRUE if available.

int nForceSpec = 0, //This is the ID of the Specialisation you want. Note they are NOT classes, but abilities. The full list is:
//ABILITY_SPELL_HIDDEN_ARCANE_WARRIOR, ABILITY_SPELL_HIDDEN_BLOODMAGE, ABILITY_SPELL_HIDDEN_SHAPESHIFTER, ABILITY_SPELL_HIDDEN_SPIRIT_HEALER
//ABILITY_SPELL_HIDDEN_BARD, ABILITY_TALENT_HIDDEN_ASSASSIN, ABILITY_TALENT_HIDDEN_DUELIST, ABILITY_TALENT_HIDDEN_RANGER
//ABILITY_TALENT_HIDDEN_BERSERKER, ABILITY_TALENT_HIDDEN_CHAMPION, ABILITY_TALENT_HIDDEN_REAVER, ABILITY_TALENT_HIDDEN_TEMPLAR
//I recommended forcing a spec, particularly if your ALTable includes abilities from one.

int nALTable = 0, //This is the ID of an ALTable from 2DA_base.GDA or your module's m2DA_base_*.GDA I recommended the latter, but you can edit that into GetCustomFollowerALTable below rather than passing it.

int bInvokePicker = FALSE, //Sets whether the party picker should be opened on hiring. I think it's cleaner to call the picker outside this script, particularly if you have multiple hires at once.

int nInitialState = FOLLOWER_STATE_AVAILABLE, //This sets whether the follower joins the active party or not. Options are:
//FOLLOWER_STATE_ACTIVE (put them in the active party)
//FOLLOWER_STATE_LOCKEDACTIVE (force them into the active party and keep them there, remember to change this later.
//FOLLOWER_STATE_AVAILABLE (make them available on the party picker (if you've set it up for them), but not in the active party)
//Plus some others you're unlikely to need at this time. Defaults to AVAILABLE because having 4+ active followers is screwy.

string sCurrPlot = "", //If you set FOLLOWER_STATE_ACTIVE or FOLLOWER_STATE_LOCKEDACTIVE, the script will check to see if you passed this.
//It is recommended that you have a plot flag set for a given follower being in the active party, this makes conversation interjection etc. much easier.

int nCurrPlotFlag = 0, //This flag will be set if FOLLOWER_STATE_ACTIVE or FOLLOWER_STATE_LOCKEDACTIVE are true
//AND sCurrPlot has a value AND nCurrPlotFlag is > 0.
//ie if you added someone to the active party and have a plot flag to cope with it.

int nAutolevel = 0, //Sets the Autolevel flag on the character sheet. 0 is off, 1 is on, 2 forces it on and removes it so the player can't turn it off.

bFreeSpecPoint = TRUE, //This grants a specialisation point to the follower if they do not have a specialisation.
//It's important to set this false for classes that do not have specs, such as CLASS_DOG.

int nTargetLevel = 0, //If you want a specific level, set this. Generally not worthwhile unless you set it higher than the player, since they'll just get XP from the party picker anyway.

int nMinLevel = 0 //Set this if there's a specific level you don't want the follower to go below. Probably only useful if the PC might be very low level but not necessarily so.

)
*/
/* GetCustomFollowerALTable()
This function is where you put your custom table assignments.

You should explicitly test for the tag of your follower (not mine!) and assign a value to nTable from your m2DA extension to M2DA_base

See wiki for details on how to do this, or ignore it to get the default Warrior/Rogue/Wizard AL tables.

NOTE: you MUST explicitly set a table for non-Warrior/Rogue/Wizards, eg dogs. Use TABLE_AL_DOG for a default Mabari.
*/

int GetCustomFollowerALTable(object oFollower) {
int nTable = _GetTableToUseForAL(oFollower);

if (GetTag(oFollower) == "bc_party_miera") {
nTable = 50143;
}

if (GetTag(oFollower) == "bc_party_jysavin") {
nTable = 50144;
}

if (GetTag(oFollower) == "bc_party_geldual") {
nTable = 50145;
}

if (GetTag(oFollower) == "bc_party_braghon") {
nTable = 50146;
}

return nTable;
}

// This just cleans up the main function a little

int GetCustomFollowerTargetLevel(object oFollower, object oHero, int nPackage, int nMinLevel = 0) {
int nPlayerLevel = GetLevel(oHero);
int nTargetLevel = 0;

if((nPlayerLevel >= 13) || (nPlayerLevel == 1) || (!_UT_GetIsPlotFollower(oFollower))) {
nTargetLevel = nPlayerLevel;
} else {
nTargetLevel = nPlayerLevel + 1;
}

if (nMinLevel == 0) { //If nMinLevel is not specified, checks package 2DA for a value
nMinLevel = GetM2DAInt(TABLE_PACKAGES, "MinLevel", nPackage);
}
if(nMinLevel > 0 && nMinLevel > nTargetLevel) {
nTargetLevel = nMinLevel;
}

return nTargetLevel;

}

// Moving this black box out :) I don't really understand it, but it should function if you have tactics set up in a package.

void InitCustomFollowerTactics(object oFollower, int nPackage) {
int nTableID = GetM2DAInt(TABLE_PACKAGES, "FollowerTacticsTable", nPackage);
if (nTableID != -1)
{
int nRows = GetM2DARows(nTableID);
int nMaxTactics = GetNumTactics(oFollower);

int nTacticsEntry = 1;
int i;
for (i = 1; i <= nRows && nTacticsEntry <= nMaxTactics; ++i)
{
int bAddEntry = FALSE;
int nTargetType = GetM2DAInt(nTableID, "TargetType", i);
int nCondition = GetM2DAInt(nTableID, "Condition", i);
int nCommandType = GetM2DAInt(nTableID, "Command", i);
int nCommandParam = GetM2DAInt(nTableID, "SubCommand", i);

int nUseType = GetM2DAInt(TABLE_COMMAND_TYPES, "UseType", nCommandType);
if (nUseType == 0)
{
bAddEntry = TRUE;
}
else
{
bAddEntry = HasAbility(oFollower, nCommandParam);
}

if (bAddEntry)
{
SetTacticEntry(oFollower, nTacticsEntry, TRUE, nTargetType, nCondition, nCommandType, nCommandParam);
++nTacticsEntry;
}
}
}
}

/* InitCustomFollowerSpec:

This function tries to set the forced Specialisation. If there is none, it checks the package for one.

If there isn't either of those, it grants a free spec point if bFreeSpecPoint is true.

*/

void InitCustomFollowerSpec(object oFollower, int nPackage, int nForceSpec, int bFreeSpecPoint) {
// Find specialization, and optionally add a spec point if none is found.

if (nForceSpec == 0) {

int nSpecAbility = GetM2DAInt(TABLE_PACKAGES, "switch1_class", nPackage); // followers can have only 1 advanced class
if(nSpecAbility > 0)
{
AddAbility(oFollower, nSpecAbility);
} else {
if (bFreeSpecPoint) {
SetCreatureProperty(oFollower, 38, 1.00);
}
}

} else {

AddAbility(oFollower, nForceSpec);

}
}

/* hireCustomFollower() (See doco at top of page)

I strongly suggest you reorder the parameters if you're adding many followers with advanced options.

Feel free to leave them alone if you only want to set class, plot, spec or don't mind long declarations.

Note nForceClass is currently compulsory due to flakiness with GetCreatureCoreClass()
*/

void hireCustomFollower(object oFollower, int nForceClass, string sPlot = "", int nPlotFlag = 0, int nForceSpec = 0,
int nALTable = 0, int bInvokePicker = FALSE, int nInitialState = FOLLOWER_STATE_AVAILABLE, string sCurrPlot = "",
int nCurrPlotFlag = 0, int nAutolevel = 0, int bFreeSpecPoint = TRUE, int nTargetLevel = 0, int nMinLevel = 0)
{

object oHero = GetHero();

/* ################# BEGIN BASIC FOLLOWER JOIN BLOCK ###################

This loosely replicates WR_SetFollowerState.

*/

if (nForceClass == 0) {
nForceClass = GetCreatureCoreClass(oFollower); //This is not working. Hence nForceClass mandatory.
}

SetGroupId(oFollower, GetGroupId(oHero)); //Puts the follower in the pc's Group.
SetEventScript(oFollower, RESOURCE_SCRIPT_PLAYER_CORE); //This makes them act like a player.
SetFollowerState(oFollower, nInitialState); //This sets whether they are available, in the active party etc.

/* ################# END BASIC FOLLOWER JOIN BLOCK ##################### */

/* ################# BEGIN PLAYER_CORE EVENT_TYPE_PARTY_MEMBER_HIRED EMULATION #################
This replicates the EVENT_TYPE_PARTY_MEMBER_HIRED handler from player_core, stripped down for simplicity and allowing our custom options.

*/

Chargen_EnableTacticsPresets(oFollower); //I assume this is important.

SetLocalInt(oFollower, FOLLOWER_SCALED, 1); //This should prevent the follower being rescaled by player_core or what have you

int nPackage = GetPackage(oFollower); //Gets the package, which will be used to find a number of 2DA IDs.
int nPackageClass = GetM2DAInt(TABLE_PACKAGES, "StartingClass", nPackage); //I don't think this is used, even by player_core

// set behavior according to package
int nBehavior = GetM2DAInt(TABLE_PACKAGES, "FollowerBehavior", nPackage);

if(nBehavior >= 0) {
SetAIBehavior(oFollower, nBehavior);
}

Chargen_InitializeCharacter(oFollower); //We initialise the follower and choose race/class.

Chargen_SelectRace(oFollower,GetCreatureRacialType(oFollower));
Chargen_SelectCoreClass(oFollower,nForceClass);

if (nTargetLevel == 0) { //This block picks a target level if not specified

nTargetLevel = GetCustomFollowerTargetLevel(oFollower, oHero, nPackage, nMinLevel);
}

int nXp = RW_GetXPNeededForLevel(Max(nTargetLevel, 1)); //Here is where the XP is calculated and rewarded
RewardXP(oFollower, nXp, FALSE, FALSE);

// -------------------------------------------------------------
// add hidden approval talents - (JN: I don't know how to set these yet, but when I figure it out this should make it work)
// -------------------------------------------------------------
int nIndex = Approval_GetFollowerIndex(oFollower);
Approval_AddFollowerBonusAbility(nIndex, 0);

//Handle Specialisation
InitCustomFollowerSpec(oFollower, nPackage, nForceSpec, bFreeSpecPoint);

// -------------------------------------------------------------
// This spends all available attribute and stat points on the
// creature according to the levelup table. (JN: this replicates AL_DoAutoLevelUp but with our choice of table)
// -------------------------------------------------------------

if (nALTable == 0) {
nALTable = GetCustomFollowerALTable(oFollower);
}

AL_SpendAttributePoints(oFollower, nALTable, FALSE);
AL_SpendSkillPoints(oFollower, nALTable, TRUE);
AL_SpendSpecializationPoints(oFollower, nALTable);
AL_SpendTalentSpellPoints(oFollower, nALTable, TRUE);

// -------------------------------------------------------------------------
// Update various UIs
// -------------------------------------------------------------------------
Chargen_SetNumTactics(oFollower);
SetCanLevelUp(oFollower,Chargen_HasPointsToSpend(oFollower));

// load tactics
InitCustomFollowerTactics(oFollower, nPackage);

/* ################# END PLAYER_CORE EVENT_TYPE_PARTY_MEMBER_HIRED EMULATION ################# */

SetAutoLevelUp(oFollower, nAutolevel); //This is the autolevel flag on the character sheet.

//Set plot flags

if (!((sPlot == "") || (nPlotFlag == 0))) { //Joined Party
WR_SetPlotFlag(sPlot, nPlotFlag, TRUE);
}

if ((nInitialState == FOLLOWER_STATE_ACTIVE) || (nInitialState == FOLLOWER_STATE_LOCKEDACTIVE)) {
if (!((sCurrPlot == "") || (nCurrPlotFlag == 0))) {
WR_SetPlotFlag(sCurrPlot, nCurrPlotFlag, TRUE); //Currently in Party
}
}

// Invoke picker if requested.

if (bInvokePicker) {
SetPartyPickerGUIStatus(2);
ShowPartyPickerGUI();
}
}
</dascript>

Yeah, I know. It can't really be any smaller. Feel free to modify it if you're confident with scripting.
==== Add Your Custom Autolevel Template to GetCustomFollowerALTable() ====
While you can pass the ID you made for your autolevel template to that monster function as an argument, it's better to have them all in one place if you have multiple followers.

GetCustomFollowerALTable() is the first function in our include, and you can add an explicit if test for your follower there to assign the correct table id (the one from your M2DA_base_ m2DA). There is a function very much like it in sys_autolevel_h.nss for the core followers, so we'll copy Bioware's practice.

Let's take a look at the function by itself:

<dascript>
int GetCustomFollowerALTable(object oFollower) {
int nTable = _GetTableToUseForAL(oFollower);

if (GetTag(oFollower) == "bc_party_miera") {
nTable = 50143;
}

if (GetTag(oFollower) == "bc_party_jysavin") {
nTable = 50144;
}

if (GetTag(oFollower) == "bc_party_geldual") {
nTable = 50145;
}

if (GetTag(oFollower) == "bc_party_braghon") {
nTable = 50146;
}

return nTable;

}
</dascript>

So we have a test for each follower tag from my module, matching up to an ID which is assigned to nTable. All you need to do is change a tag from my follower to yours, and my ID to the correct one from your M2DA_base_* m2DA. Then you should delete the rest of the example if statements :)

Save and export the script. Ignore the compiler error about lack of main();

=== Include Function In Your Hire Script and Call It ===

So instead of a hire script that calls UT_HireFollower(), we want one that includes our shiny new function and calls it.

Take a look at the following example:

<dascript>
#include "plt_bc_create_party" //Make sure you include your party handling plot
#include "hireCustomFollower_h" // And include the function script - which will in turn include a bunch of stuff

void main() {

//Initialising my objects, not super-relevant to the example

object oHero = GetHero();
object oMiera = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_miera.utc", GetLocation(oHero));
object oJysavin = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_jysavin.utc", GetLocation(oHero));
object oBraghon = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_braghon.utc", GetLocation(oHero));
object oSpider = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_geldual.utc", GetLocation(oHero));

//Simplest hire call - adds to the party as a wizard. Class is currently compulsory due to a bug.
hireCustomFollower(oMiera, CLASS_WIZARD);

//Add to the party and set joining plot flags
hireCustomFollower(oJysavin, CLASS_WARRIOR, PLT_BC_CREATE_PARTY, PARTY_JYSAVIN_JOINED);

//Add to the party, set plot flags, force a specialisation
hireCustomFollower(oBraghon, CLASS_ROGUE, PLT_BC_CREATE_PARTY, PARTY_BRAGHON_JOINED, ABILITY_TALENT_HIDDEN_ASSASSIN);

//More complex example - Follower added as a unique class (Dog), not granted a specialisation or spec point.
//Note unique classes must have an ALTable passed here or specified in GetCustomFollowerALTable() or they won't work
hireCustomFollower(oSpider, CLASS_DOG, PLT_BC_CREATE_PARTY, PARTY_GELDUAL_JOINED, 0, 0, FALSE, FOLLOWER_STATE_AVAILABLE, "", 0, 0, FALSE);

//Show the party picker to let the player choose from their new companions!
SetPartyPickerGUIStatus(2);
ShowPartyPickerGUI();
}
</dascript>

The example shows several of the more simple ways of invoking the function. Check the comments at the start of the function for a full list of arguments.

I would suggest best practice for most followers would be to call as follows:

'''hireCustomFollower(oFollower, CLASS, PLOT, PLOT_FLAG, SPECIALISATION)'''

This will safely set the follower up as the desired class and specialisation (doubly important if there are spec abilities in their ALTable) while setting your plot flag for them being in the party. hireCustomFollower(oFollower, CLASS, PLOT, PLOT_FLAG, SPECIALISATION, 0, TRUE) will do the same while invoking the Party Picker automatically.

Note that the specialisations are abilities and not classes - you'll find them as ABILITY_HIDDEN_ constants.

If it's all worked, you should find you can now add followers with a lot more flexibility!

[[File:picker_advanced.jpg|thumb|500px|center]]

== Common Follower Problems & FAQ ==

====Why don't my followers gain XP?====
There is a bug in UT_HireFollower. Make a copy of UT_HireFollower in a function of your own, then make the following change:
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, TRUE);
to
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, bPreventLevelup);

====When I choose followers from the Party Picker, they spawn into the area but do not join.====

You need to intercept the EVENT_TYPE_PARTYMEMBER_ADDED event and set the follower to FOLLOWER_STATE_ACTIVE. See Simple Follower Creation earlier in this document.

====My followers don't have skill trees!====

If a follower hasn't been through an initial chargen/autolevel event (via player_core/sys_autolevel_h) then the skill tree doesn't show. You're probably trying to be clever and get around UT_HireFollower without going all the way (see monster function above ^_^).

====My followers don't have a class====

GetCreatureCoreClass() seems flaky under some conditions. It's best to explicitly set the class yourself; this is why class is currently a mandatory argument to hireCustomFollower()

====Dog talents and equipment slots don't work====
Symptoms: dog talents appear on the talents screen but remain greyed out on level up. Warrior talents appear in the quickslots. Equipment slots are for humans, not dogs.

Line 78 of packages_base in packages.xls (Dog) should have the LevelUpTable column set to 257 which is the ALDog table.

The EquipmentLayout 2DA needs a new entry for the follower:

ID=same as partypicker 2DA
Tag=follower tag
AvailableEquipmentSlots=794624
Layout=2
EnableWeaponSets=0

If the creature is not using the appearance "Dog, Party Member", it needs a new appearance line in APR_base. Most of the entries can be copied from the standard appearance (e.g. Wolf), but

MaxScaleLevel=-1
DefaultArmor=
AppearanceRestrictionGroup=1

Otherwise, it won't be able to progress beyond a specified level. The player will receive an unwanted set of armour when the it is hired, and it won't be able to use Marabi crunch items. You may also need to tweak PERSPACE and/or BumpLevel if excessive clipping occurs.

====Isn't there an easier way to do this?====

Possibly. There is a way of recruiting a follower by setting a plot flag. However I don't understand it, and I expect it still doesn't allow custom autolevel templates, full control over specialisations etc. There's still a fair bit of stuff hardcoded for the core followers, I'm not sure putting a custom follower through the same process as Al, Leli et al will have good results.

The next section answers this question, up to a point.

==== What if there are more than three potential followers? ====
This example handles larger numbers of followers, and doesn't force the player to use the party picker unless the party is already full.

The prefix zzz, used throughout, can be replaced with whatever [[Prefixes_in_use | prefix]] you are using for your resources.

If you're making a new campaign, to keep life simple, allocate a unique number to each follower. You could either use a creature variable or a script, e.g.
<pre>
// Party member id (e.g. 1=Alicia, 2=Godwin...)
int zzzPartyMemberID(object oPartyMember)
{
string sPartyMember = GetTag(oPartyMember);

if (sPartyMember == "zzzcr_alicia") return 1;
if (sPartyMember == "zzzcr_godwin") return 2;
if (sPartyMember == "zzzcr_harold") return 3;
if (sPartyMember == "zzzcr_lara" ) return 4;
return 0;
}
</pre>

Make two separate plots, e.g. zzzpt_hired for when a follower is first recruited, and zzzpt_party to flag whether they're currently in the party. Use flag values that correspond to the unique follower id, e.g. ZZZPT_HIRED_GODWIN will be 2.

If you're modifying the official campaign, you won't be able to make this simplification - you'll need a set of plot flags for your new party members, similar to the official ones. The logic of what follows is still correct, it just means that instead of having one set of common code that works for everyone, you have to explicitly script each party member individually using their personal plot flags.

Follower conversation is now very simple. In Godwin's dialogue, the hiring line will be conditional - when ZZZPT_HIRED_GODWIN is clear - and it will set ZZZPT_HIRED_GODWIN. No conversation script is necessary. Instead, in the properties of the plot zzzpt_hired, we add a plot event script, as follows.
<pre>
// PARTY HIRE PLOT SCRIPT
//
// This is called in conversation when a party member is hired for the first time.
// If the party is full, the party picker is displayed, which forces the PARTYMEMBER_ADDED
// module event.
//
// The flag value is never referenced, because the code is common for all party members.

#include "events_h"
#include "global_objects_h"
#include "utility_h"
#include "sys_rewards_h"
#include "log_h"
#include "utility_h"
#include "wrappers_h"
#include "plot_h"

#include "zzz_h" // A header containing the zzzPartyMemberID function
#include "plt_zzzpt_hired"
#include "plt_zzzpt_party"

int StartingConditional()
{
event eParms = GetCurrentEvent();
int nType = GetEventType(eParms); // GET or SET
string strPlot = GetEventString(eParms, 0); // Plot GUID
int nFlag = GetEventInteger(eParms, 1); // Plot flag
object oParty = GetEventCreator(eParms); // Plot table owner
object oFollower = GetEventObject(eParms, 0); // Conversation owner (if any)
int nPlotType = GetEventInteger(eParms, 5); // Plot type

int bIsTutorial = GetM2DAInt(TABLE_PLOT_TYPES, "IsTutorial", nPlotType);
int bIsCodex = GetM2DAInt(TABLE_PLOT_TYPES, "IsCodex", nPlotType);

int nResult = FALSE; // return value for DEFINED GET
object oPC = GetPartyLeader();

plot_GlobalPlotHandler(eParms); // any global plot operations, including debug info

if (nType == EVENT_TYPE_SET_PLOT) // actions -> normal flags only
{
int nValue = GetEventInteger(eParms, 2); // 0=Clear 1=Set
int nOldValue = GetEventInteger(eParms, 3); // Current flag value

if (nValue)
{
if (GetArraySize(GetPartyList(oPC)) < 4)
{
// Code from UT_HireFollower with level up bug fixed
SetAutoLevelUp(oFollower, 2);
SetGroupId(oFollower, GetGroupId(GetHero()));
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, FALSE);
// End of code from UT_HireFollower
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero())));
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), TRUE);
}
else
{
WR_SetFollowerState(oFollower, FOLLOWER_STATE_AVAILABLE, FALSE);
SetEventScript(oFollower, RESOURCE_SCRIPT_PLAYER_CORE);
SendPartyMemberHiredEvent(oFollower, TRUE);
// SetPartyPickerGUIStatus(PP_GUI_STATUS_USE);
// ShowPartyPickerGUI();
}
}
}
else // EVENT_TYPE_GET_PLOT -> defined conditions only
{
switch(nFlag)
{

}
}

plot_OutputDefinedFlag(eParms, nResult);
return nResult;
}
</pre>
We still need to handle the party picker events in our module event script:
<pre>
// PARTY MEMBER ADDED - Allow XP gain. Come here, follow me, flag as party member.
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0);
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero())));
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE);
SetImmortal(oFollower, FALSE);
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), TRUE);
break;
}
// PARTY MEMBER DROPPED - flag as not party member.
case EVENT_TYPE_PARTYMEMBER_DROPPED:
{
object oFollower = GetEventObject(ev, 0);
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), FALSE);
}
</pre>
When we need to refer to a particular follower explicitly, we can still do so - for example, the flag ZZZPT_PARTY_GODWIN will tell use whether Godwin is currently in the party or not.

==== How do I turn off sustained abilities when a follower is dismissed? ====
'''Please note:''' The 1.04 DA:O patch is bugged and removed/broke several features of the toolkit, if you are using it please follow [http://social.bioware.com/forum/1/topic/71/index/3172230/1#3172537 these steps] to re-enable them as one is required for the script below to compile.

There is a potential exploit in what we've done so far. If a follower casts a sustained spell like Flaming Weapons, it affects all party members. When the follower is dismissed, the remaining party members continue to benefit from the spell.

We can prevent this by deactivating modal abilities before opening the party picker. Add these snippets to the module event script:
<pre>
#include "ability_h"
void zDeactivateModalAbilities();
</pre>
and
<pre>
case EVENT_TYPE_PARTYPICKER_INIT:
{
// Deactivate party modal abilities. This ensures that the party no longer benefits
// from spells like Flaming Weapons if the caster is dismissed from the party.
zDeactivateModalAbilities();
break;
}
</pre>
The function looks like this:
<pre>
// Deactivate party's modal abilities

void zDeactivateModalAbilities()
{
object oPC = GetHero();
object [] oFollowerTable = GetPartyList(oPC);
object oFollower;
int nPartySize = GetArraySize(oFollowerTable);
int [] nAbilityTable;
int nAbilityCount;
int nAbility;
int i = -1;
int j;

while (++i < nPartySize)
{
oFollower = oFollowerTable[i];
nAbilityTable = GetAbilityList(oFollower);
nAbilityCount = GetArraySize(nAbilityTable);
j = -1;

while (++j < nAbilityCount)
{
nAbility = nAbilityTable[j];

if (Ability_IsAbilityActive(oFollower, nAbility))
if (Ability_IsModalAbility(nAbility))
Ability_DeactivateModalAbility(oFollower, nAbility);
}
}
}
</pre>
If other ways of dismissing party members are permitted, the same function can be used.

== Advanced Follower Creation: An Alternative Approach ==

While these things are to a large extent a matter of taste, I see no reason to reinvent the wheel when there is a perfectly good wheel at hand. The following describes how to adapt the existing machinery for the recruitment and tracking of your own party members.

First create the setup as described above in Simple Follower Creation, except for the scripts and plot tables. In addition, create the GDA extensions for a level-up table and the M2DA which points to those tables, as described in Advanced Follower Creation above.

Now ...

=== Step 1: Create a party plot table ===

Have a look at the gen00pt_party plot table and create a similar table for your own followers. Don't bother with the Defined Flags for the moment, just the Main Flags will do, ie recruited, in-camp and in-party for each follower. (Critical Note: Do not duplicate the plot table, create one from scratch. This is the case for ALL plot tables because of a show-stopping bug which means a new GUID is not assigned on Duplicate of a plot.)

=== Step 2: Create a party script ===

Duplicate the gen00pt_party script and rename for your module (conventionally plot tables and their plot scripts have the same name). Delete (or comment out) the Defined Flags section at the end and any lines dealing with logging and tutorials. Change names to those of your party members. If you are using gifting, approval or forced inclusion you may wish to retain those sections of code, but additional machinery will be needed for these facilities to work. For approval you can specify a starting level of approval here for each follower if you want it to be other than zero (as per the existing section dealing with Dog). Note that the custom hire function at the head of the script allows you to specify whether or not to invoke the party picker on recruitment. You may not want to do so for the first couple of followers (but see below). You should already have defined all required constants in a separate file for your module, eg <module prefix>_constants_h. If not, do so now and include it, as well as your plot table, at the head of the script. Delete includes that only refer to the main campaign. (If this is all Greek to you, spend a couple of hours examining the set-up of the Demo, which is packaged with the toolset, and go through the introductory tutorials referenced on the main page of this wiki).

Looking at the new party script, notice that the follower-in-camp function is not defined. This is because for some arcane reason it is defined in party_h, and unhappily references the main campaign's plot table. So we will have to create a new function to replace it, change the other function's flag reference (for the sake of neatness), and change the call in the main body of the script. (You may decide later for other reasons to replicate and customise party_h, but that won't interfere with re-creating this function here.)

Our two functions at the head of the script should be:

<dascript>void SetFollowerInParty(object oFollower, string sPlot, int nCampFlag)
{
WR_SetPlotFlag(sPlot, nCampFlag, FALSE);
WR_SetObjectActive(oFollower, TRUE);
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE);
command cJump = CommandJumpToObject(GetPartyLeader());
WR_AddCommand(oFollower, cJump);
}

void SetFollowerInCamp(object oFollower, string sPlot, int nPartyFlag)
{
WR_SetPlotFlag(sPlot, nPartyFlag, FALSE);
WR_SetObjectActive(oFollower, FALSE);
WR_SetFollowerState(oFollower, FOLLOWER_STATE_AVAILABLE, FALSE);
}</dascript>

and the line in the in-camp sections for each follower should now be:

<dascript>SetFollowerInCamp(o<follower>, strPlot, <follower>_IN_PARTY);</dascript>

=== Step 3: Create package GDAs and reference them in you 2DA_base extension ===

Look at the packages_base GDA and create an extension GDA with one line for each follower based on a main campaign follower that is most like your own follower, eg a sword-shield warrior can be a copy of Alistair, a battle mage a copy of Morrigan, etc. You can look at the Excel version of this GDA to more easily see what the fields mean. It is here that you can specify what if any specialisation will be assigned on hire and the level at which this spec point becomes available. (The IDs for each spec are in the 4000-range of ABI_base.)

Most importantly, it is here also that you define the ID of both your level-up table and the AIP table you are about to create.

Now create aip_follower_<follower name> gda tables, again based on a existing tables most like your own followers. No changes should be required to the copies you create.

In the m2da_base_<your module> extension you have already created, add lines for your AIP tables with a package ID referencing the IDs you assigned in your packages extension table.

Carefully check that all IDs in your GDAs are correct and cross-reference properly, and save the GDAs to your override directory.

Desirable but not obligatory (except for non-humanoid characters), is an extension to the Portraits gda. Finally the Equipment Layout gda will need an extension for non-humanoids, who use a different equipment mask.

=== Step 4: Module script addition ===

Modify your own module script to point to the new plot table and your own followers. To see an example of the required code for the two new sections look at the relevant section of module_core, which are for EVENT_TYPE_PARTYMEMBER_ADDED and EVENT_TYPE_PARTYMEMBER_DROPPED.

=== How it works ===

The recruit flag is set in a conversation (usually, but it could be a script) and that event is then processed by the plot script, which among other things sets both the in-camp and in-party flags, and fires up the party picker by default. If the player then selects the follower in the picker, the in-camp flag is unset (or vice versa if the follower is not selected to join). Subsequently, if the character is selected (or unselected) in the picker, the event is picked up by the module script, which sets the relevant plot flag as true, and that plot event is then sent to the plot scipt which sets the other flag as false.

(Note that if the party picker is turned off for a particular follower's recruit event, that follower will be placed in the active party regardless of the number of members, so ONLY do this for a follower who cannot be recruited when there are already 3 possible followers.)

On recruitment, player_core rebuilds the character according to the specifications laid out in the GDAs, so no further scripting is required.

=== Uses ===

To recruit a party member, set the recruit flag from your plot table in the relevant dialogue. Adding or subtracting followers from the active party is automatically tracked via this machinery, and the plot flags can be interrogated in all your scripts and conversations if you need to know who is currently in the party and who is in camp.

Defined flags can be added as you need them to the script and plot table but there is no point having flags that you will not use, so as with all Defined Flags this is an as-you-go decision, but quite easy to do.

Hiring and firing of temporary party members at the start of a campaign (such as Ser Jory, or Jowan, or Soris, etc) can be handled by UT_HireFollower, and the party picker is not invoked (nor is the Party Camp an available destination).

=== Troubleshooting ===

If you haven't done so already, create a simple debugging area for your module where you can dump the player, all followers and a couple of conversation dummies, and set up a dialogue in which you can invoke all required flags and conditions and see if they actually work as expected. (This setup can be used to test many other components as well.) Global machinery such as this can be painful to set up and get right (unless you are of an exceptionally methodical cast of mind), but it is worthwhile to ensure they are absolutely bullet-proof before you develop the specifics of your module.

=== The KISS principle ===

This is an "out-of-the-box" solution, and once set up is quite robust. If you want variants not catered for here, do NOT try to modify what you already have working.

'''Use-case:''' You want a follower (example tag: dairren) to be recruited without a set specialisation and one level higher than the PC.

Go to your packages gda and set the spec field to 0. In the character's plot table (you should have at least one for each follower) create a flag which we will call BLAH_BLAH. In the table's plot scipt insert the following very simple event handler:

<dascript>case BLAH_BLAH:
{
SetCreatureProperty(oDairren, 38, 1.00); //awards the spec point; field from the properties gda
int aLevel = GetLevel(oHero); //some simple arithmetic to find out the XP we need to award
int bLevel = (aLevel+1);
int aPoints = RW_GetXPNeededForLevel(aLevel);
int bPoints = RW_GetXPNeededForLevel(bLevel);
int targetPoints = (bPoints - aPoints);
RewardXP(oDairren, targetPoints, FALSE, TRUE); //award the XP, and we're done
break;
}</dascript>

The flag can be set in the same conversation as the recruit flag, so long as it comes afterwards. This way you not only maintain the integrity of your core machinery, but keep exceptions/variations for particular characters where they belong -- with that character's plot tables and scripts.

[[Category:Tutorials]]
{{Languages}}

Follower tutorial

2011-06-15T16:45:20Z

Proleric1: /* What if there are more than three potential followers? */

== Simple Follower Creation ==

Follow these steps to create a follower that

- Levels up with a default package

- Can be chosen from the party picker

- Can gain XP

This guide assumes you know how to create a creature and are comfortable with basic scripting.

You should only use this simple method if you are sure there will be empty space in the active party when your follower is recruited.

A more comprehensive approach when there are more than three potential party members is discussed in the FAQ below. It's worth taking the time to understand the basics first, though.

=== Create the creature ===

Create a creature to act as your follower. Set its name, appearance, gender, head morph, conversation, inventory etc as you want them to behave in-game.

Set an appropriate '''Tag''' (you'll be using it a lot). I suggest "party_charname".

Make sure you choose a '''Class'''. For most followers this should be Rogue, Warrior or Wizard.

[[File:class.jpg]]

Under Package/Scaling set:

'''General Package Type''' to be '''Party Members'''

'''Package''' to be an appropriate value (probably "Generic - Wizard" or similar)

'''Package AI''' (there should only be one choice)

'''Rank''' to be '''Player'''

[[File:package.jpg]]

Save and export your character as normal.

=== Overlay char_stage ===

In the official campaign, the party picker uses a special area called char_stage. Whether you're extending the official campaign or making a standalone campaign, there is a function that allows you to overlap the offical stage with your own, so that both stages are active simultaneously in game.

In your resource palette, right-click char_stage under the Global folder and select Duplicate to make a copy of the stage with a new resource name, e.g. my_char_stage. In the resource properties, ensure that both Module and Owner Module are set to your module, and the folder of your choice.

[[File:area_palette.jpg]]

Create a new waypoint for your follower to appear on the party picker. This waypoint '''must''' have a tag in the form of "char_" followed by the exact tag of your follower.

[[File:char_stage.jpg]]

In this example the tag of my follower is '''bc_party_miera''' so her waypoint tag must be '''char_bc_party_miera'''

For a standalone module (such as in this example), put your waypoint wherever you please. The illustrated one is directly on top of Morrigan's. For an add-in to the main campaign, you should position your wp appropriately relative to the core party members.

Save and export the area.

Add the following to your module event script:
<dascript>
case EVENT_TYPE_MODULE_GETCHARSTAGE:
{
// Overlay the existing stage with my stage
// "my_char_stage" is the resource name of the overlay area
// "partypicker" is the name of the default GDA
SetPartyPickerStage("my_char_stage", "partypicker");
break;
}
</dascript>

=== Create m2DAs for the Party Picker ===

You will need to create two Excel spreadsheets.

The first should be named (both worksheet and file) '''partypicker_''' with a unique suffix. In this example, my first spreadsheet is named partypicker_fofbc.xls with a worksheet name of partypicker_fofbc - the suffix being the acronym of my module.

Set up your columns as follows:

[[File:partypickerm2da.jpg]]

The '''ID''' for your follower must be '''12 or higher'''. 11 is the highest value used in the base 2DA. 12 is fine for standalone modules, add-ins will probably want to use an arbitrarily high number to avoid potential conflicts.

The '''Label''' should be the follower's name as you wish it to appear on the party picker.

The '''Tag''' must be your follower's tag.

All other values are non-functioning defaults and should be specified as in the image above unless you know explicitly what you're doing.

'''NOTE - ON SELECTION ANIMATIONS'''

Add Animation and Remove Animation are actually Id numbers of different animations, taken from anim_base.gda

Enter and Exit version of animations are generally the best ones to use, altough one can try others. NOT ALL ANIMATIONS WILL WORK, since some require special conditions.
Here are some examples you can use:

819 - talk cursing

629 - reading a book (doesn't work, since it probably requires a book object)

844 - hands behind back (848 and 849 are Enter and Exit versions respectfully)

850 - chest pounding salute

811 - fist pounding

277 - dance

247 - cast area spell

500 - vfx cast

600 - surprised

603 - praying

607 - head bow

609 - standing at attention

651,652 - crouch pray (Enter and exit)

808 - point forward

825 - nodding

840 - hand chop or frustration

905,906 - crouch (Enter, Exit)

919,920 - sit on ground (enter, exit)

965 - kneel down loop

972 - wipe nose

976,977 - squat (Enter, Exit)

986 - wipe eyes

998,999 - hands clasped (Enter, exit)

3029 - inspect nails

3031,3032 - playful (enter, exit)

3054,3056 - slouch (enter, exit)
255 - in-place fly

'''NOTE - ON SELECTION VFX'''

The VFX column is the ID of the vFX effect taken from vFx_base.gda. This one is a bit more tricky, since it also references the BlendTree value from the same file.
Find the ID of the spell effect and look for the BlendTreeName column (should the the 12th columun) and enter BOTH into the respective columns for your character in the partypicker file.

Some examples:

ID --- BLENDTREENAME --- EFFECT

6039 --- fxm_energy_up_p --- Lady of the Forest pillar of light

6040 --- fxm_power_in_p --- Branka - power in

3054 --- fxc_lotf_c --- Lady of the Forest - swirling leaves

3009 --- fxc_succubus_c --- Succubus crust

1549 --- fxa_hly_imp_c --- Holy Impact crust

1076 --- fxa_spi_aur_mht_c --- Spirit - Aura Might crust

The second spreadsheet should be named '''party_picker_''' (note middle underscore). Once again append your unique suffix (in this example party_picker_fofbc.xls with party_picker_fofbc as its worksheet).

Set up your columns and data like so:

[[File:party_pickerm2da.jpg]]

'''ID''' and '''Tag''' should match what you did in the first spreadsheet. Specify INVALID COLUMN for the third column.

If you're familiar with m2DAs, generate them from these files, copy them to your module's override directory, and skip to the next step. Otherwise, read on:

- Go to '''\Program Files\Dragon Age\tools\ResourceBuild\Processors''' (or wherever you installed Dragon Age)

- Copy '''ExcelProcessor.exe''' from that folder to whichever folder has the excel sheets you just created.

- Drag and drop your xls files onto ExcelProcessor. This will create .gda files.

- Copy these .gda files to your module's export directory (probably \Documents\Bioware\Dragon Age\AddIns\yourModule\module\override\toolsetexport). Make sure they are included in your .dazip when the time comes to build your module.

If you are an OpenOffice user and have trouble with ExcelProcessor, you can use [http://social.bioware.com/project/755/ GDApp] to directly create the 2DAs. It rocks!

=== Capture the EVENT_TYPE_PARTYMEMBER_ADDED Event ===

Amusingly enough, the Party Picker does not actually add followers to the party. However it raises an event that allows you to do so. Your module script needs to capture this event and execute some code.

The following example shows what to do with the event. The full script would work as a module script for an add-in (assuming it didn't need to do anything else), but otherwise you'll have to incorporate the event into your own module script.

If you're not sure how to set a module script, go to '''File''' then '''Manage Modules,''' select your module and click '''Properties.'''

<dascript>
#include "utility_h"

void main()
{
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);
switch(nEventType)
{
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0); //Allows the follower to gain XP
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero()))); //Ensures follower appears at PC's location.
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE); //Adds follower to the active party
break;
}

}
}
</dascript>

'''SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE)''' is the key statement to add the follower to the active party. You must have this.

'''SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0)''' is a bug-fix, as followers hired with UT_HireFollower() do not receive XP by default. This statement fixes that, and I consider it best practice to keep it in this event to ensure it is always set. You will not wish to do this if you want a follower that should not gain XP to be on the party picker.

Note that you do not need to intercept the corresponding event for a party member being removed - the party picker handles spawning/despawning, and thus will successfully remove members.

Remember to save and export your module script.

If you're not sure how to set a module script, go to '''File''' then '''Manage Modules,''' select your module and click '''Properties.''' The module script is in the General category, as seen below:

[[File:module_script.jpg]]

You can set this to any script you've created. See [[Scripting tutorial]] and [[Character generation]] for more background and some simple examples of event-handling scripts. In general, you will want to make sure standalone module scripts pass events through to module_core (as in the [[Character generation]] examples) and add-in scripts do not (as in the example above).

=== Create Your Hiring Script ===

Now all that remains is to actually hire the follower :)

Create a script to handle the hiring (which will most likely be fired from a conversation). The script is quite simple:

<dascript>
#include "utility_h"

void main() {

object oFollower = GetObjectByTag("bc_party_miera"); //Use CreateObject() if the creature isn't present in the module yet

UT_HireFollower(oFollower); //Hires the follower

SetPartyPickerGUIStatus(2);

ShowPartyPickerGUI(); //Shows the Party Picker; necessary for the follower to gain XP

}
</dascript>

Make sure you use your own follower's tag and not the example one :)

This script fires the party picker after hiring the follower. That is absolutely necessary via this method, as we have put the XP fix onto an event fired by the party picker. You cannot put the XP fix into this script, it must be called from a later one (the bug is caused by an errant call to an event in player_core, which will be executed AFTER this script).

The easiest way to use this script is directly from conversation, putting it as an action on a line of dialogue where the PC invites the follower to join them. If you're not sure how to associate a script with a dialogue line, see the following image:

[[File:hire_conv.jpg]]

Create your dialogue as normal, select the line you want to fire the script, and click the '''Plots and Scripting''' tab. Use the '''Script''' file chooser in the Action section to browse to the script you created.

If everything worked, you should see something like this:

[[File:picker_success.jpg|thumb|200px|center]]

== Advanced Follower Creation ==

Follow these steps to have full control over the creation of your follower, with options such as:

- Unique level-up template

- Class and specialisation chosen via script

- Any starting state

- Level higher than the PC

- Starts with a specialisation point rather than a specific specialisation

- Set plot flags in the call to the hire script

=== Prepare Creature, char_stage and Party Picker m2DAs ===

Follow the same steps to create your follower creature, char_stage and Party Picker m2DAs as above.

=== Create Party Plot ===

While not necessary, it's very helpful to have plot flags set when a follower is hired or joins/leaves the active party. This makes conversation interjections and the like very easy.

Create a plot with appropriate flags. There's no real need to associate journal text with them:

[[File:follower_plot.jpg]]

See FAQ for an alternative approach to plots when there are more than three potential party members.

=== Add Plot Flags to Party Picker Event Intercept ===

We then update our module script to make use of that plot, like so:

<dascript>
#include "utility_h"
#include "wrappers_h"
#include "plt_bc_create_party" //make sure you include your own plot, not mine

void main()
{
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);
switch(nEventType)
{
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0);
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE);

AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero()))); //Ensures follower appears at PC's location.

if (GetTag(oFollower) == "bc_party_miera") { //You must explicitly test for your follower's tag.
WR_SetPlotFlag(PLT_BC_CREATE_PARTY, PARTY_MIERA_IN_PARTY, TRUE); //Make sure you use your own flags!
}

break;
}

case EVENT_TYPE_PARTYMEMBER_DROPPED:
{
object oFollower = GetEventObject(ev, 0);

if (GetTag(oFollower) == "bc_party_miera") {
WR_SetPlotFlag(PLT_BC_CREATE_PARTY, PARTY_MIERA_IN_PARTY, FALSE); //As above, but set false.
}

}

}
}
</dascript>

=== Create a Level Up Template ===

You can skip this step if you're content to use one of the generic Rogue, Wizard or Warrior templates, but I don't recommend it. Making a template that suits your character is easy and will almost always be better for the player than a generic one that spends points poorly.

Go to \Program Files\Dragon Age\tools\Source\2DA (or wherever you installed Dragon Age).

You should see a number of excel sheets of the form '''ALCharacter.xls''' (such as ALAlistair.xls, ALLeliana.xls, ALRogue_Default.xls etc). Open the one closest to your character (ie Morrigan or Wynne for a wizard, Leliana or Zevran for a rogue). Save a copy as '''ALYourcharacter.xls''' in whatever directory you're using to create your 2DAs, remembering to rename the worksheet '''ALYourcharacter''' (in this example, ALMiera.xls with ALMiera as its worksheet).

It should look something like this:

[[File:ALtable.jpg|thumb|500px|center]]

'''Columns B''' and '''C''' are the talents/spells available to this character. Do not change them.

'''Columns F''' and '''G''' are the skills available to this character. Do not change them.

We will edit the remaining columns like so:

==== Setting Stat Weights ====

The stat weights in '''column J''' determine how the follower will spend their attribute points, in a rough ratio. So if Dexterity is set to 1.5 and Intelligence to 1, you should expect to see 3 points of Dex for every 2 points of Cunning in-game (note Intelligence is the label used in the toolset for Cunning).

Simply change the values in J to reflect how you'd like the character to spend their points. In this example we're creating a wizard, so we're not going to mess around:

[[File:miera_stat_weights.jpg]]

This character will only raise magic. I set the value to 5 rather than something like 1 to provide room underneath for the other stats while still overwhelmingly favouring magic, but in practice I only really ever want that one stat.

In a note left on this column in the existing templates, Bioware's Georg Zoeller writes, "This is the weight of each attribute (row id links into properties.xls.id). 1.0 means 'try to keep this attribute level' (spend 1 point per level). 0.5 means 'try to spend 1 point every two levels' and so on."

The default Mage, Rogue and Warrior templates include '''column L''' labeled "AttInit." Editing these values seems to have no effect on followers set to use these templates.

==== Setting Talent and Skill Priorities ====

'''Columns D''' and '''E''' are the talents/spells that the character will buy, in preference order from top to bottom.

'''Columns H''' and '''I''' are the skills that the character will buy, in preference order from top to bottom.

To change these, just copy the appropriate two cells from columns B&C or F&G over the ones you want to replace.

For example, here we're copying Morrigan's template. Morrigan has Spider Shape high in her preferences, which we do not want.

[[File:AlMori_talent_pref.jpg]]

We decide we'd prefer Flame Blast, so we find it in columns B&C and copy both cells:

[[File:ALMori_copy.jpg]]

Then we select the cells we want to replace in columns D&E and paste over them:

[[File:ALMori_paste.jpg]]

Continue this process until your priorities list for both skills and talents/spells is exactly as you want it. Make sure you have at least as many priorities as the core follower you're copying - points that cannot be spent according to these priorities have a habit of vanishing.

If you used any abilities from a specialisation, make sure you remember to set that specialisation with the function we'll introduce later. The autolevel scripts will add specialisation abilities to a character regardless of whether they have that spec or not.

==== Create a M2DA_base_ m2DA ====

Dragon Age will need to know where to find your autolevel template. We tell it by extending M2DA_base.gda

Create a spreadsheet with the name and worksheet name in the form '''M2DA_base_''' with your unique suffix (in this example, M2DA_base_fofbc.xls with M2DA_base_fofbc as a worksheet).

Set up its columns and data like so (note I used GDApp because Open Office wasn't cooperating for this one!):

[[File:m2da_base_fofbc.jpg]]

The '''ID''' should be very high to avoid conflicts. I've arbitrarily chosen 50,000+ here. Carefully note the ID you've chosen for your character, you will need it later.

Set the '''Label''' and '''Worksheet''' to be the name of your autolevel template worksheet (ALCharactername if you've been following this).

Set the '''PackageIDForAI''' to be 0, it shouldn't be needed for followers.

When you're done, use ExcelProcessor to make GDAs of both spreadsheets and copy them to your module's export folder.

FOR AUTOLEVEL TO WORK AFTER RECRUITING:

Look in packages.xls.
There is a column called LevelupTable. That links to a corresponding AL* table. For instance, row 81 is for Leliana. Her LevelupTable value is 258. If you look that up in 2DA_base, you'll see it links to ALLeliana.
(alternatively, you could try packages_base.gda)

=== Create a New Hire Function Include ===

This section is probably only relevent if you have a specific need to override the functionality of player_core.

Many vital steps of follower addition happen inside an event in player_core. Followers tend to be extremely buggy (no skill tree, for example) if this event does not fire.

However, that event is not very flexible. In order to control it to our requirements, we need to replicate its functionality inside our own script. This is probably much safer than messing with player_core directly!

Create a new script file, naming it something like '''hireCustomFollower_h'''. We will be including this wherever we want to hire a follower.

Paste in the following script:

<dascript>
#include "sys_chargen_h"
#include "wrappers_h"
#include "utility_h"
#include "sys_rewards_h"
#include "approval_h"
#include "sys_autolevelup_h"

/* Jye Nicolson 5-Jan-2010
This function set duplicates the full functionality chain of UT_HireFollower, with the following exceptions:

- Followers can gain XP
- Autolevel status can be set (default off)
- Followers can be set to any starting state (default Available) and will still be properly initalised and added to the party pool
- Autolevel tables for non-core followers can be explicitly set.
- Class and Specialisation can be chosen via script
- Followers without specialisations are granted a spec point by default.

It should only ever be called once each for characters you intend to be full followers.
Much of the protective code handling summoned creatures etc. in player_core is not present here.

Calling the function:

Simple:

hireCustomFollower(oFollower, CLASS_WARRIOR);

Change the class to CLASS_WIZARD or CLASS_ROGUE as appropriate.
This will hire your follower and make them available.
They will auto level up with a default package, and receive a free spec point.

Best Practice:

hireCustomFollower(oFollower, CLASS_WARRIOR, PLT_YOUR_PARTY_PLOT, YOUR_FOLLOWER_JOINED_FLAG, ABILITY_TALENT_HIDDEN_CHAMPION);

Where the plot and flag are those for your module (remember to create the plot and include it on the calling script), and ABILITY_TALENT_HIDDEN etc is the desired spec.

You should also have a custom ALTable set up.
See wiki for details, and remember to edit it in to GetCustomFollowerALTable below or pass it directly as an argument to hireCustomFollower.

Full argument list:

void hireCustomFollower (
object oFollower, //Pass your follower object, mandatory

int nForceClass, //Pass a Class constant here, usually CLASS_ROGUE, CLASS_WARRIOR, CLASS_WIZARD. Mandatory due to a bug.

string sPlot = "", //It's recommended you have a plot flag to be set when the follower joins. Pass the plot constant here. Remember to #include in calling script

int nPlotFlag = "", //And then pass the flag constant. Will be set to TRUE if available.

int nForceSpec = 0, //This is the ID of the Specialisation you want. Note they are NOT classes, but abilities. The full list is:
//ABILITY_SPELL_HIDDEN_ARCANE_WARRIOR, ABILITY_SPELL_HIDDEN_BLOODMAGE, ABILITY_SPELL_HIDDEN_SHAPESHIFTER, ABILITY_SPELL_HIDDEN_SPIRIT_HEALER
//ABILITY_SPELL_HIDDEN_BARD, ABILITY_TALENT_HIDDEN_ASSASSIN, ABILITY_TALENT_HIDDEN_DUELIST, ABILITY_TALENT_HIDDEN_RANGER
//ABILITY_TALENT_HIDDEN_BERSERKER, ABILITY_TALENT_HIDDEN_CHAMPION, ABILITY_TALENT_HIDDEN_REAVER, ABILITY_TALENT_HIDDEN_TEMPLAR
//I recommended forcing a spec, particularly if your ALTable includes abilities from one.

int nALTable = 0, //This is the ID of an ALTable from 2DA_base.GDA or your module's m2DA_base_*.GDA I recommended the latter, but you can edit that into GetCustomFollowerALTable below rather than passing it.

int bInvokePicker = FALSE, //Sets whether the party picker should be opened on hiring. I think it's cleaner to call the picker outside this script, particularly if you have multiple hires at once.

int nInitialState = FOLLOWER_STATE_AVAILABLE, //This sets whether the follower joins the active party or not. Options are:
//FOLLOWER_STATE_ACTIVE (put them in the active party)
//FOLLOWER_STATE_LOCKEDACTIVE (force them into the active party and keep them there, remember to change this later.
//FOLLOWER_STATE_AVAILABLE (make them available on the party picker (if you've set it up for them), but not in the active party)
//Plus some others you're unlikely to need at this time. Defaults to AVAILABLE because having 4+ active followers is screwy.

string sCurrPlot = "", //If you set FOLLOWER_STATE_ACTIVE or FOLLOWER_STATE_LOCKEDACTIVE, the script will check to see if you passed this.
//It is recommended that you have a plot flag set for a given follower being in the active party, this makes conversation interjection etc. much easier.

int nCurrPlotFlag = 0, //This flag will be set if FOLLOWER_STATE_ACTIVE or FOLLOWER_STATE_LOCKEDACTIVE are true
//AND sCurrPlot has a value AND nCurrPlotFlag is > 0.
//ie if you added someone to the active party and have a plot flag to cope with it.

int nAutolevel = 0, //Sets the Autolevel flag on the character sheet. 0 is off, 1 is on, 2 forces it on and removes it so the player can't turn it off.

bFreeSpecPoint = TRUE, //This grants a specialisation point to the follower if they do not have a specialisation.
//It's important to set this false for classes that do not have specs, such as CLASS_DOG.

int nTargetLevel = 0, //If you want a specific level, set this. Generally not worthwhile unless you set it higher than the player, since they'll just get XP from the party picker anyway.

int nMinLevel = 0 //Set this if there's a specific level you don't want the follower to go below. Probably only useful if the PC might be very low level but not necessarily so.

)
*/
/* GetCustomFollowerALTable()
This function is where you put your custom table assignments.

You should explicitly test for the tag of your follower (not mine!) and assign a value to nTable from your m2DA extension to M2DA_base

See wiki for details on how to do this, or ignore it to get the default Warrior/Rogue/Wizard AL tables.

NOTE: you MUST explicitly set a table for non-Warrior/Rogue/Wizards, eg dogs. Use TABLE_AL_DOG for a default Mabari.
*/

int GetCustomFollowerALTable(object oFollower) {
int nTable = _GetTableToUseForAL(oFollower);

if (GetTag(oFollower) == "bc_party_miera") {
nTable = 50143;
}

if (GetTag(oFollower) == "bc_party_jysavin") {
nTable = 50144;
}

if (GetTag(oFollower) == "bc_party_geldual") {
nTable = 50145;
}

if (GetTag(oFollower) == "bc_party_braghon") {
nTable = 50146;
}

return nTable;
}

// This just cleans up the main function a little

int GetCustomFollowerTargetLevel(object oFollower, object oHero, int nPackage, int nMinLevel = 0) {
int nPlayerLevel = GetLevel(oHero);
int nTargetLevel = 0;

if((nPlayerLevel >= 13) || (nPlayerLevel == 1) || (!_UT_GetIsPlotFollower(oFollower))) {
nTargetLevel = nPlayerLevel;
} else {
nTargetLevel = nPlayerLevel + 1;
}

if (nMinLevel == 0) { //If nMinLevel is not specified, checks package 2DA for a value
nMinLevel = GetM2DAInt(TABLE_PACKAGES, "MinLevel", nPackage);
}
if(nMinLevel > 0 && nMinLevel > nTargetLevel) {
nTargetLevel = nMinLevel;
}

return nTargetLevel;

}

// Moving this black box out :) I don't really understand it, but it should function if you have tactics set up in a package.

void InitCustomFollowerTactics(object oFollower, int nPackage) {
int nTableID = GetM2DAInt(TABLE_PACKAGES, "FollowerTacticsTable", nPackage);
if (nTableID != -1)
{
int nRows = GetM2DARows(nTableID);
int nMaxTactics = GetNumTactics(oFollower);

int nTacticsEntry = 1;
int i;
for (i = 1; i <= nRows && nTacticsEntry <= nMaxTactics; ++i)
{
int bAddEntry = FALSE;
int nTargetType = GetM2DAInt(nTableID, "TargetType", i);
int nCondition = GetM2DAInt(nTableID, "Condition", i);
int nCommandType = GetM2DAInt(nTableID, "Command", i);
int nCommandParam = GetM2DAInt(nTableID, "SubCommand", i);

int nUseType = GetM2DAInt(TABLE_COMMAND_TYPES, "UseType", nCommandType);
if (nUseType == 0)
{
bAddEntry = TRUE;
}
else
{
bAddEntry = HasAbility(oFollower, nCommandParam);
}

if (bAddEntry)
{
SetTacticEntry(oFollower, nTacticsEntry, TRUE, nTargetType, nCondition, nCommandType, nCommandParam);
++nTacticsEntry;
}
}
}
}

/* InitCustomFollowerSpec:

This function tries to set the forced Specialisation. If there is none, it checks the package for one.

If there isn't either of those, it grants a free spec point if bFreeSpecPoint is true.

*/

void InitCustomFollowerSpec(object oFollower, int nPackage, int nForceSpec, int bFreeSpecPoint) {
// Find specialization, and optionally add a spec point if none is found.

if (nForceSpec == 0) {

int nSpecAbility = GetM2DAInt(TABLE_PACKAGES, "switch1_class", nPackage); // followers can have only 1 advanced class
if(nSpecAbility > 0)
{
AddAbility(oFollower, nSpecAbility);
} else {
if (bFreeSpecPoint) {
SetCreatureProperty(oFollower, 38, 1.00);
}
}

} else {

AddAbility(oFollower, nForceSpec);

}
}

/* hireCustomFollower() (See doco at top of page)

I strongly suggest you reorder the parameters if you're adding many followers with advanced options.

Feel free to leave them alone if you only want to set class, plot, spec or don't mind long declarations.

Note nForceClass is currently compulsory due to flakiness with GetCreatureCoreClass()
*/

void hireCustomFollower(object oFollower, int nForceClass, string sPlot = "", int nPlotFlag = 0, int nForceSpec = 0,
int nALTable = 0, int bInvokePicker = FALSE, int nInitialState = FOLLOWER_STATE_AVAILABLE, string sCurrPlot = "",
int nCurrPlotFlag = 0, int nAutolevel = 0, int bFreeSpecPoint = TRUE, int nTargetLevel = 0, int nMinLevel = 0)
{

object oHero = GetHero();

/* ################# BEGIN BASIC FOLLOWER JOIN BLOCK ###################

This loosely replicates WR_SetFollowerState.

*/

if (nForceClass == 0) {
nForceClass = GetCreatureCoreClass(oFollower); //This is not working. Hence nForceClass mandatory.
}

SetGroupId(oFollower, GetGroupId(oHero)); //Puts the follower in the pc's Group.
SetEventScript(oFollower, RESOURCE_SCRIPT_PLAYER_CORE); //This makes them act like a player.
SetFollowerState(oFollower, nInitialState); //This sets whether they are available, in the active party etc.

/* ################# END BASIC FOLLOWER JOIN BLOCK ##################### */

/* ################# BEGIN PLAYER_CORE EVENT_TYPE_PARTY_MEMBER_HIRED EMULATION #################
This replicates the EVENT_TYPE_PARTY_MEMBER_HIRED handler from player_core, stripped down for simplicity and allowing our custom options.

*/

Chargen_EnableTacticsPresets(oFollower); //I assume this is important.

SetLocalInt(oFollower, FOLLOWER_SCALED, 1); //This should prevent the follower being rescaled by player_core or what have you

int nPackage = GetPackage(oFollower); //Gets the package, which will be used to find a number of 2DA IDs.
int nPackageClass = GetM2DAInt(TABLE_PACKAGES, "StartingClass", nPackage); //I don't think this is used, even by player_core

// set behavior according to package
int nBehavior = GetM2DAInt(TABLE_PACKAGES, "FollowerBehavior", nPackage);

if(nBehavior >= 0) {
SetAIBehavior(oFollower, nBehavior);
}

Chargen_InitializeCharacter(oFollower); //We initialise the follower and choose race/class.

Chargen_SelectRace(oFollower,GetCreatureRacialType(oFollower));
Chargen_SelectCoreClass(oFollower,nForceClass);

if (nTargetLevel == 0) { //This block picks a target level if not specified

nTargetLevel = GetCustomFollowerTargetLevel(oFollower, oHero, nPackage, nMinLevel);
}

int nXp = RW_GetXPNeededForLevel(Max(nTargetLevel, 1)); //Here is where the XP is calculated and rewarded
RewardXP(oFollower, nXp, FALSE, FALSE);

// -------------------------------------------------------------
// add hidden approval talents - (JN: I don't know how to set these yet, but when I figure it out this should make it work)
// -------------------------------------------------------------
int nIndex = Approval_GetFollowerIndex(oFollower);
Approval_AddFollowerBonusAbility(nIndex, 0);

//Handle Specialisation
InitCustomFollowerSpec(oFollower, nPackage, nForceSpec, bFreeSpecPoint);

// -------------------------------------------------------------
// This spends all available attribute and stat points on the
// creature according to the levelup table. (JN: this replicates AL_DoAutoLevelUp but with our choice of table)
// -------------------------------------------------------------

if (nALTable == 0) {
nALTable = GetCustomFollowerALTable(oFollower);
}

AL_SpendAttributePoints(oFollower, nALTable, FALSE);
AL_SpendSkillPoints(oFollower, nALTable, TRUE);
AL_SpendSpecializationPoints(oFollower, nALTable);
AL_SpendTalentSpellPoints(oFollower, nALTable, TRUE);

// -------------------------------------------------------------------------
// Update various UIs
// -------------------------------------------------------------------------
Chargen_SetNumTactics(oFollower);
SetCanLevelUp(oFollower,Chargen_HasPointsToSpend(oFollower));

// load tactics
InitCustomFollowerTactics(oFollower, nPackage);

/* ################# END PLAYER_CORE EVENT_TYPE_PARTY_MEMBER_HIRED EMULATION ################# */

SetAutoLevelUp(oFollower, nAutolevel); //This is the autolevel flag on the character sheet.

//Set plot flags

if (!((sPlot == "") || (nPlotFlag == 0))) { //Joined Party
WR_SetPlotFlag(sPlot, nPlotFlag, TRUE);
}

if ((nInitialState == FOLLOWER_STATE_ACTIVE) || (nInitialState == FOLLOWER_STATE_LOCKEDACTIVE)) {
if (!((sCurrPlot == "") || (nCurrPlotFlag == 0))) {
WR_SetPlotFlag(sCurrPlot, nCurrPlotFlag, TRUE); //Currently in Party
}
}

// Invoke picker if requested.

if (bInvokePicker) {
SetPartyPickerGUIStatus(2);
ShowPartyPickerGUI();
}
}
</dascript>

Yeah, I know. It can't really be any smaller. Feel free to modify it if you're confident with scripting.
==== Add Your Custom Autolevel Template to GetCustomFollowerALTable() ====
While you can pass the ID you made for your autolevel template to that monster function as an argument, it's better to have them all in one place if you have multiple followers.

GetCustomFollowerALTable() is the first function in our include, and you can add an explicit if test for your follower there to assign the correct table id (the one from your M2DA_base_ m2DA). There is a function very much like it in sys_autolevel_h.nss for the core followers, so we'll copy Bioware's practice.

Let's take a look at the function by itself:

<dascript>
int GetCustomFollowerALTable(object oFollower) {
int nTable = _GetTableToUseForAL(oFollower);

if (GetTag(oFollower) == "bc_party_miera") {
nTable = 50143;
}

if (GetTag(oFollower) == "bc_party_jysavin") {
nTable = 50144;
}

if (GetTag(oFollower) == "bc_party_geldual") {
nTable = 50145;
}

if (GetTag(oFollower) == "bc_party_braghon") {
nTable = 50146;
}

return nTable;

}
</dascript>

So we have a test for each follower tag from my module, matching up to an ID which is assigned to nTable. All you need to do is change a tag from my follower to yours, and my ID to the correct one from your M2DA_base_* m2DA. Then you should delete the rest of the example if statements :)

Save and export the script. Ignore the compiler error about lack of main();

=== Include Function In Your Hire Script and Call It ===

So instead of a hire script that calls UT_HireFollower(), we want one that includes our shiny new function and calls it.

Take a look at the following example:

<dascript>
#include "plt_bc_create_party" //Make sure you include your party handling plot
#include "hireCustomFollower_h" // And include the function script - which will in turn include a bunch of stuff

void main() {

//Initialising my objects, not super-relevant to the example

object oHero = GetHero();
object oMiera = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_miera.utc", GetLocation(oHero));
object oJysavin = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_jysavin.utc", GetLocation(oHero));
object oBraghon = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_braghon.utc", GetLocation(oHero));
object oSpider = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_geldual.utc", GetLocation(oHero));

//Simplest hire call - adds to the party as a wizard. Class is currently compulsory due to a bug.
hireCustomFollower(oMiera, CLASS_WIZARD);

//Add to the party and set joining plot flags
hireCustomFollower(oJysavin, CLASS_WARRIOR, PLT_BC_CREATE_PARTY, PARTY_JYSAVIN_JOINED);

//Add to the party, set plot flags, force a specialisation
hireCustomFollower(oBraghon, CLASS_ROGUE, PLT_BC_CREATE_PARTY, PARTY_BRAGHON_JOINED, ABILITY_TALENT_HIDDEN_ASSASSIN);

//More complex example - Follower added as a unique class (Dog), not granted a specialisation or spec point.
//Note unique classes must have an ALTable passed here or specified in GetCustomFollowerALTable() or they won't work
hireCustomFollower(oSpider, CLASS_DOG, PLT_BC_CREATE_PARTY, PARTY_GELDUAL_JOINED, 0, 0, FALSE, FOLLOWER_STATE_AVAILABLE, "", 0, 0, FALSE);

//Show the party picker to let the player choose from their new companions!
SetPartyPickerGUIStatus(2);
ShowPartyPickerGUI();
}
</dascript>

The example shows several of the more simple ways of invoking the function. Check the comments at the start of the function for a full list of arguments.

I would suggest best practice for most followers would be to call as follows:

'''hireCustomFollower(oFollower, CLASS, PLOT, PLOT_FLAG, SPECIALISATION)'''

This will safely set the follower up as the desired class and specialisation (doubly important if there are spec abilities in their ALTable) while setting your plot flag for them being in the party. hireCustomFollower(oFollower, CLASS, PLOT, PLOT_FLAG, SPECIALISATION, 0, TRUE) will do the same while invoking the Party Picker automatically.

Note that the specialisations are abilities and not classes - you'll find them as ABILITY_HIDDEN_ constants.

If it's all worked, you should find you can now add followers with a lot more flexibility!

[[File:picker_advanced.jpg|thumb|500px|center]]

== Common Follower Problems & FAQ ==

====Why don't my followers gain XP?====
There is a bug in UT_HireFollower. Make a copy of UT_HireFollower in a function of your own, then make the following change:
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, TRUE);
to
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, bPreventLevelup);

====When I choose followers from the Party Picker, they spawn into the area but do not join.====

You need to intercept the EVENT_TYPE_PARTYMEMBER_ADDED event and set the follower to FOLLOWER_STATE_ACTIVE. See Simple Follower Creation earlier in this document.

====My followers don't have skill trees!====

If a follower hasn't been through an initial chargen/autolevel event (via player_core/sys_autolevel_h) then the skill tree doesn't show. You're probably trying to be clever and get around UT_HireFollower without going all the way (see monster function above ^_^).

====My followers don't have a class====

GetCreatureCoreClass() seems flaky under some conditions. It's best to explicitly set the class yourself; this is why class is currently a mandatory argument to hireCustomFollower()

====Dog talents and equipment slots don't work====
Symptoms: dog talents appear on the talents screen but remain greyed out on level up. Warrior talents appear in the quickslots. Equipment slots are for humans, not dogs.

Line 78 of packages_base in packages.xls (Dog) should have the LevelUpTable column set to 257 which is the ALDog table.

The EquipmentLayout 2DA needs a new entry for the follower:

ID=same as partypicker 2DA
Tag=follower tag
AvailableEquipmentSlots=794624
Layout=2
EnableWeaponSets=0

If the creature is not using the appearance "Dog, Party Member", it needs a new appearance line in APR_base. Most of the entries can be copied from the standard appearance (e.g. Wolf), but

MaxScaleLevel=-1
DefaultArmor=
AppearanceRestrictionGroup=1

Otherwise, it won't be able to progress beyond a specified level. The player will receive an unwanted set of armour when the it is hired, and it won't be able to use Marabi crunch items. You may also need to tweak PERSPACE and/or BumpLevel if excessive clipping occurs.

====Isn't there an easier way to do this?====

Possibly. There is a way of recruiting a follower by setting a plot flag. However I don't understand it, and I expect it still doesn't allow custom autolevel templates, full control over specialisations etc. There's still a fair bit of stuff hardcoded for the core followers, I'm not sure putting a custom follower through the same process as Al, Leli et al will have good results.

The next section answers this question, up to a point.

==== What if there are more than three potential followers? ====
This example handles larger numbers of followers, and doesn't force the player to use the party picker unless the party is already full.

The prefix zzz, used throughout, can be replaced with whatever [[Prefixes_in_use | prefix]] you are using for your resources.

If you're making a new campaign, to keep life simple, allocate a unique number to each follower. You could either use a creature variable or a script, e.g.
<pre>
// Party member id (e.g. 1=Alicia, 2=Godwin...)
int zzzPartyMemberID(object oPartyMember)
{
string sPartyMember = GetTag(oPartyMember);

if (sPartyMember == "zzzcr_alicia") return 1;
if (sPartyMember == "zzzcr_godwin") return 2;
if (sPartyMember == "zzzcr_harold") return 3;
if (sPartyMember == "zzzcr_lara" ) return 4;
return 0;
}
</pre>

Make two separate plots, e.g. zzzpt_hired for when a follower is first recruited, and zzzpt_party to flag whether they're currently in the party. Use flag values that correspond to the unique follower id, e.g. ZZZPT_HIRED_GODWIN will be 2.

If you're modifying the official campaign, you won't be able to make this simplification - you'll need a set of plot flags for your new party members, similar to the official ones. The logic of what follows is still correct, it just means that instead of having one set of common code that works for everyone, you have to explicitly script each party member individually using their personal plot flags.

Follower conversation is now very simple. In Godwin's dialogue, the hiring line will be conditional - when ZZZPT_HIRED_GODWIN is clear - and it will set ZZZPT_HIRED_GODWIN. No conversation script is necessary. Instead, in the properties of the plot zzzpt_hired, we add a plot event script, as follows.
<pre>
// PARTY HIRE PLOT SCRIPT
//
// This is called in conversation when a party member is hired for the first time.
// If the party is full, the party picker is displayed, which forces the PARTYMEMBER_ADDED
// module event.
//
// The flag value is never referenced, because the code is common for all party members.

#include "events_h"
#include "global_objects_h"
#include "utility_h"
#include "sys_rewards_h"
#include "log_h"
#include "utility_h"
#include "wrappers_h"
#include "plot_h"

#include "zzz_h" // A header containing the zzzPartyMemberID function
#include "plt_zzzpt_hired"
#include "plt_zzzpt_party"

int StartingConditional()
{
event eParms = GetCurrentEvent();
int nType = GetEventType(eParms); // GET or SET
string strPlot = GetEventString(eParms, 0); // Plot GUID
int nFlag = GetEventInteger(eParms, 1); // Plot flag
object oParty = GetEventCreator(eParms); // Plot table owner
object oFollower = GetEventObject(eParms, 0); // Conversation owner (if any)
int nPlotType = GetEventInteger(eParms, 5); // Plot type

int bIsTutorial = GetM2DAInt(TABLE_PLOT_TYPES, "IsTutorial", nPlotType);
int bIsCodex = GetM2DAInt(TABLE_PLOT_TYPES, "IsCodex", nPlotType);

int nResult = FALSE; // return value for DEFINED GET
object oPC = GetPartyLeader();

plot_GlobalPlotHandler(eParms); // any global plot operations, including debug info

if (nType == EVENT_TYPE_SET_PLOT) // actions -> normal flags only
{
int nValue = GetEventInteger(eParms, 2); // 0=Clear 1=Set
int nOldValue = GetEventInteger(eParms, 3); // Current flag value

if (nValue)
{
if (GetArraySize(GetPartyList(oPC)) < 4)
{
// Code from UT_HireFollower with level up bug fixed
SetAutoLevelUp(oFollower, 2);
SetGroupId(oFollower, GetGroupId(GetHero()));
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, FALSE);
// End of code from UT_HireFollower
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero())));
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), TRUE);
}
else
{
WR_SetFollowerState(oFollower, FOLLOWER_STATE_AVAILABLE, FALSE);
SetEventScript(oFollower, RESOURCE_SCRIPT_PLAYER_CORE);
SendPartyMemberHiredEvent(oFollower, TRUE);
// SetPartyPickerGUIStatus(PP_GUI_STATUS_USE);
// ShowPartyPickerGUI();
}
}
}
else // EVENT_TYPE_GET_PLOT -> defined conditions only
{
switch(nFlag)
{

}
}

plot_OutputDefinedFlag(eParms, nResult);
return nResult;
}
</pre>
We still need to handle the party picker events in our module event script:
<pre>
// PARTY MEMBER ADDED - Allow XP gain. Come here, follow me, flag as party member.
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0);
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero())));
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE);
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), TRUE);
break;
}
// PARTY MEMBER DROPPED - flag as not party member.
case EVENT_TYPE_PARTYMEMBER_DROPPED:
{
object oFollower = GetEventObject(ev, 0);
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), FALSE);
}
</pre>
When we need to refer to a particular follower explicitly, we can still do so - for example, the flag ZZZPT_PARTY_GODWIN will tell use whether Godwin is currently in the party or not.

==== How do I turn off sustained abilities when a follower is dismissed? ====
'''Please note:''' The 1.04 DA:O patch is bugged and removed/broke several features of the toolkit, if you are using it please follow [http://social.bioware.com/forum/1/topic/71/index/3172230/1#3172537 these steps] to re-enable them as one is required for the script below to compile.

There is a potential exploit in what we've done so far. If a follower casts a sustained spell like Flaming Weapons, it affects all party members. When the follower is dismissed, the remaining party members continue to benefit from the spell.

We can prevent this by deactivating modal abilities before opening the party picker. Add these snippets to the module event script:
<pre>
#include "ability_h"
void zDeactivateModalAbilities();
</pre>
and
<pre>
case EVENT_TYPE_PARTYPICKER_INIT:
{
// Deactivate party modal abilities. This ensures that the party no longer benefits
// from spells like Flaming Weapons if the caster is dismissed from the party.
zDeactivateModalAbilities();
break;
}
</pre>
The function looks like this:
<pre>
// Deactivate party's modal abilities

void zDeactivateModalAbilities()
{
object oPC = GetHero();
object [] oFollowerTable = GetPartyList(oPC);
object oFollower;
int nPartySize = GetArraySize(oFollowerTable);
int [] nAbilityTable;
int nAbilityCount;
int nAbility;
int i = -1;
int j;

while (++i < nPartySize)
{
oFollower = oFollowerTable[i];
nAbilityTable = GetAbilityList(oFollower);
nAbilityCount = GetArraySize(nAbilityTable);
j = -1;

while (++j < nAbilityCount)
{
nAbility = nAbilityTable[j];

if (Ability_IsAbilityActive(oFollower, nAbility))
if (Ability_IsModalAbility(nAbility))
Ability_DeactivateModalAbility(oFollower, nAbility);
}
}
}
</pre>
If other ways of dismissing party members are permitted, the same function can be used.

== Advanced Follower Creation: An Alternative Approach ==

While these things are to a large extent a matter of taste, I see no reason to reinvent the wheel when there is a perfectly good wheel at hand. The following describes how to adapt the existing machinery for the recruitment and tracking of your own party members.

First create the setup as described above in Simple Follower Creation, except for the scripts and plot tables. In addition, create the GDA extensions for a level-up table and the M2DA which points to those tables, as described in Advanced Follower Creation above.

Now ...

=== Step 1: Create a party plot table ===

Have a look at the gen00pt_party plot table and create a similar table for your own followers. Don't bother with the Defined Flags for the moment, just the Main Flags will do, ie recruited, in-camp and in-party for each follower. (Critical Note: Do not duplicate the plot table, create one from scratch. This is the case for ALL plot tables because of a show-stopping bug which means a new GUID is not assigned on Duplicate of a plot.)

=== Step 2: Create a party script ===

Duplicate the gen00pt_party script and rename for your module (conventionally plot tables and their plot scripts have the same name). Delete (or comment out) the Defined Flags section at the end and any lines dealing with logging and tutorials. Change names to those of your party members. If you are using gifting, approval or forced inclusion you may wish to retain those sections of code, but additional machinery will be needed for these facilities to work. For approval you can specify a starting level of approval here for each follower if you want it to be other than zero (as per the existing section dealing with Dog). Note that the custom hire function at the head of the script allows you to specify whether or not to invoke the party picker on recruitment. You may not want to do so for the first couple of followers (but see below). You should already have defined all required constants in a separate file for your module, eg <module prefix>_constants_h. If not, do so now and include it, as well as your plot table, at the head of the script. Delete includes that only refer to the main campaign. (If this is all Greek to you, spend a couple of hours examining the set-up of the Demo, which is packaged with the toolset, and go through the introductory tutorials referenced on the main page of this wiki).

Looking at the new party script, notice that the follower-in-camp function is not defined. This is because for some arcane reason it is defined in party_h, and unhappily references the main campaign's plot table. So we will have to create a new function to replace it, change the other function's flag reference (for the sake of neatness), and change the call in the main body of the script. (You may decide later for other reasons to replicate and customise party_h, but that won't interfere with re-creating this function here.)

Our two functions at the head of the script should be:

<dascript>void SetFollowerInParty(object oFollower, string sPlot, int nCampFlag)
{
WR_SetPlotFlag(sPlot, nCampFlag, FALSE);
WR_SetObjectActive(oFollower, TRUE);
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE);
command cJump = CommandJumpToObject(GetPartyLeader());
WR_AddCommand(oFollower, cJump);
}

void SetFollowerInCamp(object oFollower, string sPlot, int nPartyFlag)
{
WR_SetPlotFlag(sPlot, nPartyFlag, FALSE);
WR_SetObjectActive(oFollower, FALSE);
WR_SetFollowerState(oFollower, FOLLOWER_STATE_AVAILABLE, FALSE);
}</dascript>

and the line in the in-camp sections for each follower should now be:

<dascript>SetFollowerInCamp(o<follower>, strPlot, <follower>_IN_PARTY);</dascript>

=== Step 3: Create package GDAs and reference them in you 2DA_base extension ===

Look at the packages_base GDA and create an extension GDA with one line for each follower based on a main campaign follower that is most like your own follower, eg a sword-shield warrior can be a copy of Alistair, a battle mage a copy of Morrigan, etc. You can look at the Excel version of this GDA to more easily see what the fields mean. It is here that you can specify what if any specialisation will be assigned on hire and the level at which this spec point becomes available. (The IDs for each spec are in the 4000-range of ABI_base.)

Most importantly, it is here also that you define the ID of both your level-up table and the AIP table you are about to create.

Now create aip_follower_<follower name> gda tables, again based on a existing tables most like your own followers. No changes should be required to the copies you create.

In the m2da_base_<your module> extension you have already created, add lines for your AIP tables with a package ID referencing the IDs you assigned in your packages extension table.

Carefully check that all IDs in your GDAs are correct and cross-reference properly, and save the GDAs to your override directory.

Desirable but not obligatory (except for non-humanoid characters), is an extension to the Portraits gda. Finally the Equipment Layout gda will need an extension for non-humanoids, who use a different equipment mask.

=== Step 4: Module script addition ===

Modify your own module script to point to the new plot table and your own followers. To see an example of the required code for the two new sections look at the relevant section of module_core, which are for EVENT_TYPE_PARTYMEMBER_ADDED and EVENT_TYPE_PARTYMEMBER_DROPPED.

=== How it works ===

The recruit flag is set in a conversation (usually, but it could be a script) and that event is then processed by the plot script, which among other things sets both the in-camp and in-party flags, and fires up the party picker by default. If the player then selects the follower in the picker, the in-camp flag is unset (or vice versa if the follower is not selected to join). Subsequently, if the character is selected (or unselected) in the picker, the event is picked up by the module script, which sets the relevant plot flag as true, and that plot event is then sent to the plot scipt which sets the other flag as false.

(Note that if the party picker is turned off for a particular follower's recruit event, that follower will be placed in the active party regardless of the number of members, so ONLY do this for a follower who cannot be recruited when there are already 3 possible followers.)

On recruitment, player_core rebuilds the character according to the specifications laid out in the GDAs, so no further scripting is required.

=== Uses ===

To recruit a party member, set the recruit flag from your plot table in the relevant dialogue. Adding or subtracting followers from the active party is automatically tracked via this machinery, and the plot flags can be interrogated in all your scripts and conversations if you need to know who is currently in the party and who is in camp.

Defined flags can be added as you need them to the script and plot table but there is no point having flags that you will not use, so as with all Defined Flags this is an as-you-go decision, but quite easy to do.

Hiring and firing of temporary party members at the start of a campaign (such as Ser Jory, or Jowan, or Soris, etc) can be handled by UT_HireFollower, and the party picker is not invoked (nor is the Party Camp an available destination).

=== Troubleshooting ===

If you haven't done so already, create a simple debugging area for your module where you can dump the player, all followers and a couple of conversation dummies, and set up a dialogue in which you can invoke all required flags and conditions and see if they actually work as expected. (This setup can be used to test many other components as well.) Global machinery such as this can be painful to set up and get right (unless you are of an exceptionally methodical cast of mind), but it is worthwhile to ensure they are absolutely bullet-proof before you develop the specifics of your module.

=== The KISS principle ===

This is an "out-of-the-box" solution, and once set up is quite robust. If you want variants not catered for here, do NOT try to modify what you already have working.

'''Use-case:''' You want a follower (example tag: dairren) to be recruited without a set specialisation and one level higher than the PC.

Go to your packages gda and set the spec field to 0. In the character's plot table (you should have at least one for each follower) create a flag which we will call BLAH_BLAH. In the table's plot scipt insert the following very simple event handler:

<dascript>case BLAH_BLAH:
{
SetCreatureProperty(oDairren, 38, 1.00); //awards the spec point; field from the properties gda
int aLevel = GetLevel(oHero); //some simple arithmetic to find out the XP we need to award
int bLevel = (aLevel+1);
int aPoints = RW_GetXPNeededForLevel(aLevel);
int bPoints = RW_GetXPNeededForLevel(bLevel);
int targetPoints = (bPoints - aPoints);
RewardXP(oDairren, targetPoints, FALSE, TRUE); //award the XP, and we're done
break;
}</dascript>

The flag can be set in the same conversation as the recruit flag, so long as it comes afterwards. This way you not only maintain the integrity of your core machinery, but keep exceptions/variations for particular characters where they belong -- with that character's plot tables and scripts.

[[Category:Tutorials]]
{{Languages}}

Follower tutorial

2011-06-15T16:41:46Z

Proleric1: /* Why don't my followers gain XP? */

== Simple Follower Creation ==

Follow these steps to create a follower that

- Levels up with a default package

- Can be chosen from the party picker

- Can gain XP

This guide assumes you know how to create a creature and are comfortable with basic scripting.

You should only use this simple method if you are sure there will be empty space in the active party when your follower is recruited.

A more comprehensive approach when there are more than three potential party members is discussed in the FAQ below. It's worth taking the time to understand the basics first, though.

=== Create the creature ===

Create a creature to act as your follower. Set its name, appearance, gender, head morph, conversation, inventory etc as you want them to behave in-game.

Set an appropriate '''Tag''' (you'll be using it a lot). I suggest "party_charname".

Make sure you choose a '''Class'''. For most followers this should be Rogue, Warrior or Wizard.

[[File:class.jpg]]

Under Package/Scaling set:

'''General Package Type''' to be '''Party Members'''

'''Package''' to be an appropriate value (probably "Generic - Wizard" or similar)

'''Package AI''' (there should only be one choice)

'''Rank''' to be '''Player'''

[[File:package.jpg]]

Save and export your character as normal.

=== Overlay char_stage ===

In the official campaign, the party picker uses a special area called char_stage. Whether you're extending the official campaign or making a standalone campaign, there is a function that allows you to overlap the offical stage with your own, so that both stages are active simultaneously in game.

In your resource palette, right-click char_stage under the Global folder and select Duplicate to make a copy of the stage with a new resource name, e.g. my_char_stage. In the resource properties, ensure that both Module and Owner Module are set to your module, and the folder of your choice.

[[File:area_palette.jpg]]

Create a new waypoint for your follower to appear on the party picker. This waypoint '''must''' have a tag in the form of "char_" followed by the exact tag of your follower.

[[File:char_stage.jpg]]

In this example the tag of my follower is '''bc_party_miera''' so her waypoint tag must be '''char_bc_party_miera'''

For a standalone module (such as in this example), put your waypoint wherever you please. The illustrated one is directly on top of Morrigan's. For an add-in to the main campaign, you should position your wp appropriately relative to the core party members.

Save and export the area.

Add the following to your module event script:
<dascript>
case EVENT_TYPE_MODULE_GETCHARSTAGE:
{
// Overlay the existing stage with my stage
// "my_char_stage" is the resource name of the overlay area
// "partypicker" is the name of the default GDA
SetPartyPickerStage("my_char_stage", "partypicker");
break;
}
</dascript>

=== Create m2DAs for the Party Picker ===

You will need to create two Excel spreadsheets.

The first should be named (both worksheet and file) '''partypicker_''' with a unique suffix. In this example, my first spreadsheet is named partypicker_fofbc.xls with a worksheet name of partypicker_fofbc - the suffix being the acronym of my module.

Set up your columns as follows:

[[File:partypickerm2da.jpg]]

The '''ID''' for your follower must be '''12 or higher'''. 11 is the highest value used in the base 2DA. 12 is fine for standalone modules, add-ins will probably want to use an arbitrarily high number to avoid potential conflicts.

The '''Label''' should be the follower's name as you wish it to appear on the party picker.

The '''Tag''' must be your follower's tag.

All other values are non-functioning defaults and should be specified as in the image above unless you know explicitly what you're doing.

'''NOTE - ON SELECTION ANIMATIONS'''

Add Animation and Remove Animation are actually Id numbers of different animations, taken from anim_base.gda

Enter and Exit version of animations are generally the best ones to use, altough one can try others. NOT ALL ANIMATIONS WILL WORK, since some require special conditions.
Here are some examples you can use:

819 - talk cursing

629 - reading a book (doesn't work, since it probably requires a book object)

844 - hands behind back (848 and 849 are Enter and Exit versions respectfully)

850 - chest pounding salute

811 - fist pounding

277 - dance

247 - cast area spell

500 - vfx cast

600 - surprised

603 - praying

607 - head bow

609 - standing at attention

651,652 - crouch pray (Enter and exit)

808 - point forward

825 - nodding

840 - hand chop or frustration

905,906 - crouch (Enter, Exit)

919,920 - sit on ground (enter, exit)

965 - kneel down loop

972 - wipe nose

976,977 - squat (Enter, Exit)

986 - wipe eyes

998,999 - hands clasped (Enter, exit)

3029 - inspect nails

3031,3032 - playful (enter, exit)

3054,3056 - slouch (enter, exit)
255 - in-place fly

'''NOTE - ON SELECTION VFX'''

The VFX column is the ID of the vFX effect taken from vFx_base.gda. This one is a bit more tricky, since it also references the BlendTree value from the same file.
Find the ID of the spell effect and look for the BlendTreeName column (should the the 12th columun) and enter BOTH into the respective columns for your character in the partypicker file.

Some examples:

ID --- BLENDTREENAME --- EFFECT

6039 --- fxm_energy_up_p --- Lady of the Forest pillar of light

6040 --- fxm_power_in_p --- Branka - power in

3054 --- fxc_lotf_c --- Lady of the Forest - swirling leaves

3009 --- fxc_succubus_c --- Succubus crust

1549 --- fxa_hly_imp_c --- Holy Impact crust

1076 --- fxa_spi_aur_mht_c --- Spirit - Aura Might crust

The second spreadsheet should be named '''party_picker_''' (note middle underscore). Once again append your unique suffix (in this example party_picker_fofbc.xls with party_picker_fofbc as its worksheet).

Set up your columns and data like so:

[[File:party_pickerm2da.jpg]]

'''ID''' and '''Tag''' should match what you did in the first spreadsheet. Specify INVALID COLUMN for the third column.

If you're familiar with m2DAs, generate them from these files, copy them to your module's override directory, and skip to the next step. Otherwise, read on:

- Go to '''\Program Files\Dragon Age\tools\ResourceBuild\Processors''' (or wherever you installed Dragon Age)

- Copy '''ExcelProcessor.exe''' from that folder to whichever folder has the excel sheets you just created.

- Drag and drop your xls files onto ExcelProcessor. This will create .gda files.

- Copy these .gda files to your module's export directory (probably \Documents\Bioware\Dragon Age\AddIns\yourModule\module\override\toolsetexport). Make sure they are included in your .dazip when the time comes to build your module.

If you are an OpenOffice user and have trouble with ExcelProcessor, you can use [http://social.bioware.com/project/755/ GDApp] to directly create the 2DAs. It rocks!

=== Capture the EVENT_TYPE_PARTYMEMBER_ADDED Event ===

Amusingly enough, the Party Picker does not actually add followers to the party. However it raises an event that allows you to do so. Your module script needs to capture this event and execute some code.

The following example shows what to do with the event. The full script would work as a module script for an add-in (assuming it didn't need to do anything else), but otherwise you'll have to incorporate the event into your own module script.

If you're not sure how to set a module script, go to '''File''' then '''Manage Modules,''' select your module and click '''Properties.'''

<dascript>
#include "utility_h"

void main()
{
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);
switch(nEventType)
{
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0); //Allows the follower to gain XP
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero()))); //Ensures follower appears at PC's location.
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE); //Adds follower to the active party
break;
}

}
}
</dascript>

'''SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE)''' is the key statement to add the follower to the active party. You must have this.

'''SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0)''' is a bug-fix, as followers hired with UT_HireFollower() do not receive XP by default. This statement fixes that, and I consider it best practice to keep it in this event to ensure it is always set. You will not wish to do this if you want a follower that should not gain XP to be on the party picker.

Note that you do not need to intercept the corresponding event for a party member being removed - the party picker handles spawning/despawning, and thus will successfully remove members.

Remember to save and export your module script.

If you're not sure how to set a module script, go to '''File''' then '''Manage Modules,''' select your module and click '''Properties.''' The module script is in the General category, as seen below:

[[File:module_script.jpg]]

You can set this to any script you've created. See [[Scripting tutorial]] and [[Character generation]] for more background and some simple examples of event-handling scripts. In general, you will want to make sure standalone module scripts pass events through to module_core (as in the [[Character generation]] examples) and add-in scripts do not (as in the example above).

=== Create Your Hiring Script ===

Now all that remains is to actually hire the follower :)

Create a script to handle the hiring (which will most likely be fired from a conversation). The script is quite simple:

<dascript>
#include "utility_h"

void main() {

object oFollower = GetObjectByTag("bc_party_miera"); //Use CreateObject() if the creature isn't present in the module yet

UT_HireFollower(oFollower); //Hires the follower

SetPartyPickerGUIStatus(2);

ShowPartyPickerGUI(); //Shows the Party Picker; necessary for the follower to gain XP

}
</dascript>

Make sure you use your own follower's tag and not the example one :)

This script fires the party picker after hiring the follower. That is absolutely necessary via this method, as we have put the XP fix onto an event fired by the party picker. You cannot put the XP fix into this script, it must be called from a later one (the bug is caused by an errant call to an event in player_core, which will be executed AFTER this script).

The easiest way to use this script is directly from conversation, putting it as an action on a line of dialogue where the PC invites the follower to join them. If you're not sure how to associate a script with a dialogue line, see the following image:

[[File:hire_conv.jpg]]

Create your dialogue as normal, select the line you want to fire the script, and click the '''Plots and Scripting''' tab. Use the '''Script''' file chooser in the Action section to browse to the script you created.

If everything worked, you should see something like this:

[[File:picker_success.jpg|thumb|200px|center]]

== Advanced Follower Creation ==

Follow these steps to have full control over the creation of your follower, with options such as:

- Unique level-up template

- Class and specialisation chosen via script

- Any starting state

- Level higher than the PC

- Starts with a specialisation point rather than a specific specialisation

- Set plot flags in the call to the hire script

=== Prepare Creature, char_stage and Party Picker m2DAs ===

Follow the same steps to create your follower creature, char_stage and Party Picker m2DAs as above.

=== Create Party Plot ===

While not necessary, it's very helpful to have plot flags set when a follower is hired or joins/leaves the active party. This makes conversation interjections and the like very easy.

Create a plot with appropriate flags. There's no real need to associate journal text with them:

[[File:follower_plot.jpg]]

See FAQ for an alternative approach to plots when there are more than three potential party members.

=== Add Plot Flags to Party Picker Event Intercept ===

We then update our module script to make use of that plot, like so:

<dascript>
#include "utility_h"
#include "wrappers_h"
#include "plt_bc_create_party" //make sure you include your own plot, not mine

void main()
{
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);
switch(nEventType)
{
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0);
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE);

AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero()))); //Ensures follower appears at PC's location.

if (GetTag(oFollower) == "bc_party_miera") { //You must explicitly test for your follower's tag.
WR_SetPlotFlag(PLT_BC_CREATE_PARTY, PARTY_MIERA_IN_PARTY, TRUE); //Make sure you use your own flags!
}

break;
}

case EVENT_TYPE_PARTYMEMBER_DROPPED:
{
object oFollower = GetEventObject(ev, 0);

if (GetTag(oFollower) == "bc_party_miera") {
WR_SetPlotFlag(PLT_BC_CREATE_PARTY, PARTY_MIERA_IN_PARTY, FALSE); //As above, but set false.
}

}

}
}
</dascript>

=== Create a Level Up Template ===

You can skip this step if you're content to use one of the generic Rogue, Wizard or Warrior templates, but I don't recommend it. Making a template that suits your character is easy and will almost always be better for the player than a generic one that spends points poorly.

Go to \Program Files\Dragon Age\tools\Source\2DA (or wherever you installed Dragon Age).

You should see a number of excel sheets of the form '''ALCharacter.xls''' (such as ALAlistair.xls, ALLeliana.xls, ALRogue_Default.xls etc). Open the one closest to your character (ie Morrigan or Wynne for a wizard, Leliana or Zevran for a rogue). Save a copy as '''ALYourcharacter.xls''' in whatever directory you're using to create your 2DAs, remembering to rename the worksheet '''ALYourcharacter''' (in this example, ALMiera.xls with ALMiera as its worksheet).

It should look something like this:

[[File:ALtable.jpg|thumb|500px|center]]

'''Columns B''' and '''C''' are the talents/spells available to this character. Do not change them.

'''Columns F''' and '''G''' are the skills available to this character. Do not change them.

We will edit the remaining columns like so:

==== Setting Stat Weights ====

The stat weights in '''column J''' determine how the follower will spend their attribute points, in a rough ratio. So if Dexterity is set to 1.5 and Intelligence to 1, you should expect to see 3 points of Dex for every 2 points of Cunning in-game (note Intelligence is the label used in the toolset for Cunning).

Simply change the values in J to reflect how you'd like the character to spend their points. In this example we're creating a wizard, so we're not going to mess around:

[[File:miera_stat_weights.jpg]]

This character will only raise magic. I set the value to 5 rather than something like 1 to provide room underneath for the other stats while still overwhelmingly favouring magic, but in practice I only really ever want that one stat.

In a note left on this column in the existing templates, Bioware's Georg Zoeller writes, "This is the weight of each attribute (row id links into properties.xls.id). 1.0 means 'try to keep this attribute level' (spend 1 point per level). 0.5 means 'try to spend 1 point every two levels' and so on."

The default Mage, Rogue and Warrior templates include '''column L''' labeled "AttInit." Editing these values seems to have no effect on followers set to use these templates.

==== Setting Talent and Skill Priorities ====

'''Columns D''' and '''E''' are the talents/spells that the character will buy, in preference order from top to bottom.

'''Columns H''' and '''I''' are the skills that the character will buy, in preference order from top to bottom.

To change these, just copy the appropriate two cells from columns B&C or F&G over the ones you want to replace.

For example, here we're copying Morrigan's template. Morrigan has Spider Shape high in her preferences, which we do not want.

[[File:AlMori_talent_pref.jpg]]

We decide we'd prefer Flame Blast, so we find it in columns B&C and copy both cells:

[[File:ALMori_copy.jpg]]

Then we select the cells we want to replace in columns D&E and paste over them:

[[File:ALMori_paste.jpg]]

Continue this process until your priorities list for both skills and talents/spells is exactly as you want it. Make sure you have at least as many priorities as the core follower you're copying - points that cannot be spent according to these priorities have a habit of vanishing.

If you used any abilities from a specialisation, make sure you remember to set that specialisation with the function we'll introduce later. The autolevel scripts will add specialisation abilities to a character regardless of whether they have that spec or not.

==== Create a M2DA_base_ m2DA ====

Dragon Age will need to know where to find your autolevel template. We tell it by extending M2DA_base.gda

Create a spreadsheet with the name and worksheet name in the form '''M2DA_base_''' with your unique suffix (in this example, M2DA_base_fofbc.xls with M2DA_base_fofbc as a worksheet).

Set up its columns and data like so (note I used GDApp because Open Office wasn't cooperating for this one!):

[[File:m2da_base_fofbc.jpg]]

The '''ID''' should be very high to avoid conflicts. I've arbitrarily chosen 50,000+ here. Carefully note the ID you've chosen for your character, you will need it later.

Set the '''Label''' and '''Worksheet''' to be the name of your autolevel template worksheet (ALCharactername if you've been following this).

Set the '''PackageIDForAI''' to be 0, it shouldn't be needed for followers.

When you're done, use ExcelProcessor to make GDAs of both spreadsheets and copy them to your module's export folder.

FOR AUTOLEVEL TO WORK AFTER RECRUITING:

Look in packages.xls.
There is a column called LevelupTable. That links to a corresponding AL* table. For instance, row 81 is for Leliana. Her LevelupTable value is 258. If you look that up in 2DA_base, you'll see it links to ALLeliana.
(alternatively, you could try packages_base.gda)

=== Create a New Hire Function Include ===

This section is probably only relevent if you have a specific need to override the functionality of player_core.

Many vital steps of follower addition happen inside an event in player_core. Followers tend to be extremely buggy (no skill tree, for example) if this event does not fire.

However, that event is not very flexible. In order to control it to our requirements, we need to replicate its functionality inside our own script. This is probably much safer than messing with player_core directly!

Create a new script file, naming it something like '''hireCustomFollower_h'''. We will be including this wherever we want to hire a follower.

Paste in the following script:

<dascript>
#include "sys_chargen_h"
#include "wrappers_h"
#include "utility_h"
#include "sys_rewards_h"
#include "approval_h"
#include "sys_autolevelup_h"

/* Jye Nicolson 5-Jan-2010
This function set duplicates the full functionality chain of UT_HireFollower, with the following exceptions:

- Followers can gain XP
- Autolevel status can be set (default off)
- Followers can be set to any starting state (default Available) and will still be properly initalised and added to the party pool
- Autolevel tables for non-core followers can be explicitly set.
- Class and Specialisation can be chosen via script
- Followers without specialisations are granted a spec point by default.

It should only ever be called once each for characters you intend to be full followers.
Much of the protective code handling summoned creatures etc. in player_core is not present here.

Calling the function:

Simple:

hireCustomFollower(oFollower, CLASS_WARRIOR);

Change the class to CLASS_WIZARD or CLASS_ROGUE as appropriate.
This will hire your follower and make them available.
They will auto level up with a default package, and receive a free spec point.

Best Practice:

hireCustomFollower(oFollower, CLASS_WARRIOR, PLT_YOUR_PARTY_PLOT, YOUR_FOLLOWER_JOINED_FLAG, ABILITY_TALENT_HIDDEN_CHAMPION);

Where the plot and flag are those for your module (remember to create the plot and include it on the calling script), and ABILITY_TALENT_HIDDEN etc is the desired spec.

You should also have a custom ALTable set up.
See wiki for details, and remember to edit it in to GetCustomFollowerALTable below or pass it directly as an argument to hireCustomFollower.

Full argument list:

void hireCustomFollower (
object oFollower, //Pass your follower object, mandatory

int nForceClass, //Pass a Class constant here, usually CLASS_ROGUE, CLASS_WARRIOR, CLASS_WIZARD. Mandatory due to a bug.

string sPlot = "", //It's recommended you have a plot flag to be set when the follower joins. Pass the plot constant here. Remember to #include in calling script

int nPlotFlag = "", //And then pass the flag constant. Will be set to TRUE if available.

int nForceSpec = 0, //This is the ID of the Specialisation you want. Note they are NOT classes, but abilities. The full list is:
//ABILITY_SPELL_HIDDEN_ARCANE_WARRIOR, ABILITY_SPELL_HIDDEN_BLOODMAGE, ABILITY_SPELL_HIDDEN_SHAPESHIFTER, ABILITY_SPELL_HIDDEN_SPIRIT_HEALER
//ABILITY_SPELL_HIDDEN_BARD, ABILITY_TALENT_HIDDEN_ASSASSIN, ABILITY_TALENT_HIDDEN_DUELIST, ABILITY_TALENT_HIDDEN_RANGER
//ABILITY_TALENT_HIDDEN_BERSERKER, ABILITY_TALENT_HIDDEN_CHAMPION, ABILITY_TALENT_HIDDEN_REAVER, ABILITY_TALENT_HIDDEN_TEMPLAR
//I recommended forcing a spec, particularly if your ALTable includes abilities from one.

int nALTable = 0, //This is the ID of an ALTable from 2DA_base.GDA or your module's m2DA_base_*.GDA I recommended the latter, but you can edit that into GetCustomFollowerALTable below rather than passing it.

int bInvokePicker = FALSE, //Sets whether the party picker should be opened on hiring. I think it's cleaner to call the picker outside this script, particularly if you have multiple hires at once.

int nInitialState = FOLLOWER_STATE_AVAILABLE, //This sets whether the follower joins the active party or not. Options are:
//FOLLOWER_STATE_ACTIVE (put them in the active party)
//FOLLOWER_STATE_LOCKEDACTIVE (force them into the active party and keep them there, remember to change this later.
//FOLLOWER_STATE_AVAILABLE (make them available on the party picker (if you've set it up for them), but not in the active party)
//Plus some others you're unlikely to need at this time. Defaults to AVAILABLE because having 4+ active followers is screwy.

string sCurrPlot = "", //If you set FOLLOWER_STATE_ACTIVE or FOLLOWER_STATE_LOCKEDACTIVE, the script will check to see if you passed this.
//It is recommended that you have a plot flag set for a given follower being in the active party, this makes conversation interjection etc. much easier.

int nCurrPlotFlag = 0, //This flag will be set if FOLLOWER_STATE_ACTIVE or FOLLOWER_STATE_LOCKEDACTIVE are true
//AND sCurrPlot has a value AND nCurrPlotFlag is > 0.
//ie if you added someone to the active party and have a plot flag to cope with it.

int nAutolevel = 0, //Sets the Autolevel flag on the character sheet. 0 is off, 1 is on, 2 forces it on and removes it so the player can't turn it off.

bFreeSpecPoint = TRUE, //This grants a specialisation point to the follower if they do not have a specialisation.
//It's important to set this false for classes that do not have specs, such as CLASS_DOG.

int nTargetLevel = 0, //If you want a specific level, set this. Generally not worthwhile unless you set it higher than the player, since they'll just get XP from the party picker anyway.

int nMinLevel = 0 //Set this if there's a specific level you don't want the follower to go below. Probably only useful if the PC might be very low level but not necessarily so.

)
*/
/* GetCustomFollowerALTable()
This function is where you put your custom table assignments.

You should explicitly test for the tag of your follower (not mine!) and assign a value to nTable from your m2DA extension to M2DA_base

See wiki for details on how to do this, or ignore it to get the default Warrior/Rogue/Wizard AL tables.

NOTE: you MUST explicitly set a table for non-Warrior/Rogue/Wizards, eg dogs. Use TABLE_AL_DOG for a default Mabari.
*/

int GetCustomFollowerALTable(object oFollower) {
int nTable = _GetTableToUseForAL(oFollower);

if (GetTag(oFollower) == "bc_party_miera") {
nTable = 50143;
}

if (GetTag(oFollower) == "bc_party_jysavin") {
nTable = 50144;
}

if (GetTag(oFollower) == "bc_party_geldual") {
nTable = 50145;
}

if (GetTag(oFollower) == "bc_party_braghon") {
nTable = 50146;
}

return nTable;
}

// This just cleans up the main function a little

int GetCustomFollowerTargetLevel(object oFollower, object oHero, int nPackage, int nMinLevel = 0) {
int nPlayerLevel = GetLevel(oHero);
int nTargetLevel = 0;

if((nPlayerLevel >= 13) || (nPlayerLevel == 1) || (!_UT_GetIsPlotFollower(oFollower))) {
nTargetLevel = nPlayerLevel;
} else {
nTargetLevel = nPlayerLevel + 1;
}

if (nMinLevel == 0) { //If nMinLevel is not specified, checks package 2DA for a value
nMinLevel = GetM2DAInt(TABLE_PACKAGES, "MinLevel", nPackage);
}
if(nMinLevel > 0 && nMinLevel > nTargetLevel) {
nTargetLevel = nMinLevel;
}

return nTargetLevel;

}

// Moving this black box out :) I don't really understand it, but it should function if you have tactics set up in a package.

void InitCustomFollowerTactics(object oFollower, int nPackage) {
int nTableID = GetM2DAInt(TABLE_PACKAGES, "FollowerTacticsTable", nPackage);
if (nTableID != -1)
{
int nRows = GetM2DARows(nTableID);
int nMaxTactics = GetNumTactics(oFollower);

int nTacticsEntry = 1;
int i;
for (i = 1; i <= nRows && nTacticsEntry <= nMaxTactics; ++i)
{
int bAddEntry = FALSE;
int nTargetType = GetM2DAInt(nTableID, "TargetType", i);
int nCondition = GetM2DAInt(nTableID, "Condition", i);
int nCommandType = GetM2DAInt(nTableID, "Command", i);
int nCommandParam = GetM2DAInt(nTableID, "SubCommand", i);

int nUseType = GetM2DAInt(TABLE_COMMAND_TYPES, "UseType", nCommandType);
if (nUseType == 0)
{
bAddEntry = TRUE;
}
else
{
bAddEntry = HasAbility(oFollower, nCommandParam);
}

if (bAddEntry)
{
SetTacticEntry(oFollower, nTacticsEntry, TRUE, nTargetType, nCondition, nCommandType, nCommandParam);
++nTacticsEntry;
}
}
}
}

/* InitCustomFollowerSpec:

This function tries to set the forced Specialisation. If there is none, it checks the package for one.

If there isn't either of those, it grants a free spec point if bFreeSpecPoint is true.

*/

void InitCustomFollowerSpec(object oFollower, int nPackage, int nForceSpec, int bFreeSpecPoint) {
// Find specialization, and optionally add a spec point if none is found.

if (nForceSpec == 0) {

int nSpecAbility = GetM2DAInt(TABLE_PACKAGES, "switch1_class", nPackage); // followers can have only 1 advanced class
if(nSpecAbility > 0)
{
AddAbility(oFollower, nSpecAbility);
} else {
if (bFreeSpecPoint) {
SetCreatureProperty(oFollower, 38, 1.00);
}
}

} else {

AddAbility(oFollower, nForceSpec);

}
}

/* hireCustomFollower() (See doco at top of page)

I strongly suggest you reorder the parameters if you're adding many followers with advanced options.

Feel free to leave them alone if you only want to set class, plot, spec or don't mind long declarations.

Note nForceClass is currently compulsory due to flakiness with GetCreatureCoreClass()
*/

void hireCustomFollower(object oFollower, int nForceClass, string sPlot = "", int nPlotFlag = 0, int nForceSpec = 0,
int nALTable = 0, int bInvokePicker = FALSE, int nInitialState = FOLLOWER_STATE_AVAILABLE, string sCurrPlot = "",
int nCurrPlotFlag = 0, int nAutolevel = 0, int bFreeSpecPoint = TRUE, int nTargetLevel = 0, int nMinLevel = 0)
{

object oHero = GetHero();

/* ################# BEGIN BASIC FOLLOWER JOIN BLOCK ###################

This loosely replicates WR_SetFollowerState.

*/

if (nForceClass == 0) {
nForceClass = GetCreatureCoreClass(oFollower); //This is not working. Hence nForceClass mandatory.
}

SetGroupId(oFollower, GetGroupId(oHero)); //Puts the follower in the pc's Group.
SetEventScript(oFollower, RESOURCE_SCRIPT_PLAYER_CORE); //This makes them act like a player.
SetFollowerState(oFollower, nInitialState); //This sets whether they are available, in the active party etc.

/* ################# END BASIC FOLLOWER JOIN BLOCK ##################### */

/* ################# BEGIN PLAYER_CORE EVENT_TYPE_PARTY_MEMBER_HIRED EMULATION #################
This replicates the EVENT_TYPE_PARTY_MEMBER_HIRED handler from player_core, stripped down for simplicity and allowing our custom options.

*/

Chargen_EnableTacticsPresets(oFollower); //I assume this is important.

SetLocalInt(oFollower, FOLLOWER_SCALED, 1); //This should prevent the follower being rescaled by player_core or what have you

int nPackage = GetPackage(oFollower); //Gets the package, which will be used to find a number of 2DA IDs.
int nPackageClass = GetM2DAInt(TABLE_PACKAGES, "StartingClass", nPackage); //I don't think this is used, even by player_core

// set behavior according to package
int nBehavior = GetM2DAInt(TABLE_PACKAGES, "FollowerBehavior", nPackage);

if(nBehavior >= 0) {
SetAIBehavior(oFollower, nBehavior);
}

Chargen_InitializeCharacter(oFollower); //We initialise the follower and choose race/class.

Chargen_SelectRace(oFollower,GetCreatureRacialType(oFollower));
Chargen_SelectCoreClass(oFollower,nForceClass);

if (nTargetLevel == 0) { //This block picks a target level if not specified

nTargetLevel = GetCustomFollowerTargetLevel(oFollower, oHero, nPackage, nMinLevel);
}

int nXp = RW_GetXPNeededForLevel(Max(nTargetLevel, 1)); //Here is where the XP is calculated and rewarded
RewardXP(oFollower, nXp, FALSE, FALSE);

// -------------------------------------------------------------
// add hidden approval talents - (JN: I don't know how to set these yet, but when I figure it out this should make it work)
// -------------------------------------------------------------
int nIndex = Approval_GetFollowerIndex(oFollower);
Approval_AddFollowerBonusAbility(nIndex, 0);

//Handle Specialisation
InitCustomFollowerSpec(oFollower, nPackage, nForceSpec, bFreeSpecPoint);

// -------------------------------------------------------------
// This spends all available attribute and stat points on the
// creature according to the levelup table. (JN: this replicates AL_DoAutoLevelUp but with our choice of table)
// -------------------------------------------------------------

if (nALTable == 0) {
nALTable = GetCustomFollowerALTable(oFollower);
}

AL_SpendAttributePoints(oFollower, nALTable, FALSE);
AL_SpendSkillPoints(oFollower, nALTable, TRUE);
AL_SpendSpecializationPoints(oFollower, nALTable);
AL_SpendTalentSpellPoints(oFollower, nALTable, TRUE);

// -------------------------------------------------------------------------
// Update various UIs
// -------------------------------------------------------------------------
Chargen_SetNumTactics(oFollower);
SetCanLevelUp(oFollower,Chargen_HasPointsToSpend(oFollower));

// load tactics
InitCustomFollowerTactics(oFollower, nPackage);

/* ################# END PLAYER_CORE EVENT_TYPE_PARTY_MEMBER_HIRED EMULATION ################# */

SetAutoLevelUp(oFollower, nAutolevel); //This is the autolevel flag on the character sheet.

//Set plot flags

if (!((sPlot == "") || (nPlotFlag == 0))) { //Joined Party
WR_SetPlotFlag(sPlot, nPlotFlag, TRUE);
}

if ((nInitialState == FOLLOWER_STATE_ACTIVE) || (nInitialState == FOLLOWER_STATE_LOCKEDACTIVE)) {
if (!((sCurrPlot == "") || (nCurrPlotFlag == 0))) {
WR_SetPlotFlag(sCurrPlot, nCurrPlotFlag, TRUE); //Currently in Party
}
}

// Invoke picker if requested.

if (bInvokePicker) {
SetPartyPickerGUIStatus(2);
ShowPartyPickerGUI();
}
}
</dascript>

Yeah, I know. It can't really be any smaller. Feel free to modify it if you're confident with scripting.
==== Add Your Custom Autolevel Template to GetCustomFollowerALTable() ====
While you can pass the ID you made for your autolevel template to that monster function as an argument, it's better to have them all in one place if you have multiple followers.

GetCustomFollowerALTable() is the first function in our include, and you can add an explicit if test for your follower there to assign the correct table id (the one from your M2DA_base_ m2DA). There is a function very much like it in sys_autolevel_h.nss for the core followers, so we'll copy Bioware's practice.

Let's take a look at the function by itself:

<dascript>
int GetCustomFollowerALTable(object oFollower) {
int nTable = _GetTableToUseForAL(oFollower);

if (GetTag(oFollower) == "bc_party_miera") {
nTable = 50143;
}

if (GetTag(oFollower) == "bc_party_jysavin") {
nTable = 50144;
}

if (GetTag(oFollower) == "bc_party_geldual") {
nTable = 50145;
}

if (GetTag(oFollower) == "bc_party_braghon") {
nTable = 50146;
}

return nTable;

}
</dascript>

So we have a test for each follower tag from my module, matching up to an ID which is assigned to nTable. All you need to do is change a tag from my follower to yours, and my ID to the correct one from your M2DA_base_* m2DA. Then you should delete the rest of the example if statements :)

Save and export the script. Ignore the compiler error about lack of main();

=== Include Function In Your Hire Script and Call It ===

So instead of a hire script that calls UT_HireFollower(), we want one that includes our shiny new function and calls it.

Take a look at the following example:

<dascript>
#include "plt_bc_create_party" //Make sure you include your party handling plot
#include "hireCustomFollower_h" // And include the function script - which will in turn include a bunch of stuff

void main() {

//Initialising my objects, not super-relevant to the example

object oHero = GetHero();
object oMiera = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_miera.utc", GetLocation(oHero));
object oJysavin = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_jysavin.utc", GetLocation(oHero));
object oBraghon = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_braghon.utc", GetLocation(oHero));
object oSpider = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_geldual.utc", GetLocation(oHero));

//Simplest hire call - adds to the party as a wizard. Class is currently compulsory due to a bug.
hireCustomFollower(oMiera, CLASS_WIZARD);

//Add to the party and set joining plot flags
hireCustomFollower(oJysavin, CLASS_WARRIOR, PLT_BC_CREATE_PARTY, PARTY_JYSAVIN_JOINED);

//Add to the party, set plot flags, force a specialisation
hireCustomFollower(oBraghon, CLASS_ROGUE, PLT_BC_CREATE_PARTY, PARTY_BRAGHON_JOINED, ABILITY_TALENT_HIDDEN_ASSASSIN);

//More complex example - Follower added as a unique class (Dog), not granted a specialisation or spec point.
//Note unique classes must have an ALTable passed here or specified in GetCustomFollowerALTable() or they won't work
hireCustomFollower(oSpider, CLASS_DOG, PLT_BC_CREATE_PARTY, PARTY_GELDUAL_JOINED, 0, 0, FALSE, FOLLOWER_STATE_AVAILABLE, "", 0, 0, FALSE);

//Show the party picker to let the player choose from their new companions!
SetPartyPickerGUIStatus(2);
ShowPartyPickerGUI();
}
</dascript>

The example shows several of the more simple ways of invoking the function. Check the comments at the start of the function for a full list of arguments.

I would suggest best practice for most followers would be to call as follows:

'''hireCustomFollower(oFollower, CLASS, PLOT, PLOT_FLAG, SPECIALISATION)'''

This will safely set the follower up as the desired class and specialisation (doubly important if there are spec abilities in their ALTable) while setting your plot flag for them being in the party. hireCustomFollower(oFollower, CLASS, PLOT, PLOT_FLAG, SPECIALISATION, 0, TRUE) will do the same while invoking the Party Picker automatically.

Note that the specialisations are abilities and not classes - you'll find them as ABILITY_HIDDEN_ constants.

If it's all worked, you should find you can now add followers with a lot more flexibility!

[[File:picker_advanced.jpg|thumb|500px|center]]

== Common Follower Problems & FAQ ==

====Why don't my followers gain XP?====
There is a bug in UT_HireFollower. Make a copy of UT_HireFollower in a function of your own, then make the following change:
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, TRUE);
to
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, bPreventLevelup);

====When I choose followers from the Party Picker, they spawn into the area but do not join.====

You need to intercept the EVENT_TYPE_PARTYMEMBER_ADDED event and set the follower to FOLLOWER_STATE_ACTIVE. See Simple Follower Creation earlier in this document.

====My followers don't have skill trees!====

If a follower hasn't been through an initial chargen/autolevel event (via player_core/sys_autolevel_h) then the skill tree doesn't show. You're probably trying to be clever and get around UT_HireFollower without going all the way (see monster function above ^_^).

====My followers don't have a class====

GetCreatureCoreClass() seems flaky under some conditions. It's best to explicitly set the class yourself; this is why class is currently a mandatory argument to hireCustomFollower()

====Dog talents and equipment slots don't work====
Symptoms: dog talents appear on the talents screen but remain greyed out on level up. Warrior talents appear in the quickslots. Equipment slots are for humans, not dogs.

Line 78 of packages_base in packages.xls (Dog) should have the LevelUpTable column set to 257 which is the ALDog table.

The EquipmentLayout 2DA needs a new entry for the follower:

ID=same as partypicker 2DA
Tag=follower tag
AvailableEquipmentSlots=794624
Layout=2
EnableWeaponSets=0

If the creature is not using the appearance "Dog, Party Member", it needs a new appearance line in APR_base. Most of the entries can be copied from the standard appearance (e.g. Wolf), but

MaxScaleLevel=-1
DefaultArmor=
AppearanceRestrictionGroup=1

Otherwise, it won't be able to progress beyond a specified level. The player will receive an unwanted set of armour when the it is hired, and it won't be able to use Marabi crunch items. You may also need to tweak PERSPACE and/or BumpLevel if excessive clipping occurs.

====Isn't there an easier way to do this?====

Possibly. There is a way of recruiting a follower by setting a plot flag. However I don't understand it, and I expect it still doesn't allow custom autolevel templates, full control over specialisations etc. There's still a fair bit of stuff hardcoded for the core followers, I'm not sure putting a custom follower through the same process as Al, Leli et al will have good results.

The next section answers this question, up to a point.

==== What if there are more than three potential followers? ====
This example handles larger numbers of followers, and doesn't force the player to use the party picker unless the party is already full.

The prefix zzz, used throughout, can be replaced with whatever [[Prefixes_in_use | prefix]] you are using for your resources.

If you're making a new campaign, to keep life simple, allocate a unique number to each follower. You could either use a creature variable or a script, e.g.
<pre>
// Party member id (e.g. 1=Alicia, 2=Godwin...)
int zzzPartyMemberID(object oPartyMember)
{
string sPartyMember = GetTag(oPartyMember);

if (sPartyMember == "zzzcr_alicia") return 1;
if (sPartyMember == "zzzcr_godwin") return 2;
if (sPartyMember == "zzzcr_harold") return 3;
if (sPartyMember == "zzzcr_lara" ) return 4;
return 0;
}
</pre>

Make two separate plots, e.g. zzzpt_hired for when a follower is first recruited, and zzzpt_party to flag whether they're currently in the party. Use flag values that correspond to the unique follower id, e.g. ZZZPT_HIRED_GODWIN will be 2.

If you're modifying the official campaign, you won't be able to make this simplification - you'll need a set of plot flags for your new party members, similar to the official ones. The logic of what follows is still correct, it just means that instead of having one set of common code that works for everyone, you have to explicitly script each party member individually using their personal plot flags.

Follower conversation is now very simple. In Godwin's dialogue, the hiring line will be conditional - when ZZZPT_HIRED_GODWIN is clear - and it will set ZZZPT_HIRED_GODWIN. No conversation script is necessary. Instead, in the properties of the plot zzzpt_hired, we add a plot event script, as follows.
<pre>
// PARTY HIRE PLOT SCRIPT
//
// This is called in conversation when a party member is hired for the first time.
// If the party is full, the party picker is displayed, which forces the PARTYMEMBER_ADDED
// module event.
//
// The flag value is never referenced, because the code is common for all party members.

#include "events_h"
#include "global_objects_h"
#include "utility_h"
#include "sys_rewards_h"
#include "log_h"
#include "utility_h"
#include "wrappers_h"
#include "plot_h"

#include "zzz_h" // A header containing the zzzPartyMemberID function
#include "plt_zzzpt_hired"
#include "plt_zzzpt_party"

int StartingConditional()
{
event eParms = GetCurrentEvent();
int nType = GetEventType(eParms); // GET or SET
string strPlot = GetEventString(eParms, 0); // Plot GUID
int nFlag = GetEventInteger(eParms, 1); // Plot flag
object oParty = GetEventCreator(eParms); // Plot table owner
object oFollower = GetEventObject(eParms, 0); // Conversation owner (if any)
int nPlotType = GetEventInteger(eParms, 5); // Plot type

int bIsTutorial = GetM2DAInt(TABLE_PLOT_TYPES, "IsTutorial", nPlotType);
int bIsCodex = GetM2DAInt(TABLE_PLOT_TYPES, "IsCodex", nPlotType);

int nResult = FALSE; // return value for DEFINED GET
object oPC = GetPartyLeader();

plot_GlobalPlotHandler(eParms); // any global plot operations, including debug info

if (nType == EVENT_TYPE_SET_PLOT) // actions -> normal flags only
{
int nValue = GetEventInteger(eParms, 2); // 0=Clear 1=Set
int nOldValue = GetEventInteger(eParms, 3); // Current flag value

if (nValue)
{
if (GetArraySize(GetPartyList(oPC)) < 4)
{
UT_HireFollower(oFollower);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0);
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero())));
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE);
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), TRUE);
}
else
{
WR_SetFollowerState(oFollower, FOLLOWER_STATE_AVAILABLE, FALSE);
SetEventScript(oFollower, RESOURCE_SCRIPT_PLAYER_CORE);
SendPartyMemberHiredEvent(oFollower, TRUE);
// SetPartyPickerGUIStatus(PP_GUI_STATUS_USE);
// ShowPartyPickerGUI();
}
}
}
else // EVENT_TYPE_GET_PLOT -> defined conditions only
{
switch(nFlag)
{

}
}

plot_OutputDefinedFlag(eParms, nResult);
return nResult;
}
</pre>
We still need to handle the party picker events in our module event script:
<pre>
// PARTY MEMBER ADDED - Allow XP gain. Come here, follow me, flag as party member.
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0);
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero())));
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE);
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), TRUE);
break;
}
// PARTY MEMBER DROPPED - flag as not party member.
case EVENT_TYPE_PARTYMEMBER_DROPPED:
{
object oFollower = GetEventObject(ev, 0);
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), FALSE);
}
</pre>
When we need to refer to a particular follower explicitly, we can still do so - for example, the flag ZZZPT_PARTY_GODWIN will tell use whether Godwin is currently in the party or not.

==== How do I turn off sustained abilities when a follower is dismissed? ====
'''Please note:''' The 1.04 DA:O patch is bugged and removed/broke several features of the toolkit, if you are using it please follow [http://social.bioware.com/forum/1/topic/71/index/3172230/1#3172537 these steps] to re-enable them as one is required for the script below to compile.

There is a potential exploit in what we've done so far. If a follower casts a sustained spell like Flaming Weapons, it affects all party members. When the follower is dismissed, the remaining party members continue to benefit from the spell.

We can prevent this by deactivating modal abilities before opening the party picker. Add these snippets to the module event script:
<pre>
#include "ability_h"
void zDeactivateModalAbilities();
</pre>
and
<pre>
case EVENT_TYPE_PARTYPICKER_INIT:
{
// Deactivate party modal abilities. This ensures that the party no longer benefits
// from spells like Flaming Weapons if the caster is dismissed from the party.
zDeactivateModalAbilities();
break;
}
</pre>
The function looks like this:
<pre>
// Deactivate party's modal abilities

void zDeactivateModalAbilities()
{
object oPC = GetHero();
object [] oFollowerTable = GetPartyList(oPC);
object oFollower;
int nPartySize = GetArraySize(oFollowerTable);
int [] nAbilityTable;
int nAbilityCount;
int nAbility;
int i = -1;
int j;

while (++i < nPartySize)
{
oFollower = oFollowerTable[i];
nAbilityTable = GetAbilityList(oFollower);
nAbilityCount = GetArraySize(nAbilityTable);
j = -1;

while (++j < nAbilityCount)
{
nAbility = nAbilityTable[j];

if (Ability_IsAbilityActive(oFollower, nAbility))
if (Ability_IsModalAbility(nAbility))
Ability_DeactivateModalAbility(oFollower, nAbility);
}
}
}
</pre>
If other ways of dismissing party members are permitted, the same function can be used.

== Advanced Follower Creation: An Alternative Approach ==

While these things are to a large extent a matter of taste, I see no reason to reinvent the wheel when there is a perfectly good wheel at hand. The following describes how to adapt the existing machinery for the recruitment and tracking of your own party members.

First create the setup as described above in Simple Follower Creation, except for the scripts and plot tables. In addition, create the GDA extensions for a level-up table and the M2DA which points to those tables, as described in Advanced Follower Creation above.

Now ...

=== Step 1: Create a party plot table ===

Have a look at the gen00pt_party plot table and create a similar table for your own followers. Don't bother with the Defined Flags for the moment, just the Main Flags will do, ie recruited, in-camp and in-party for each follower. (Critical Note: Do not duplicate the plot table, create one from scratch. This is the case for ALL plot tables because of a show-stopping bug which means a new GUID is not assigned on Duplicate of a plot.)

=== Step 2: Create a party script ===

Duplicate the gen00pt_party script and rename for your module (conventionally plot tables and their plot scripts have the same name). Delete (or comment out) the Defined Flags section at the end and any lines dealing with logging and tutorials. Change names to those of your party members. If you are using gifting, approval or forced inclusion you may wish to retain those sections of code, but additional machinery will be needed for these facilities to work. For approval you can specify a starting level of approval here for each follower if you want it to be other than zero (as per the existing section dealing with Dog). Note that the custom hire function at the head of the script allows you to specify whether or not to invoke the party picker on recruitment. You may not want to do so for the first couple of followers (but see below). You should already have defined all required constants in a separate file for your module, eg <module prefix>_constants_h. If not, do so now and include it, as well as your plot table, at the head of the script. Delete includes that only refer to the main campaign. (If this is all Greek to you, spend a couple of hours examining the set-up of the Demo, which is packaged with the toolset, and go through the introductory tutorials referenced on the main page of this wiki).

Looking at the new party script, notice that the follower-in-camp function is not defined. This is because for some arcane reason it is defined in party_h, and unhappily references the main campaign's plot table. So we will have to create a new function to replace it, change the other function's flag reference (for the sake of neatness), and change the call in the main body of the script. (You may decide later for other reasons to replicate and customise party_h, but that won't interfere with re-creating this function here.)

Our two functions at the head of the script should be:

<dascript>void SetFollowerInParty(object oFollower, string sPlot, int nCampFlag)
{
WR_SetPlotFlag(sPlot, nCampFlag, FALSE);
WR_SetObjectActive(oFollower, TRUE);
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE);
command cJump = CommandJumpToObject(GetPartyLeader());
WR_AddCommand(oFollower, cJump);
}

void SetFollowerInCamp(object oFollower, string sPlot, int nPartyFlag)
{
WR_SetPlotFlag(sPlot, nPartyFlag, FALSE);
WR_SetObjectActive(oFollower, FALSE);
WR_SetFollowerState(oFollower, FOLLOWER_STATE_AVAILABLE, FALSE);
}</dascript>

and the line in the in-camp sections for each follower should now be:

<dascript>SetFollowerInCamp(o<follower>, strPlot, <follower>_IN_PARTY);</dascript>

=== Step 3: Create package GDAs and reference them in you 2DA_base extension ===

Look at the packages_base GDA and create an extension GDA with one line for each follower based on a main campaign follower that is most like your own follower, eg a sword-shield warrior can be a copy of Alistair, a battle mage a copy of Morrigan, etc. You can look at the Excel version of this GDA to more easily see what the fields mean. It is here that you can specify what if any specialisation will be assigned on hire and the level at which this spec point becomes available. (The IDs for each spec are in the 4000-range of ABI_base.)

Most importantly, it is here also that you define the ID of both your level-up table and the AIP table you are about to create.

Now create aip_follower_<follower name> gda tables, again based on a existing tables most like your own followers. No changes should be required to the copies you create.

In the m2da_base_<your module> extension you have already created, add lines for your AIP tables with a package ID referencing the IDs you assigned in your packages extension table.

Carefully check that all IDs in your GDAs are correct and cross-reference properly, and save the GDAs to your override directory.

Desirable but not obligatory (except for non-humanoid characters), is an extension to the Portraits gda. Finally the Equipment Layout gda will need an extension for non-humanoids, who use a different equipment mask.

=== Step 4: Module script addition ===

Modify your own module script to point to the new plot table and your own followers. To see an example of the required code for the two new sections look at the relevant section of module_core, which are for EVENT_TYPE_PARTYMEMBER_ADDED and EVENT_TYPE_PARTYMEMBER_DROPPED.

=== How it works ===

The recruit flag is set in a conversation (usually, but it could be a script) and that event is then processed by the plot script, which among other things sets both the in-camp and in-party flags, and fires up the party picker by default. If the player then selects the follower in the picker, the in-camp flag is unset (or vice versa if the follower is not selected to join). Subsequently, if the character is selected (or unselected) in the picker, the event is picked up by the module script, which sets the relevant plot flag as true, and that plot event is then sent to the plot scipt which sets the other flag as false.

(Note that if the party picker is turned off for a particular follower's recruit event, that follower will be placed in the active party regardless of the number of members, so ONLY do this for a follower who cannot be recruited when there are already 3 possible followers.)

On recruitment, player_core rebuilds the character according to the specifications laid out in the GDAs, so no further scripting is required.

=== Uses ===

To recruit a party member, set the recruit flag from your plot table in the relevant dialogue. Adding or subtracting followers from the active party is automatically tracked via this machinery, and the plot flags can be interrogated in all your scripts and conversations if you need to know who is currently in the party and who is in camp.

Defined flags can be added as you need them to the script and plot table but there is no point having flags that you will not use, so as with all Defined Flags this is an as-you-go decision, but quite easy to do.

Hiring and firing of temporary party members at the start of a campaign (such as Ser Jory, or Jowan, or Soris, etc) can be handled by UT_HireFollower, and the party picker is not invoked (nor is the Party Camp an available destination).

=== Troubleshooting ===

If you haven't done so already, create a simple debugging area for your module where you can dump the player, all followers and a couple of conversation dummies, and set up a dialogue in which you can invoke all required flags and conditions and see if they actually work as expected. (This setup can be used to test many other components as well.) Global machinery such as this can be painful to set up and get right (unless you are of an exceptionally methodical cast of mind), but it is worthwhile to ensure they are absolutely bullet-proof before you develop the specifics of your module.

=== The KISS principle ===

This is an "out-of-the-box" solution, and once set up is quite robust. If you want variants not catered for here, do NOT try to modify what you already have working.

'''Use-case:''' You want a follower (example tag: dairren) to be recruited without a set specialisation and one level higher than the PC.

Go to your packages gda and set the spec field to 0. In the character's plot table (you should have at least one for each follower) create a flag which we will call BLAH_BLAH. In the table's plot scipt insert the following very simple event handler:

<dascript>case BLAH_BLAH:
{
SetCreatureProperty(oDairren, 38, 1.00); //awards the spec point; field from the properties gda
int aLevel = GetLevel(oHero); //some simple arithmetic to find out the XP we need to award
int bLevel = (aLevel+1);
int aPoints = RW_GetXPNeededForLevel(aLevel);
int bPoints = RW_GetXPNeededForLevel(bLevel);
int targetPoints = (bPoints - aPoints);
RewardXP(oDairren, targetPoints, FALSE, TRUE); //award the XP, and we're done
break;
}</dascript>

The flag can be set in the same conversation as the recruit flag, so long as it comes afterwards. This way you not only maintain the integrity of your core machinery, but keep exceptions/variations for particular characters where they belong -- with that character's plot tables and scripts.

[[Category:Tutorials]]
{{Languages}}

PrintToLog

2011-05-30T07:19:15Z

Proleric1: /* Description */

{{dafunction
|name=PrintToLog
|brief=Prints a timestamped entry to the log file.
|param1type=string
|param1name=sMessage
|param1desc=The string entry to print to the log file.
|returntype=void
|returndesc=
|sourcefile=script.ldf
|sourcemodule=
}}

== Description ==

Prints an entry to the log file. Note this will only be visible if Script logging is enabled. To enable script logging open the <code><DragonAgeInstallDirectory>\bin_ship\[[ECLog.ini]]</code> file and set <code>Script=1</code> in the <code>[LogTypes]</code> section. If this file doesn't exist, create it.






== See also ==

[[PrintInteger]], [[PrintFloat]], [[PrintString]], [[PrintObject]], [[PrintVector]]
[[Category: Print & log functions]]
[[Category:Logging]]

Follower tutorial

2011-05-28T18:32:07Z

Proleric1: /* Dog talents and equipment slots don't work */

== Simple Follower Creation ==

Follow these steps to create a follower that

- Levels up with a default package

- Can be chosen from the party picker

- Can gain XP

This guide assumes you know how to create a creature and are comfortable with basic scripting.

You should only use this simple method if you are sure there will be empty space in the active party when your follower is recruited.

A more comprehensive approach when there are more than three potential party members is discussed in the FAQ below. It's worth taking the time to understand the basics first, though.

=== Create the creature ===

Create a creature to act as your follower. Set its name, appearance, gender, head morph, conversation, inventory etc as you want them to behave in-game.

Set an appropriate '''Tag''' (you'll be using it a lot). I suggest "party_charname".

Make sure you choose a '''Class'''. For most followers this should be Rogue, Warrior or Wizard.

[[File:class.jpg]]

Under Package/Scaling set:

'''General Package Type''' to be '''Party Members'''

'''Package''' to be an appropriate value (probably "Generic - Wizard" or similar)

'''Package AI''' (there should only be one choice)

'''Rank''' to be '''Player'''

[[File:package.jpg]]

Save and export your character as normal.

=== Overlay char_stage ===

In the official campaign, the party picker uses a special area called char_stage. Whether you're extending the official campaign or making a standalone campaign, there is a function that allows you to overlap the offical stage with your own, so that both stages are active simultaneously in game.

In your resource palette, right-click char_stage under the Global folder and select Duplicate to make a copy of the stage with a new resource name, e.g. my_char_stage. In the resource properties, ensure that both Module and Owner Module are set to your module, and the folder of your choice.

[[File:area_palette.jpg]]

Create a new waypoint for your follower to appear on the party picker. This waypoint '''must''' have a tag in the form of "char_" followed by the exact tag of your follower.

[[File:char_stage.jpg]]

In this example the tag of my follower is '''bc_party_miera''' so her waypoint tag must be '''char_bc_party_miera'''

For a standalone module (such as in this example), put your waypoint wherever you please. The illustrated one is directly on top of Morrigan's. For an add-in to the main campaign, you should position your wp appropriately relative to the core party members.

Save and export the area.

Add the following to your module event script:
<dascript>
case EVENT_TYPE_MODULE_GETCHARSTAGE:
{
// Overlay the existing stage with my stage
// "my_char_stage" is the resource name of the overlay area
// "partypicker" is the name of the default GDA
SetPartyPickerStage("my_char_stage", "partypicker");
break;
}
</dascript>

=== Create m2DAs for the Party Picker ===

You will need to create two Excel spreadsheets.

The first should be named (both worksheet and file) '''partypicker_''' with a unique suffix. In this example, my first spreadsheet is named partypicker_fofbc.xls with a worksheet name of partypicker_fofbc - the suffix being the acronym of my module.

Set up your columns as follows:

[[File:partypickerm2da.jpg]]

The '''ID''' for your follower must be '''12 or higher'''. 11 is the highest value used in the base 2DA. 12 is fine for standalone modules, add-ins will probably want to use an arbitrarily high number to avoid potential conflicts.

The '''Label''' should be the follower's name as you wish it to appear on the party picker.

The '''Tag''' must be your follower's tag.

All other values are non-functioning defaults and should be specified as in the image above unless you know explicitly what you're doing.

'''NOTE - ON SELECTION ANIMATIONS'''

Add Animation and Remove Animation are actually Id numbers of different animations, taken from anim_base.gda

Enter and Exit version of animations are generally the best ones to use, altough one can try others. NOT ALL ANIMATIONS WILL WORK, since some require special conditions.
Here are some examples you can use:

819 - talk cursing

629 - reading a book (doesn't work, since it probably requires a book object)

844 - hands behind back (848 and 849 are Enter and Exit versions respectfully)

850 - chest pounding salute

811 - fist pounding

277 - dance

247 - cast area spell

500 - vfx cast

600 - surprised

603 - praying

607 - head bow

609 - standing at attention

651,652 - crouch pray (Enter and exit)

808 - point forward

825 - nodding

840 - hand chop or frustration

905,906 - crouch (Enter, Exit)

919,920 - sit on ground (enter, exit)

965 - kneel down loop

972 - wipe nose

976,977 - squat (Enter, Exit)

986 - wipe eyes

998,999 - hands clasped (Enter, exit)

3029 - inspect nails

3031,3032 - playful (enter, exit)

3054,3056 - slouch (enter, exit)
255 - in-place fly

'''NOTE - ON SELECTION VFX'''

The VFX column is the ID of the vFX effect taken from vFx_base.gda. This one is a bit more tricky, since it also references the BlendTree value from the same file.
Find the ID of the spell effect and look for the BlendTreeName column (should the the 12th columun) and enter BOTH into the respective columns for your character in the partypicker file.

Some examples:

ID --- BLENDTREENAME --- EFFECT

6039 --- fxm_energy_up_p --- Lady of the Forest pillar of light

6040 --- fxm_power_in_p --- Branka - power in

3054 --- fxc_lotf_c --- Lady of the Forest - swirling leaves

3009 --- fxc_succubus_c --- Succubus crust

1549 --- fxa_hly_imp_c --- Holy Impact crust

1076 --- fxa_spi_aur_mht_c --- Spirit - Aura Might crust

The second spreadsheet should be named '''party_picker_''' (note middle underscore). Once again append your unique suffix (in this example party_picker_fofbc.xls with party_picker_fofbc as its worksheet).

Set up your columns and data like so:

[[File:party_pickerm2da.jpg]]

'''ID''' and '''Tag''' should match what you did in the first spreadsheet. Specify INVALID COLUMN for the third column.

If you're familiar with m2DAs, generate them from these files, copy them to your module's override directory, and skip to the next step. Otherwise, read on:

- Go to '''\Program Files\Dragon Age\tools\ResourceBuild\Processors''' (or wherever you installed Dragon Age)

- Copy '''ExcelProcessor.exe''' from that folder to whichever folder has the excel sheets you just created.

- Drag and drop your xls files onto ExcelProcessor. This will create .gda files.

- Copy these .gda files to your module's export directory (probably \Documents\Bioware\Dragon Age\AddIns\yourModule\module\override\toolsetexport). Make sure they are included in your .dazip when the time comes to build your module.

If you are an OpenOffice user and have trouble with ExcelProcessor, you can use [http://social.bioware.com/project/755/ GDApp] to directly create the 2DAs. It rocks!

=== Capture the EVENT_TYPE_PARTYMEMBER_ADDED Event ===

Amusingly enough, the Party Picker does not actually add followers to the party. However it raises an event that allows you to do so. Your module script needs to capture this event and execute some code.

The following example shows what to do with the event. The full script would work as a module script for an add-in (assuming it didn't need to do anything else), but otherwise you'll have to incorporate the event into your own module script.

If you're not sure how to set a module script, go to '''File''' then '''Manage Modules,''' select your module and click '''Properties.'''

<dascript>
#include "utility_h"

void main()
{
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);
switch(nEventType)
{
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0); //Allows the follower to gain XP
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero()))); //Ensures follower appears at PC's location.
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE); //Adds follower to the active party
break;
}

}
}
</dascript>

'''SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE)''' is the key statement to add the follower to the active party. You must have this.

'''SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0)''' is a bug-fix, as followers hired with UT_HireFollower() do not receive XP by default. This statement fixes that, and I consider it best practice to keep it in this event to ensure it is always set. You will not wish to do this if you want a follower that should not gain XP to be on the party picker.

Note that you do not need to intercept the corresponding event for a party member being removed - the party picker handles spawning/despawning, and thus will successfully remove members.

Remember to save and export your module script.

If you're not sure how to set a module script, go to '''File''' then '''Manage Modules,''' select your module and click '''Properties.''' The module script is in the General category, as seen below:

[[File:module_script.jpg]]

You can set this to any script you've created. See [[Scripting tutorial]] and [[Character generation]] for more background and some simple examples of event-handling scripts. In general, you will want to make sure standalone module scripts pass events through to module_core (as in the [[Character generation]] examples) and add-in scripts do not (as in the example above).

=== Create Your Hiring Script ===

Now all that remains is to actually hire the follower :)

Create a script to handle the hiring (which will most likely be fired from a conversation). The script is quite simple:

<dascript>
#include "utility_h"

void main() {

object oFollower = GetObjectByTag("bc_party_miera"); //Use CreateObject() if the creature isn't present in the module yet

UT_HireFollower(oFollower); //Hires the follower

SetPartyPickerGUIStatus(2);

ShowPartyPickerGUI(); //Shows the Party Picker; necessary for the follower to gain XP

}
</dascript>

Make sure you use your own follower's tag and not the example one :)

This script fires the party picker after hiring the follower. That is absolutely necessary via this method, as we have put the XP fix onto an event fired by the party picker. You cannot put the XP fix into this script, it must be called from a later one (the bug is caused by an errant call to an event in player_core, which will be executed AFTER this script).

The easiest way to use this script is directly from conversation, putting it as an action on a line of dialogue where the PC invites the follower to join them. If you're not sure how to associate a script with a dialogue line, see the following image:

[[File:hire_conv.jpg]]

Create your dialogue as normal, select the line you want to fire the script, and click the '''Plots and Scripting''' tab. Use the '''Script''' file chooser in the Action section to browse to the script you created.

If everything worked, you should see something like this:

[[File:picker_success.jpg|thumb|200px|center]]

== Advanced Follower Creation ==

Follow these steps to have full control over the creation of your follower, with options such as:

- Unique level-up template

- Class and specialisation chosen via script

- Any starting state

- Level higher than the PC

- Starts with a specialisation point rather than a specific specialisation

- Set plot flags in the call to the hire script

=== Prepare Creature, char_stage and Party Picker m2DAs ===

Follow the same steps to create your follower creature, char_stage and Party Picker m2DAs as above.

=== Create Party Plot ===

While not necessary, it's very helpful to have plot flags set when a follower is hired or joins/leaves the active party. This makes conversation interjections and the like very easy.

Create a plot with appropriate flags. There's no real need to associate journal text with them:

[[File:follower_plot.jpg]]

See FAQ for an alternative approach to plots when there are more than three potential party members.

=== Add Plot Flags to Party Picker Event Intercept ===

We then update our module script to make use of that plot, like so:

<dascript>
#include "utility_h"
#include "wrappers_h"
#include "plt_bc_create_party" //make sure you include your own plot, not mine

void main()
{
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);
switch(nEventType)
{
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0);
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE);

AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero()))); //Ensures follower appears at PC's location.

if (GetTag(oFollower) == "bc_party_miera") { //You must explicitly test for your follower's tag.
WR_SetPlotFlag(PLT_BC_CREATE_PARTY, PARTY_MIERA_IN_PARTY, TRUE); //Make sure you use your own flags!
}

break;
}

case EVENT_TYPE_PARTYMEMBER_DROPPED:
{
object oFollower = GetEventObject(ev, 0);

if (GetTag(oFollower) == "bc_party_miera") {
WR_SetPlotFlag(PLT_BC_CREATE_PARTY, PARTY_MIERA_IN_PARTY, FALSE); //As above, but set false.
}

}

}
}
</dascript>

=== Create a Level Up Template ===

You can skip this step if you're content to use one of the generic Rogue, Wizard or Warrior templates, but I don't recommend it. Making a template that suits your character is easy and will almost always be better for the player than a generic one that spends points poorly.

Go to \Program Files\Dragon Age\tools\Source\2DA (or wherever you installed Dragon Age).

You should see a number of excel sheets of the form '''ALCharacter.xls''' (such as ALAlistair.xls, ALLeliana.xls, ALRogue_Default.xls etc). Open the one closest to your character (ie Morrigan or Wynne for a wizard, Leliana or Zevran for a rogue). Save a copy as '''ALYourcharacter.xls''' in whatever directory you're using to create your 2DAs, remembering to rename the worksheet '''ALYourcharacter''' (in this example, ALMiera.xls with ALMiera as its worksheet).

It should look something like this:

[[File:ALtable.jpg|thumb|500px|center]]

'''Columns B''' and '''C''' are the talents/spells available to this character. Do not change them.

'''Columns F''' and '''G''' are the skills available to this character. Do not change them.

We will edit the remaining columns like so:

==== Setting Stat Weights ====

The stat weights in '''column J''' determine how the follower will spend their attribute points, in a rough ratio. So if Dexterity is set to 1.5 and Intelligence to 1, you should expect to see 3 points of Dex for every 2 points of Cunning in-game (note Intelligence is the label used in the toolset for Cunning).

Simply change the values in J to reflect how you'd like the character to spend their points. In this example we're creating a wizard, so we're not going to mess around:

[[File:miera_stat_weights.jpg]]

This character will only raise magic. I set the value to 5 rather than something like 1 to provide room underneath for the other stats while still overwhelmingly favouring magic, but in practice I only really ever want that one stat.

In a note left on this column in the existing templates, Bioware's Georg Zoeller writes, "This is the weight of each attribute (row id links into properties.xls.id). 1.0 means 'try to keep this attribute level' (spend 1 point per level). 0.5 means 'try to spend 1 point every two levels' and so on."

The default Mage, Rogue and Warrior templates include '''column L''' labeled "AttInit." Editing these values seems to have no effect on followers set to use these templates.

==== Setting Talent and Skill Priorities ====

'''Columns D''' and '''E''' are the talents/spells that the character will buy, in preference order from top to bottom.

'''Columns H''' and '''I''' are the skills that the character will buy, in preference order from top to bottom.

To change these, just copy the appropriate two cells from columns B&C or F&G over the ones you want to replace.

For example, here we're copying Morrigan's template. Morrigan has Spider Shape high in her preferences, which we do not want.

[[File:AlMori_talent_pref.jpg]]

We decide we'd prefer Flame Blast, so we find it in columns B&C and copy both cells:

[[File:ALMori_copy.jpg]]

Then we select the cells we want to replace in columns D&E and paste over them:

[[File:ALMori_paste.jpg]]

Continue this process until your priorities list for both skills and talents/spells is exactly as you want it. Make sure you have at least as many priorities as the core follower you're copying - points that cannot be spent according to these priorities have a habit of vanishing.

If you used any abilities from a specialisation, make sure you remember to set that specialisation with the function we'll introduce later. The autolevel scripts will add specialisation abilities to a character regardless of whether they have that spec or not.

==== Create a M2DA_base_ m2DA ====

Dragon Age will need to know where to find your autolevel template. We tell it by extending M2DA_base.gda

Create a spreadsheet with the name and worksheet name in the form '''M2DA_base_''' with your unique suffix (in this example, M2DA_base_fofbc.xls with M2DA_base_fofbc as a worksheet).

Set up its columns and data like so (note I used GDApp because Open Office wasn't cooperating for this one!):

[[File:m2da_base_fofbc.jpg]]

The '''ID''' should be very high to avoid conflicts. I've arbitrarily chosen 50,000+ here. Carefully note the ID you've chosen for your character, you will need it later.

Set the '''Label''' and '''Worksheet''' to be the name of your autolevel template worksheet (ALCharactername if you've been following this).

Set the '''PackageIDForAI''' to be 0, it shouldn't be needed for followers.

When you're done, use ExcelProcessor to make GDAs of both spreadsheets and copy them to your module's export folder.

FOR AUTOLEVEL TO WORK AFTER RECRUITING:

Look in packages.xls.
There is a column called LevelupTable. That links to a corresponding AL* table. For instance, row 81 is for Leliana. Her LevelupTable value is 258. If you look that up in 2DA_base, you'll see it links to ALLeliana.
(alternatively, you could try packages_base.gda)

=== Create a New Hire Function Include ===

This section is probably only relevent if you have a specific need to override the functionality of player_core.

Many vital steps of follower addition happen inside an event in player_core. Followers tend to be extremely buggy (no skill tree, for example) if this event does not fire.

However, that event is not very flexible. In order to control it to our requirements, we need to replicate its functionality inside our own script. This is probably much safer than messing with player_core directly!

Create a new script file, naming it something like '''hireCustomFollower_h'''. We will be including this wherever we want to hire a follower.

Paste in the following script:

<dascript>
#include "sys_chargen_h"
#include "wrappers_h"
#include "utility_h"
#include "sys_rewards_h"
#include "approval_h"
#include "sys_autolevelup_h"

/* Jye Nicolson 5-Jan-2010
This function set duplicates the full functionality chain of UT_HireFollower, with the following exceptions:

- Followers can gain XP
- Autolevel status can be set (default off)
- Followers can be set to any starting state (default Available) and will still be properly initalised and added to the party pool
- Autolevel tables for non-core followers can be explicitly set.
- Class and Specialisation can be chosen via script
- Followers without specialisations are granted a spec point by default.

It should only ever be called once each for characters you intend to be full followers.
Much of the protective code handling summoned creatures etc. in player_core is not present here.

Calling the function:

Simple:

hireCustomFollower(oFollower, CLASS_WARRIOR);

Change the class to CLASS_WIZARD or CLASS_ROGUE as appropriate.
This will hire your follower and make them available.
They will auto level up with a default package, and receive a free spec point.

Best Practice:

hireCustomFollower(oFollower, CLASS_WARRIOR, PLT_YOUR_PARTY_PLOT, YOUR_FOLLOWER_JOINED_FLAG, ABILITY_TALENT_HIDDEN_CHAMPION);

Where the plot and flag are those for your module (remember to create the plot and include it on the calling script), and ABILITY_TALENT_HIDDEN etc is the desired spec.

You should also have a custom ALTable set up.
See wiki for details, and remember to edit it in to GetCustomFollowerALTable below or pass it directly as an argument to hireCustomFollower.

Full argument list:

void hireCustomFollower (
object oFollower, //Pass your follower object, mandatory

int nForceClass, //Pass a Class constant here, usually CLASS_ROGUE, CLASS_WARRIOR, CLASS_WIZARD. Mandatory due to a bug.

string sPlot = "", //It's recommended you have a plot flag to be set when the follower joins. Pass the plot constant here. Remember to #include in calling script

int nPlotFlag = "", //And then pass the flag constant. Will be set to TRUE if available.

int nForceSpec = 0, //This is the ID of the Specialisation you want. Note they are NOT classes, but abilities. The full list is:
//ABILITY_SPELL_HIDDEN_ARCANE_WARRIOR, ABILITY_SPELL_HIDDEN_BLOODMAGE, ABILITY_SPELL_HIDDEN_SHAPESHIFTER, ABILITY_SPELL_HIDDEN_SPIRIT_HEALER
//ABILITY_SPELL_HIDDEN_BARD, ABILITY_TALENT_HIDDEN_ASSASSIN, ABILITY_TALENT_HIDDEN_DUELIST, ABILITY_TALENT_HIDDEN_RANGER
//ABILITY_TALENT_HIDDEN_BERSERKER, ABILITY_TALENT_HIDDEN_CHAMPION, ABILITY_TALENT_HIDDEN_REAVER, ABILITY_TALENT_HIDDEN_TEMPLAR
//I recommended forcing a spec, particularly if your ALTable includes abilities from one.

int nALTable = 0, //This is the ID of an ALTable from 2DA_base.GDA or your module's m2DA_base_*.GDA I recommended the latter, but you can edit that into GetCustomFollowerALTable below rather than passing it.

int bInvokePicker = FALSE, //Sets whether the party picker should be opened on hiring. I think it's cleaner to call the picker outside this script, particularly if you have multiple hires at once.

int nInitialState = FOLLOWER_STATE_AVAILABLE, //This sets whether the follower joins the active party or not. Options are:
//FOLLOWER_STATE_ACTIVE (put them in the active party)
//FOLLOWER_STATE_LOCKEDACTIVE (force them into the active party and keep them there, remember to change this later.
//FOLLOWER_STATE_AVAILABLE (make them available on the party picker (if you've set it up for them), but not in the active party)
//Plus some others you're unlikely to need at this time. Defaults to AVAILABLE because having 4+ active followers is screwy.

string sCurrPlot = "", //If you set FOLLOWER_STATE_ACTIVE or FOLLOWER_STATE_LOCKEDACTIVE, the script will check to see if you passed this.
//It is recommended that you have a plot flag set for a given follower being in the active party, this makes conversation interjection etc. much easier.

int nCurrPlotFlag = 0, //This flag will be set if FOLLOWER_STATE_ACTIVE or FOLLOWER_STATE_LOCKEDACTIVE are true
//AND sCurrPlot has a value AND nCurrPlotFlag is > 0.
//ie if you added someone to the active party and have a plot flag to cope with it.

int nAutolevel = 0, //Sets the Autolevel flag on the character sheet. 0 is off, 1 is on, 2 forces it on and removes it so the player can't turn it off.

bFreeSpecPoint = TRUE, //This grants a specialisation point to the follower if they do not have a specialisation.
//It's important to set this false for classes that do not have specs, such as CLASS_DOG.

int nTargetLevel = 0, //If you want a specific level, set this. Generally not worthwhile unless you set it higher than the player, since they'll just get XP from the party picker anyway.

int nMinLevel = 0 //Set this if there's a specific level you don't want the follower to go below. Probably only useful if the PC might be very low level but not necessarily so.

)
*/
/* GetCustomFollowerALTable()
This function is where you put your custom table assignments.

You should explicitly test for the tag of your follower (not mine!) and assign a value to nTable from your m2DA extension to M2DA_base

See wiki for details on how to do this, or ignore it to get the default Warrior/Rogue/Wizard AL tables.

NOTE: you MUST explicitly set a table for non-Warrior/Rogue/Wizards, eg dogs. Use TABLE_AL_DOG for a default Mabari.
*/

int GetCustomFollowerALTable(object oFollower) {
int nTable = _GetTableToUseForAL(oFollower);

if (GetTag(oFollower) == "bc_party_miera") {
nTable = 50143;
}

if (GetTag(oFollower) == "bc_party_jysavin") {
nTable = 50144;
}

if (GetTag(oFollower) == "bc_party_geldual") {
nTable = 50145;
}

if (GetTag(oFollower) == "bc_party_braghon") {
nTable = 50146;
}

return nTable;
}

// This just cleans up the main function a little

int GetCustomFollowerTargetLevel(object oFollower, object oHero, int nPackage, int nMinLevel = 0) {
int nPlayerLevel = GetLevel(oHero);
int nTargetLevel = 0;

if((nPlayerLevel >= 13) || (nPlayerLevel == 1) || (!_UT_GetIsPlotFollower(oFollower))) {
nTargetLevel = nPlayerLevel;
} else {
nTargetLevel = nPlayerLevel + 1;
}

if (nMinLevel == 0) { //If nMinLevel is not specified, checks package 2DA for a value
nMinLevel = GetM2DAInt(TABLE_PACKAGES, "MinLevel", nPackage);
}
if(nMinLevel > 0 && nMinLevel > nTargetLevel) {
nTargetLevel = nMinLevel;
}

return nTargetLevel;

}

// Moving this black box out :) I don't really understand it, but it should function if you have tactics set up in a package.

void InitCustomFollowerTactics(object oFollower, int nPackage) {
int nTableID = GetM2DAInt(TABLE_PACKAGES, "FollowerTacticsTable", nPackage);
if (nTableID != -1)
{
int nRows = GetM2DARows(nTableID);
int nMaxTactics = GetNumTactics(oFollower);

int nTacticsEntry = 1;
int i;
for (i = 1; i <= nRows && nTacticsEntry <= nMaxTactics; ++i)
{
int bAddEntry = FALSE;
int nTargetType = GetM2DAInt(nTableID, "TargetType", i);
int nCondition = GetM2DAInt(nTableID, "Condition", i);
int nCommandType = GetM2DAInt(nTableID, "Command", i);
int nCommandParam = GetM2DAInt(nTableID, "SubCommand", i);

int nUseType = GetM2DAInt(TABLE_COMMAND_TYPES, "UseType", nCommandType);
if (nUseType == 0)
{
bAddEntry = TRUE;
}
else
{
bAddEntry = HasAbility(oFollower, nCommandParam);
}

if (bAddEntry)
{
SetTacticEntry(oFollower, nTacticsEntry, TRUE, nTargetType, nCondition, nCommandType, nCommandParam);
++nTacticsEntry;
}
}
}
}

/* InitCustomFollowerSpec:

This function tries to set the forced Specialisation. If there is none, it checks the package for one.

If there isn't either of those, it grants a free spec point if bFreeSpecPoint is true.

*/

void InitCustomFollowerSpec(object oFollower, int nPackage, int nForceSpec, int bFreeSpecPoint) {
// Find specialization, and optionally add a spec point if none is found.

if (nForceSpec == 0) {

int nSpecAbility = GetM2DAInt(TABLE_PACKAGES, "switch1_class", nPackage); // followers can have only 1 advanced class
if(nSpecAbility > 0)
{
AddAbility(oFollower, nSpecAbility);
} else {
if (bFreeSpecPoint) {
SetCreatureProperty(oFollower, 38, 1.00);
}
}

} else {

AddAbility(oFollower, nForceSpec);

}
}

/* hireCustomFollower() (See doco at top of page)

I strongly suggest you reorder the parameters if you're adding many followers with advanced options.

Feel free to leave them alone if you only want to set class, plot, spec or don't mind long declarations.

Note nForceClass is currently compulsory due to flakiness with GetCreatureCoreClass()
*/

void hireCustomFollower(object oFollower, int nForceClass, string sPlot = "", int nPlotFlag = 0, int nForceSpec = 0,
int nALTable = 0, int bInvokePicker = FALSE, int nInitialState = FOLLOWER_STATE_AVAILABLE, string sCurrPlot = "",
int nCurrPlotFlag = 0, int nAutolevel = 0, int bFreeSpecPoint = TRUE, int nTargetLevel = 0, int nMinLevel = 0)
{

object oHero = GetHero();

/* ################# BEGIN BASIC FOLLOWER JOIN BLOCK ###################

This loosely replicates WR_SetFollowerState.

*/

if (nForceClass == 0) {
nForceClass = GetCreatureCoreClass(oFollower); //This is not working. Hence nForceClass mandatory.
}

SetGroupId(oFollower, GetGroupId(oHero)); //Puts the follower in the pc's Group.
SetEventScript(oFollower, RESOURCE_SCRIPT_PLAYER_CORE); //This makes them act like a player.
SetFollowerState(oFollower, nInitialState); //This sets whether they are available, in the active party etc.

/* ################# END BASIC FOLLOWER JOIN BLOCK ##################### */

/* ################# BEGIN PLAYER_CORE EVENT_TYPE_PARTY_MEMBER_HIRED EMULATION #################
This replicates the EVENT_TYPE_PARTY_MEMBER_HIRED handler from player_core, stripped down for simplicity and allowing our custom options.

*/

Chargen_EnableTacticsPresets(oFollower); //I assume this is important.

SetLocalInt(oFollower, FOLLOWER_SCALED, 1); //This should prevent the follower being rescaled by player_core or what have you

int nPackage = GetPackage(oFollower); //Gets the package, which will be used to find a number of 2DA IDs.
int nPackageClass = GetM2DAInt(TABLE_PACKAGES, "StartingClass", nPackage); //I don't think this is used, even by player_core

// set behavior according to package
int nBehavior = GetM2DAInt(TABLE_PACKAGES, "FollowerBehavior", nPackage);

if(nBehavior >= 0) {
SetAIBehavior(oFollower, nBehavior);
}

Chargen_InitializeCharacter(oFollower); //We initialise the follower and choose race/class.

Chargen_SelectRace(oFollower,GetCreatureRacialType(oFollower));
Chargen_SelectCoreClass(oFollower,nForceClass);

if (nTargetLevel == 0) { //This block picks a target level if not specified

nTargetLevel = GetCustomFollowerTargetLevel(oFollower, oHero, nPackage, nMinLevel);
}

int nXp = RW_GetXPNeededForLevel(Max(nTargetLevel, 1)); //Here is where the XP is calculated and rewarded
RewardXP(oFollower, nXp, FALSE, FALSE);

// -------------------------------------------------------------
// add hidden approval talents - (JN: I don't know how to set these yet, but when I figure it out this should make it work)
// -------------------------------------------------------------
int nIndex = Approval_GetFollowerIndex(oFollower);
Approval_AddFollowerBonusAbility(nIndex, 0);

//Handle Specialisation
InitCustomFollowerSpec(oFollower, nPackage, nForceSpec, bFreeSpecPoint);

// -------------------------------------------------------------
// This spends all available attribute and stat points on the
// creature according to the levelup table. (JN: this replicates AL_DoAutoLevelUp but with our choice of table)
// -------------------------------------------------------------

if (nALTable == 0) {
nALTable = GetCustomFollowerALTable(oFollower);
}

AL_SpendAttributePoints(oFollower, nALTable, FALSE);
AL_SpendSkillPoints(oFollower, nALTable, TRUE);
AL_SpendSpecializationPoints(oFollower, nALTable);
AL_SpendTalentSpellPoints(oFollower, nALTable, TRUE);

// -------------------------------------------------------------------------
// Update various UIs
// -------------------------------------------------------------------------
Chargen_SetNumTactics(oFollower);
SetCanLevelUp(oFollower,Chargen_HasPointsToSpend(oFollower));

// load tactics
InitCustomFollowerTactics(oFollower, nPackage);

/* ################# END PLAYER_CORE EVENT_TYPE_PARTY_MEMBER_HIRED EMULATION ################# */

SetAutoLevelUp(oFollower, nAutolevel); //This is the autolevel flag on the character sheet.

//Set plot flags

if (!((sPlot == "") || (nPlotFlag == 0))) { //Joined Party
WR_SetPlotFlag(sPlot, nPlotFlag, TRUE);
}

if ((nInitialState == FOLLOWER_STATE_ACTIVE) || (nInitialState == FOLLOWER_STATE_LOCKEDACTIVE)) {
if (!((sCurrPlot == "") || (nCurrPlotFlag == 0))) {
WR_SetPlotFlag(sCurrPlot, nCurrPlotFlag, TRUE); //Currently in Party
}
}

// Invoke picker if requested.

if (bInvokePicker) {
SetPartyPickerGUIStatus(2);
ShowPartyPickerGUI();
}
}
</dascript>

Yeah, I know. It can't really be any smaller. Feel free to modify it if you're confident with scripting.
==== Add Your Custom Autolevel Template to GetCustomFollowerALTable() ====
While you can pass the ID you made for your autolevel template to that monster function as an argument, it's better to have them all in one place if you have multiple followers.

GetCustomFollowerALTable() is the first function in our include, and you can add an explicit if test for your follower there to assign the correct table id (the one from your M2DA_base_ m2DA). There is a function very much like it in sys_autolevel_h.nss for the core followers, so we'll copy Bioware's practice.

Let's take a look at the function by itself:

<dascript>
int GetCustomFollowerALTable(object oFollower) {
int nTable = _GetTableToUseForAL(oFollower);

if (GetTag(oFollower) == "bc_party_miera") {
nTable = 50143;
}

if (GetTag(oFollower) == "bc_party_jysavin") {
nTable = 50144;
}

if (GetTag(oFollower) == "bc_party_geldual") {
nTable = 50145;
}

if (GetTag(oFollower) == "bc_party_braghon") {
nTable = 50146;
}

return nTable;

}
</dascript>

So we have a test for each follower tag from my module, matching up to an ID which is assigned to nTable. All you need to do is change a tag from my follower to yours, and my ID to the correct one from your M2DA_base_* m2DA. Then you should delete the rest of the example if statements :)

Save and export the script. Ignore the compiler error about lack of main();

=== Include Function In Your Hire Script and Call It ===

So instead of a hire script that calls UT_HireFollower(), we want one that includes our shiny new function and calls it.

Take a look at the following example:

<dascript>
#include "plt_bc_create_party" //Make sure you include your party handling plot
#include "hireCustomFollower_h" // And include the function script - which will in turn include a bunch of stuff

void main() {

//Initialising my objects, not super-relevant to the example

object oHero = GetHero();
object oMiera = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_miera.utc", GetLocation(oHero));
object oJysavin = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_jysavin.utc", GetLocation(oHero));
object oBraghon = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_braghon.utc", GetLocation(oHero));
object oSpider = CreateObject(OBJECT_TYPE_CREATURE, R"bc_party_geldual.utc", GetLocation(oHero));

//Simplest hire call - adds to the party as a wizard. Class is currently compulsory due to a bug.
hireCustomFollower(oMiera, CLASS_WIZARD);

//Add to the party and set joining plot flags
hireCustomFollower(oJysavin, CLASS_WARRIOR, PLT_BC_CREATE_PARTY, PARTY_JYSAVIN_JOINED);

//Add to the party, set plot flags, force a specialisation
hireCustomFollower(oBraghon, CLASS_ROGUE, PLT_BC_CREATE_PARTY, PARTY_BRAGHON_JOINED, ABILITY_TALENT_HIDDEN_ASSASSIN);

//More complex example - Follower added as a unique class (Dog), not granted a specialisation or spec point.
//Note unique classes must have an ALTable passed here or specified in GetCustomFollowerALTable() or they won't work
hireCustomFollower(oSpider, CLASS_DOG, PLT_BC_CREATE_PARTY, PARTY_GELDUAL_JOINED, 0, 0, FALSE, FOLLOWER_STATE_AVAILABLE, "", 0, 0, FALSE);

//Show the party picker to let the player choose from their new companions!
SetPartyPickerGUIStatus(2);
ShowPartyPickerGUI();
}
</dascript>

The example shows several of the more simple ways of invoking the function. Check the comments at the start of the function for a full list of arguments.

I would suggest best practice for most followers would be to call as follows:

'''hireCustomFollower(oFollower, CLASS, PLOT, PLOT_FLAG, SPECIALISATION)'''

This will safely set the follower up as the desired class and specialisation (doubly important if there are spec abilities in their ALTable) while setting your plot flag for them being in the party. hireCustomFollower(oFollower, CLASS, PLOT, PLOT_FLAG, SPECIALISATION, 0, TRUE) will do the same while invoking the Party Picker automatically.

Note that the specialisations are abilities and not classes - you'll find them as ABILITY_HIDDEN_ constants.

If it's all worked, you should find you can now add followers with a lot more flexibility!

[[File:picker_advanced.jpg|thumb|500px|center]]

== Common Follower Problems & FAQ ==

====Why don't my followers gain XP?====
There is a bug in UT_HireFollower. For now the best/easiest approach to take might be to make a copy of UT_HireFollower in an include file and rename it something like UT_HireFollower_Fixed, then make the following change:
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, TRUE);
to
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, bPreventLevelup);
(Note: Be aware if you use the name UT_HireFollower_Fixed you may end up finding your include file conflicting with someone else who has named it the same in their include.)

Alternately you need to clear a flag in a separate script to the one in which they're hired.

You must use the '''SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0);''' statement in a script you can be sure will run soon after your hiring script.

====When I choose followers from the Party Picker, they spawn into the area but do not join.====

You need to intercept the EVENT_TYPE_PARTYMEMBER_ADDED event and set the follower to FOLLOWER_STATE_ACTIVE. See Simple Follower Creation earlier in this document.

====My followers don't have skill trees!====

If a follower hasn't been through an initial chargen/autolevel event (via player_core/sys_autolevel_h) then the skill tree doesn't show. You're probably trying to be clever and get around UT_HireFollower without going all the way (see monster function above ^_^).

====My followers don't have a class====

GetCreatureCoreClass() seems flaky under some conditions. It's best to explicitly set the class yourself; this is why class is currently a mandatory argument to hireCustomFollower()

====Dog talents and equipment slots don't work====
Symptoms: dog talents appear on the talents screen but remain greyed out on level up. Warrior talents appear in the quickslots. Equipment slots are for humans, not dogs.

Line 78 of packages_base in packages.xls (Dog) should have the LevelUpTable column set to 257 which is the ALDog table.

The EquipmentLayout 2DA needs a new entry for the follower:

ID=same as partypicker 2DA
Tag=follower tag
AvailableEquipmentSlots=794624
Layout=2
EnableWeaponSets=0

If the creature is not using the appearance "Dog, Party Member", it needs a new appearance line in APR_base. Most of the entries can be copied from the standard appearance (e.g. Wolf), but

MaxScaleLevel=-1
DefaultArmor=
AppearanceRestrictionGroup=1

Otherwise, it won't be able to progress beyond a specified level. The player will receive an unwanted set of armour when the it is hired, and it won't be able to use Marabi crunch items. You may also need to tweak PERSPACE and/or BumpLevel if excessive clipping occurs.

====Isn't there an easier way to do this?====

Possibly. There is a way of recruiting a follower by setting a plot flag. However I don't understand it, and I expect it still doesn't allow custom autolevel templates, full control over specialisations etc. There's still a fair bit of stuff hardcoded for the core followers, I'm not sure putting a custom follower through the same process as Al, Leli et al will have good results.

The next section answers this question, up to a point.

==== What if there are more than three potential followers? ====
This example handles larger numbers of followers, and doesn't force the player to use the party picker unless the party is already full.

The prefix zzz, used throughout, can be replaced with whatever [[Prefixes_in_use | prefix]] you are using for your resources.

If you're making a new campaign, to keep life simple, allocate a unique number to each follower. You could either use a creature variable or a script, e.g.
<pre>
// Party member id (e.g. 1=Alicia, 2=Godwin...)
int zzzPartyMemberID(object oPartyMember)
{
string sPartyMember = GetTag(oPartyMember);

if (sPartyMember == "zzzcr_alicia") return 1;
if (sPartyMember == "zzzcr_godwin") return 2;
if (sPartyMember == "zzzcr_harold") return 3;
if (sPartyMember == "zzzcr_lara" ) return 4;
return 0;
}
</pre>

Make two separate plots, e.g. zzzpt_hired for when a follower is first recruited, and zzzpt_party to flag whether they're currently in the party. Use flag values that correspond to the unique follower id, e.g. ZZZPT_HIRED_GODWIN will be 2.

If you're modifying the official campaign, you won't be able to make this simplification - you'll need a set of plot flags for your new party members, similar to the official ones. The logic of what follows is still correct, it just means that instead of having one set of common code that works for everyone, you have to explicitly script each party member individually using their personal plot flags.

Follower conversation is now very simple. In Godwin's dialogue, the hiring line will be conditional - when ZZZPT_HIRED_GODWIN is clear - and it will set ZZZPT_HIRED_GODWIN. No conversation script is necessary. Instead, in the properties of the plot zzzpt_hired, we add a plot event script, as follows.
<pre>
// PARTY HIRE PLOT SCRIPT
//
// This is called in conversation when a party member is hired for the first time.
// If the party is full, the party picker is displayed, which forces the PARTYMEMBER_ADDED
// module event.
//
// The flag value is never referenced, because the code is common for all party members.

#include "events_h"
#include "global_objects_h"
#include "utility_h"
#include "sys_rewards_h"
#include "log_h"
#include "utility_h"
#include "wrappers_h"
#include "plot_h"

#include "zzz_h" // A header containing the zzzPartyMemberID function
#include "plt_zzzpt_hired"
#include "plt_zzzpt_party"

int StartingConditional()
{
event eParms = GetCurrentEvent();
int nType = GetEventType(eParms); // GET or SET
string strPlot = GetEventString(eParms, 0); // Plot GUID
int nFlag = GetEventInteger(eParms, 1); // Plot flag
object oParty = GetEventCreator(eParms); // Plot table owner
object oFollower = GetEventObject(eParms, 0); // Conversation owner (if any)
int nPlotType = GetEventInteger(eParms, 5); // Plot type

int bIsTutorial = GetM2DAInt(TABLE_PLOT_TYPES, "IsTutorial", nPlotType);
int bIsCodex = GetM2DAInt(TABLE_PLOT_TYPES, "IsCodex", nPlotType);

int nResult = FALSE; // return value for DEFINED GET
object oPC = GetPartyLeader();

plot_GlobalPlotHandler(eParms); // any global plot operations, including debug info

if (nType == EVENT_TYPE_SET_PLOT) // actions -> normal flags only
{
int nValue = GetEventInteger(eParms, 2); // 0=Clear 1=Set
int nOldValue = GetEventInteger(eParms, 3); // Current flag value

if (nValue)
{
if (GetArraySize(GetPartyList(oPC)) < 4)
{
UT_HireFollower(oFollower);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0);
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero())));
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE);
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), TRUE);
}
else
{
WR_SetFollowerState(oFollower, FOLLOWER_STATE_AVAILABLE, FALSE);
SetEventScript(oFollower, RESOURCE_SCRIPT_PLAYER_CORE);
SendPartyMemberHiredEvent(oFollower, TRUE);
// SetPartyPickerGUIStatus(PP_GUI_STATUS_USE);
// ShowPartyPickerGUI();
}
}
}
else // EVENT_TYPE_GET_PLOT -> defined conditions only
{
switch(nFlag)
{

}
}

plot_OutputDefinedFlag(eParms, nResult);
return nResult;
}
</pre>
We still need to handle the party picker events in our module event script:
<pre>
// PARTY MEMBER ADDED - Allow XP gain. Come here, follow me, flag as party member.
case EVENT_TYPE_PARTYMEMBER_ADDED:
{
object oFollower = GetEventObject(ev, 0);
SetLocalInt(oFollower, CREATURE_REWARD_FLAGS, 0);
AddCommand(oFollower, CommandJumpToLocation(GetLocation(GetHero())));
SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE);
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), TRUE);
break;
}
// PARTY MEMBER DROPPED - flag as not party member.
case EVENT_TYPE_PARTYMEMBER_DROPPED:
{
object oFollower = GetEventObject(ev, 0);
WR_SetPlotFlag(PLT_ZZZPT_PARTY, zzzPartyMemberID(oFollower), FALSE);
}
</pre>
When we need to refer to a particular follower explicitly, we can still do so - for example, the flag ZZZPT_PARTY_GODWIN will tell use whether Godwin is currently in the party or not.

==== How do I turn off sustained abilities when a follower is dismissed? ====
'''Please note:''' The 1.04 DA:O patch is bugged and removed/broke several features of the toolkit, if you are using it please follow [http://social.bioware.com/forum/1/topic/71/index/3172230/1#3172537 these steps] to re-enable them as one is required for the script below to compile.

There is a potential exploit in what we've done so far. If a follower casts a sustained spell like Flaming Weapons, it affects all party members. When the follower is dismissed, the remaining party members continue to benefit from the spell.

We can prevent this by deactivating modal abilities before opening the party picker. Add these snippets to the module event script:
<pre>
#include "ability_h"
void zDeactivateModalAbilities();
</pre>
and
<pre>
case EVENT_TYPE_PARTYPICKER_INIT:
{
// Deactivate party modal abilities. This ensures that the party no longer benefits
// from spells like Flaming Weapons if the caster is dismissed from the party.
zDeactivateModalAbilities();
break;
}
</pre>
The function looks like this:
<pre>
// Deactivate party's modal abilities

void zDeactivateModalAbilities()
{
object oPC = GetHero();
object [] oFollowerTable = GetPartyList(oPC);
object oFollower;
int nPartySize = GetArraySize(oFollowerTable);
int [] nAbilityTable;
int nAbilityCount;
int nAbility;
int i = -1;
int j;

while (++i < nPartySize)
{
oFollower = oFollowerTable[i];
nAbilityTable = GetAbilityList(oFollower);
nAbilityCount = GetArraySize(nAbilityTable);
j = -1;

while (++j < nAbilityCount)
{
nAbility = nAbilityTable[j];

if (Ability_IsAbilityActive(oFollower, nAbility))
if (Ability_IsModalAbility(nAbility))
Ability_DeactivateModalAbility(oFollower, nAbility);
}
}
}
</pre>
If other ways of dismissing party members are permitted, the same function can be used.

== Advanced Follower Creation: An Alternative Approach ==

While these things are to a large extent a matter of taste, I see no reason to reinvent the wheel when there is a perfectly good wheel at hand. The following describes how to adapt the existing machinery for the recruitment and tracking of your own party members.

First create the setup as described above in Simple Follower Creation, except for the scripts and plot tables. In addition, create the GDA extensions for a level-up table and the M2DA which points to those tables, as described in Advanced Follower Creation above.

Now ...

=== Step 1: Create a party plot table ===

Have a look at the gen00pt_party plot table and create a similar table for your own followers. Don't bother with the Defined Flags for the moment, just the Main Flags will do, ie recruited, in-camp and in-party for each follower. (Critical Note: Do not duplicate the plot table, create one from scratch. This is the case for ALL plot tables because of a show-stopping bug which means a new GUID is not assigned on Duplicate of a plot.)

=== Step 2: Create a party script ===

Duplicate the gen00pt_party script and rename for your module (conventionally plot tables and their plot scripts have the same name). Delete (or comment out) the Defined Flags section at the end and any lines dealing with logging and tutorials. Change names to those of your party members. If you are using gifting, approval or forced inclusion you may wish to retain those sections of code, but additional machinery will be needed for these facilities to work. For approval you can specify a starting level of approval here for each follower if you want it to be other than zero (as per the existing section dealing with Dog). Note that the custom hire function at the head of the script allows you to specify whether or not to invoke the party picker on recruitment. You may not want to do so for the first couple of followers (but see below). You should already have defined all required constants in a separate file for your module, eg <module prefix>_constants_h. If not, do so now and include it, as well as your plot table, at the head of the script. Delete includes that only refer to the main campaign. (If this is all Greek to you, spend a couple of hours examining the set-up of the Demo, which is packaged with the toolset, and go through the introductory tutorials referenced on the main page of this wiki).

Looking at the new party script, notice that the follower-in-camp function is not defined. This is because for some arcane reason it is defined in party_h, and unhappily references the main campaign's plot table. So we will have to create a new function to replace it, change the other function's flag reference (for the sake of neatness), and change the call in the main body of the script. (You may decide later for other reasons to replicate and customise party_h, but that won't interfere with re-creating this function here.)

Our two functions at the head of the script should be:

<dascript>void SetFollowerInParty(object oFollower, string sPlot, int nCampFlag)
{
WR_SetPlotFlag(sPlot, nCampFlag, FALSE);
WR_SetObjectActive(oFollower, TRUE);
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE);
command cJump = CommandJumpToObject(GetPartyLeader());
WR_AddCommand(oFollower, cJump);
}

void SetFollowerInCamp(object oFollower, string sPlot, int nPartyFlag)
{
WR_SetPlotFlag(sPlot, nPartyFlag, FALSE);
WR_SetObjectActive(oFollower, FALSE);
WR_SetFollowerState(oFollower, FOLLOWER_STATE_AVAILABLE, FALSE);
}</dascript>

and the line in the in-camp sections for each follower should now be:

<dascript>SetFollowerInCamp(o<follower>, strPlot, <follower>_IN_PARTY);</dascript>

=== Step 3: Create package GDAs and reference them in you 2DA_base extension ===

Look at the packages_base GDA and create an extension GDA with one line for each follower based on a main campaign follower that is most like your own follower, eg a sword-shield warrior can be a copy of Alistair, a battle mage a copy of Morrigan, etc. You can look at the Excel version of this GDA to more easily see what the fields mean. It is here that you can specify what if any specialisation will be assigned on hire and the level at which this spec point becomes available. (The IDs for each spec are in the 4000-range of ABI_base.)

Most importantly, it is here also that you define the ID of both your level-up table and the AIP table you are about to create.

Now create aip_follower_<follower name> gda tables, again based on a existing tables most like your own followers. No changes should be required to the copies you create.

In the m2da_base_<your module> extension you have already created, add lines for your AIP tables with a package ID referencing the IDs you assigned in your packages extension table.

Carefully check that all IDs in your GDAs are correct and cross-reference properly, and save the GDAs to your override directory.

Desirable but not obligatory (except for non-humanoid characters), is an extension to the Portraits gda. Finally the Equipment Layout gda will need an extension for non-humanoids, who use a different equipment mask.

=== Step 4: Module script addition ===

Modify your own module script to point to the new plot table and your own followers. To see an example of the required code for the two new sections look at the relevant section of module_core, which are for EVENT_TYPE_PARTYMEMBER_ADDED and EVENT_TYPE_PARTYMEMBER_DROPPED.

=== How it works ===

The recruit flag is set in a conversation (usually, but it could be a script) and that event is then processed by the plot script, which among other things sets both the in-camp and in-party flags, and fires up the party picker by default. If the player then selects the follower in the picker, the in-camp flag is unset (or vice versa if the follower is not selected to join). Subsequently, if the character is selected (or unselected) in the picker, the event is picked up by the module script, which sets the relevant plot flag as true, and that plot event is then sent to the plot scipt which sets the other flag as false.

(Note that if the party picker is turned off for a particular follower's recruit event, that follower will be placed in the active party regardless of the number of members, so ONLY do this for a follower who cannot be recruited when there are already 3 possible followers.)

On recruitment, player_core rebuilds the character according to the specifications laid out in the GDAs, so no further scripting is required.

=== Uses ===

To recruit a party member, set the recruit flag from your plot table in the relevant dialogue. Adding or subtracting followers from the active party is automatically tracked via this machinery, and the plot flags can be interrogated in all your scripts and conversations if you need to know who is currently in the party and who is in camp.

Defined flags can be added as you need them to the script and plot table but there is no point having flags that you will not use, so as with all Defined Flags this is an as-you-go decision, but quite easy to do.

Hiring and firing of temporary party members at the start of a campaign (such as Ser Jory, or Jowan, or Soris, etc) can be handled by UT_HireFollower, and the party picker is not invoked (nor is the Party Camp an available destination).

=== Troubleshooting ===

If you haven't done so already, create a simple debugging area for your module where you can dump the player, all followers and a couple of conversation dummies, and set up a dialogue in which you can invoke all required flags and conditions and see if they actually work as expected. (This setup can be used to test many other components as well.) Global machinery such as this can be painful to set up and get right (unless you are of an exceptionally methodical cast of mind), but it is worthwhile to ensure they are absolutely bullet-proof before you develop the specifics of your module.

=== The KISS principle ===

This is an "out-of-the-box" solution, and once set up is quite robust. If you want variants not catered for here, do NOT try to modify what you already have working.

'''Use-case:''' You want a follower (example tag: dairren) to be recruited without a set specialisation and one level higher than the PC.

Go to your packages gda and set the spec field to 0. In the character's plot table (you should have at least one for each follower) create a flag which we will call BLAH_BLAH. In the table's plot scipt insert the following very simple event handler:

<dascript>case BLAH_BLAH:
{
SetCreatureProperty(oDairren, 38, 1.00); //awards the spec point; field from the properties gda
int aLevel = GetLevel(oHero); //some simple arithmetic to find out the XP we need to award
int bLevel = (aLevel+1);
int aPoints = RW_GetXPNeededForLevel(aLevel);
int bPoints = RW_GetXPNeededForLevel(bLevel);
int targetPoints = (bPoints - aPoints);
RewardXP(oDairren, targetPoints, FALSE, TRUE); //award the XP, and we're done
break;
}</dascript>

The flag can be set in the same conversation as the recruit flag, so long as it comes afterwards. This way you not only maintain the integrity of your core machinery, but keep exceptions/variations for particular characters where they belong -- with that character's plot tables and scripts.

[[Category:Tutorials]]
{{Languages}}

2DA ranges in use

2011-05-28T08:18:53Z

Proleric1: /* APR_base */

This page is meant to enumerate row ID ranges that are used by the main game and by various popular addins, to avoid accidental overlap. See also [[Prefixes in use]] and [[Compatibility]].

Note that there's no need for 2DA row IDs to be sequential, so you can use very large row ID numbers to reduce the chances of collision.

Version 1.0 of the toolset had a bug in ExcelProcessor that caused problems with high row ID numbers, but this has been fixed in subsequent releases. See [[Bug: ExcelProcessor doesn't handle row IDs above 8.3 million correctly|the bug report]].

As of now there is a bug that prevents ID's above 255 to be used for some M2DA's. See [[Bug: High M2DA ID ranges might work in the toolset, but not in game|Bug report]] for a list of tables affected.

Another [[Bug: DLC conflicts with standalone campaigns|bug]] affects the rewards M2DA.

== ABI_base ==

According to the [[ABI_base]] page under the ''tooltipstrref'' column, anything over 500000 is considered a debuff. This would limit the range a fair amount.

{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 200262'''
| '''Bioware - Main campaign'''
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 24000 - 26000
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|-
| 37000 - 38000
| [http://bg2redux.student.utwente.nl/trac/wiki Baldur's Gate Redux]
|-
| 50000 - 50001
| Anakin's [http://social.bioware.com/project/861/ Advanced Tactics]
|-
| 51000 - 51002
| Anakin's [http://social.bioware.com/project/1888/ Advanced Quickbar]
|-
| 450000 - 450300
| ladydesire's [http://social.bioware.com/project/815/ Tevinter Warden class]
|-
| 466000 - 466100
| Apolyon6k's [http://social.bioware.com/project/3842/ The magic of innocence]
|-
| 901974-903000 and 401974-403000(modal)
| Idomeneas' [http://social.bioware.com/project/3152/ Valeria Addon]
|-
| 1337000 - 1337008
| amcnow's [http://social.bioware.com/project/3823/ Respecification]
|-
| 2560000 - 2560500
| Timelord's [http://social.bioware.com/project/1845/ Blood and Lyrium]
|-
| 5680000 - 5680250
| Phaenan's [http://social.bioware.com/project/672/ The Winter Forge]
|-
| 30000000 - 40000000
| MCC's Senderfall: The Last Bastion (To author: unreasonable range, please correct)
|-
| 300000-300047
| rebel5555's [http://social.bioware.com/project/2646/ 2 Handed Weapon Abilities for Arcane Warriors]
|-
| 300000-300047
| rebel5555's [http://social.bioware.com/project/3637/ Dual Weapon Abilities for Arcane Warriors]
|-
| 300000-300047
| rebel5555's [http://social.bioware.com/project/2644/ Weapon and Shield Abilities for Arcane Warriors]
|}

----

== AI_TacticsPresets ==

{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 9'''
| '''Bioware - Main campaign'''
|-
| 10 - 15
| Anakin's [http://social.bioware.com/project/861/ Advanced Tactics]
|}

----
== ambient_ai ==

{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 1000000'''
| '''Bioware - Main campaign'''
|-
| 1000000-1001000
| [http://social.bioware.com/project/178/ Crown of Creation]
|}

----

== ANIM_base ==

{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| 65000 - 65002
| BioSpirit's [http://social.bioware.com/project/1647/ Hilltop Under Siege]
|}

----

== APR_base ==

Note that there is a bug involving this 2DA: [[Bug: APR base maximum M2DA row ID is 65535 in the toolset]]

{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 90'''
| '''Bioware - Main campaign'''
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 24000 - 26000
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|-
| 37000 - 38000
| [http://bg2redux.student.utwente.nl/trac/wiki Baldur's Gate Redux]
|-
| 40000 - 40010
| Alschemid - [http://social.bioware.com/project/3175/ Horses] and [http://social.bioware.com/project/3666/ Sandbox]
|-
| 55000 - 57000
| World of Grone (by Shodushi) [http://social.bioware.com/project/2194/ World of Grone]
|-
| 64000 - 64999
| [http://social.bioware.com/project/178/ Crown of Creation]
|-
| 65000 - 65001
| BioSpirit's [http://social.bioware.com/project/1647/ Hilltop Under Siege]
|-
| 65010 - 65025
| Mutantspicy Oracle and Enchanted Armor [Dragonage Nexus]
|-
| 1000001 - 1100000
| DA Workshop / by frosti [http://www.dragon-age-workshop.de/forum/viewforum.php?f=19/ Icewind Dale Remake]
|-
| 30000000-40000000
| MCC's Senderfall: The Last Bastion (To author: unreasonable range, please correct)
|-
|}

----

== areadata ==

{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| 24000 - 26000
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|}

----

== armor_massive_variation ==

{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 8'''
| '''Bioware - Main campaign'''
|-
| 50-50
| Alschemid - [http://social.bioware.com/project/3666/ Sandbox]
|}

Note: the highest working tested ID for this variation is 141. See [http://social.bioware.com/wiki/datoolset/index.php/Bug:_High_M2DA_ID_ranges_might_work_in_the_toolset,_but_not_in_game bug report]
----

== BITM_base and ItemStats_ ==

{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| 24000 - 26000
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|-
| 30000 - 30500
| Ambaryerno - [http://social.bioware.com/project/415/ Arms and Armor]
|-
| 37000-38000
| [http://bg2redux.student.utwente.nl/trac/wiki Baldur's Gate Redux]
|-
| 40000 - 40200
| DA Workshop / by frosti [http://www.dragon-age-workshop.de/forum/viewforum.php?f=19/ Icewind Dale Remake]
|-
| 57000-59000
| [World of Grone (by Shodushi) [http://social.bioware.com/project/2194/ World of Grone]
|-
| 77000-79000
| [Sanguine Sunrise by LukaCrosszeria [http://social.bioware.com/project/4024/ Sanguine Sunrise]
|-
| 30000000-40000000
| MCC's Senderfall: The Last Bastion (To author: unreasonable range, please correct)
|-
| 50000 - 50100
| Feline Fuelled Games - (by Silk) [http://www.felinefuelledgames.de/ Feline Fuelled Games]
|-
|}

----

== CLA_base ==

{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 25'''
| '''Bioware
|-
| 10000 - 10012
| Ladydesire
|-
| 24000 - 26000
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|}

== crafting_recipe_types ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 7'''
| '''Bioware - Main campaign'''
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 30000000-40000000
| MCC's Senderfall: The Last Bastion (To author: unreasonable range, please correct)
|-
| 5680000 - 5680020
| Phaenan's [http://social.bioware.com/project/672/ The Winter Forge]
|}

----

== crafting_recipes ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 91'''
| '''Bioware - Main campaign'''
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 30000000-40000000
| MCC's Senderfall: The Last Bastion (To author: unreasonable range, please correct)
|-
| 5680000 - 5682000
| Phaenan's [http://social.bioware.com/project/672/ The Winter Forge]
|}

----

== engineevents ==

Those ranges relates to custom events types/ID and not to engineevents based [[Event_override|events overriding]].

{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 500 - 500
| Anakin's [http://social.bioware.com/project/861/ Advanced Tactics]
|-
| 510 - 511
| Anakin's [http://social.bioware.com/project/1888/ Advanced Quickbar]
|-
| 5680000 - 5680050
| Phaenan's [http://social.bioware.com/project/672/ The Winter Forge]
|}

----

== guitypes ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 600 - 600
| Anakin's [http://social.bioware.com/project/861/ Advanced Tactics]
|-
| 601 - 601
| Anakin's [http://social.bioware.com/project/1888/ Advanced Quickbar]
|-
| 24000 - 26000
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|-
| 666000 - 666020
| Apolyon6k's [http://social.bioware.com/project/3842/ The magic of innocence]
|-
| 1337000 - 1337001
| amcnow's [http://social.bioware.com/project/3823/ Respecification]
|-
| 1974100-1974200
| Idomeneas' [http://social.bioware.com/project/3152/ Valeria Addon]
|-
| 2560000 - 2560050
| Timelord's [http://social.bioware.com/project/1845/ Blood and Lyrium]
|-
| 5680000 - 5680010
| Phaenan's [http://social.bioware.com/project/672/ The Winter Forge]
|-
|}

----

== Heraldry ==
There is a [[Bug:_High_M2DA_ID_ranges_might_work_in_the_toolset,_but_not_in_game | bug]] with this table. The range 0-255 is known to work.
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 1000001 - 1001000
| [http://social.bioware.com/project/178/ Crown of Creation] (using 201 onwards temporarily)
|-
|}
----

== itemprps ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 10022'''
| '''Bioware - Main campaign'''
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 24000 - 26000
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|-
| 37000-38000
| [http://bg2redux.student.utwente.nl/trac/wiki Baldur's Gate Redux]
|-
| 77000-79000
| Sanguine Sunrise by LukaCrosszeria [http://social.bioware.com/project/4024/ Sanguine Sunrise]
|-
| 1000001 - 2000000
| DA Workshop / by frosti [http://www.dragon-age-workshop.de/forum/viewforum.php?f=19/ Icewind Dale Remake]
|-
| 2555000-2555010
| PavelNovotny - [http://social.bioware.com/project/517/ Gay Bars of Ferelden]
|-
| 5680000 - 5680050
| Phaenan's [http://social.bioware.com/project/672/ The Winter Forge]
|-
| 7570000-7770000
| [World of Grone (by Shodushi) [http://social.bioware.com/project/2194/ World of Grone]
|-
| 536873321 - 536873322
| Elys' [http://social.bioware.com/project/522/ Mysterious Gifts]
|-
| 30000000-40000000
| MCC's Senderfall: The Last Bastion (To author: unreasonable range, please correct)
|-
| 2560000-2560050
| Timelord's [http://social.bioware.com/project/1845/ Blood and Lyrium]
|-
|}

----

== itemsets ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 30'''
| '''Bioware - Main campaign'''
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 2555000-2555010
| PavelNovotny - [http://social.bioware.com/project/517/ Gay Bars of Ferelden]
|-
| 30000000-40000000
| MCC's Senderfall: The Last Bastion (To author: unreasonable range, please correct)
|-
| 5680000 - 5680500
| Phaenan's [http://social.bioware.com/project/672/ The Winter Forge]
|-
| 7570000-7770000
| [World of Grone (by Shodushi) [http://social.bioware.com/project/2194/ World of Grone]
|-
| 1405261000 - 1405261999
| nezroy - [http://social.bioware.com/project/1834/ Warden Shields], [http://www.dragonagenexus.com/downloads/file.php?id=793 Leliana Item Set]
|-
| 1000001 - 2000000
| DA Workshop / by frosti [http://www.dragon-age-workshop.de/forum/viewforum.php?f=19/ Icewind Dale Remake]
|-
| 7771000 - 7771500
| [http://social.bioware.com/project/2157/ Dark Times: The Confederacy of Malkuth] (reserved by Starlight on Questorion's behalf)
|-
|}

----

== ItemVariations (all) ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 30'''
| '''Bioware - Main campaign'''
|-
| '''0 - 1000'''
| '''Bioware - reserved (guessed)'''
|-
| 12000 - 12100
| [http://social.bioware.com/project/1923/ Adonnay's Weaponry] (reserved by mikemike37 on his behalf)
|-
| 77 - 99
| Sanguine Sunrise by LukaCrosszeria [http://social.bioware.com/project/4024/ Sanguine Sunrise]
|-
| 140 - 160
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|-
| 101000 - 400000
| [http://social.bioware.com/project/2157/ Dark Times: The Confederacy of Malkuth] (reserved by Starlight on Questorion's behalf)
|-
|}

note: ItemVariations are affected by the bug which prevents ID's above 255 from appearing properly in the game. See [[Bug: High M2DA ID ranges might work in the toolset, but not in game|Bug report]].

----

== M2DA_base ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 1016, 2000 - 2010, 10011 - 10142, ...? '''
| '''Bioware - Main campaign'''
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 5000 - 5014
| Anakin's [http://social.bioware.com/project/861/ Advanced Tactics]
|-
| 24000 - 26000
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|-
| 37000 - 38000
| [http://bg2redux.student.utwente.nl/trac/wiki Baldur's Gate Redux]
|-
| 77000 - 79000
| [http://social.bioware.com/project/4024/ Sanguine Sunrise] by LukaCrosszeria
|-
| 100000 - 100000
| Anakin's [http://social.bioware.com/project/1907/ Event Manager]
|-
| 690000 - 690100
| [http://www.dragonagenexus.com/downloads/file.php?id=1617 Karma's Origins Companions]
|-
| 1000001 - 1100000
| DA Workshop / by frosti [http://www.dragon-age-workshop.de/forum/viewforum.php?f=19/ Icewind Dale Remake]
|-
| 1337000 - 1337001
| amcnow's [http://social.bioware.com/project/3823/ Respecification]
|-
| 2300000 - 2300100
| [http://social.bioware.com/project/178/ Crown of Creation] (M2DA prefix: COC)
|-
| 2560000 - 2560050
| Timelord's [http://social.bioware.com/project/1845/ Blood and Lyrium]
|-
| 5000000 - 5000010
| Noob766's [http://social.bioware.com/project/3827/ Companion Compatibility pack]
|-
| 5680000 - 5680050
| Phaenan's [http://social.bioware.com/project/672/ The Winter Forge]
|-
| 5680050 - 5680055
| Phaenan's [http://social.bioware.com/project/3185/ Flexible craft UI]
|-
| 5681000 - 5681005
| Phaenan's [http://social.bioware.com/project/2896/ DACrafting framework]
|-
| 6000000 - 6000050
| TreDawn - [http://social.bioware.com/project/1750/ Nesiara Companion]
|-
| 6660000 - 6660050
| Apolyon6k - [http://social.bioware.com/project/3842/ The magic of innocence]
|-
| 7000000 - 7000050
| FtG - [http://social.bioware.com/project/1688/ UI Mod]
|-
| 7000051 - 7000055
| FtG - [http://social.bioware.com/project/3663/ Custom Loading Screen]
|-
| 7000056 - 7000071
| FtG - [http://social.bioware.com/forum/1/topic/75/index/5569843 Portrait dialogue and custom tokens (test release)]
|-
| 7000075-7000080
| FtG - [http://ftg.wikidot.com/ftg-quickbar Quickbar]
|-
| 7570000 - 7770000
| [World of Grone (by Shodushi) [http://social.bioware.com/project/2194/ World of Grone]
|-
| 7777770 - 7777799
| Magic - [http://social.bioware.com/project/1429/ Void Walker] (M2DA prefix: VWK)
|-
| 9000000 - 9000050
| Ambaryerno - [http://social.bioware.com/project/415/ Arms and Armor]
|-
| 30000000 - 40000000
| MCC's Senderfall: The Last Bastion (To author: unreasonable range, please correct)
|-
| 1140150041 - 1140150091
| DLAN_Immortality - [http://social.bioware.com/project/789/ Ser Gilmore NPC]
|-
|-
| 1553521700 - 1553521750
| Alschemid - [http://social.bioware.com/project/3666/ Sandbox]
|}

----

== materialrules ==
{| class="wikitable" border="1"
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 24000 - 26000
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|-
| 37000-38000
| [http://bg2redux.student.utwente.nl/trac/wiki Baldur's Gate Redux]
|-
| 536873321 - 536873323
| Elys' [http://social.bioware.com/project/522/ Mysterious Gifts]
|-
| 1405261000 - 1405261999
| nezroy - [http://social.bioware.com/project/1834/ Warden Shields], [http://www.dragonagenexus.com/downloads/file.php?id=793 Leliana Item Set]
|}

----

== materialtypes ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 88'''
| '''Bioware - Main campaign'''
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 24000 - 26000
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|-
| 37000-38000
| [http://bg2redux.student.utwente.nl/trac/wiki Baldur's Gate Redux]
|-
| 30000000-40000000
| MCC's Senderfall: The Last Bastion (To author: unreasonable range, please correct)
|-
| 5680000 - 5680300
| Phaenan's [http://social.bioware.com/project/672/ The Winter Forge]
|-
| 536873321 - 536873340
| Elys' [http://social.bioware.com/project/522/ Mysterious Gifts]
|-
| 1405261000 - 1405261999
| nezroy - [http://social.bioware.com/project/1834/ Warden Shields], [http://www.dragonagenexus.com/downloads/file.php?id=793 Leliana Item Set]
|}

----

== PartyPicker ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 11'''
| '''Bioware - Main campaign'''
|-
| '''????'''
| '''Bioware - reserved'''
|-
| 101-199
| [http://social.bioware.com/project/178/ Crown of Creation]
|-
| 200 - 299
| DA Workshop / Author: frosti [http://www.dragon-age-workshop.de/forum/viewforum.php?f=19/ Icewind Dale Remake]
|-
| 300 - 350
| [World of Grone (by Shodushi) [http://social.bioware.com/project/2194/ World of Grone]
|-
| 1974-1980
| Idomeneas' [http://social.bioware.com/project/3152/ Valeria Addon]
|-
| 5711-5720
| [http://social.bioware.com/project/3926/ Castle Drakhaoul] by Marshal57'
|-
| 6660 - 6665
| Apolyon6k's [http://social.bioware.com/project/3842/ The magic of innocence]
|-
| 77000 - 79000
| [http://social.bioware.com/project/4024/ Sanguine Sunrise] by LukaCrosszeria
|-
| 6900000 - 6900200
| [http://www.dragonagenexus.com/downloads/file.php?id=1617 Karma's Origins Companions]
|-
|}

----

== PRCSCR ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 24000 - 26000
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|-
| 37000 - 38000
| [http://bg2redux.student.utwente.nl/trac/wiki Baldur's Gate Redux]
|-
| 77000 - 79000
| [http://social.bioware.com/project/4024/ Sanguine Sunrise] by LukaCrosszeria
|-
| 690000 - 690100
| [http://www.dragonagenexus.com/downloads/file.php?id=1617 Karma's Origins Companions]
|-
| 1000001 - 1100000
| DA Workshop / by frosti [http://www.dragon-age-workshop.de/forum/viewforum.php?f=19/ Icewind Dale Remake]
|-
| 1337000
| amcnow's [http://social.bioware.com/project/3823/ Respecification]
|-
| 2000000 - 2000050
| [http://www.dragonagenexus.com/downloads/file.php?id=942 Oracle,mutantspicy's magic vault, and other custom armors]
|-
| 5680000 - 5680020
| Phaenan's [http://social.bioware.com/project/672/ The Winter Forge]
|-
| 6000000 - 6000050
| TreDawn - [http://social.bioware.com/project/1750/ Nesiara Companion]
|-
| 7570000 - 7770000
| [World of Grone (by Shodushi) [http://social.bioware.com/project/2194/ World of Grone]
|-
| 10100000
| Camp [http://social.bioware.com/project/463/ storage chest]
|-
| 10100011 - 10100013
| Didymos' [http://social.bioware.com/project/2620/ Camp Merchant Chest]
|-
| 10100014 - 10100016
| Didymos' [http://social.bioware.com/project/2717/ Item Sets Fix]
|-
| 10100100 - 10100110
| Eshme's [http://social.bioware.com/project/1929/ Sleeping Tent]
|-
| 30000000 - 40000000
| MCC's Senderfall: The Last Bastion (To author: unreasonable range, please correct)
|-
| 42006090 - 42006100
| [http://www.dragonagenexus.com/downloads/file.php?id=1120 Morrigan Restoration Patch]
|-
| 1000197400 - 1000197410
| Idomeneas' [http://social.bioware.com/project/3152/ Valeria Addon]
|-
| 1109197751 - 1109197799
| Schwinni - [http://dragonagenexus.com/downloads/file.php?id=1020 Awakening Runes Fixes], [http://dragonagenexus.com/downloads/file.php?id=1112 Awakening Blackblade Armor Dragon Drop Fix]
|-
| 1140150041 - 1140150091
| DLAN_Immortality - [http://social.bioware.com/project/789/ Ser Gilmore NPC]
|-
| 1405261000 - 1405261999
| nezroy - [http://social.bioware.com/project/1834/ Warden Shields], [http://www.dragonagenexus.com/downloads/file.php?id=793 Leliana Item Set]
|-
| 1553521700 - 1553521710
| Alschemid - [http://social.bioware.com/project/3666/ Sandbox]
|-
| 1672464532 - 1672464542
| DLAN_Immortality - [http://social.bioware.com/project/2991/ Ser Gilmore NPC Awakening]
|-
|}

----

== placeable_types ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 14000 - 16000
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|-
| 17000 - 19000
| Standalone modules (see discussion tab)
|-
| 37000-38000
| [http://bg2redux.student.utwente.nl/trac/wiki Baldur's Gate Redux]
|-
| 43050-43061
| Eshme's [http://social.bioware.com/project/1929/ Sleeping Tent] (Greater 65535 is showing bugs so this is until it is fixed)
|-
| 43062-43065
| BioSpirit's [http://social.bioware.com/project/1647/ Hilltop Under Siege]
|-
| 56000-56200
| [http://social.bioware.com/project/2472/#details Mikes Invisible Boxes]
|-
| 2696549 - 2696700
| PavelNovotny - [http://social.bioware.com/project/517/ Gay Bars of Ferelden] (NOTE: I'm using the 6000-6200 range until Bioware fixes the bug which prevents m2da ID ranges above 900000 from showing up in game.)

|-
| 7570000-7770000
| [World of Grone (by Shodushi) [http://social.bioware.com/project/2194/ World of Grone]
|-
| 30000000-40000000
| MCC's Senderfall: The Last Bastion (To author: unreasonable range, please correct)
|-
| 1000001 - 1100000
| DA Workshop / Author: frosti [http://www.dragon-age-workshop.de/forum/viewforum.php?f=19/ Icewind Dale Remake]
|-
| 1974-1978
| Idomeneas' [http://social.bioware.com/project/3152/ Valeria Addon] (They are low so they'll show in game, recall the toolset bug)
|-
|}
----

== popups ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 1000001-1001000
| [http://social.bioware.com/project/178/ Crown of Creation]
|-
|}
----

== PRJ_base ==

{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 5680000 - 5680050
| Phaenan's [http://social.bioware.com/project/672/ The Winter Forge]
|-
|}

----
== String ID ==
It is not generally necessary to register String ID ranges here. The values generated by the toolset are sufficiently random to minimise the risk of collision. Exception : the Community Contest reserved the range below so that the builders will stick to that and can import VO without having to renumber the VO files.

{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 10000000'''
| '''Bioware - reserved'''
|-
| 89000000 - 89999999
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|-
|}

----

== tint_override ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| 500 - 520
| PavelNovotny - [http://social.bioware.com/project/517/ Gay Bars of Ferelden]
|-
| 6900 - 6920
| [http://www.dragonagenexus.com/downloads/file.php?id=1617 Karma's Origins Companions]
|-
| 1000001-1001000
| [http://social.bioware.com/project/178/ Crown of Creation]
|-
| 30000000-40000000
| MCC's Senderfall: The Last Bastion (To author: unreasonable range, please correct)
|-
| 1109197701 - 1109197750
| Schwinni - [http://dragonagenexus.com/downloads/file.php?id=1064 Helmets without wings and retints]
|-
| 1553521700 - 1553521750
| Alschemid - [http://social.bioware.com/project/3666/ Sandbox]
|}

----

== ts_material ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| 1405261000 - 1405261999
| nezroy - [http://social.bioware.com/project/1834/ Warden Shields], [http://www.dragonagenexus.com/downloads/file.php?id=793 Leliana Item Set]
|}

----

== TS_Category ==

{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 5680000 - 5680005
| Phaenan's [http://social.bioware.com/project/672/ The Winter Forge]
|-
| 1000001 - 1100000
| DA Workshop / by frosti [http://www.dragon-age-workshop.de/forum/viewforum.php?f=19/ Icewind Dale Remake]
|-
| 7570000-7770000
| [World of Grone (by Shodushi) [http://social.bioware.com/project/2194/ World of Grone]
|-
|}

----

== vfx_base ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 1000000'''
| '''Bioware - reserved'''
|-
| 24000 - 26000
| [http://social.bioware.com/wiki/datoolset/index.php/Community_Contest_Main_Page Community Contest]
|-
| 37000-38000
| [http://bg2redux.student.utwente.nl/trac/wiki Baldur's Gate Redux]
|-
| 5680000 - 5680010
| Phaenan's [http://social.bioware.com/project/672/ The Winter Forge]
|-
| 5680011 - 5680019
| BioSpirit's [http://social.bioware.com/project/1647/ Hilltop Under Siege]
|}
----

== worldmaps (has to be less than 256) ==
{| class="wikitable" border="1"
|-
! Range
! Used by
|-
| '''0 - 6'''
| '''Bioware - reserved'''
|-
| '''151 - 151'''
| Alschemid - [http://social.bioware.com/project/3666/ Sandbox]

|-
| '''210 - 220'''
| [http://social.bioware.com/project/1845/ Blood and Lyrium]
|}
----

Useful Scripts

2011-05-27T14:44:29Z

Proleric1: /* Move Inventory (e.g. remove and store player's equipment) */

{{Infobox script}}

This page lists how to accomplish tasks that are relatively simple and commonly needed, but that otherwise require deep scripting knowledge to figure out intuitively how to do.

Feel free to add new sections describing any tricks or techniques you think is worth documenting. If the page becomes too large it can be split up into specific topics.

See also: [[PRCSCR Script Templates]]

__TOC__
== Run a cutscene from a trigger ==

Create a script:

<dascript>
#include "events_h"
#include "global_objects_h"
#include "utility_h"

void main ()
{
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);
int bEventHandled = FALSE;
switch (nEventType)
{
case EVENT_TYPE_ENTER:
{
object oCreature = GetEventCreator(ev);
if(GetObjectActive(OBJECT_SELF)
&& IsPartyMember(oCreature))
{
resource rCutscene = R"my_cutscene.cut";
CS_LoadCutscene(rCutscene);
SetObjectActive(OBJECT_SELF, FALSE);
}
}
break;
}
if (!bEventHandled) //If this event wasn't handled by this script, let the core script try
{
HandleEvent(ev, RESOURCE_SCRIPT_TRIGGER_CORE);
}
}
</dascript>

And set it as the event script for the trigger that you want to have run the cutscene.

== Add a follower to the player's party ==

<dascript>
if(IsPartyMember(oCreature)) {
object oFollower = GetObjectByTag("myfollower");
UT_HireFollower(oCreature, oFollower);
}
</dascript>

Comment : originally, the above example used the function IsPlayer, which doesn't seem to exist.

Note that with Toolset v1.0.982.0, calling UT_HireFollower() will result in a follower who's unable to gain xp. This happens due to the call of
<dascript>
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, '''TRUE''');
</dascript>
to the function
<dascript>
void WR_SetFollowerState(object oCreature, int nState, int nSendEvent = TRUE, int nMinLevel = 0, '''int bPreventLevelup''' = FALSE)
</dascript>
To enable the xp gain, the flag CREATURE_REWARD_FLAGS needs to be cleared from the follower after the hired event was processed (there the flag is set). For now the best/easiest approach to take might be to make a copy of UT_HireFollower in an include file and rename it something like UT_HireFollower_Fixed, then make the following change:

<dascript>
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, TRUE);
</dascript>
to
<dascript>
WR_SetFollowerState(oFollower, FOLLOWER_STATE_ACTIVE, TRUE, 0, bPreventLevelup);
</dascript>

== Have an enemy play possum and then get up to fight ==

Set the creature's CREATURE_SPAWN_DEAD variable to 2.

When it's time for the creature to rise and attack, execute the following script commands:

<dascript>
#include "wrappers_h"
...
WR_SetObjectActive(oCreature, TRUE);
SetCommandable(oCreature, TRUE);
// Make sure to set this flag back to 0 to avoid problems with savegames.
SetLocalInt(oCreature, CREATURE_SPAWN_DEAD, 0);
UT_CombatStart(oCreature, oPC);
</dascript>

== Insert content into an existing area ==

If you want to add new content on to an existing area (for example, putting a new character or area transition door into an area that exists in the single-player campaign) there are two different ways to do it. One is to override the existing area with a new area of your own design that duplicates the original with the exception of your additions. This is straightforward to do but can interact poorly with other add-ons - you can only have one version of an area active at a time. '''[To Editor: Edit in a Custom Module or the existing Single Player Campaign Module?]'''

A more elegant and extensible approach is to use a [[PRCSCR]]_-prefixed M2DA. The PRCSCR M2DA has a very simple structure and a simple but profound effect:

*ID - a unique integer identifier for each row
*AreaListName - a string that identifies a specific area list, or the special keyword "any".
*Script - the name of a script file.

Whenever a player enters an area in an area list in this M2DA the associated script will be run. A modder can therefore include a script with his mod that will be run when the player enters an existing area that he didn't create. This script can freely add or remove placeables and creatures and perform whatever other modifications to the area that a script is capable of doing.

Note that the script will be run every time the player enters the area, so you'll want to have an associated plot flag to ensure that the changes are only made once.

The following example is a script that adds a new character from an add-on module to an existing area in the main game:

<dascript>
// this is the name of a precreated plot file "joblos_quest" prefixed with the special "plt_"
// "plt_" + quest name allows you to reference the flag names as constants.
#include "plt_joblos_quest"
#include "wrappers_h"

void main()
{
//Check whether we've added Joblo already.
if (WR_GetPlotFlag(PLT_JOBLOS_QUEST, JOBLO_ADDED_TO_TOWN) == FALSE)
{
object oTown = GetObjectByTag("lot100ar_lothering"); //An area's tag is the same as its resource name
vector vJobloLocation = Vector(126.745f, 120.724f, 0.460568f); // See below for how to get these coordinates

CreateObject(
OBJECT_TYPE_CREATURE,
R"joblo.utc",
Location(oTown, vJobloLocation, 180.0f); //See below for how to get the value for orientation
)

WR_SetPlotFlag("joblos_quest", JOBLO_ADDED_TO_TOWN, TRUE);
}
}
</dascript>

Since you can't add [[waypoint]]s to an existing area you'll need to enter the position and orientation values for the target location manually. You can find them by creating a local copy of the area in question and temporarily adding a waypoint to copy down the coordinates and orientation you'll need.

== Move Inventory (e.g. remove and store player's equipment) ==

Here's a fairly general function for moving items from one creature / placeable to another.

Applications might include

* Moving a player's equipped items, inventory and money to a chest while they are in jail (with an option to prevent them being naked).
* Replacing an NPC's equipment with a new set from a nearby invisible placeable.
* Removing all items from an NPC except their equipment.
<dascript>
const int ITEM_TYPE_AMMO = 7;
/**
* @brief Move inventory from one object to another
*
* @param oSource - object to move inventory from
* @param oTarget - object to move inventory to
* @param bUnequipSource - TRUE if any items that the source has equipped should be moved
* @param bEquipTarget - TRUE if target should equip items received if possible
* @param bRemoveClothing - TRUE if chest slot should be unequipped when bUnequipSource is TRUE
* @param bMoveMoney - TRUE if creature money should move from source to target
*
* The target will acquire the items even if its maximum inventory is exceeded.
* If the source contains more than one item for an inventory slot, the outcome of equipping
* on the target is unpredictable.
* If money is moved from a creature to a placeable, money items are created.
*
* @returns void
**/
void zzzMoveInventory(object oSource, object oTarget, int bUnequipSource=FALSE, int bEquipTarget=FALSE,
int bRemoveClothing=FALSE, int bMoveMoney=FALSE);
void zzzMoveInventory(object oSource, object oTarget, int bUnequipSource=FALSE, int bEquipTarget=FALSE,
int bRemoveClothing=FALSE, int bMoveMoney=FALSE)
{
object [] oItemTable;
object oClothing = OBJECT_INVALID;
object oItem;
int nItemCount;
int nGetItemsOption = GET_ITEMS_OPTION_BACKPACK;
int nMoney;
int nStack;
object oMoney;
int i = -1;

if (bUnequipSource) nGetItemsOption = GET_ITEMS_OPTION_ALL;

if (GetObjectType(oSource) == OBJECT_TYPE_CREATURE)
if (!bRemoveClothing)
oClothing = GetItemInEquipSlot(INVENTORY_SLOT_CHEST, oSource);

oItemTable = GetItemsInInventory(oSource, nGetItemsOption);
nItemCount = GetArraySize(oItemTable);

while (++i < nItemCount)
{
oItem = oItemTable[i];

if (oItem != oClothing)
{
MoveItem(oSource, oTarget, oItem);

if (bEquipTarget && (GetObjectType(oTarget) == OBJECT_TYPE_CREATURE))
switch(GetItemType(oItem))
{
case ITEM_TYPE_WEAPON_RANGED:
{EquipItem(oTarget, oItem, INVENTORY_SLOT_MAIN, 1); break;}
case ITEM_TYPE_WEAPON_MELEE:
{EquipItem(oTarget, oItem, INVENTORY_SLOT_MAIN, 0); break;}
case ITEM_TYPE_SHIELD:
{EquipItem(oTarget, oItem, INVENTORY_SLOT_OFFHAND, 0); break;}
case ITEM_TYPE_AMMO:
{EquipItem(oTarget, oItem, INVENTORY_SLOT_RANGEDAMMO, 1); break;}
default : EquipItem(oTarget, oItem);
}
}
}

if (bMoveMoney)
{
nMoney = GetCreatureMoney(oSource);

if (GetObjectType(oTarget) == OBJECT_TYPE_CREATURE)
AddCreatureMoney(nMoney, oTarget);
else
while (nMoney)
{
oMoney = CreateItemOnObject(R"gen_im_copper.uti", oTarget, 1, "", TRUE);
nStack = GetMaxItemStackSize(oMoney);
if (nStack > nMoney) nStack = nMoney;
SetItemStackSize(oMoney, nStack);
nMoney -= nStack;
}
SetCreatureMoney(0, oSource);
}
}
</dascript>

== Create a lootable placeable that vanishes when looted ==

For a player-usable placeable, use the following event script to make it give its contents to the player and then vanish when clicked on.

<dascript>
#include "wrappers_h"
void main()
{
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);
switch (nEventType)
{
case EVENT_TYPE_USE:
{
//MoveAllItems(OBJECT_SELF, GetHero());
AddCreatureMoney (1000000, GetHero(), TRUE);
Safe_Destroy_Object(OBJECT_SELF);
break;
}
}
}
</dascript>

If you wanted to use standard resources you could achieve the same thing (though not destroying the placeable) simply by adding "_autoloot" to the end of the placeable's tag.

== Move the player to a new area after a cutscene plays ==

Stand-alone cutscenes have an "end script" parameter that sets a script to run once the cutscene ends. Use a script such as the following:

<dascript>
void main()
{
DoAreaTransition("destination_area_tag", "destination_waypoint_tag");
}
</dascript>

== Override Events (e.g. those in player_core) ==

Look here: [[Event override]]

{{Languages}}
[[category:tutorials]]
[[Category:Scripts]]

Treasure system

2011-05-22T07:09:05Z

Proleric1: /* Overrides */

The Treasure System only works on creatures and placeable containers (not bags). Creatures will fire the Treasure System when they die, and placeables will fire it when they spawn.

There are 2 specific pieces of information that the Treasure System uses to determine what treasure an object drops. The first piece of information is the combat Rank of the object. Placeables are never involved in combat, but will have to have something entered in the field for the system to work. A Lieutenant-ranked chest will drop treasure equivalent to a Lieutenant-ranked creature. Rank determines the quantity and quality of the treasure dropped. The second piece of information is the Treasure Category of the object. This determines what set of treasure tables the system will look at for this object.

If either the Rank or Treasure Category is set to Invalid (value 0), the Treasure System will not drop anything. Items placed manually on the object will appear normally.

If there doesn't seem to be a treasure table that applies to a specific object, contact the designer in charge of the system to get a new table added.

== Overrides ==

There are a number of override variables on objects that will change the way the Treasure System functions. For each of these variables, a value less than 0 turns off that part of the system, a value of 0 ignores the override, and a value greater than 0 uses that value instead of the one on the creature. Each variable has a short explanation of what overriding does.

{{variable table start}}
{{variable table row|TS_OVERRIDE_CATEGORY |int|0| A value here directly relates to ID values in the TS_Category 2DA.}}
{{variable table row|TS_OVERRIDE_EQUIPMENT |float|0| A value here determines the chance of any particular piece of equipped items dropping. Set this to a negative number to prevent the treasure system from using the default value from the auto scaling table.}}
{{variable table row|TS_OVERRIDE_HIGH|float|0| high chance }}
{{variable table row|TS_OVERRIDE_ITEM|float|0| item chance }}
{{variable table row|TS_OVERRIDE_MONEY |int|0| A value here overrides the TS_MoneyValue value in the autoscale 2DA.}}
{{variable table row|TS_OVERRIDE_RANK |int|0| A value here directly relates to ID values in the autoscale 2DA.}}
{{variable table row|TS_OVERRIDE_REACTIVE|float|0|Reactive chance, only present in the creature variable table{{undocumented}} }}
{{variable table row|TS_OVERRIDE_SCALING |int|0| A value here has no additional effect. This is currently only useful to turn off scaling.}}
{{variable table row|TS_OVERRIDE_STEALING |int|0| A value here directly relates to ID values in the TS_Stealing 2DA.}}
{{variable table row|TS_TREASURE_GENERATED|int|0| A value of -1 here ensures that there is never any treasure, period.}}
{{variable table end}}

== Stealing ==

Stealing from a creature functions the same as a normal treasure drop, except the loot is only ever a single Minor Item. No Money or Major Items will be dropped.

The TS_OVERRIDE_STEALING variable allows special functionality to be added when a creature is stolen from. A value placed in the override is actually an ID lookup in the TS_Stealing 2DA. When that creature is stolen from (and a creature can normally only be successfully stolen from once), it gets the item resource referenced by that ID and adds it to the treasure gained from stealing.

Stealing from creatures is mostly handled by systems, so there are only a couple places a designer can interact with it. First it will be useful to describe exactly what happens when the Stealing skill is used.

When a character tries to use Stealing on another creature, it checks a variety of factors on the character and the target to determine success. If the target has already been stolen from, the character neither succeeds nor fails. If the character fails, the [[EVENT_TYPE_STEALING_FAILURE]] event is fired on the current area. If the character succeeds, the [[EVENT_TYPE_STEALING_SUCCESS]] event is fired on the current area and the FLAG_STOLEN_FROM variable on the target is set to TRUE. Additionally, a successful use of the Stealing skill causes the Treasure System to generate a single Minor Item on the character using the skill. This requires the target to be properly set up for the Treasure System.

The [[EVENT_TYPE_STEALING_FAILURE]] and [[EVENT_TYPE_STEALING_SUCCESS]] events are intended for use in the Infamy system and will be used in the Stealing Reactivity pass.

The FLAG_STOLEN_FROM variable can be set on a creature manually to allow them to be immune to stealing attempts. This can be used to shield plot characters from the skill, though Stealing won't actually remove any items from their inventory. Additionally, you can set the flag to FALSE through scripting to allow the player to steal from a target more than once. Creatures with this flag set will not fire [[EVENT_TYPE_STEALING_FAILURE]] or [[EVENT_TYPE_STEALING_SUCCESS]] events, so they won't interact with the Infamy system.

=== Specific Items ===

The Treasure System has functionality added to allow you to get specific items when stealing from a character. The TS_OVERRIDE_STEALING variable on creatures allows you to set associate a creature with a specific ID value in the TS_Stealing 2DA. Each ID value references a specific item resource name. When a character with this variable set is stolen from, that specific item resource will be added to the treasure the player receives.

The target does not have to have a valid Rank or Treasure Category for this item to drop. This is so you can drop only the specific item and nothing else.

== TS_System.xls and related 2das ==

See [[TS_System.xls]]

[[Category:Creatures]]
[[Category:Placeables]]
{{Languages}}

Placeable

2011-05-22T07:07:12Z

Proleric1: /* Variables */

{| style="float:right;"
|-
| {{Resource palette}}
|}

Interactive Objects are the objects placed in the designer toolset that the end-user can interact with. They are also known as placeable objects.

Designers place interactive objects in area using the Area Editor. Placeable and trigger templates must be created prior to being placed in an area. In the toolset, doors are considered to be just another form of placeables.

Interactive objects are placed in the Area Editor of the Designer toolest. They can be interacted with by the player in-game.

Like all objects, interactive objects receive only one [[Event (dascript type)|event]]. Information encoded in this event can be used to determine if this is a default action or a secondary action (for example, determining whether the player is picking the placeable's lock or simply bashing it open).

== Locked Objects ==

Any interactive object can be locked (though generally it only makes sense to do so with containers and doors). If the character's lockpicking skill is higher than the lock, the lock is opened.

Interactive objects cannot be trapped in the manner that Neverwinter objects were trapped (i.e., no trapped chests or doors). Instead, a placeable object can be set as the trigger for an associated trap object; Dragon Age generally does this via floor plates that trigger when stepped on.

== Destroying Objects ==

All interactive objects need a destroyed animation. If a container is destroyed the contents of its inventory are transferred to a Bodybag. Some of the items may be destroyed (scripting determines the chance of this).

== Types of Interactive Objects ==

The function that a placeable performs when interacted with is defined by its appearance, as listed in [[Placeables.xls]].

=== Doors ===
Doors can be opened and closed by the player. They restrict access between portions of an area.
* Examples: Door, Cage Door, Secret door
* Default Action: When a character clicks on the door it opens with an animation.
* Secondary Action: The character attacks the door with his equipped weapon
* Doors are special and get [[Door|their own page]] describing additional details.
=== Trigger-Animating ===
These are items that a player clicks on to activate something elsewhere on a level. Usually this means a locked or secret door somewhere on the level, though sometimes it might summon a monster or sound the alarm for the entire level.
* Examples: Lever, gong, turning wheel.
* Default Action: When a character clicks on the object, it plays an animation and an effect. The effect can be a script, a sound, a spell or a combination.
* Secondary Action: The character attacks the object with his equipped weapon.
=== Container-Animating ===
These are common containers where a player can find treasure. These objects play a simple ‘open’ animation when left clicked.
* Examples: Chest, Armoire, Safe.
* Default Action: An open animation is played. The container’s inventory is shown on a GUI. If the container is locked, then the character’s lock picking skill is compared against the lock’s complexity.
* Secondary Action: The character attacks the container with his equipped weapon.
=== Container-Static ===
These are common containers where a player can find treasure. These containers have no ‘open’ animation.
* Examples: Bookshelf, bush (with material components), corpse.
* Default Action: The container’s inventory is shown on a GUI. Static containers cannot be locked.
* Secondary Action: The character attacks the container with his equipped weapon.
=== Cage ===
These are cages where animals or prisoners are kept. Players can release prisoners as an act of good will or simply to interrogate them for information. Animals can be released to act as temporary allies.
*Examples: Animal cage, gaol.
*Default Action: An open animation is played. If the cage is locked, then the character’s lock picking skill is compared against the lock’s complexity.
*Secondary Action: The character attacks the cage with his equipped weapon.
=== Informational ===
These are notes or signs that a player can click on to learn important information about the game. They range from simply location signs to notes giving information about a plot.
*Examples: Road sign, note on wall.
*Default Action: A GUI pops up displaying the text of the message.
*Secondary Action: Nothing happens.
=== Selectable Trap ===
These are traps that originate from visible (and thus selectable and destroyable) objects. They can also can be disarmed by disarming their floor trigger - i.e., sinking floor piece - (see Trap Triggers).
*Examples: Archer statue that fires arrows (after player steps on floor piece). Dragon statue that breathes fire(after player steps on floor piece).
*Default Action: Trap triggers, targeting the character that selected it.
*Secondary Action: The character attacks the trap with his equipped weapon.
=== Non-Selectable Trap ===
These are hidden traps that spring from the walls, floor or ceiling. These traps cannot be selected or destroyed directly BUT they can be disarmed by disarming their floor trigger - i.e., sinking floor piece - (see Trap Triggers).
*Examples: Pendulum blade, scything blade.
*Default Action: Cannot target trap.
*Secondary Action: Cannot target trap.
=== Trap Trigger ===
All traps need to be associated with a floor trigger. When a character walks over a floor trigger, the trap will activate. If two or more characters are selected, the one with the highest trap skill is the one that moves to disarm the trap.
*Examples: Sinking floor piece.
*Default Action: If the character has the ‘Traps’ skill, then he plays a ‘disarm’ animation and his skill is compared against the difficulty of the trap. Characters without the traps skill cannot select the trap trigger.
*Secondary Action: The character attacks the trigger with his equipped weapon. This triggers the trap.
=== Area Effect Item/Informational ===
These are objects that a character can attack, triggering an event that has an immediate effect on the battlefield. When a character attacks one of these objects, the object usually falls over and deals damage to any creature in its area of effect. If a player just left clicks on one of these objects, he will receive a text message.
*Examples: Weakened pillar (pillar collapses into rubble), old rotting tree (tree falls over), chandelier (rope is cut, chandelier smashes into floor and vanishes), marble statue (statue tips over), window (window smashes, leaving glass all over floor), boulder (rolls along preset path).
*Default Action: A GUI pops up displaying the text of a message.
*Secondary Action: The character attacks the trigger with his equipped weapon. If the player has the appropriate strength, then the item plays its ‘area effect damage’ animation.
=== Area Effect Item/Container ===
These These are objects that a character can attack, triggering an event that has an immediate effect on the battlefield. When a character attacks one of these objects, the object usually falls over and deals damage to any creature in its area of effect. If a player just left clicks on one of these objects, it will act as a container.
*Examples: Bag of flour (explodes into cloud of flour), wagon with barrels (wagon tips and barrels spill over floor), bookcase (bookcase tips over).
*Default Action: The container’s inventory is shown on a GUI.
*Secondary Action: The character attacks the trigger with his equipped weapon. If the player has the appropriate strength, then the item plays its ‘area effect damage’ animation.
=== Furniture ===
Characters can either sit down or lie down on these objects.
*Examples: Chair, couch, bed, bench.
*Default Action: The character either sits down or lies down on the furniture object. As soon as the player clicks to move, he will stand up.
*Secondary Action: The character attacks the object with his equipped weapon.
=== Puzzle ===
The player clicks and triggers an interactive dialog with the object
*Examples: any puzzle object.
*Default Action: Trigger dialog.
*Secondary Action: The character attacks the object with his equipped weapon.
=== Area Transition ===
These are visible or invisible objects used to transition between areas.
*Examples: Large Gate
*Default Action: Transition into destination area.
*Secondary Action: Nothing happens.

== How will designers assign appearances to interactive objects? ==
*This will be done through the Toolset appearance field. It refers placeables.2da
*Each placeable has a Type.
*Each TYPE corresponds to an Animation State Type (example, the AnimCnt_Door sheet in placeables.2da controls the door states). This controls the type of animations available to this object. There should be 10-15 types or so
**Death
**Damaged
**Normal State
**Others...
*Each Animation State Type refers to a list of animations in the Animations 2da ([[ANIM_Placeables.xls]])

== How will battle-field damage work? ==
*Interactive Objects will not have DECALS or BATTLE-SCARING.
*Interactive Objects will have a Damage state, in addition to the Death state that they all have. Example damage states:
**A chest might have a chunk of wood taken out of its front
**A cask of ale might start leaking ale

== Use Points ==
Objects will have use points to indicate where people using them stand. There will be multiple use points on an object.

Use points will need to be activated relative to what state they are in (i.e., an overturned pillar will have different action points than an upright pillar).

Use points may also need to be labeled and are activated relative to a players position. This seems likely how are doors will work. Since we decided that doors in Dragon Age will function like real-world doors, they will always open in the same direction every time. This means that the use point I use is NOT relative to the state, but instead to the position of the character. We might need use points labeled.

This system will probably also be used by creatures (a dragon might have Front-Claw Use Point, Tail Use Point et cetera)

== How Will Sitting and Sleeping Work? ==
* All things that can be sat on will need a consistent Height and Width
* All things that can be slept on will need a consistent Height and Width
* Animals will not be able to sit or sleep on anything
* Animation will create sit & sleep animations for Elves, Dwarves, Humans
* The player can’t sit — only ambient NPCs.

The current planned interactive object animation system should be able to handle the "sitting" and "lying down" of creatures.

== What happens if no animations exist for an action? ==
Example: E.g A creature uses an object for which there is no proper animation, like a Dog opens a chest.

The chest will still open but if no animations were created to show Dog opening the chest, none will play.

== Variables ==

For var_placeable:

{{variable table start}}
{{variable table row| PLC_AT_DEST_AREA_TAG | string |none| resource name of an area transition door's destination area}}
{{variable table row| PLC_AT_DEST_TAG | string |none| resource name of the waypoint within that area to send the PC to. }}
{{variable table row|PLC_AT_WORLD_MAP_ACTIVE_1 to 5 | string |none| resource name of pins on the world map that should be made active when the player uses this area transition to reach the world map. }}
{{variable table row|PLC_CODEX_FLAG | int | -1 | Flag within the CODEX_PLOT plot that is set when this placeable is examined. }}
{{variable table row|PLC_CODEX_PLOT | string |none| resource name of a plot containing a codex page that is given to the player when this placeable is examined. }}
{{variable table row|PLC_COUNTER_1 to 3 | int |0| generic counter variables }}
{{variable table row|PLC_DO_ONCE_A and B | int |0| flags for behaviors that happen only once }}
{{variable table row|PLC_FLIP_COVER_USE_COUNT | int |0| Flip cover has been removed from the default ruleset }}
{{variable table row|PLC_SPAWN_NON_INTERACTIVE | int |0| }}
{{variable table row|PLC_TRAP_* | || see [[Trap system]] }}
{{variable table row|TS_OVERRIDE_* | || See [[Treasure system]] }}
{{variable table row|TS_TREASURE_GENERATED | int || See [[Treasure system]] }}
{{variable table end}}

If you use the var_placeable_react 2da instead, the above variables are all included and the following are added:

{{variable table start}}
{{variable table row|PLC_REACT_DESTROY_SET_FLAG | int || When placeable is destroyed set this flag }}
{{variable table row|PLC_REACT_DESTROY_SET_PLOT | string || When placeable is destroyed set this plot}}
{{variable table row|PLC_REACT_INVENTORY_REMOVED_SET_FLAG | int || When the PC takes something from the placeable fire this flag}}
{{variable table row|PLC_REACT_INVENTORY_REMOVED_SET_PLOT | string || When the PC takes something from the placeable fire this plot}}
{{variable table row|PLC_REACT_OVERRIDE_USE_BEHAVIOR | int |0| Makes it so what's supposed to happen when you use the placeable doesn't happen (e.g. a door doesn't open)}}
{{variable table row|PLC_REACT_REPEAT | int | 1 | Whether or not the placeable reaction script will fire multiple times (default to TRUE)}}
{{variable table row|PLC_REACT_USE_SET_FLAG | int |0| When placeable is used fire this flag}}
{{variable table row|PLC_REACT_USE_SET_PLOT | string || When placeable is used fire this plot}}
{{variable table end}}

== Properties ==

{{inspector start}}
{{inspector section|General}}
{{inspector row|Appearance| Appearance type for the placeable }}
{{inspector row|Character| One or more placeables can be mapped to a single character. }}
{{inspector row|Comments| General information about this placeable. }}
{{inspector row|Conversation| Default conversation resource for this placeable. }}
{{inspector row|Group| The placeable's group as specified in groups.2da. Each group can be either hostile or non-hostile towards each other. }}
{{inspector row|Name| Name of the placeable as seen in the game. }}
{{inspector row|NameRequiresReTranslation| A true/false flag used during game development for [[localization]] work }}
{{inspector row|Plot| True/false, if true the placeable cannot be damaged or affected by any hostile effect. }}
{{inspector row|PopupText| {{undocumented}} }}
{{inspector row|PopupTextRequiresReTranslation| A true/false flag used during game development for [[localization]] work }}
{{inspector row|Rank| Placeables are never involved in combat, but their combat rank is still used by the [[treasure system]] when generating treasure. }}
{{inspector row|Resource Name| A unique string identifier the tooleset and the game both use to refer to this resource. }}
{{inspector row|Script| Event script assigned to the resource. }}
{{inspector row|Tag| A non-unique string identifier used mostly by scripts and other resources to refer to this resource. }}
{{inspector row|Team| Numeric identifier of the team the placeable belongs to. Team numbers are often used in scripting. }}
{{inspector row|Treasure Category| Determines what variety of treasure is generated by the [[treasure system]] }}
{{inspector row|Variable 2da| Allows selecting a variable table. Only the values in this table can be set and retrieved by scripting. }}
{{inspector row|Variables| Displays the table selected in the "Variable 2da" field. Allows setting initial states for parameters. }}

{{inspector section|Key}}
{{inspector row|Auto Remove Key| Sets whether the game will remove a key from inventory once used to open this placeable. }}
{{inspector row|Key Required| Sets whether or not a key is the only way to open this placeable }}
{{inspector row|Key Tag| The tag of the key needed to open this placeable }}

{{inspector section|Sound}}
{{inspector row|Close to Open Sound| Sound emitted when the object changes from a closed state to an opened state }}
{{inspector row|Destroyed Sound| Sound emitted when the object is destroyed }}
{{inspector row|Hit Sound| Sound emitted when the object is hit for damage }}
{{inspector row|Locked Sound| Sound emitted when an attempt is made to open a locked object }}
{{inspector row|Open to Close Sound| Sound emitted when the object changes from an opened to a closed state. }}
{{inspector row|Used Sound| Sound emitted when the object is "used" (generically). }}

{{inspector section|Stats}}
{{inspector row|Health| Amount of health the placeable currently has}}
{{inspector row|Initial State| The animation state the placeable will be in when first spawned. }}
{{inspector row|Interactive| Sets whether or not this placeable can be clicked on during the game. }}
{{inspector row|Inventory List| Opens the inventory panel and enables user to assign items to the placeable's inventory }}
{{inspector row|Max Health| The maximum amount of health this placeable can have.}}
{{inspector row|Pick Lock Level| The difficulty level to pick the lock }}

{{inspector section|Trap}}
{{inspector row|Is Trapped| Sets whether or not a trap trigger is linked to this placeable }}
{{inspector row|Trap Detection Difficulty| Sets the skill level required to detect this trap. }}
{{inspector row|Trap Disarm Difficulty| Sets the skill level required to disarm this trap. }}

{{inspector end}}

== See also ==

*[[Chanter's board]]

[[Category:Placeables]]

Treasure system

2011-05-22T07:03:04Z

Proleric1: /* Overrides */

The Treasure System only works on creatures and placeable containers (not bags). Creatures will fire the Treasure System when they die, and placeables will fire it when they spawn.

There are 2 specific pieces of information that the Treasure System uses to determine what treasure an object drops. The first piece of information is the combat Rank of the object. Placeables are never involved in combat, but will have to have something entered in the field for the system to work. A Lieutenant-ranked chest will drop treasure equivalent to a Lieutenant-ranked creature. Rank determines the quantity and quality of the treasure dropped. The second piece of information is the Treasure Category of the object. This determines what set of treasure tables the system will look at for this object.

If either the Rank or Treasure Category is set to Invalid (value 0), the Treasure System will not drop anything. Items placed manually on the object will appear normally.

If there doesn't seem to be a treasure table that applies to a specific object, contact the designer in charge of the system to get a new table added.

== Overrides ==

There are a number of override variables on objects that will change the way the Treasure System functions. For each of these variables, a value less than 0 turns off that part of the system, a value of 0 ignores the override, and a value greater than 0 uses that value instead of the one on the creature. Each variable has a short explanation of what overriding does.

{{variable table start}}
{{variable table row|TS_OVERRIDE_CATEGORY |int|0| A value here directly relates to ID values in the TS_Category 2DA.}}
{{variable table row|TS_OVERRIDE_EQUIPMENT |float|0| A value here determines the chance of any particular piece of equipped items dropping. Set this to a negative number to prevent the treasure system from using the default value from the auto scaling table.}}
{{variable table row|TS_OVERRIDE_HIGH|float|0| high chance }}
{{variable table row|TS_OVERRIDE_ITEM|float|0| item chance }}
{{variable table row|TS_OVERRIDE_MONEY |int|0| A value here overrides the TS_MoneyValue value in the autoscale 2DA.}}
{{variable table row|TS_OVERRIDE_RANK |int|0| A value here directly relates to ID values in the autoscale 2DA.}}
{{variable table row|TS_OVERRIDE_REACTIVE|float|0|Reactive chance, only present in the creature variable table{{undocumented}} }}
{{variable table row|TS_OVERRIDE_SCALING |int|0| A value here has no additional effect. This is currently only useful to turn off scaling.}}
{{variable table row|TS_OVERRIDE_STEALING |int|0| A value here directly relates to ID values in the TS_Stealing 2DA.}}
{{variable table row|TS_TREASURE_GENERATED|int|0| A value here ensures the creature never has any treasure, period.}}
{{variable table end}}

== Stealing ==

Stealing from a creature functions the same as a normal treasure drop, except the loot is only ever a single Minor Item. No Money or Major Items will be dropped.

The TS_OVERRIDE_STEALING variable allows special functionality to be added when a creature is stolen from. A value placed in the override is actually an ID lookup in the TS_Stealing 2DA. When that creature is stolen from (and a creature can normally only be successfully stolen from once), it gets the item resource referenced by that ID and adds it to the treasure gained from stealing.

Stealing from creatures is mostly handled by systems, so there are only a couple places a designer can interact with it. First it will be useful to describe exactly what happens when the Stealing skill is used.

When a character tries to use Stealing on another creature, it checks a variety of factors on the character and the target to determine success. If the target has already been stolen from, the character neither succeeds nor fails. If the character fails, the [[EVENT_TYPE_STEALING_FAILURE]] event is fired on the current area. If the character succeeds, the [[EVENT_TYPE_STEALING_SUCCESS]] event is fired on the current area and the FLAG_STOLEN_FROM variable on the target is set to TRUE. Additionally, a successful use of the Stealing skill causes the Treasure System to generate a single Minor Item on the character using the skill. This requires the target to be properly set up for the Treasure System.

The [[EVENT_TYPE_STEALING_FAILURE]] and [[EVENT_TYPE_STEALING_SUCCESS]] events are intended for use in the Infamy system and will be used in the Stealing Reactivity pass.

The FLAG_STOLEN_FROM variable can be set on a creature manually to allow them to be immune to stealing attempts. This can be used to shield plot characters from the skill, though Stealing won't actually remove any items from their inventory. Additionally, you can set the flag to FALSE through scripting to allow the player to steal from a target more than once. Creatures with this flag set will not fire [[EVENT_TYPE_STEALING_FAILURE]] or [[EVENT_TYPE_STEALING_SUCCESS]] events, so they won't interact with the Infamy system.

=== Specific Items ===

The Treasure System has functionality added to allow you to get specific items when stealing from a character. The TS_OVERRIDE_STEALING variable on creatures allows you to set associate a creature with a specific ID value in the TS_Stealing 2DA. Each ID value references a specific item resource name. When a character with this variable set is stolen from, that specific item resource will be added to the treasure the player receives.

The target does not have to have a valid Rank or Treasure Category for this item to drop. This is so you can drop only the specific item and nothing else.

== TS_System.xls and related 2das ==

See [[TS_System.xls]]

[[Category:Creatures]]
[[Category:Placeables]]
{{Languages}}

CommandUnsheatheWeapons

2011-05-20T12:35:42Z

Proleric1:

{{dafunction
|name=CommandUnsheatheWeapons
|brief=This function is an unsheathe weapons command constructor.
|returntype=command
|returndesc=a valid command
|sourcefile=script.ldf
|sourcemodule=
}}

== Description ==

Makes the creature executing this command draw its weapons.

== Remarks ==

This command doesn't seem to work. It is not used in the OC or core scripts.







[[Category: Commands functions]]

CommandUnsheatheWeapons

2011-05-20T12:35:04Z

Proleric1:

{{Generated}}
{{dafunction
|name=CommandUnsheatheWeapons
|brief=This function is an unsheathe weapons command constructor.
|returntype=command
|returndesc=a valid command
|sourcefile=script.ldf
|sourcemodule=
}}

== Description ==

Makes the creature executing this command draw its weapons.

== Remarks ==

This command doesn't seem to work. It is not used in the OC or core scripts.







[[Category: Commands functions]]

Custom AI

2011-05-18T12:53:59Z

Proleric1:

Custom AI allows the creature's event script to handle the creature's combat activities directly and prevents the usual default combat AI from running for it.

== Custom AI state variable ==

Custom AI is enabled via the AI_CUSTOM_AI_ACTIVE variable in a [[creature]]'s variable table, which also keeps track of the current 'state' the custom AI is in.

When the game completes the [[command]] that a creature is currently executing, a creature whose AI_CUSTOM_AI_ACTIVE variable is set to a non-zero value will be sent an [[EVENT_TYPE_CUSTOM_COMMAND_COMPLETE]] event (older documentation said [[EVENT_TYPE_HANDLE_CUSTOM_AI]], but this doesn't seem to be the case).

The event is sent after rules_core has processed the regular [[EVENT_TYPE_COMMAND_COMPLETE]] event, which may mean that [[Ambient behaviour]] has already issued another command.

These are the available value ranges and predefined constants for AI_CUSTOM_AI_ACTIVE:

{| border="1"
|-
| 0 - 999 || Reserved for Basic Custom AI Modes
|-
| 1000 - 9999 || Free to use for Local Custom AI
|-
| 10000 - * || Reserved for Global Custom AI
|}

Basic custom AI modes that have been defined are:

*CAI_DISABLED - Custom AI is disabled (normal AI takes over again)
*CAI_STASIS - Creature will become dormant and issue no commands
*CAI_INACTIVE -
*CAI_INITIATE - A default "starting state" that can be used for initialization.

Global custom AI constants that have been defined are:

*CAI_RUNNER_RUN - used by a creature who flees from the PC in the middle of combat for some reason or another.
*CAI_USEPLACEABLE_LYRIUM_VEIN
*CAI_USEPLACEABLE_BALISTA

== Custom AI creature variables ==

The default var_creature variable table has three variables that are intended for use by designers writing custom AI scripts. They are:

{{variable table start}}
{{variable table row|AI_CUSTOM_AI_VAR_FLOAT | float || A float value that can be used by custom AI scripts for any purpose.}}
{{variable table row|AI_CUSTOM_AI_VAR_INT | int || An int value that can be used by custom AI scripts for any purpose.}}
{{variable table row|AI_CUSTOM_AI_VAR_STRING | string || A string value that can be used by custom AI scripts for any purpose}}
{{variable table end}}

To make using them easier, the following functions are defined:

*CAI_SetCustomAIFloat
*CAI_SetCustomAIInteger
*CAI_SetCustomAIString
*CAI_GetCustomAIFloat
*CAI_GetCustomAIInteger
*CAI_GetCustomAIString

== Giving creatures commands ==

It's very important that you ensure that every time the custom AI code is called the creature has a command in its command queue when the code is finished running. If it doesn't, the creature's AI code won't be called again and it will cease performing any actions from that point onward.

The function AI_DetermineCombatRound(); is very useful and important when designing a custom AI. This function issues the creature a "default" command that's based on its capabilities and perceptions. For example, in a monster's custom AI this will generally mean attacking the player in some way.

== Example code with comments ==

Here is the skeleton of a basic [[EVENT_TYPE_HANDLE_CUSTOM_AI]] case for an event script. This code is for an extremely simple custom AI that causes a creature to do nothing except run an animation every five seconds during combat.

<dascript>
#include "cai_h" //Include this file to use custom AI support functions

const int CAI_USER_DEFINED_STATE_ANIMATION = 1000;
const int CAI_USER_DEFINED_STATE_DELAY = 1001;
//and so forth - use more descriptive names for your state constants to make the code easier to understand.

...

case EVENT_TYPE_SPAWN:
{
//Setting the custom AI to "initiate" means the custom AI will be called
//when the creature enters combat. You can use one of your own custom states
//as the starting point instead, CAI_INITIATE is only 'special' in that it has
//had a constant pre-defined for it already in the core library.
CAI_SetCustomAI(OBJECT_SELF, CAI_INITIATE);
break;
}

case EVENT_TYPE_HANDLE_CUSTOM_AI:
{
// Determine which custom AI state the creature is in.
int nCustomAI = CAI_GetCustomAI(OBJECT_SELF);

Log_Trace(LOG_CHANNEL_TEMP, GetCurrentScriptName(), "Firing custom AI event: " + ToString(nCustomAI));

//Fall-through for if the custom AI command failed.
//This addresses issues with creatures that run appear/disappear animations
//when they're made active or inactive.
if (GetEventInteger(ev,2)==COMMAND_FAILED)
{
WR_AddCommand(OBJECT_SELF,CommandWait(0.01f),TRUE);
return;
}

switch ( nCustomAI )
{
case CAI_INITIATE:
{
//insert whatever initialization code you need here, and then set the custom
//AI to another state.

CAI_SetCustomAI(OBJECT_SELF, CAI_USER_DEFINED_STATE_ANIMATION);
AI_DetermineCombatRound(); //we didn't give the creature a command in this state, so call this to determine a default action.
bActionPerformed = TRUE;
break;
}

case CAI_USER_DEFINED_STATE_ANIMATION:
{
//creates a command to play an animation (index is to a row defined in the ANIM_base 2DA)
command cPlayAnim = CommandPlayAnimation(247);

//Puts the animation at the front of the creature's command queue.
//Setting it as "static" means nothing will interrupt it, which
//is particularly useful for animations.
WR_AddCommand(OBJECT_SELF, cPlayAnim, TRUE, TRUE);

//Set the next state we want to be in
CAI_SetCustomAI(OBJECT_SELF, CAI_USER_DEFINED_STATE_DELAY);

break;
}

case CAI_USER_DEFINED_STATE_DELAY:
{
AddCommand(OBJECT_SELF, CommandWait(5)); //adds a wait command.
CAI_SetCustomAI(OBJECT_SELF, CAI_USER_DEFINED_STATE_ANIMATION); //we'll do this state next
break;
}

//Include this default case just in case something weird happens and the custom AI event is
//run with an unexpected state.
default: AI_DetermineCombatRound();

break;
}
break;
}

...
</dascript>

[[Category:Scripts]]
[[Category:Creatures]]

Bug: EVENT TYPE CUSTOM COMMAND COMPLETE not being handled

2011-05-18T12:36:49Z

Proleric1: /* Comment */

*'''Version found:''' v1.0.1008.0
*'''Status:''' Open

== Description ==

== Workarounds ==

== Comment ==

This may be a spurious bug report.

If the AI_CUSTOM_AI_ACTIVE variable on the creature template is set (see [[Custom AI]]), EVENT_TYPE_CUSTOM_COMMAND_COMPLETE is sent to the creature script.

[[Category:Toolset bugs]]

Ambient behaviour

2011-05-18T12:34:59Z

Proleric1: /* Movement */

{{infobox creature}}

Ambient behaviour begins when the player moves within 50m of a creature and ceases when the player remains more than 50m away for at least 40s. Ambient behaviour alternates between a movement phase and an animation phase, simulating a bubble of activity around the player. In a movement phase, the creature (optionally) moves to a new destination (typically a [[waypoint]] but it could be any object) and turns to face the same direction as the destination object. In an animation phase, the creature (optionally) performs one or more animations either in sequence or at random. Exact behaviour is controlled by local variables set on either the creature instance or template (see table below). All other local variables with the prefix AMBIENT_* are used internally by the ambient behaviour system (see script [[sys_ambient_h]].nss) and should not be manually modified. Never directly modify AMBIENT_* local variables at run time using [[SetLocalInt]] - always use the functions [[Ambient_Start]], [[Ambient_Stop]], [[Ambient_OverrideBehaviour]], and [[Ambient_RestoreBehaviour]] instead. Ambient behaviour is persisted when a game is saved and automatically resumes when a game is loaded.

== Local Variables (var_creature) ==

{{Variable table start}}
{{Variable table row|AMBIENT_SYSTEM_STATE| int| 0| Bitmask controlling ambient system operation. (ergo, values below are in hexadecimal).
* 0x01 (AMBIENT_SYSTEM_ENABLED): Ambient behaviour enabled. For non-looping animations this is the only bit that need be set.
* 0x02 (AMBIENT_SYSTEM_SPAWNSTART: Begin ambient behaviour immediately after spawning. Generally, only infinitely looping animations require this.
* 0x04 (AMBIENT_SYSTEM_NOPLAYNEXT): Sets '''bPlayNext''' parameter to [[CommandPlayAnimation]] to false. Only infinitely looping animations require this.
* 0x08 (AMBIENT_SYSTEM_NOBLEND): Sets '''bBlendIn''' parameter to [[CommandPlayAnimation]] to false. Set this to force a creature to resume an infinitely looping animation after a conversation.
* 0x10 (AMBIENT_SYSTEM_ALWAYSON): Ambient behaviour never stops, regardless of distance to player. This should rarely, if ever, be used but at least the functionality exists if needed.}}
{{Variable table row|AMBIENT_MOVE_PATTERN| int | 0 | Dictates how the creature moves. Add 100 to the values below make creature run instead of walk. Add 10-90 for a random mix of running and walking (a higher value means more running).
* 0 (AMBIENT_MOVE_NONE): No ambient movement
* 1 (AMBIENT_MOVE_PATROL): Patrol waypoints (1, 2, 3, 2, 1, ...)
* 2 (AMBIENT_MOVE_LOOP): Loop through waypoints (1, 2, 3, 1, 2, 3, ...)
* 3 (AMBIENT_MOVE_WARP): Jump creature from the last waypoint to the first (1, 2, 3, jump to 1, 2, 3, ...)
* 4 (AMBIENT_MOVE_RANDOM): Move to a random waypoint other than the one the creature is currently at
* 5 (AMBIENT_MOVE_WANDER): Move to random location within 10m of home location
* 6 (AMBIENT_MOVE_WANDER_FAR): Move to random location within 30m of home location
* 7 (AMBIENT_MOVE_PATH_PATROL): Patrol all waypoints using [[CommandMoveToMultiLocations]] (1,2,3,2,1,...)
* 8 (AMBIENT_MOVE_PATH_LOOP): Loop through all waypoints using [[CommandMoveToMultiLocations]] (1,2,3. 1,2,3)
* 9 (AMBIENT_MOVE_ONCE): Walk through the waypoint set once (1-2-3)}}
{{Variable table row|AMBIENT_MOVE_PREFIX| string | ap_<tag>| The prefix is used to determine the waypoints the creature can travel to. Note that ''<tag>'' is a placeholder filled in at run-time with the tag of the creature. Hence, for example, if AMBIENT_MOVE_PREFIX is ''ap_<tag>'' and the creature's tag is ''cr_dog'' then the system will look for waypoints with tags ''ap_cr_dog_01'', ''ap_cr_dog_02'', ''etc''. If no waypoint is found with the ''_01'' extension, the system will search instead for all waypoints with tags matching the AMBIENT_MOVE_PREFIX value exactly (i.e. ''ap_cr_dog''). This is useful in cases where you just want to add N waypoints all with the same tag.}}
{{Variable table row| AMBIENT_ANIM_PATTERN| int | 0 | Index into [[ambient_ai.xls]]. Specifies the list of possible actions the creature can/will perform during an animation phase.
* 0: No ambient animation pattern (ergo, no ambient animations).}}
{{Variable table row| AMBIENT_ANIM_FREQ| float | -1.0 | Animation frequency. The part left of the decimal specifies the minimum and the part right of the decimal specifies the maximum number of random animations to play during an animation phase. So, for example, a value of 1.3 will play between 1 and 3 random animations from the animation pattern listed in ambient_ai.xls. A value of -1.0 plays all animations in the animation pattern in the order they are listed in ambient_ai.xls. Animation pattens that are highlighted in green on the worksheeet should always be played in order (i.e. AMBIENT_ANIM_FREQ is -1.0).}}
{{Variable table row| AMBIENT_COMMAND | int | 0 |If non-zero, this value forces the creature to perform a specific command (instead of moving and animating).
* 0: Use standard ambient ambient behaviour system to perform movement and animations.
* 1: Forces creature to attack the nearest object with tag ''<tag>_target''. There's an interval of 1-5 seconds between attack commands.
* 2: Forces creature to attack the nearest object with tag ''<tag>_target''. There's an interval of 0-0.5 seconds between attack commands.}}
{{Variable table row|AMBIENT_ANIM_PATTERN_OVERRIDE| int| 0| Overrides AMBIENT_ANIM_PATTERN if non-zero.}}
{{Variable table row|AMBIENT_ANIM_FREQ_OVERRIDE| int| 0| Overrides AMBIENT_ANIM_FREQ if non-zero.}}
{{Variable table row|AMBIENT_ANIM_STATE | int |0| Internal use by ambient behaviour system. Tracks number of animations left to play.}}
{{Variable table row|AMBIENT_MOVE_COUNT | int |-1| Internal use by ambient behaviour system. Tracks total number of destination points for a creature.}}
{{Variable table row|AMBIENT_MOVE_STATE | int |0| Internal use by ambient behaviour system. Tracks the last waypoint creature moved to and direction of travel.}}
{{Variable table row|AMBIENT_TICK_COUNT | int |0| Used internally, do not modify}}
{{Variable table row|AMBIENT_ANIM_OVERRIDE_COUNT|int|0|}}
{{Variable table end}}

== ambient_ai.xls ==
The actions used in an animation phase are listed in the ambient_anim_patterns worksheet of [[ambient_ai.xls]]. Each row defines an animation pattern, consisting of up to thirteen actions. Each action is composed of an animation (left of the decimal) and the number of loops it is played (right of decimal). For example, 619.02 will play a sleeping loop animation twice and 619.99 will play an infinitely looping sleeping animation. Non-looping animations require no loop-count (i.e. decimal) component. The list of all available animations is located in [[ANIM_base.xls]].

== sys_ambient_h ==

The script [[sys_ambient_h]] contains the implementation of the ambient behaviour system. The AMBIENT_* local variables should never be directly modified at run-time. Instead, use the following functions to customize a creature's ambient behaviour through script.

<dascript>
// Normally this function is called automatically to begin or resume ambient behaviour when a
// creature perceives the player. However, it can be called explicitly to force a creature to begin
// performing ambient behaviour or, if nAmbientEnable is 1, to enable ambient behaviour on a creature.
void Ambient_Start(object oCreature = OBJECT_SELF, int nAmbientEnable = 0, int nMovePattern = 0, string sMovePrefix = "");

// Normally this function is called automatically to pause ambient behaviour after the party has
// been out of the creature's sight for a while. However, this function can be used to force a
// creature to temporarily cease ambient behaviour. Note that the creature will automatically
// resume ambient behaviour when it perceives the player again.
void Ambient_Pause(object oCreature = OBJECT_SELF, int bCheckVisibility = TRUE);

// Turns off ambient behaviour on a creature. The creature will resume ambient behaviour only
// after Ambient_Start() is called.
void Ambient_Stop(object oCreature = OBJECT_SELF);

// Overrides the ambient animation pattern and animation frequency defined by the creature's template.
void Ambient_OverrideBehaviour(object oCreature, int nAnimPattern, float fAnimFreq);

// Restores a creature's ambient animation behaviour to that defined in the creature's template.
void Ambient_RestoreBehaviour(object oCreature);
</dascript>

== Overriding Ambient Behaviour ==

{{Variable table start}}
{{Variable table row|AMBIENT_ANIM_PATTERN_OVERRIDE | int | 0 | Index into [[ambient_ai.xls]]. Specifies the list of possible actions the creature can/will perform during an animation phase.
* 0: no animations.}}
{{Variable table row| AMBIENT_ANIM_FREQ_OVERRIDE | float | -1.0 | Animation frequency. The portion left of decimal specifies the minimum and the portion right of the decimal specifies the maximum number of animations to play during an animation phase. A value of -1.0 plays all animations in the animation pattern in the order listed in [[ambient_ai.xls]].}}
{{Variable table row| AMBIENT_ANIM_OVERRIDE_COUNT | int | | Used internally, do not modify}}
{{Variable table end}}

== Customising Ambient Behaviour ==

=== Animations ===

New ambient_anim_patterns can be added as an M2DA.

Provisionally, it seems that some animations are cutscene-only. They don't work when scripted. This requires further investigation and documentation, as there is a [[Bug:_Some_animations_in_ANIM_base_won%27t_fire | bug]] which may account for some or all of this.

=== Movement ===

The system doesn't provide an explicit hook for a user-defined movement pattern.

However, it does support walking once through a set of waypoints.

We can implement any custom movement pattern as several sets of waypoints (each with its own prefix).

For example, if we want to walk from A to B, then C or D and E depending on some condition, we might define the sets as ap1 (A, B), ap2 (C) and ap3 (D, E).

We tell Ambient AI to walk waypoints prefixed ap1. On completion, we tell it to walk ap2 or ap3, depending on the condition.

Intercepting the Ambient AI is tricky. By default, EVENT_TYPE_COMMAND_COMPLETE is handled directly by the rules_core script, which kicks off the next Ambient AI action before we can stop it. Presumably, this is for performance reasons.

Set the AI_CUSTOM_AI_ACTIVE variable (see [[Custom AI]]) on the creature template to generate a new event (EVENT_TYPE_CUSTOM_COMMAND_COMPLETE) which can be handled in the creature script. If the creature is a non-combatant, CAI_INACTIVE (1) works fine.

Using AMBIENT_MOVE_ONCE, when the final waypoint is reached, Ambient AI will reset the move pattern to AMBIENT_MOVE_NONE before this new event fires.

We can then trigger the next set of waypoints by including a snippet like this in our creature script:

<dascript>
case EVENT_TYPE_CUSTOM_COMMAND_COMPLETE:
{
object oCreature = OBJECT_SELF;

// Do nothing unless we have arrived at our destination

if (GetLocalInt(oCreature, AMBIENT_MOVE_PATTERN) == AMBIENT_MOVE_NONE)
{
int nLastCommandType = GetEventInteger(ev, 0);
int nCommandStatus = GetEventInteger(ev, 1);
int nLastSubCommand = GetEventInteger(ev, 2);
object oLastTarget = OBJECT_INVALID;
object oBlockingObject = GetEventObject(ev, 2);

// Check which path just finished

if (GetLocalString(oCreature, AMBIENT_MOVE_PREFIX) != "ap1_<tag>") break;

// Stop Ambient AI for good order

Ambient_Stop(oCreature);

// Fix bug in Ambient_Start

SetLocalInt(oCreature, AMBIENT_MOVE_COUNT, AMBIENT_MOVE_COUNT_INVALID);
SetLocalInt(oCreature, AMBIENT_MOVE_STATE, AMBIENT_MOVE_NEXT);

// Restart on new path

Ambient_Start(oCreature, AMBIENT_SYSTEM_ENABLED, AMBIENT_MOVE_ONCE, "ap2_<tag>");
}

bEventHandled = TRUE;
break;
}
</dascript>

Note that when using any movement pattern other than AMBIENT_MOVE_ONCE, Ambient AI will issue the next movement command before EVENT_TYPE_CUSTOM_COMMAND_COMPLETE fires.

== Bugs ==

Changing the movement path for a creature is [[Bug:_Ambient_movement_erratic_when_a_new_path_is_specified | bugged]].

[[Category:Ambient behavior]]

Ambient behaviour

2011-05-18T09:55:49Z

Proleric1: /* Animations */

{{infobox creature}}

Ambient behaviour begins when the player moves within 50m of a creature and ceases when the player remains more than 50m away for at least 40s. Ambient behaviour alternates between a movement phase and an animation phase, simulating a bubble of activity around the player. In a movement phase, the creature (optionally) moves to a new destination (typically a [[waypoint]] but it could be any object) and turns to face the same direction as the destination object. In an animation phase, the creature (optionally) performs one or more animations either in sequence or at random. Exact behaviour is controlled by local variables set on either the creature instance or template (see table below). All other local variables with the prefix AMBIENT_* are used internally by the ambient behaviour system (see script [[sys_ambient_h]].nss) and should not be manually modified. Never directly modify AMBIENT_* local variables at run time using [[SetLocalInt]] - always use the functions [[Ambient_Start]], [[Ambient_Stop]], [[Ambient_OverrideBehaviour]], and [[Ambient_RestoreBehaviour]] instead. Ambient behaviour is persisted when a game is saved and automatically resumes when a game is loaded.

== Local Variables (var_creature) ==

{{Variable table start}}
{{Variable table row|AMBIENT_SYSTEM_STATE| int| 0| Bitmask controlling ambient system operation. (ergo, values below are in hexadecimal).
* 0x01 (AMBIENT_SYSTEM_ENABLED): Ambient behaviour enabled. For non-looping animations this is the only bit that need be set.
* 0x02 (AMBIENT_SYSTEM_SPAWNSTART: Begin ambient behaviour immediately after spawning. Generally, only infinitely looping animations require this.
* 0x04 (AMBIENT_SYSTEM_NOPLAYNEXT): Sets '''bPlayNext''' parameter to [[CommandPlayAnimation]] to false. Only infinitely looping animations require this.
* 0x08 (AMBIENT_SYSTEM_NOBLEND): Sets '''bBlendIn''' parameter to [[CommandPlayAnimation]] to false. Set this to force a creature to resume an infinitely looping animation after a conversation.
* 0x10 (AMBIENT_SYSTEM_ALWAYSON): Ambient behaviour never stops, regardless of distance to player. This should rarely, if ever, be used but at least the functionality exists if needed.}}
{{Variable table row|AMBIENT_MOVE_PATTERN| int | 0 | Dictates how the creature moves. Add 100 to the values below make creature run instead of walk. Add 10-90 for a random mix of running and walking (a higher value means more running).
* 0 (AMBIENT_MOVE_NONE): No ambient movement
* 1 (AMBIENT_MOVE_PATROL): Patrol waypoints (1, 2, 3, 2, 1, ...)
* 2 (AMBIENT_MOVE_LOOP): Loop through waypoints (1, 2, 3, 1, 2, 3, ...)
* 3 (AMBIENT_MOVE_WARP): Jump creature from the last waypoint to the first (1, 2, 3, jump to 1, 2, 3, ...)
* 4 (AMBIENT_MOVE_RANDOM): Move to a random waypoint other than the one the creature is currently at
* 5 (AMBIENT_MOVE_WANDER): Move to random location within 10m of home location
* 6 (AMBIENT_MOVE_WANDER_FAR): Move to random location within 30m of home location
* 7 (AMBIENT_MOVE_PATH_PATROL): Patrol all waypoints using [[CommandMoveToMultiLocations]] (1,2,3,2,1,...)
* 8 (AMBIENT_MOVE_PATH_LOOP): Loop through all waypoints using [[CommandMoveToMultiLocations]] (1,2,3. 1,2,3)
* 9 (AMBIENT_MOVE_ONCE): Walk through the waypoint set once (1-2-3)}}
{{Variable table row|AMBIENT_MOVE_PREFIX| string | ap_<tag>| The prefix is used to determine the waypoints the creature can travel to. Note that ''<tag>'' is a placeholder filled in at run-time with the tag of the creature. Hence, for example, if AMBIENT_MOVE_PREFIX is ''ap_<tag>'' and the creature's tag is ''cr_dog'' then the system will look for waypoints with tags ''ap_cr_dog_01'', ''ap_cr_dog_02'', ''etc''. If no waypoint is found with the ''_01'' extension, the system will search instead for all waypoints with tags matching the AMBIENT_MOVE_PREFIX value exactly (i.e. ''ap_cr_dog''). This is useful in cases where you just want to add N waypoints all with the same tag.}}
{{Variable table row| AMBIENT_ANIM_PATTERN| int | 0 | Index into [[ambient_ai.xls]]. Specifies the list of possible actions the creature can/will perform during an animation phase.
* 0: No ambient animation pattern (ergo, no ambient animations).}}
{{Variable table row| AMBIENT_ANIM_FREQ| float | -1.0 | Animation frequency. The part left of the decimal specifies the minimum and the part right of the decimal specifies the maximum number of random animations to play during an animation phase. So, for example, a value of 1.3 will play between 1 and 3 random animations from the animation pattern listed in ambient_ai.xls. A value of -1.0 plays all animations in the animation pattern in the order they are listed in ambient_ai.xls. Animation pattens that are highlighted in green on the worksheeet should always be played in order (i.e. AMBIENT_ANIM_FREQ is -1.0).}}
{{Variable table row| AMBIENT_COMMAND | int | 0 |If non-zero, this value forces the creature to perform a specific command (instead of moving and animating).
* 0: Use standard ambient ambient behaviour system to perform movement and animations.
* 1: Forces creature to attack the nearest object with tag ''<tag>_target''. There's an interval of 1-5 seconds between attack commands.
* 2: Forces creature to attack the nearest object with tag ''<tag>_target''. There's an interval of 0-0.5 seconds between attack commands.}}
{{Variable table row|AMBIENT_ANIM_PATTERN_OVERRIDE| int| 0| Overrides AMBIENT_ANIM_PATTERN if non-zero.}}
{{Variable table row|AMBIENT_ANIM_FREQ_OVERRIDE| int| 0| Overrides AMBIENT_ANIM_FREQ if non-zero.}}
{{Variable table row|AMBIENT_ANIM_STATE | int |0| Internal use by ambient behaviour system. Tracks number of animations left to play.}}
{{Variable table row|AMBIENT_MOVE_COUNT | int |-1| Internal use by ambient behaviour system. Tracks total number of destination points for a creature.}}
{{Variable table row|AMBIENT_MOVE_STATE | int |0| Internal use by ambient behaviour system. Tracks the last waypoint creature moved to and direction of travel.}}
{{Variable table row|AMBIENT_TICK_COUNT | int |0| Used internally, do not modify}}
{{Variable table row|AMBIENT_ANIM_OVERRIDE_COUNT|int|0|}}
{{Variable table end}}

== ambient_ai.xls ==
The actions used in an animation phase are listed in the ambient_anim_patterns worksheet of [[ambient_ai.xls]]. Each row defines an animation pattern, consisting of up to thirteen actions. Each action is composed of an animation (left of the decimal) and the number of loops it is played (right of decimal). For example, 619.02 will play a sleeping loop animation twice and 619.99 will play an infinitely looping sleeping animation. Non-looping animations require no loop-count (i.e. decimal) component. The list of all available animations is located in [[ANIM_base.xls]].

== sys_ambient_h ==

The script [[sys_ambient_h]] contains the implementation of the ambient behaviour system. The AMBIENT_* local variables should never be directly modified at run-time. Instead, use the following functions to customize a creature's ambient behaviour through script.

<dascript>
// Normally this function is called automatically to begin or resume ambient behaviour when a
// creature perceives the player. However, it can be called explicitly to force a creature to begin
// performing ambient behaviour or, if nAmbientEnable is 1, to enable ambient behaviour on a creature.
void Ambient_Start(object oCreature = OBJECT_SELF, int nAmbientEnable = 0, int nMovePattern = 0, string sMovePrefix = "");

// Normally this function is called automatically to pause ambient behaviour after the party has
// been out of the creature's sight for a while. However, this function can be used to force a
// creature to temporarily cease ambient behaviour. Note that the creature will automatically
// resume ambient behaviour when it perceives the player again.
void Ambient_Pause(object oCreature = OBJECT_SELF, int bCheckVisibility = TRUE);

// Turns off ambient behaviour on a creature. The creature will resume ambient behaviour only
// after Ambient_Start() is called.
void Ambient_Stop(object oCreature = OBJECT_SELF);

// Overrides the ambient animation pattern and animation frequency defined by the creature's template.
void Ambient_OverrideBehaviour(object oCreature, int nAnimPattern, float fAnimFreq);

// Restores a creature's ambient animation behaviour to that defined in the creature's template.
void Ambient_RestoreBehaviour(object oCreature);
</dascript>

== Overriding Ambient Behaviour ==

{{Variable table start}}
{{Variable table row|AMBIENT_ANIM_PATTERN_OVERRIDE | int | 0 | Index into [[ambient_ai.xls]]. Specifies the list of possible actions the creature can/will perform during an animation phase.
* 0: no animations.}}
{{Variable table row| AMBIENT_ANIM_FREQ_OVERRIDE | float | -1.0 | Animation frequency. The portion left of decimal specifies the minimum and the portion right of the decimal specifies the maximum number of animations to play during an animation phase. A value of -1.0 plays all animations in the animation pattern in the order listed in [[ambient_ai.xls]].}}
{{Variable table row| AMBIENT_ANIM_OVERRIDE_COUNT | int | | Used internally, do not modify}}
{{Variable table end}}

== Customising Ambient Behaviour ==

=== Animations ===

New ambient_anim_patterns can be added as an M2DA.

Provisionally, it seems that some animations are cutscene-only. They don't work when scripted. This requires further investigation and documentation, as there is a [[Bug:_Some_animations_in_ANIM_base_won%27t_fire | bug]] which may account for some or all of this.

=== Movement ===

The system doesn't provide an explicit hook for a user-defined movement pattern.

However, it does support walking once through a set of waypoints.

We can implement any custom movement pattern as several sets of waypoints (each with its own prefix).

For example, if we want to walk from A to B, then C or D and E depending on some condition, we might define the sets as ap1 (A, B), ap2 (C) and ap3 (D, E).

We tell Ambient AI to walk waypoints prefixed ap1. On completion, we tell it to walk ap2 or ap3, depending on the condition.

Intercepting the Ambient AI is tricky. By default, EVENT_TYPE_COMMAND_COMPLETE is handled directly by the rules_core script, which kicks off the next Ambient AI action before we can stop it. Presumably, this is for performance reasons.

Set the AI_CUSTOM_AI_ACTIVE variable on the creature template to 1 (i.e. TRUE) to generate a new event (EVENT_TYPE_CUSTOM_COMMAND_COMPLETE) which can be handled in the creature script.

Using AMBIENT_MOVE_ONCE, when the final waypoint is reached, Ambient AI will reset the move pattern to AMBIENT_MOVE_NONE before this new event fires.

We can then trigger the next set of waypoints by including a snippet like this in our creature script:

<dascript>
case EVENT_TYPE_CUSTOM_COMMAND_COMPLETE:
{
object oCreature = OBJECT_SELF;

// Do nothing unless we have arrived at our destination

if (GetLocalInt(oCreature, AMBIENT_MOVE_PATTERN) == AMBIENT_MOVE_NONE)
{
int nLastCommandType = GetEventInteger(ev, 0);
int nCommandStatus = GetEventInteger(ev, 1);
int nLastSubCommand = GetEventInteger(ev, 2);
object oLastTarget = OBJECT_INVALID;
object oBlockingObject = GetEventObject(ev, 2);

// Check which path just finished

if (GetLocalString(oCreature, AMBIENT_MOVE_PREFIX) != "ap1_<tag>") break;

// Stop Ambient AI for good order

Ambient_Stop(oCreature);

// Fix bug in Ambient_Start

SetLocalInt(oCreature, AMBIENT_MOVE_COUNT, AMBIENT_MOVE_COUNT_INVALID);
SetLocalInt(oCreature, AMBIENT_MOVE_STATE, AMBIENT_MOVE_NEXT);

// Restart on new path

Ambient_Start(oCreature, AMBIENT_SYSTEM_ENABLED, AMBIENT_MOVE_ONCE, "ap2_<tag>");
}

bEventHandled = TRUE;
break;
}
</dascript>

Note that when using any movement pattern other than AMBIENT_MOVE_ONCE, Ambient AI will issue the next movement command before EVENT_TYPE_CUSTOM_COMMAND_COMPLETE fires.

== Bugs ==

Changing the movement path for a creature is [[Bug:_Ambient_movement_erratic_when_a_new_path_is_specified | bugged]].

[[Category:Ambient behavior]]

Bug: Light Map glitches

2011-05-18T09:51:38Z

Proleric1: /* Workarounds */

*'''Version found:''' 1.0.982.19 
*'''Status:''' Open
== Description ==

After light maps have been rendered, they may contain obvious glitches (e.g. dark triangles, shadows from models that have been deleted, severe brightness / darkness issues etc).

This may be related in part to the hard-coding of "single player" in part of the resource processing pipeline, which has already been identified as a bug affecting water planes.

However, that's probably not the whole story, because deleting the old erf file can improve the results, too (and makes the rendering process much faster).

There are numerous bugs and glitches with the currently available eclipseray 1.2 as you can read at the appropriate threads. e.g.:

== Bugs ==
* black spots randomly placed at the lightmaps around tesselation borders
* shiny blue shade at certain models
* bugged and therefore corrupted lightmap of a chunk if more than one static/animated light lits it
* wrong calculated intensity value of baked lights
* alpha maps are not rendered correctly -> spider webs drop a shadow but they should not do so
* light probes are not rendered correctly -> they all show the same mirrored texture

There is '''no workaround''' for any of the glitches! The dark triangles are directly connected with tesselation borders. If you tesselate your mesh the triangles will wander around the new border where the high resolution grid hits the low resolution grid.

== Workarounds ==


Most lighting bugs seem to go away if you

* Delete any erf files for the level (you may need to close the toolset first)
* Delete Windows temporary files
* In (Documents)\Bioware\Dragon Age\Toolset, delete all files from subfolders LvlWorkspace, ProbeLightMaps and resourcepostintermediateWin32
* Switch to the Single Player campaign in the toolset (File > Manage Modules)
* Open your level and do all the rendering and posting in Single Player
* Delete the old level folder from AddIns > [module] > core > override > toolsetexport
* Move the folder you just made in packages > core > override > toolsetexport to that Addins location
* Reopen your module (File > Manage Modules)

If you get a "failed to load" error in Single Player, your level may contain an unnecessary custom object, such as a test creature.

Routine file deletion (mentioned above) can be done at a stroke using free configurable tools such as [http://www.piriform.com/ccleaner CCleaner].

[[Category:Toolset bugs]]
[[Category:Level layout bugs]]

Bug: EVENT TYPE CUSTOM COMMAND COMPLETE not being handled

2011-05-18T09:35:51Z

Proleric1:

*'''Version found:''' v1.0.1008.0
*'''Status:''' Open

== Description ==

== Workarounds ==

== Comment ==

This may be a spurious bug report.

If the AI_CUSTOM_AI_ACTIVE variable on the creature template is set (to 1), EVENT_TYPE_CUSTOM_COMMAND_COMPLETE is sent to the creature script.

[[Category:Toolset bugs]]

Bug: Builder to Builder Create includes core resources by default

2011-05-18T09:30:27Z

Proleric1: Created page with '*'''Toolset verion:''' 1.0.1008.0 *'''Game version:''' 1.04 *'''Status:''' Open == Description == <!-- Describe the bug here including as many details as possible. What situati...'

*'''Toolset verion:''' 1.0.1008.0
*'''Game version:''' 1.04
*'''Status:''' Open

== Description ==


Builder to Builder Create includes dependent core resources by default.

This is a major inconvenience when taking daily backups of a large module.

It makes the extract much bigger and slower than it needs to be.

It also makes the load process more confusing.

== Workarounds ==

Unselect all.

Sort to module order.

Page down from the top to the end of the module.

Select all resources for the module.

Remember how many pages you have to scroll down, to speed things up next time.

== Comment ==

An earlier comment in the wiki suggested that dependent core resources should be included to prevent integrity issues on Load.

In practice, there is almost never a problem, because everyone has the same core resources. If there is, Load just doesn't load the resources in question, which is easily fixed. So, in the light of experience, this is considered to be a bug.
[[Category:Toolset bugs]]

Bug: Water plane missing in-game

2011-05-18T09:18:33Z

Proleric1: /* Workarounds */

*'''Version found:''' 1.0.982.19 
*'''Status:''' Open
{{EV|203997|[[User:Allan Smith|Allan Smith]]}}
== Description ==


If you create a level with a water plane in it the water is appearing properly in the toolset but is non-existent in the game. This problem has been identified. It is not lightmapper related; it turns out that "single player" is hard-coded into a part of the resource processing pipeline.

== Workarounds ==


A proper fix may take some time, but there's a fairly simple workaround for it.

To post a level layout with water, first ensure that you've switched to the single player module via [[manage modules]], and then once you've posted it you'll need to manually copy the resulting files from the single player [[override directory]] into your addin's override directory.

N.B. This bug is one of several path-related errors in level processing. For example, light mapping is also bugged. So, it's advisable to do all level work in the Single Player module, as described above.

[[Category:Toolset bugs]]
[[Category:Level layout bugs]]

Bug: Ambient movement erratic when a new path is specified

2011-05-18T09:13:43Z

Proleric1: /* Description */

*'''Toolset verion:''' 1.0.1008.0
*'''Game version:''' 1.04
*'''Status:''' Open

== Description ==

The Ambient_Start function allows the waypoint path AMBIENT_MOVE_PREFIX to be specified.

However, if it is used to specify a new path for a creature, the new waypoints may be visited in the wrong order.

Specifically, if the creature last moved to old path waypoint N, it will visit new path waypoint N (if it exists) before new path waypoint 1.

This has been verified in AMBIENT_MOVE_ONCE mode, but probably affects most movement patterns.

Ambient_StartTeam() and Ambient_StartTag() depend on Ambient_Start, so they have the same bug.

== Workarounds ==


Add the following initialistions before calling Ambient_Start:

<dascript>
SetLocalInt(oCreature, AMBIENT_MOVE_COUNT, AMBIENT_MOVE_COUNT_INVALID);
SetLocalInt(oCreature, AMBIENT_MOVE_STATE, AMBIENT_MOVE_NEXT);
Ambient_Start(oCreature, ...
</dascript>

where oCreature is the creature object in question.

[[Category:Toolset bugs]]

Ambient behaviour

2011-05-18T09:08:29Z

Proleric1:

{{infobox creature}}

Ambient behaviour begins when the player moves within 50m of a creature and ceases when the player remains more than 50m away for at least 40s. Ambient behaviour alternates between a movement phase and an animation phase, simulating a bubble of activity around the player. In a movement phase, the creature (optionally) moves to a new destination (typically a [[waypoint]] but it could be any object) and turns to face the same direction as the destination object. In an animation phase, the creature (optionally) performs one or more animations either in sequence or at random. Exact behaviour is controlled by local variables set on either the creature instance or template (see table below). All other local variables with the prefix AMBIENT_* are used internally by the ambient behaviour system (see script [[sys_ambient_h]].nss) and should not be manually modified. Never directly modify AMBIENT_* local variables at run time using [[SetLocalInt]] - always use the functions [[Ambient_Start]], [[Ambient_Stop]], [[Ambient_OverrideBehaviour]], and [[Ambient_RestoreBehaviour]] instead. Ambient behaviour is persisted when a game is saved and automatically resumes when a game is loaded.

== Local Variables (var_creature) ==

{{Variable table start}}
{{Variable table row|AMBIENT_SYSTEM_STATE| int| 0| Bitmask controlling ambient system operation. (ergo, values below are in hexadecimal).
* 0x01 (AMBIENT_SYSTEM_ENABLED): Ambient behaviour enabled. For non-looping animations this is the only bit that need be set.
* 0x02 (AMBIENT_SYSTEM_SPAWNSTART: Begin ambient behaviour immediately after spawning. Generally, only infinitely looping animations require this.
* 0x04 (AMBIENT_SYSTEM_NOPLAYNEXT): Sets '''bPlayNext''' parameter to [[CommandPlayAnimation]] to false. Only infinitely looping animations require this.
* 0x08 (AMBIENT_SYSTEM_NOBLEND): Sets '''bBlendIn''' parameter to [[CommandPlayAnimation]] to false. Set this to force a creature to resume an infinitely looping animation after a conversation.
* 0x10 (AMBIENT_SYSTEM_ALWAYSON): Ambient behaviour never stops, regardless of distance to player. This should rarely, if ever, be used but at least the functionality exists if needed.}}
{{Variable table row|AMBIENT_MOVE_PATTERN| int | 0 | Dictates how the creature moves. Add 100 to the values below make creature run instead of walk. Add 10-90 for a random mix of running and walking (a higher value means more running).
* 0 (AMBIENT_MOVE_NONE): No ambient movement
* 1 (AMBIENT_MOVE_PATROL): Patrol waypoints (1, 2, 3, 2, 1, ...)
* 2 (AMBIENT_MOVE_LOOP): Loop through waypoints (1, 2, 3, 1, 2, 3, ...)
* 3 (AMBIENT_MOVE_WARP): Jump creature from the last waypoint to the first (1, 2, 3, jump to 1, 2, 3, ...)
* 4 (AMBIENT_MOVE_RANDOM): Move to a random waypoint other than the one the creature is currently at
* 5 (AMBIENT_MOVE_WANDER): Move to random location within 10m of home location
* 6 (AMBIENT_MOVE_WANDER_FAR): Move to random location within 30m of home location
* 7 (AMBIENT_MOVE_PATH_PATROL): Patrol all waypoints using [[CommandMoveToMultiLocations]] (1,2,3,2,1,...)
* 8 (AMBIENT_MOVE_PATH_LOOP): Loop through all waypoints using [[CommandMoveToMultiLocations]] (1,2,3. 1,2,3)
* 9 (AMBIENT_MOVE_ONCE): Walk through the waypoint set once (1-2-3)}}
{{Variable table row|AMBIENT_MOVE_PREFIX| string | ap_<tag>| The prefix is used to determine the waypoints the creature can travel to. Note that ''<tag>'' is a placeholder filled in at run-time with the tag of the creature. Hence, for example, if AMBIENT_MOVE_PREFIX is ''ap_<tag>'' and the creature's tag is ''cr_dog'' then the system will look for waypoints with tags ''ap_cr_dog_01'', ''ap_cr_dog_02'', ''etc''. If no waypoint is found with the ''_01'' extension, the system will search instead for all waypoints with tags matching the AMBIENT_MOVE_PREFIX value exactly (i.e. ''ap_cr_dog''). This is useful in cases where you just want to add N waypoints all with the same tag.}}
{{Variable table row| AMBIENT_ANIM_PATTERN| int | 0 | Index into [[ambient_ai.xls]]. Specifies the list of possible actions the creature can/will perform during an animation phase.
* 0: No ambient animation pattern (ergo, no ambient animations).}}
{{Variable table row| AMBIENT_ANIM_FREQ| float | -1.0 | Animation frequency. The part left of the decimal specifies the minimum and the part right of the decimal specifies the maximum number of random animations to play during an animation phase. So, for example, a value of 1.3 will play between 1 and 3 random animations from the animation pattern listed in ambient_ai.xls. A value of -1.0 plays all animations in the animation pattern in the order they are listed in ambient_ai.xls. Animation pattens that are highlighted in green on the worksheeet should always be played in order (i.e. AMBIENT_ANIM_FREQ is -1.0).}}
{{Variable table row| AMBIENT_COMMAND | int | 0 |If non-zero, this value forces the creature to perform a specific command (instead of moving and animating).
* 0: Use standard ambient ambient behaviour system to perform movement and animations.
* 1: Forces creature to attack the nearest object with tag ''<tag>_target''. There's an interval of 1-5 seconds between attack commands.
* 2: Forces creature to attack the nearest object with tag ''<tag>_target''. There's an interval of 0-0.5 seconds between attack commands.}}
{{Variable table row|AMBIENT_ANIM_PATTERN_OVERRIDE| int| 0| Overrides AMBIENT_ANIM_PATTERN if non-zero.}}
{{Variable table row|AMBIENT_ANIM_FREQ_OVERRIDE| int| 0| Overrides AMBIENT_ANIM_FREQ if non-zero.}}
{{Variable table row|AMBIENT_ANIM_STATE | int |0| Internal use by ambient behaviour system. Tracks number of animations left to play.}}
{{Variable table row|AMBIENT_MOVE_COUNT | int |-1| Internal use by ambient behaviour system. Tracks total number of destination points for a creature.}}
{{Variable table row|AMBIENT_MOVE_STATE | int |0| Internal use by ambient behaviour system. Tracks the last waypoint creature moved to and direction of travel.}}
{{Variable table row|AMBIENT_TICK_COUNT | int |0| Used internally, do not modify}}
{{Variable table row|AMBIENT_ANIM_OVERRIDE_COUNT|int|0|}}
{{Variable table end}}

== ambient_ai.xls ==
The actions used in an animation phase are listed in the ambient_anim_patterns worksheet of [[ambient_ai.xls]]. Each row defines an animation pattern, consisting of up to thirteen actions. Each action is composed of an animation (left of the decimal) and the number of loops it is played (right of decimal). For example, 619.02 will play a sleeping loop animation twice and 619.99 will play an infinitely looping sleeping animation. Non-looping animations require no loop-count (i.e. decimal) component. The list of all available animations is located in [[ANIM_base.xls]].

== sys_ambient_h ==

The script [[sys_ambient_h]] contains the implementation of the ambient behaviour system. The AMBIENT_* local variables should never be directly modified at run-time. Instead, use the following functions to customize a creature's ambient behaviour through script.

<dascript>
// Normally this function is called automatically to begin or resume ambient behaviour when a
// creature perceives the player. However, it can be called explicitly to force a creature to begin
// performing ambient behaviour or, if nAmbientEnable is 1, to enable ambient behaviour on a creature.
void Ambient_Start(object oCreature = OBJECT_SELF, int nAmbientEnable = 0, int nMovePattern = 0, string sMovePrefix = "");

// Normally this function is called automatically to pause ambient behaviour after the party has
// been out of the creature's sight for a while. However, this function can be used to force a
// creature to temporarily cease ambient behaviour. Note that the creature will automatically
// resume ambient behaviour when it perceives the player again.
void Ambient_Pause(object oCreature = OBJECT_SELF, int bCheckVisibility = TRUE);

// Turns off ambient behaviour on a creature. The creature will resume ambient behaviour only
// after Ambient_Start() is called.
void Ambient_Stop(object oCreature = OBJECT_SELF);

// Overrides the ambient animation pattern and animation frequency defined by the creature's template.
void Ambient_OverrideBehaviour(object oCreature, int nAnimPattern, float fAnimFreq);

// Restores a creature's ambient animation behaviour to that defined in the creature's template.
void Ambient_RestoreBehaviour(object oCreature);
</dascript>

== Overriding Ambient Behaviour ==

{{Variable table start}}
{{Variable table row|AMBIENT_ANIM_PATTERN_OVERRIDE | int | 0 | Index into [[ambient_ai.xls]]. Specifies the list of possible actions the creature can/will perform during an animation phase.
* 0: no animations.}}
{{Variable table row| AMBIENT_ANIM_FREQ_OVERRIDE | float | -1.0 | Animation frequency. The portion left of decimal specifies the minimum and the portion right of the decimal specifies the maximum number of animations to play during an animation phase. A value of -1.0 plays all animations in the animation pattern in the order listed in [[ambient_ai.xls]].}}
{{Variable table row| AMBIENT_ANIM_OVERRIDE_COUNT | int | | Used internally, do not modify}}
{{Variable table end}}

== Customising Ambient Behaviour ==

=== Animations ===

New ambient_anim_patterns can be added as an M2DA.

Provisionally, it seems that some animations are cutscene-only. They don't work when scripted. This requires further investigation and documentation.

=== Movement ===

The system doesn't provide an explicit hook for a user-defined movement pattern.

However, it does support walking once through a set of waypoints.

We can implement any custom movement pattern as several sets of waypoints (each with its own prefix).

For example, if we want to walk from A to B, then C or D and E depending on some condition, we might define the sets as ap1 (A, B), ap2 (C) and ap3 (D, E).

We tell Ambient AI to walk waypoints prefixed ap1. On completion, we tell it to walk ap2 or ap3, depending on the condition.

Intercepting the Ambient AI is tricky. By default, EVENT_TYPE_COMMAND_COMPLETE is handled directly by the rules_core script, which kicks off the next Ambient AI action before we can stop it. Presumably, this is for performance reasons.

Set the AI_CUSTOM_AI_ACTIVE variable on the creature template to 1 (i.e. TRUE) to generate a new event (EVENT_TYPE_CUSTOM_COMMAND_COMPLETE) which can be handled in the creature script.

Using AMBIENT_MOVE_ONCE, when the final waypoint is reached, Ambient AI will reset the move pattern to AMBIENT_MOVE_NONE before this new event fires.

We can then trigger the next set of waypoints by including a snippet like this in our creature script:

<dascript>
case EVENT_TYPE_CUSTOM_COMMAND_COMPLETE:
{
object oCreature = OBJECT_SELF;

// Do nothing unless we have arrived at our destination

if (GetLocalInt(oCreature, AMBIENT_MOVE_PATTERN) == AMBIENT_MOVE_NONE)
{
int nLastCommandType = GetEventInteger(ev, 0);
int nCommandStatus = GetEventInteger(ev, 1);
int nLastSubCommand = GetEventInteger(ev, 2);
object oLastTarget = OBJECT_INVALID;
object oBlockingObject = GetEventObject(ev, 2);

// Check which path just finished

if (GetLocalString(oCreature, AMBIENT_MOVE_PREFIX) != "ap1_<tag>") break;

// Stop Ambient AI for good order

Ambient_Stop(oCreature);

// Fix bug in Ambient_Start

SetLocalInt(oCreature, AMBIENT_MOVE_COUNT, AMBIENT_MOVE_COUNT_INVALID);
SetLocalInt(oCreature, AMBIENT_MOVE_STATE, AMBIENT_MOVE_NEXT);

// Restart on new path

Ambient_Start(oCreature, AMBIENT_SYSTEM_ENABLED, AMBIENT_MOVE_ONCE, "ap2_<tag>");
}

bEventHandled = TRUE;
break;
}
</dascript>

Note that when using any movement pattern other than AMBIENT_MOVE_ONCE, Ambient AI will issue the next movement command before EVENT_TYPE_CUSTOM_COMMAND_COMPLETE fires.

== Bugs ==

Changing the movement path for a creature is [[Bug:_Ambient_movement_erratic_when_a_new_path_is_specified | bugged]].

[[Category:Ambient behavior]]

Bug: Ambient movement erratic when a new path is specified

2011-05-18T07:24:32Z

*'''Toolset verion:''' 1.0.1008.0
*'''Game version:''' 1.04
*'''Status:''' Open

== Description ==

The Ambient_Start function allows the waypoint path AMBIENT_MOVE_PREFIX to be specified.

However, if it is used to specify a new path for a creature, the new waypoints may be visited in the wrong order.

Specifically, if the creature last moved to old path waypoint N, it will visit new path waypoint N before new path waypoint 1.

This has been verified in AMBIENT_MOVE_ONCE mode, but probably affects most movement patterns.

Ambient_StartTeam() and Ambient_StartTag() depend on Ambient_Start, so they have the same bug.

== Workarounds ==


Add the following initialistions before calling Ambient_Start:

<dascript>
SetLocalInt(oCreature, AMBIENT_MOVE_COUNT, AMBIENT_MOVE_COUNT_INVALID);
SetLocalInt(oCreature, AMBIENT_MOVE_STATE, AMBIENT_MOVE_NEXT);
Ambient_Start(oCreature, ...
</dascript>

where oCreature is the creature object in question.

[[Category:Toolset bugs]]

Ambient behaviour

2011-05-16T10:25:21Z

Proleric1: /* Local Variables (var_creature) */

Backgrounds tutorial

2011-05-15T09:05:01Z

Proleric1: /* Creating the background strings */

== Introduction ==
This tutorial shows you how to modify the character backgrounds that can be selected during character generation. This is likely only of use if you are creating your own module or campaign as there would be no point to changing the background in the single player campaign unless you were also going to make extensive additions to support the new backgrounds (e.g a completely new origin story). So the example we will use for this tutorial is a new stand alone module in which we completely replace the existing backgrounds. Changing backgrounds is especially useful if your module is set in a different lore to the main Dragon Age game or if you simply want to reduce the scope of the number of different backgrounds.

We will also demonstrate some important principals that can be followed when modifying other core rules such as available races or classes. Most importantly we will add the new backgrounds in a way that doesn’t require any editing of core resources. By leaving the core resources alone we make our changes compatible with future patches which might otherwise overwrite our work. Furthermore keeping the core resources in tact allows us to make different modifications to different modules within the same toolset.

It is recommended that the reader should have some experience with scripting or coding in order to carry out the operations involved. The more you are relying on just copy pasting these instructions the more likely you are to make mistakes that you won’t know how to fix.

== The backgrounds demo module ==
Any basic module will do for the purposes of this tutorial. If you want to create a test module for this tutorial then just create a simple module with a single area and a starting location. Make sure that the only thing selected in the module’s hierarchy is ''Core game resources''. This will ensure that the module is a stand alone module rather than an add-in to the single player campaign or some other module. For the purposes of this tutorial we will assume the module is called ''Backgrounds demo'' and I will prefix my resources with ''bdm_'' to be sure that they are distinct from any that are already in existence.

We are going to completely replace the existing backgrounds with 3 new ones of our own. You can use new backgrounds in your module however you see fit. You could create entire origin stories for each one like in the single player campaign (possibly a major undertaking depending on length) or you can just use them to influence dialogue and plot options in the main part of your game.

For our demo we are creating a module in which the player starts off in a small human village (we will not be creating the details of this module so this is just for the purpose of an example). There is a wizard in this village who plays a pivotal role in the story. We allow the player to start as the wizard’s apprentice (if they are a mage) or as his servant (if they are human or elven and not a mage) or as a wandering traveller who has come to visit the wizard (if they are not human and not a mage). So the three backgrounds will be:

* Servant
* Apprentice
* Traveller

== Creating the background strings ==
Before we start modifying the 2DA files we are going to create some strings. Open the string editor in the toolset and create the following strings in your ‘Backgrounds demo’ talk table:

[[Image:Back_tut_talk_table.png]]

Your string IDs might be different to these so be sure to reference the right string ID in the instructions that follow. Simply replace these string Ids with your own.

'''IMPORTANT!''' ''There is currently a bug in the game that causes it to crash if a background description ID has a value greater than 109 912 680. There is a [http://social.bioware.com/project/4695/ community fix] for this. Alternatively, you can go into your module’s properties and change the start ID for strings to be less than the critical value. After that the string editor will generate IDs in a range that won’t crash. Reset the start ID to its original value after you create the background descriptions (that way you have less to alter once Bioware fix this, and less risk of incompatibility with other mods).''

You may have noticed that we have given two different names and descriptions for the traveller background depending on the PC’s race. We will say more about that in the following section.

{{TutorialRef|String editor}}

== Modifying the 2DAs ==
The next thing we need to do is to modify the worksheets in backgrounds.xls. Be sure to make a copy of the spreadsheet first so that you leave the original intact. See LINK for general information about editing 2DA files. The first worksheet is called ‘backgrounds’; modify it to look like the following:

[[Image:back_tut_backgrounds.png]]

Note that since 2DAs combine together to form M2DAs, and we don’t want the existing backgrounds in our game, we have overwritten the last two slots as unused1 and unused2, even though we won’t be using them. The name and desc string refs on this tab will be overwritten by the race specific ones on the names tab so we can leave those blank (AFAIK these string refs are not used providing the ones on the names tab are provided - also the tooltip string ref seems not to be used anywhere – if you prefer you can set these to something just to be safe).

The three race columns determine which backgrounds can be selected by which race and the 3 class columns determine which background can be selected by which class. So, as you can see from the picture our Servant background is accessible to elf or human warriors and rogues, the Apprentice background can be selected by elf or human mages and the Traveller background by elf or dwarf warriors and rogues.

The last three tabs indicate a starting ability for each background by race. Note that by default these columns are not hooked up into the character generation script (instead they are hard coded in the script) and are not used, but we will correct that later on when we do the scripting. You have to be careful here because the columns relate to the race IDs, so 1=dwarf, 2=elf and 3=human, which is in a different order to the other race columns in this table. The number in the column is an ability ID as given in ABI_base.xls. For this demo we have just given the same skill for each race for a given background. Servants get combat tactics, Apprentices get persuade and Travellers get survival.

The next tab table to modify is background_names.

[[Image:back_tut_bg_names.png]]

Make sure that the IDs here match the IDs in your string table. Note that for Apprentices and Servants we use the same strings regardless of race, but for the Traveller background we use different strings. This is to illustrate how you can divide a single background up into multiple names and descriptions. Internally they are both stored as the same background ID but during character generation a different name, description and icon can be shown to the player. In the single player game this was done with the Noble background by splitting it into human and dwarf Noble variations.

NOTE – you must be careful when splitting a single background into different parts for each race. You must make both the names and descriptions different! If you don’t make the descriptions different then the engine will not recognise them as different even if they have different names.

Now modify the background_desc table as follows

[[Image:back_tut_bg_desc.png]]

Again note the distinct descriptions for the Traveller background.

Now for the background_icons table. For this demo we will just use some of the existing icons but you may want to create your own icons to add here.

[[Image:back_tut_bg_icons.png]]

The background_defaults table must have an entry for each race, background and class combination that is allowed. The ID column must be calculated as follows:

(1000 * raceID) + (100 * classID) + backgroundID

[[Image:back_tute_bg_defaults.png]]

The label column should give a description of the row (AFAIK this is not used anywhere).
For this simple demo we will have each background combination spawn in the same place (the module default start location) but if you wanted different origins to spawn in different places then you can use the next two columns to specify this (AFAIK you have to write your own scripts to accomplish this though).

In the template column you can put the name of a creature resource that you want to use as a template for this race/background/class combination. In the picture you can see that we have just used some default templates that shipped with the toolset but you can easily create your own. Note that only the inventory is copied across to the PC so if you want to create your own templates you do not need to alter anything on the creature except for their inventory.

The name columns take string Ids. If you want to add your own names then you’ll have to create new strings in the string editor.

Finally we have the ability column. As with the skill columns in the backgrounds table these IDs correspond to entries in the ABI_base.xls file. It should be noted that race, class and background are all possible sources of starting abilities so before you decide what to put in this column you should familiarise yourself with what skills are already being added in different parts of character generation in order to ensure that you don’t duplicate an ability somewhere.

The final table is the chargen_preload table. The two columns here should exactly match the entries from the ID and Template columns of the previous table.

[[Image:back_tut_chargen_preload.png]]

{{TutorialRef|2DA|2DA#Excel file formatting|Background.xls}}

== Compiling and fixing the GDAs ==
Now compile backgrounds.xls and place the resulting GDAs into your ''AddIns\module_name\module\override'' directory.
Never place anything in your ''AddIns\module_name\core\override'' directory or it will affect other modules than the one you are editing.

There used to be a [[Bug: ExcelProcessor doesn't handle row IDs above 8.3 million correctly|bug]] that prevented large string IDs from compiling correctly. This is now fixed. For the record, the old workaround was to edit the GDA files in the toolset to correct the string IDs manually, but you should now see that the string IDs are correct.

{{TutorialRef|Compiling 2DAs|GDA}}

== Creating the backgrounds plot ==
The background plot is used for keeping track of a PC’s background and can be used to affect conversation options.

The single player game uses a plot called gen00pt_backgrounds to keep track of the PC background. You can find it in the ''\_Global\Generic'' folder of the plots tab if you want to take a look. We will create a similar plot for our custom backgrounds. Create a new plot and call it ''bdm_000pt_backgrounds'' (My naming convention is to use 000 to indicate a resource that isn’t tied to any particular area – feel free to use your own convention but remember to update any references later in the tutorial). Add main plot flags as indicated in the picture below:

[[Image:Back_tut_bg_plot.png]]

You could also add some defined flags if you wanted. Defined flags can be used to return some combination of the main flags such as TRAVELLER or add some extra condition like FEMALE_APPRENTICE or ELVEN_APPRENTICE. Defined flags are beyond the scope of this tutorial however.

{{TutorialRef|Designer Resources|Plot}}

== Creating the scripts ==
We are not going to edit any of the original core game scripts, we will only be adding new scripts of our own. As we discuss how to do this you should examine the core scripts that are referred to, but under no circumstances should you make any changes to those files. By leaving the core scripts as they are we make our modification more compatible with any future patches that may be released. If you modified the core scripts and then a patch was released that overwrote those scripts you would lose your changes. Also keeping your modification contained within your own module allows you to make different modifications to different modules within the one toolset.

Lets start off with a script to handle the character generation events that are normally handled by the module_core script. Create a new script called ''bdm_module_core''. It is up to you what directory structure to use for your scripts but it can be a good idea to keep all your scripts in a directory with your module name to make them distinct from the core scripts. Then if you are emulating the functionality of a particular core script you can mirror the original directory structure underneath your main module folder. So in this case the module_core script is contained in the ''\_Core Scripts'' folder so we will put our bdm_module_core in ''\Backgrounds demo\_Core Scripts'' (the underscore ensures the core directories come first – looks like Bioware accidentally created one without it! I’m pretty sure Core and _Core are meant to be the same directory). Organising things this way will really help with keeping track of your scripts.

The ''bdm_module_core'' script should contain the following code:

<dascript>
#include "global_objects_h"
void main(){
event ev = GetCurrentEvent();
int nEvent = GetEventType(ev); //extract event type from current event
int nEventHandled = FALSE; //keep track of whether the event has been handled
switch(nEvent){
case EVENT_TYPE_MODULE_START:{
// -----------------------------------------------------------------
// Initiate character generation.
// -----------------------------------------------------------------
PreloadCharGen(); //preloads resources for character generation
StartCharGen(GetHero(),0,TRUE); //initiates character generation
break;
}
default:
{
// -----------------------------------------------------------------
// Handle character generation events sent by the engine.
// -----------------------------------------------------------------
if ((nEvent >= EVENT_TYPE_CHARGEN_START && nEvent <= EVENT_TYPE_CHARGEN_END)
|| nEvent == EVENT_TYPE_PLAYERLEVELUP )
{
HandleEvent(ev, R"bdm_sys_chargen.ncs");
nEventHandled = TRUE;
}
break;
}

}
if (!nEventHandled) { //If this event wasn't handled by this script, let the core script try
HandleEvent(ev, RESOURCE_SCRIPT_MODULE_CORE);
}
}
</dascript>

Now go to ''file > manage modules'' and open the properties for your module and set the script property to point at this script.

Our new script handles some of the events that are usually handled by the module_core script. Once it has handled the event it chooses whether or not to pass the event on to module_core. The first event that we handle is EVENT_TYPE_MODULE_START, which is where we initiate character generation. In this case we pass the event on to the core script to handle after we have done what we need to.

NOTE : you may find that you don't need to change any other scripts. It's not clear what the scripts in the rest of this section are trying to do - see discussion.

The second thing we handle is actually a group of events. If you look in the module_core script you will see that right down the bottom in the default event handler is some code that looks just like the code we have added in our default event, with a couple of little differences. Instead of passing the character generation events to the sys_chargen.ncs script we are going to pass it to our own script called ''bdm_sys_chargen.ncs'' which we will write shortly. If we catch one of those character generation events then we want to handle it ourselves and prevent the core script from handling it so we set nEventHandled = TRUE. Note that any other event that is caught by the default handler but isn’t a character generation event is going to go straight on through to the core script.

Before we create the ''bdm_sys_chargen'' script we are going to need some new constants defined. Create a new script called ''bdm_2da_constants_h'' and put it in folder ''\Backgrounds demo\_Core Includes''. Now add the following to this script:

<dascript>
// -----------------------------------------------------------------------------
// Backgrounds - rules/backgrounds.xls
// -----------------------------------------------------------------------------
const int BACKGROUND_SERVANT = 1;
const int BACKGROUND_APPRENTICE = 2;
const int BACKGROUND_TRAVELLER = 3;
</dascript>

These constants provide a way for us to refer to the background IDs that we defined in the 2DA files without having to remember the numbers. Constants like this also make your code more readable. If you need to add more new items to 2DAs when you are modding something else you can also add constants for them here. From now on we will be using these background constants instead of the original single player background constants that you can find in the ''2da_constants_h'' script. That means we’d better find all the places where those constants are used and update them with our own scripts.

Create another new script and call it ''bdm_sys_chargen'' and put it in a folder called ''\Backgrounds demo\_Systems''. Put the following code in it:

<dascript>
#include "bdm_sys_chargen_h"
#include "log_h"

const int CHARGEN_QUICKSTART_QUICK = 0;
const int CHARGEN_QUICKSTART_NORMAL = 1;
const int CHARGEN_QUICKSTART_ADVANCED = 2;

void _RunChargen(int nRace, int nClass, object oChar, int nBackground)
{

Chargen_InitializeCharacter(oChar);
Chargen_SelectGender(oChar,GENDER_MALE);
Chargen_SelectRace(oChar,nRace);
Chargen_SelectCoreClass(oChar,nClass);
Chargen_SelectBackground(oChar, nBackground,FALSE);

int nEquipIdx = Chargen_GetEquipIndex(nRace, nClass, nBackground);
Chargen_InitInventory(oChar,0,nEquipIdx);
Chargen_SpendAttributePoints(oChar,PROPERTY_ATTRIBUTE_STRENGTH, 3,FALSE);
Chargen_SpendAttributePoints(oChar,PROPERTY_ATTRIBUTE_DEXTERITY, 2,FALSE);

}

void main(){
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);
object oChar = GetEventObject(ev,0);

int nMode;
int nInt0 = GetEventInteger(ev,0);
int nInt1 = GetEventInteger(ev,1);
// -------------------------------------------------------------------------
// Debug Data.
// -------------------------------------------------------------------------
Log_Trace(LOG_CHANNEL_EVENTS_CHARGEN,"bdm_sys_chargen","Chargen Event:" + Log_GetEventNameById (nEventType)
+ " " + ToString(nInt0) + "," + ToString(nInt1), oChar);

int nEventHandled = FALSE;

switch (nEventType)
{
// ----------------------------------------------------------------------
// This fires when the player selects the icon corresponding to any of
// the available backgrounds
//
// nInt0 - Constant BACKGROUND_* integer
// ----------------------------------------------------------------------
case EVENT_TYPE_CHARGEN_SELECT_BACKGROUND: {
int nBackground = nInt0;
// -----------------------------------------------------------------
// Set the background on the player and reinitialize plot flags
// for the background
// -----------------------------------------------------------------
Chargen_InitializeCharacter(oChar,TRUE);
Chargen_SelectGender(oChar,GetCreatureGender(oChar));
Chargen_SelectRace(oChar,GetCreatureRacialType(oChar));
Chargen_SelectCoreClass(oChar,GetCreatureCoreClass(oChar));

bdm_Chargen_SelectBackground(oChar, nBackground, FALSE);
bdm_Chargen_SetupPlotFlags(oChar);

// -----------------------------------------------------------------
// Generate the index into the equipment template 2da and
// then load the starting equipment based on the data returned.
// -----------------------------------------------------------------
int nClass = GetCreatureCoreClass(oChar);
int nRace = GetCreatureRacialType(oChar);
int nEquipIdx = Chargen_GetEquipIndex(nRace, nClass, nBackground);
Chargen_InitInventory(oChar,0,nEquipIdx);
nEventHandled = TRUE;
break;
}
case EVENT_TYPE_CHARGEN_END: {
nMode = nInt0;
int nQuickStart = nInt1;
// 0 - quickstart
// 1 - normal \
// 2 - advanced / treat as the same
Log_Trace(LOG_CHANNEL_CHARACTER,"bdm_sys_chargen","MODE: " + IntToString(nMode)
+ ", Quick Start: " + IntToString(nQuickStart));
if (nMode == CHARGEN_MODE_CREATE && nQuickStart == CHARGEN_QUICKSTART_QUICK){
Log_Trace(LOG_CHANNEL_CHARACTER,"bdm_sys_chargen","Setting default values for player character");

int nRandClass = abs((GetLowResTimer()%3)+1);

if(nRandClass == CLASS_ROGUE || nRandClass == CLASS_WARRIOR)
{
_RunChargen(RACE_HUMAN, nRandClass, oChar, BACKGROUND_SERVANT );

WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_SERVANT, TRUE);
}
else // mage
{
_RunChargen(RACE_HUMAN, nRandClass, oChar, BACKGROUND_APPRENTICE );
WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_APPRENTICE, TRUE);
}
Chargen_SetNumTactics(oChar);
SetCanLevelUp(oChar,Chargen_HasPointsToSpend(oChar));
SendEventModuleChargenDone("", "");
nEventHandled = TRUE;
}
break;
}
} //end switch

if (!nEventHandled){
HandleEvent(ev, R"sys_chargen.ncs");
}

}
</dascript>

There are two events in the original sys_chargen script that we need to replace because they deal with backgrounds. The first of these is EVENT_TYPE_CHARGEN_SELECT_BACKGROUND and the other is EVENT_TYPE_CHARGEN_END. For the second event we only need to change the case where the character is being created in quickstart mode, so we just handle that section of the code. The objective here is to change only as much as we need to and then pass any remaining events through to the original sys_chargen script. Take some time to compare the new script with Bioware’s ''sys_chargen'' script .

You will notice that we include a script called ''bdm_sys_chargen_h'' and that we use some functions with a ''bdm_'' prefix. Those functions are contained in that include file which we’ll write now. Essentially these are modifications of a couple of functions from the ''sys_chargen_h'' include file. Create a new script and call it ''bdm_sys_chargen_h''. Put it in folder ''\Backgrounds demo\_Systems\Includes'' and add the following code:

<dascript>
#include "sys_chargen_h"
#include "bdm_2da_constants_h"
#include "wrappers_h"
#include "plt_bdm_000pt_backgrounds"

void bdm_Chargen_SelectBackground(object oChar, int nBackground, int bUnApply = FALSE)
{
Log_Chargen("bdm_Chargen_SelectBackground","-- " + (bUnApply?"Un":"") +"Selecting BG: " + ToString(nBackground),oChar);
// -------------------------------------------------------------------------
// 1. Set the background variable
// - Create creature property (or check what we used so far
// - We don't set backgrounds on non player generated chars.
// -------------------------------------------------------------------------
if (bUnApply)
{
SetCreatureProperty(oChar, PROPERTY_SIMPLE_BACKGROUND, 0.0, PROPERTY_VALUE_BASE);
}
else
{
SetCreatureProperty(oChar, PROPERTY_SIMPLE_BACKGROUND, IntToFloat(nBackground), PROPERTY_VALUE_BASE);
}
// -------------------------------------------------------------------------
// 2. Give one skill
// - retrieve the skill that is granted by the background from backgrounds.xls
// - give it to the player.
// -------------------------------------------------------------------------
int nAbility = ChargenGetBackgroundSkill(GetCreatureRacialType(oChar), nBackground);
if (nAbility)
{
_AddAbility (oChar, nAbility, bUnApply);
}
}

void bdm_Chargen_SetupPlotFlags(object oChar)
{
int nRace = GetCreatureRacialType(oChar);
int nBackground = GetPlayerBackground(oChar);

Log_Trace(LOG_CHANNEL_CHARACTER,"bdm_sys_chargen_h","Setting plot flags, race: "
+ IntToString(nRace) + ", background: " + IntToString(nBackground));

// First, init all flags (debug setup)
WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_SERVANT,FALSE);
WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_APPRENTICE,FALSE);
WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_DWARF_TRAVELLER,FALSE);
WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_ELF_TRAVELLER,FALSE);

switch (nBackground)
{
case BACKGROUND_SERVANT:
{
WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_SERVANT,TRUE); break;
break;
}
case BACKGROUND_APPRENTICE:
{
WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_APPRENTICE,TRUE); break;
break;
}
case BACKGROUND_TRAVELLER:
{
switch(nRace)
{
case RACE_DWARF: WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_DWARF_TRAVELLER,TRUE); break;
case RACE_ELF: WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_ELF_TRAVELLER,TRUE); break;
}
break;
}
}
}
</dascript>

Lets examine these two functions. First you should compare them to their original versions. For ''bdm_Chargen_SelectBackground()'' we have actually made a more generic version of the function that should work with any backgrounds. We have removed the hard coded values for the background abilities and now use the function ChargenGetBackgroundSkill() which actually gets the background skill from the backgrounds 2DA file that we edited earlier (recall the last three columns that give a skill depending on background and race). If you need fancier logic than just reading the values form the GDA (e.g. like Bioware’s logic for the Noble background) then you can always go back to hard coding them the way Bioware did.

The second function is ''bdm_Chargen_SetupPlotFlags()'' which does just what it says. Remember the plot we created earlier? Here we set the appropriate flag based on race and background.

{{TutorialRef|Script}}

== Testing that everything works ==
Now compile your scripts and export your module. Also, make sure that you export your talk table.

'''IMPORTANT!''' ''Always make sure you empty your \Dragon Age\packages\core\override folder after doing an export. Due to a bug in the current toolset your single player game will become damaged if you don’t do this before playing.''

You should now be able to run your game and see the backgrounds you created appear in character generation. If you want to test that the background plots have been set correctly, add an NPC to the start area and create a conversation for them in which each line is switched according to a background plot flag. You can also check that the character is receiving the abilities that we set in the 2DAs.

'''NOTE''' ''There seems to be no way to change the popup message that comes up at the beginning of character generation. Altering the Pre-chargen string ID in the loadhints GDA does not seem to do anything.''

{{TutorialRef|Exporting a module}}

== Optional extras ==
There are a couple of other Bioware scripts that reference the background constants. They are not essential to modify because they are not used anywhere by default. The genev_tutorial script uses a background check but unless you plan on firing the tutorial from your module then you won’t have need of it. Also there is at least one debug script that makes use of the original single player backgrounds (to grant a background plot flag to the PC) so if you want similar debug functionality you may have to roll your own function.

== Race & Gender descriptions ==
If your module is not set in Ferelden, you may wish to change the descriptions of the Race and Gender buttons that appear during Character Creation.

The Race descriptions are in the Description column of the RACE_base 2DA, so you can replace them with new strings. As before, until the bug is fixed, use a string id in the 100000000 range.

Unfortunately, the gender description is hard-coded in the game as string id 377283. Fortunately, you can make a [[String_editor#Editing_a_string_with_a_specific_id | local version]] of this string, which only applies to your campaign.

Alternatively, if you an advanced user who is familar with the [[UI_Tutorial_%28draft%29 | UI Tutorial]], it's set in the GUI's Localization.as file as LOC_GENDER_DESCRIPTION = 377283, which is then used in the RaceGenderScene.as file. after editing the Localization.as file, you compile it and inject it into the appropriate .gfx'es.

== Conclusion ==
In this tutorial we have demonstrated a way to modify the backgrounds used in the game without altering any of the core scripts. It is expected that a similar approach could be taken to modding other aspects of the game such as adding classes or races. In these cases the scripts that were created in this tutorial could be extended to handle other parts of the character generation process such as class and race selection.

[[Category:Character generation]]
[[Category:Tutorials]]

SetMaxHealth

2011-05-11T07:24:16Z

Proleric1: /* Description */

{{dafunction
|name=SetMaxHealth
|brief=Set object's maximum health
|param1type=object
|param1name=oObject
|param1desc=the object that we are modifying
|param2type=int
|param2name=nHealth
|param2desc=the new maximum health value for the object
|returntype=void
|returndesc=
|sourcefile=script.ldf
|sourcemodule=
}}

== Description ==

Set object's maximum health.

== Remarks ==
This function doesn't seem to work for creatures.

It appears that Chargen_ModifyCreaturePropertyBase with PROPERTY_DEPLETABLE_HEALTH will increase or decrease maximum health by the specified amount. This workaround has not yet been tested exhaustively, but it is based on the Bioware code in sys_autoscale_h.






[[Category: Stats functions]]

Cutscene tutorial

2011-04-20T16:44:46Z

Proleric1: /* Adding dialogue */

{{Infobox cutscenes}}

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

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

== Creating a new cutscene ==

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

[[Image:New resource.png]]

The result is opened in the cutscene editor.

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

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

=== Viewports ===

{{sidebox|
* Viewports can be attached to various cameras to preview what they can see
* Add a "Safe Frame" to camera viewports to ensure the correct aspect ratio
* Set a viewport to "User" to see where cameras are positioned from another perspective. This can be done by selecting "Detach From Camera" in the viewport's right-click menu in the title bar
}}

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

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

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

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

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

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

=== Timeline ===

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

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

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

[[Image:Cutscene tutorial timeline.png]]

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

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

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

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

== The setting of the cutscene ==

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

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

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

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

=== Adding objects and creatures ===

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

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

[[Image:Cutscene activate object.png]]

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

[[Image:Cutscene object activated.png]]

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

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

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

=== Adding the player ===

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

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

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

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

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

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

=== Adding cameras ===

{{sidebox|
* Remember to enable Safe Frame when attaching a viewport to a camera.
* Use an "Active Camera" viewport to preview the cutscene.
* Use a "User" viewport to see camera positions from the outside. This can be done by selecting "Detach From Camera" in the viewport's right-click menu in the title bar.
}}

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

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

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

[[Image:Cutscene insert camera.png]]

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

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

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

== Adding an animation to an actor ==

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

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

[[Image:Cutscene set pose.png]]

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

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

[[Image:Cutscene add track.png]]

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

[[Image:Cutscene add action.png]]

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

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

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

Note that only a single animation can play at any time on a given track. However, it is possible to have multiple animations for a character, each of which must be on a different track. This is essential in order to be able to blend animations together as detailed in [[Play_animation#Blending_Animations]]. Animation blending is necessary in order to have your characters transition seamlessly from one animation to another, which is essential to making character movement look natural.

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

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

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

== Moving an actor ==

=== Position and orientation keys ===

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

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

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

[[Image:Cutscene key selection.png]]

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

[[Image:Cutscene key marker.png]]

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

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

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

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

=== Using GAD ===

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

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

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

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

[[Image:Cutscene gad warning.png]]

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

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

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

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

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

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

== Moving a camera ==

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

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

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

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

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

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

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

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

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

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

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

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

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

== Switching cameras ==

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

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

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

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

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

== Adding dialogue ==

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

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

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

Here we are going to add dialogue to a cutscene (though sometimes it is better to take a [[Conversation#Conversation-centred_approach | conversation-centred approach]]).

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

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

[[Image:Cutscene conversation.png]]

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

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

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

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

== Adding other details ==

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

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

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

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

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

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

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

The finished timeline of our cutscene:

[[Image:Cutscene finished timeline.png]]

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

=== Cutscene Tips and Tricks ===

Here are a few tips and tricks that might save the cutscene creator some time and perhaps hair pulling.

- Head tracking is often used to look at another actor or a visible item in the cutscene. However you can further manipulate the head of the actor by having the actor look at invisible objects. You can have the actor look from one invisible object to another or move the invisible object around in the cutscene to get the actor to look at things independent of visible actors or items.

- You may find it useful to give meaningful names to your cameras if you are using more than one or two. (You might name a camera after the actor or placeable that it follows or name one camera ‘close-up’ and another ‘wide-angle’ for example.)

- If you are panning a camera around a room following a series of actors or placeables and you find that the camera suddenly decides to rotate in the other direction you can force it to stay moving in the direction you desire by adding or subtracting 360 degrees from the position/orientation you are using to move the camera.

- Feel free to experiment with animations. Try using animations that are not normally meant for your actor type, you might find some interesting or bizarre movements for your actor.

- You can put multiple actions along one track as long as they do not overlap rather than using many different tracks.

- Pay attention to what your key frames ‘transition out’ are set to when moving your cameras. Step will jump the camera from position to position while Bezier and Linear will move the camera in a smoother motion. If you are not getting the desired effect when moving cameras check what your key frames ‘transition out’ are set to.

- If you have a longer more detailed cutscene you can keep the number of cameras you use to a reasonable number by just moving one (or more) around while another camera is the ‘active’ camera.

- For testing purposes change the length of the cutscene in the cutscenes properties to a smaller value and enlarge that number as you add on to the cutscene. In this way you won’t need to wait for a long period of time for the cutscene to end.

- After placing an animation on a track you can speed up the animation by left clicking on the small circular arrows on one end and dragging it shorter or make the animation play slower by dragging the animation longer on the track.

- You can make the content of your scene seem to change by placing invisible objects in the cutsence, using an fx to obscure the view and making the object visible while the fx is playing. (For example you might have some invisible rock debris. Use a cave in fx with clouds of dust to obscure the screen. While the fx is playing make the debris visible. When the fx is finished your debris will be in place.)

- If you find that your actor is walking across surfaces (such as water for instance) when they should be following the ground you can set ‘items follow surface’ in the area that your cutscene is based on. The actor should then walk on the ground and thus wade into the water. Conversely if you want a character or placeable to not follow the surface of the ground (for instance if you want a placeable or actor to be near or on the surface of water) move the actor or placeable higher by adjusting the Z axis of the boat or actor. (An example of using a placeable partly submerged in water might be something like a boat.)

- In a cutscene you can only activate things that are unique. As in if you plopped down three identical chests in an area, when trying to activate them all in a cutscene it will not allow this and gives you a warning message. In the example above you would have to make three different chests (though they could look the same) to be able to activate them all in the cutscene.
{{Languages}}

Cutscene tutorial

2011-04-20T16:43:45Z

Proleric1: /* Adding dialogue */

{{Infobox cutscenes}}

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

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

== Creating a new cutscene ==

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

[[Image:New resource.png]]

The result is opened in the cutscene editor.

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

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

=== Viewports ===

{{sidebox|
* Viewports can be attached to various cameras to preview what they can see
* Add a "Safe Frame" to camera viewports to ensure the correct aspect ratio
* Set a viewport to "User" to see where cameras are positioned from another perspective. This can be done by selecting "Detach From Camera" in the viewport's right-click menu in the title bar
}}

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

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

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

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

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

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

=== Timeline ===

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

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

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

[[Image:Cutscene tutorial timeline.png]]

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

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

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

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

== The setting of the cutscene ==

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

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

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

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

=== Adding objects and creatures ===

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

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

[[Image:Cutscene activate object.png]]

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

[[Image:Cutscene object activated.png]]

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

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

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

=== Adding the player ===

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

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

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

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

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

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

=== Adding cameras ===

{{sidebox|
* Remember to enable Safe Frame when attaching a viewport to a camera.
* Use an "Active Camera" viewport to preview the cutscene.
* Use a "User" viewport to see camera positions from the outside. This can be done by selecting "Detach From Camera" in the viewport's right-click menu in the title bar.
}}

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

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

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

[[Image:Cutscene insert camera.png]]

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

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

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

== Adding an animation to an actor ==

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

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

[[Image:Cutscene set pose.png]]

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

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

[[Image:Cutscene add track.png]]

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

[[Image:Cutscene add action.png]]

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

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

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

Note that only a single animation can play at any time on a given track. However, it is possible to have multiple animations for a character, each of which must be on a different track. This is essential in order to be able to blend animations together as detailed in [[Play_animation#Blending_Animations]]. Animation blending is necessary in order to have your characters transition seamlessly from one animation to another, which is essential to making character movement look natural.

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

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

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

== Moving an actor ==

=== Position and orientation keys ===

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

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

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

[[Image:Cutscene key selection.png]]

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

[[Image:Cutscene key marker.png]]

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

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

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

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

=== Using GAD ===

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

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

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

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

[[Image:Cutscene gad warning.png]]

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

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

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

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

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

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

== Moving a camera ==

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

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

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

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

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

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

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

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

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

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

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

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

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

== Switching cameras ==

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

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

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

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

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

== Adding dialogue ==

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

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

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

Here we are going to add dialogue to a cutscene (though sometimes it is better to take a [[http://social.bioware.com/wiki/datoolset/index.php/Conversation#Conversation-centred_approach conversation-centred approach]]).

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

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

[[Image:Cutscene conversation.png]]

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

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

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

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

== Adding other details ==

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

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

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

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

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

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

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

The finished timeline of our cutscene:

[[Image:Cutscene finished timeline.png]]

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

=== Cutscene Tips and Tricks ===

Here are a few tips and tricks that might save the cutscene creator some time and perhaps hair pulling.

- Head tracking is often used to look at another actor or a visible item in the cutscene. However you can further manipulate the head of the actor by having the actor look at invisible objects. You can have the actor look from one invisible object to another or move the invisible object around in the cutscene to get the actor to look at things independent of visible actors or items.

- You may find it useful to give meaningful names to your cameras if you are using more than one or two. (You might name a camera after the actor or placeable that it follows or name one camera ‘close-up’ and another ‘wide-angle’ for example.)

- If you are panning a camera around a room following a series of actors or placeables and you find that the camera suddenly decides to rotate in the other direction you can force it to stay moving in the direction you desire by adding or subtracting 360 degrees from the position/orientation you are using to move the camera.

- Feel free to experiment with animations. Try using animations that are not normally meant for your actor type, you might find some interesting or bizarre movements for your actor.

- You can put multiple actions along one track as long as they do not overlap rather than using many different tracks.

- Pay attention to what your key frames ‘transition out’ are set to when moving your cameras. Step will jump the camera from position to position while Bezier and Linear will move the camera in a smoother motion. If you are not getting the desired effect when moving cameras check what your key frames ‘transition out’ are set to.

- If you have a longer more detailed cutscene you can keep the number of cameras you use to a reasonable number by just moving one (or more) around while another camera is the ‘active’ camera.

- For testing purposes change the length of the cutscene in the cutscenes properties to a smaller value and enlarge that number as you add on to the cutscene. In this way you won’t need to wait for a long period of time for the cutscene to end.

- After placing an animation on a track you can speed up the animation by left clicking on the small circular arrows on one end and dragging it shorter or make the animation play slower by dragging the animation longer on the track.

- You can make the content of your scene seem to change by placing invisible objects in the cutsence, using an fx to obscure the view and making the object visible while the fx is playing. (For example you might have some invisible rock debris. Use a cave in fx with clouds of dust to obscure the screen. While the fx is playing make the debris visible. When the fx is finished your debris will be in place.)

- If you find that your actor is walking across surfaces (such as water for instance) when they should be following the ground you can set ‘items follow surface’ in the area that your cutscene is based on. The actor should then walk on the ground and thus wade into the water. Conversely if you want a character or placeable to not follow the surface of the ground (for instance if you want a placeable or actor to be near or on the surface of water) move the actor or placeable higher by adjusting the Z axis of the boat or actor. (An example of using a placeable partly submerged in water might be something like a boat.)

- In a cutscene you can only activate things that are unique. As in if you plopped down three identical chests in an area, when trying to activate them all in a cutscene it will not allow this and gives you a warning message. In the example above you would have to make three different chests (though they could look the same) to be able to activate them all in the cutscene.
{{Languages}}

Cutscene tutorial

2011-04-20T16:43:16Z

Proleric1: /* Adding dialogue */

{{Infobox cutscenes}}

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

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

== Creating a new cutscene ==

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

[[Image:New resource.png]]

The result is opened in the cutscene editor.

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

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

=== Viewports ===

{{sidebox|
* Viewports can be attached to various cameras to preview what they can see
* Add a "Safe Frame" to camera viewports to ensure the correct aspect ratio
* Set a viewport to "User" to see where cameras are positioned from another perspective. This can be done by selecting "Detach From Camera" in the viewport's right-click menu in the title bar
}}

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

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

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

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

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

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

=== Timeline ===

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

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

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

[[Image:Cutscene tutorial timeline.png]]

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

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

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

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

== The setting of the cutscene ==

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

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

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

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

=== Adding objects and creatures ===

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

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

[[Image:Cutscene activate object.png]]

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

[[Image:Cutscene object activated.png]]

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

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

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

=== Adding the player ===

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

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

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

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

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

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

=== Adding cameras ===

{{sidebox|
* Remember to enable Safe Frame when attaching a viewport to a camera.
* Use an "Active Camera" viewport to preview the cutscene.
* Use a "User" viewport to see camera positions from the outside. This can be done by selecting "Detach From Camera" in the viewport's right-click menu in the title bar.
}}

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

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

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

[[Image:Cutscene insert camera.png]]

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

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

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

== Adding an animation to an actor ==

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

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

[[Image:Cutscene set pose.png]]

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

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

[[Image:Cutscene add track.png]]

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

[[Image:Cutscene add action.png]]

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

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

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

Note that only a single animation can play at any time on a given track. However, it is possible to have multiple animations for a character, each of which must be on a different track. This is essential in order to be able to blend animations together as detailed in [[Play_animation#Blending_Animations]]. Animation blending is necessary in order to have your characters transition seamlessly from one animation to another, which is essential to making character movement look natural.

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

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

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

== Moving an actor ==

=== Position and orientation keys ===

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

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

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

[[Image:Cutscene key selection.png]]

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

[[Image:Cutscene key marker.png]]

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

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

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

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

=== Using GAD ===

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

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

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

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

[[Image:Cutscene gad warning.png]]

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

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

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

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

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

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

== Moving a camera ==

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

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

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

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

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

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

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

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

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

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

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

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

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

== Switching cameras ==

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

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

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

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

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

== Adding dialogue ==

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

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

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

Here we are going to add dialogue to a cutscene (though sometimes it is better to take a [[http://social.bioware.com/wiki/datoolset/index.php/Conversation#Conversation-centred_approach | conversation-centred approach]]).

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

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

[[Image:Cutscene conversation.png]]

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

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

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

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

== Adding other details ==

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

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

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

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

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

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

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

The finished timeline of our cutscene:

[[Image:Cutscene finished timeline.png]]

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

=== Cutscene Tips and Tricks ===

Here are a few tips and tricks that might save the cutscene creator some time and perhaps hair pulling.

- Head tracking is often used to look at another actor or a visible item in the cutscene. However you can further manipulate the head of the actor by having the actor look at invisible objects. You can have the actor look from one invisible object to another or move the invisible object around in the cutscene to get the actor to look at things independent of visible actors or items.

- You may find it useful to give meaningful names to your cameras if you are using more than one or two. (You might name a camera after the actor or placeable that it follows or name one camera ‘close-up’ and another ‘wide-angle’ for example.)

- If you are panning a camera around a room following a series of actors or placeables and you find that the camera suddenly decides to rotate in the other direction you can force it to stay moving in the direction you desire by adding or subtracting 360 degrees from the position/orientation you are using to move the camera.

- Feel free to experiment with animations. Try using animations that are not normally meant for your actor type, you might find some interesting or bizarre movements for your actor.

- You can put multiple actions along one track as long as they do not overlap rather than using many different tracks.

- Pay attention to what your key frames ‘transition out’ are set to when moving your cameras. Step will jump the camera from position to position while Bezier and Linear will move the camera in a smoother motion. If you are not getting the desired effect when moving cameras check what your key frames ‘transition out’ are set to.

- If you have a longer more detailed cutscene you can keep the number of cameras you use to a reasonable number by just moving one (or more) around while another camera is the ‘active’ camera.

- For testing purposes change the length of the cutscene in the cutscenes properties to a smaller value and enlarge that number as you add on to the cutscene. In this way you won’t need to wait for a long period of time for the cutscene to end.

- After placing an animation on a track you can speed up the animation by left clicking on the small circular arrows on one end and dragging it shorter or make the animation play slower by dragging the animation longer on the track.

- You can make the content of your scene seem to change by placing invisible objects in the cutsence, using an fx to obscure the view and making the object visible while the fx is playing. (For example you might have some invisible rock debris. Use a cave in fx with clouds of dust to obscure the screen. While the fx is playing make the debris visible. When the fx is finished your debris will be in place.)

- If you find that your actor is walking across surfaces (such as water for instance) when they should be following the ground you can set ‘items follow surface’ in the area that your cutscene is based on. The actor should then walk on the ground and thus wade into the water. Conversely if you want a character or placeable to not follow the surface of the ground (for instance if you want a placeable or actor to be near or on the surface of water) move the actor or placeable higher by adjusting the Z axis of the boat or actor. (An example of using a placeable partly submerged in water might be something like a boat.)

- In a cutscene you can only activate things that are unique. As in if you plopped down three identical chests in an area, when trying to activate them all in a cutscene it will not allow this and gives you a warning message. In the example above you would have to make three different chests (though they could look the same) to be able to activate them all in the cutscene.
{{Languages}}

Conversation

2011-04-20T16:26:27Z

Proleric1: /* Cinematics and Animation */

{| style="float:right;"
|-
| {{Resource palette}}
|-
| {{Infobox conversation}}
|}

Conversations contain lines of dialogue, usually focused on one NPC and the player's interaction with him or her. Each line of dialogue can have the following associated with it:
*The text of the line, which can be displayed in-game
*The [[Voice-Over]] (for non-player characters)
*The speaker's facial performance (lip synching and expression)
*[[Stage]] information for positioning the actors and cameras in an area (optional, some conversations can occur anywhere and use default staging)
*[[Cutscene]] cinematics that can potentially override any of the above with more detailed and complex events.

A conversation is usually associated with a [[creature]], which is referred to in the conversation with the "OWNER" tag. They can also be associated with placeables, or simply used as a container for lines of dialogue used in a cutscene.

The main body of the display for this type of object is one or more tree-shaped structures containing all of the lines or actions that can be reached in the course of following this conversation. For example:

[[Image:Conversation tutorial 2.png]]

Red lines are those spoken by NPCs, blue lines are those spoken by the player (usually chosen from a group of alternatives). Grey lines are lines that are 'linked' to other lines, allowing the flow of the conversation to jump to other branches or repeat itself if needed.

Below the main display is a tabbed pane containing options that can be set on a line-by-line basis.

== Global Settings ==

The global settings tab is only present when the root node of the entire conversation is selected. This is where one can set defaults for who is listening and who is talking (in conversations with more than two individuals you'll need to override these defaults on a line-by-line basis as needed).

You can also set a number of flags involved in cinematic effects:
*Lock all gestures
*Lock all poses
*Lock all RoboBrad
*Lock all cameras
*Ambient Soundset Type

Also available in the root node are a simplified plot and scripting tab (see below for details) that allows you to modify plot flags and trigger scripts when the conversation ends; this is helpful for preventing errors and saving time when crafting a conversation that is always supposed to have the same effect on the world when it's over but that has many different conversation end nodes scattered throughout it.

The cinematics tab of the root node allows default cinematics information to be set, which is inherited by the rest of the nodes in the conversation unless overridden.

Finally, the root node has a conversation synopsis text field where a summary of the content and purpose of the conversation can be placed for ease of reference.

== Dialogue ==

[[Image:Conversation dialog.png]]

This tab contains the string of text that is displayed to the player when this node in the tree is reached.

At the lower left corner are some statistics for this line and for the conversation it's a part of.

*Player Response Length Maximum: 60 characters
*NPC Response Length Maximum: 200 characters

There is also a limit of six lines of player responses displayed for any particular line of NPC dialogue. If there are more than six responses available to be shown, only the first six will be visible.

Also in the lower left corner is the string ID for this line of dialog, which is used when recording voice over audio. Don't forget to [[String_editor#Generated string IDs | check the dialogue and creature resources back in]] before exporting your talk tables, or else the conversation history in the player's journal won't be correct.

=== Formatting tags ===

==== Emphasis tags ====

To indicate that a word in spoken text is emphasized, use <emp> tags. In subtitles, text inside the tags will be bolded.

For example: "I don't <emp>think</emp> so." appears in-game as: "I don't '''think''' so."

==== Description tags ====

Description <desc> tags are used in three ways: 1) To set apart a non-spoken sound (NPC lines), 2) To describe action that is not voiced (player lines), 2) To indicate that a persuade line is a lie or charm (player lines), 3) For text that describes an object (object lines).

In subtitles, text inside <desc> tags will be italicized and put into parentheses.

1) Unspoken sounds (such as a sigh, sob, or grunt of pain) - NPC lines only.

Write out the sound, not a description of the sound.
* Incorrect: "No! Please don't kill me! <desc>gurgling sound as she is stabbed</desc>
* Correct: "No! Please don't kill me! <desc>Aaargh!</desc>

"If only... <desc>sigh</desc> Alas, it cannot be." appears in-game as: "If only... ''(sigh)''' Alas, it cannot be."

2) Persuade lines that need to be marked as "lie" or "charm" - player lines only: When a line that has been flagged in the toolset as a "Persuade" line needs to me marked as a specific "lie" or "charm", write Lie or Charm at the line's beginning. Then, use <desc> tags around that word so that it will be set off from the rest of the line.
For example: <desc>Lie</desc> "Of course I didn't report you to the authorities." appears in-game as: "''(Lie)'' Of course I didn't report you to the authorities."

3) Text that describes an object - Object lines only: When a line is created to describe an inanimate object, such as a bookcase or chest, descriptive lines for that object should be marked with <desc> tags. The writer creates a "character" in the toolset ("bhm700_bookcase"), and writes a line to describe that object. For example, <desc>This bookcase is full of dusty, moldering books.</desc> or <desc>The phylactery is warm to the touch and filled with a small amount of viscous, red liquid. You see no way to open it.</desc>

* Correct: <desc>This bookcase is full of dusty, moldering books.</desc>
All such text should be written in third-person, present tense, with the player always referred to as "you".
* Incorrect: <desc> The phylactery is warm to the touch and filled with a small amount of viscous, red liquid. I can't see any way to open it.</desc>
* Correct: <desc>The phylactery is warm to the touch and filled with a small amount of viscous, red liquid. You see no way to open it.</desc>

The tech designer will need to create a placeable in the appropriate area. The character for that placeable should be set as "null". (This indicates that no VO recording is needed for that line.) It should also be set to appear on the screen even if subtitles are turned off by default.

==== Action Tags ====

Action tags <act> describe player action. In subtitles, text inside <act> tags will be italicized and put into parentheses.

For example: "If that's the way you want it. <act>Kill the soldier.</act>" appears in-game as: "If that's the way you want it. ''(Kill the soldier.)''"

* Incorrect: {Owner}: "Here. Take this. <act> Opens chest, removes sword.</act> It was your father's."

=== Macros ===

The <FirstName/> macro will be replaced with the first name entered by the player for his character. Since the player character's name can be anywhere up to 20 characters long, player lines using the <FirstName/> macro can only have 40 characters (not including the macro itself).

Macros are used fairly rarely in Dragon Age since voiceovers accompany most lines and cannot be modified to match lines with variable text.

=== Other settings ===

Also on this tab are some additional flags and tags that can be set for this line.
*Skill/Icon - allows an icon to be placed next to this line indicating that a skill must be used when the line is selected by the player
*Speaker Tag and Listener Tag - defines which character is the speaker and which is the listener (can be set to default)
*Language - defines which language the line is spoken in.
*Fast Path - Any line with "Fast Path" set will be the first option presented to a player when they reach this conversation node. This can be useful if you want to provide an easy way to blow through the conversation tree without having to read it; if you mark the shortest path through the tree with this flag the player will only have to tap the "1" key to pass through it. You can also do this without the fast path flag by arranging your conversation nodes in the correct order, but restructuring an entire conversation tree for this purpose is a more complex task.

== Plots and Scripting ==

See [[conversation plots and scripting]] for details on how to use plots and scripts to make certain lines of dialog "conditional" (appearing or not appearing based on conditions in the game) and how to have certain lines cause scripted actions and change plot flags.

This tab also includes an option to easily set a line so that it appears to a player only once (either once per conversation or once per game).

== Cinematics and Animation ==

See [[conversation cinematics and animation]] for details of how to control the performance of your virtual actors. Conversations without cinematic direction set for them will use a default over-the-shoulder camera style that's serviceable for most conversations, but which might become dull when used for all of them. Adding some animation and varying the camera angles can go a long way to spicing up a conversation, and for special events you can add much more than that - even integrating full-blown cutscenes into the middle of a conversation.

== Cutscenes ==

Even more control over how a conversation appears can be achieved by turning it into a cutscene.

There are two ways of doing this.

=== Cutscene-centred approach ===

See [[Cutscene tutorial]] for a method of building one cutscene from many conversation lines (the entire conversation, perhaps).

This may be useful if the conversation is essentially action-packed and linear.

Because the cutscene is in control, the conversation logic is ignored.

So this approach is less useful when there are player options, conditions and/or actions.

Also, the conversation isn't logged.

It is possible to run a plot script and/or regular conversation at the end of the cutscene (either via the End Script property or [[CS_LoadCutscene]]).

=== Conversation-centred approach ===

If conversation options, conditions, actions or logging are important, it's better to put the conversation in control.

This may also be the easiest option if only one or two lines require the enhanced control afforded by a cutscene.

Once a stage has been specified for the conversation, you can make one cutscene for each NPC line, using the "Convert Line to Cutscene" option on the Edit menu.

By default, the cutscenes are collected in one folder per conversation, for convenience.

In this approach, the conversation works normally, except that the cutscenes provide enhanced cinematics for the lines in question.

== Fade In and Out ==

A conversation can fade in or out by converting the line to a cutscene.

It's not necessary to master the full complexity of the cutscene editor to do this.

Right-click Master.
Add Track.
Right-click the new track.
Add effect Fade In or Out (default duration of fade is 60 frames i.e. 2 seconds).
Click anywhere that's not a track to view the cutscene properties in Object Inspector.
The cutscene length is initially the dialogue duration (in frames).
Change this to (dialogue duration + 30x + 60) where x is the time the screen will be completely black in seconds.
Adjust start/end time of the new track (and the Speak Line track under OWNER, if fading in).

For fade out, Speak Line happens first, then fade. The additional duration of the cutscene ensures the screen remains black for x seconds.

For fade in, assuming the screen is already black, fade after 30x frames, then Speak Line after 30x + 60 frames.

== Localization and Editing ==

These two panels are used for keeping track of the status of the localization and editing process for this line. This is useful for large-scale collaborative projects, such as Dragon Age itself, but may not be of as much use for individual adventure designers.

== Slide Show ==

The Slide Show tab is used to produce a simple form of "cutscene" that consists of one or more pre-rendered still images. For example, the official DAO campaign ends with a slideshow that describes the aftermath.

Images used in a slide show can be in [[TGA]], [[TPC]] or [[DDS]] format.

Each image must be on its own NPC conversation line. The Dialogue text isn't used in game, but it must contain something (e.g. "Slideshow"), otherwise the slide won't appear.

As usual, the NPC lines are connected by player lines (which don't need any Dialogue text).

See [[BeginSlideshow]] for the script function that triggers a slideshow.

== Toolbars ==

[[Image:Conversation toolbar labeled.png]]

* "Find links" generates a list of other places in the tree that have this line as their child. See the "looping conversations and re-using lines" section below.
*The highlighting toolbar is handy for rapidly finding and paging through conversation nodes with particular properties. There's forward and backward buttons for jumping from highlighted node to highlighted node, and a set of togglable highlight selection buttons that turn on and off highlighting based on node characteristics.
* "Once-per" lines include both once-per-conversation and once-per-game
* Highlighting lines with plot involvement will prompt you to select which particular plot to highlight.

== Looping conversation and re-using lines in multiple places ==

Although the basic structure is tree-shaped, the flow of the conversation can be structured to return back to previous nodes in the conversation. To cause a node in the tree to repeat:

*select the node you want to return to,
*"Copy" it (control-C, or select copy from the right-click menu),
*select the node you want the repeated response to be a child of,
*select "Paste as link" from the right-click menu (keyboard shortcut: control-shift-V)

The link node will appear in gray and cannot be edited. If you edit the original copy of the node all linked copies will reflect the change. You can only link nodes that have the same type (player/non-player), the paste-as-link option won't be available if the node currently saved to the clipboard can't be linked to a child of the currently selected node.

To find the original copy of a linked node, right-click on the grey node and select "Jump to Target".

Using the "once per conversation" or "once per game" visibility setting for the children of a repeating node is useful for preventing the player from cycling multiple times through the exact same dialogue.

== Voice-Over ==

You can use both placeholder and real recorded voiceover in your conversation, depending on what your current status on the conversation is. After you have some sort of voiceover associated to your conversation, you may run "Tools->Generate [[FaceFX]]" to add a facial expression to the NPCs performance.

All information about [[Voice-Over]] (conventions, integration, etc.) is stored at a another page to keep a central organized structure.

== Glossary of design terms ==

* Branch: A dialogue option that adds flavor to a conversation, but doesn't change the direction of the plot or story. Branches always come back together at a choke point.
* Clarification Hub: This allows a player to return to an NPC and clarify plot elements, get directions, or find out information about the current area. Generally, an single NPC line asks the player what he wants; a list of questions is then available to the player. Once the player has received an answer, the same list reappears (minus the question just asked). The player can loop infinitely through this NPC dialogue.
* Path: The dialogue options players can select that change the direction of a plot or story. For example, when a player is given the option of accepting a quest, there are two different resulting paths (based on a "Yes" or "No" answer). Unlike branches, paths never come back together. Each path has a different ending condition.
* Question Hub: A list of questions presented to a player that allows him to ask multiple questions to clarify information he's just learned. After a response is given, the player can ask the remaining questions. It's possible to loop indefinitely through a question hub, but only by asking non-critical questions. Unlike a clarification hub, at least one question drives the conversation tree forward and eliminates all remaining questions. For example, an NPC gives plot critical information; once she relates the details, the player can ask four specific questions. Three of the questions are non-critical: they give flavor and/or enhance role-playing. These questions allow for infinite looping. However, the fourth question drives the conversation forward and eliminates all other questions. This important question should always be located beneath the "lesser" questions.

== Associated Links ==

*[[Conversation cinematics and animation]]
*[[Conversation plots and scripting]]
*[[Conversation tutorial]]
*[[Voice-Over]]
*[[Preparing a dialog for recording]]

[[Category:Conversations]]

Builder to player

2011-04-18T17:49:32Z

Proleric1: /* Step by Step */

{{Infobox module}}
"Builder to player" packaging is a system for packaging up the playable binary files you've exported from your toolset into a form that is easily installed and played on another system.

__TOC__
== Overview ==

"Builder to player" packs every resource that is needed to be installed on another computer into a single filetype called [[DAZIP]]. You however must select those needed resources from folders and files in a treelike view. The "builder to player" function allows only files to be included from your modules "core" and "module" override folders, and the "Core Game Resources" Folder. As so it is very important that your resources are organized correctly.

It can be found under the "Tools -> Builder" menu.

== Resources organized ==

While the Toolset exports Designer Resources into their correct location, Art Resources and 2DA's which you created with external tools need to be arranged manually.

Likely, in your first steps you have placed those into a random Override folder until it works. The Toolset can read every Override folder just fine, so this didnt cause harm until now. The "builder to player" function requires resources to be organized, so it can package them and get distributed. So that no file is missed in the package, which causes the Module to work for you ,but not for someone else. It can help if you place Resources correctly from the start up.

The primary choice is always your custom Modules folders. Depending on whether your Resources shall be available only in your "module", or to other modules "core".
<pre>*My Documents*\BioWare\Dragon Age\AddIns\*Modulename*\module\override\toolsetexport\
*My Documents*\BioWare\Dragon Age\AddIns\*Modulename*\core\override\toolsetexport\</pre>

The other folder that can be included is the "Core Game Resources" Folder. This Folder must be treated with care, as this place is reserved for Gamewide Core Resources..
<pre>*My Documents*\BioWare\Dragon Age\packages\core\override\toolsetexport\</pre>
Resources in here is not advised, it allows Resources to be available to other modules even if you deactivate your custom Module. Additionally the Toolset has the habbit of exporting Core Game Resources here, which are mere duplicates unless you modified them. These duplicates need to be deleted, as potentially they still create problems in the singleplayer campaign. ''(See: [[Bug: export creates unnecessary core override|Bug Report]])'' If all your Resources are in your Modules Folder, this is an easy thing of selecting all and deleting.

All Resources need to be present and fully exported (that is if you created them):

*[[Designer Resources]]
*[[Art Resources]]
*[[2DA|2DA's]]

== Step by Step ==

Start the process by selecting from the menu:
<pre>"Tools -> Builder -> Builder to player package" </pre>

It will ask for a "Manifest". The "Manifest" is a helper, which isnt available the first time. However can be created afterwards, which will save you resource selection, so that exporting the next time you can select this "Manifest" and wouldnt need to select all the resources again.
<pre>Click cancel, or select a previously saved Manifest.</pre>

The toolset will now list all the binary files you've exported, including 2DA's, art and designer resources, and give you the opportunity to select which ones to include in the package (you usually won't need to include core game resources "from \packages\core", for example). It will then package them into 3 [[ERF]]s (one for each directory listed above), which will be bundled together into a [[DAZIP]] file along with a manifest file used by the program DAUpdater when installing the package on the end user's machine.

If you followed a clean structure with your resources, you may only select the whole custom module folder and be ready.
<pre>Select a location to save the file in.
Click Save.</pre>

Create a Manifest if you wish, which will save your resources selection for the next time you do the process.

Currently, there is a [[Bug:_toolset_export_generates_files_with_names_that_can%27t_be_packaged_in_builder_to_player | file name bug]] which affects external levels etc. Refer to that link for a workaround.

{{languages}}

[[category:database]]
[[category:modules]]

Bug: toolset export generates files with names that can't be packaged in builder to player

2011-04-18T17:46:54Z

Proleric1:

*'''Version found:''' 1.01 
*'''Status:''' Open

{{EV|212197|[[User:BryanDerksen|BryanDerksen]]}}

== Description ==


Certain operations in the toolset will cause files to be exported that can't be packaged into [[ERF]]s by the [[builder to player]] process due to filename restrictions (ERF doesn't like filenames with two dots). Examples include:

*.gpu.rim files, generated when posting level layouts
*.mor.xml files, luckily they're not needed

See [http://social.bioware.com/forum/1/topic/74/index/515072] for a forum thread where this bug is discussed.

== Workarounds ==


The files that can't be packaged into ERFs can still be manually inserted into the [[DAZIP]] file using ordinary archive-manipulating programs, causing the installer to extract and place them in the correct locations when the DAZIP is installed.

To keep it simple, since the problem typically occurs with external levels, exclude the entire core override toolsetexport folder from the Builder-to-Player, rename to .zip, drag the missing toolsetexport folder to the core data folder in the .zip manually, then rename to .dazip.

[[Category:Toolset bugs]]

Builder to builder

2011-04-16T16:59:19Z

Proleric1: /* Importing database resources */

{{Infobox module}}
"Builder to builder" is a general term for the process of exchanging game resource information between builders, for example between several people who are collaborating on building a module. See [[builder to player]] for the process of packaging up finished works to distribute to players.

There are three basic sorts of game resources that might need to be exchanged in this manner:
*Art resources
*[[2DA]]s
*Database resources

Art resources are self-contained files stored in the computer's file system in the standard way, and so are straightforward to share between builders. 2DAs are generated from Excel files that are also straightforward to share, especially when the capabilities of M2DAs are taken advantage of (see the [[2DA]] page for more detail).

Database resources are trickier. Almost every computer user is familiar with how to manipulate files in their filesystem but fewer are familiar with databases, and there are many interdependencies within Dragon Age's database resources that need to be taken into account when making any edit. To simplify this process the toolset has the ability to save and load selected database resources and their dependencies into XML files, which are then bundled up into a single archive file for convenience.

'''Note:''' This is a different sort of export procedure than what's needed to make resources available for use in the game itself, either for testing by yourself or for distribution to players. For information on that see [[resource palette]].

== Creating resource files for transfer ==

To create a resource file archive, select the resources in the resource palette and then in the right-click menu select the "builder to builder create" command:

[[Image:B2B create menu command.png|center|thumb|300px]]

You'll be presented with a list of the resources to be exported:

[[Image:B2B_create_panel.png|center|]]

Normally, you'll restrict the selection to your own module (unless you have a specific reason for exporting core resources).

Once you're done reviewing your selection, click "Ok" to export. You'll be prompted for a filename to put the resources into.

You can select multiple resources before doing builder to builder creation and they'll all be included in the B2B package.

Also, you can open a builder to builder creation window with all of your available resources in it by going to the Tools menu and selecting Builder -> Builder to Builder Create.

[[File:Builder to builder create via tools menu.png|center|thumb|300px]]

As noted above, this only exports design resources from the database, so in addition to sharing the .dadbdata file created in this process, builders also need to exchange any simple files containing 2DAs and art resources.

== Importing database resources ==

See also [[Builder to builder#Copying a Module | Copying a Module]].

Importing resources is done via the "Builder to Builder Load" command under the "Tools" menu (there's also a B2B create command here, the same that can be reached via the palette right-click menu):

[[Image:B2B load menu command.png|center|]]

Again, note that this is a different set of commands than the main "export" commands.

You'll be prompted to select a database resource file generated by a previous export. When you do, you'll be presented with an options pane listing all of the resources present in the file:

[[File:B2B load panel 973.png|center|]]

You can choose to import or not to import specific resources from this panel with the leftmost checkbox. Note that if you only import some of the files you may break dependencies. However, many of the dependencies in any significant export are likely to be core resources that you already have in your database and it's wise to avoid re-importing such resources unless you have a specific reason to.

You have the option to assign new string ids, or retain the original string ids, which allows you to maintain integrity of reference to the talk table. There seems to be a [[Bug:_Builder_to_Builder_Load_may_not_reproduce_resource_detail_correctly | bug]] with "Use Theirs". See [[String ID]] for a discussion of sharing issues.

ResRefID is the identifier that the resource had in the database it was exported from. ResRefIDs must be unique within any given database, so these numbers will be reassigned automatically during the import process.

=== Resource name conflicts ===

The "Exists/New" column indicates whether a resource with the same name already exists within the destination database. This is a good way to identify common core resources that were included as dependencies on export but that you don't want to re-import.

In the event that you import a resource with the same name as an existing resource within your database, the default behavior is for the old resource within your database to be overwritten by the new resource coming in from the import. The last column, "create new", allows this behavior to be overridden. If you enable "create new" for such a resource, the imported resource will be renamed with "_1" (or a higher number as needed) and the old resource will be untouched. Any other new imported resources in the file that depend on the renamed resource will have their dependencies updated to refer to the new copy of the resource.

Note that if use "create new" when importing a resource's dependencies and then you later re-import the same resource the importer won't know that its dependencies have been renamed in this manner. It's best to avoid this situation as hard-to-debug problems can potentially result.

Resources with the same name that already exist in the destination database and that are checked out by other users aren't editable, so the "checked out" column will warn you of any resources that the import process will be unable to update. This is unlikely to be a concern when only a single user (yourself) has access to your database but may become significant in a more sophisticated multi-user collaborative environment.

== Copying a Module ==

You might want to copy a module to a new machine, a new data base, or another builder's data base.

Builder-to-Builder Create is a good way to backup your resources for transfer or recovery.

When you want to make a copy, create a new module in the target data base, entering the resource name and Name property manually.

If you have VO, you'll want to ensure string ids don't change during load (otherwise you'll have to rename all the VO files).

If you know what string range was defined for the original module, change the new module to the same range.

If you've lost the original module and have no independent record of the string range, you need to ensure that all the strings in the .dadbdata file are in range. Temporarily, you can set the start of the range to 1, and the end of the range to a very high value.

Now do the Builder-to-Builder Load, with the Use Theirs option for string ids.

If you have a temporary string id range, examine the new module in the String Editor to discover the lowest and highest string id values. Set the range start to the lowest, range next to one higher than the highest, and range end as high as you like.

Finally, change the other module properties, such as the start area / waypoint and the module script. That has to happen last, because you select from the resources you just loaded.

== Sharing a live database ==

If passing bundles of files around between builders proves to be a cumbersome means of collaborating, a more advanced alternative exists: sharing a single database repository.

With a default installation of the toolset on a user's computer, a database is installed on that local computer for that toolset's use. Using the toolset's configuration tool, however, it is possible to tell the toolset to use some other database instead - possibly on another machine entirely, provided it's accessible over a network. This is the collaboration mechanism that was used internally at BioWare during the development of the Dragon Age single-player campaign, along with a more traditional file repository for the art resources and 2DAs, and is the principal reason why the toolset supports the concept of "checking out" database resources for editing.

General considerations you'll need to take into account:
*Firewall and router issues - The computers of all the various collaborators will need to be able to contact the central database. This may require port forwarding and other potentially tricky configuration settings.
*Availability - If all work is being done on a single database, nobody will be able to do anything when that database is unavailable. It may be a good idea to set up a machine dedicated solely to running the database.
*Security - You'll be exposing your database to potential intrusion attempts from the outside world, so make sure you understand the risks and the steps that can be taken to ameliorate them.

Though this is fully possible in principle with the existing toolset, the specifics for how to accomplish this outside the BioWare intranet haven't been tested yet so we don't have documentation for it yet.

{{languages}}
[[Category:Database]]
[[category:modules]]

Builder to builder

2011-04-16T16:58:52Z

Proleric1: /* Importing database resources */

{{Infobox module}}
"Builder to builder" is a general term for the process of exchanging game resource information between builders, for example between several people who are collaborating on building a module. See [[builder to player]] for the process of packaging up finished works to distribute to players.

There are three basic sorts of game resources that might need to be exchanged in this manner:
*Art resources
*[[2DA]]s
*Database resources

Art resources are self-contained files stored in the computer's file system in the standard way, and so are straightforward to share between builders. 2DAs are generated from Excel files that are also straightforward to share, especially when the capabilities of M2DAs are taken advantage of (see the [[2DA]] page for more detail).

Database resources are trickier. Almost every computer user is familiar with how to manipulate files in their filesystem but fewer are familiar with databases, and there are many interdependencies within Dragon Age's database resources that need to be taken into account when making any edit. To simplify this process the toolset has the ability to save and load selected database resources and their dependencies into XML files, which are then bundled up into a single archive file for convenience.

'''Note:''' This is a different sort of export procedure than what's needed to make resources available for use in the game itself, either for testing by yourself or for distribution to players. For information on that see [[resource palette]].

== Creating resource files for transfer ==

To create a resource file archive, select the resources in the resource palette and then in the right-click menu select the "builder to builder create" command:

[[Image:B2B create menu command.png|center|thumb|300px]]

You'll be presented with a list of the resources to be exported:

[[Image:B2B_create_panel.png|center|]]

Normally, you'll restrict the selection to your own module (unless you have a specific reason for exporting core resources).

Once you're done reviewing your selection, click "Ok" to export. You'll be prompted for a filename to put the resources into.

You can select multiple resources before doing builder to builder creation and they'll all be included in the B2B package.

Also, you can open a builder to builder creation window with all of your available resources in it by going to the Tools menu and selecting Builder -> Builder to Builder Create.

[[File:Builder to builder create via tools menu.png|center|thumb|300px]]

As noted above, this only exports design resources from the database, so in addition to sharing the .dadbdata file created in this process, builders also need to exchange any simple files containing 2DAs and art resources.

== Importing database resources ==

See also [[Builder to builder#Copying a Module]].

Importing resources is done via the "Builder to Builder Load" command under the "Tools" menu (there's also a B2B create command here, the same that can be reached via the palette right-click menu):

[[Image:B2B load menu command.png|center|]]

Again, note that this is a different set of commands than the main "export" commands.

You'll be prompted to select a database resource file generated by a previous export. When you do, you'll be presented with an options pane listing all of the resources present in the file:

[[File:B2B load panel 973.png|center|]]

You can choose to import or not to import specific resources from this panel with the leftmost checkbox. Note that if you only import some of the files you may break dependencies. However, many of the dependencies in any significant export are likely to be core resources that you already have in your database and it's wise to avoid re-importing such resources unless you have a specific reason to.

You have the option to assign new string ids, or retain the original string ids, which allows you to maintain integrity of reference to the talk table. There seems to be a [[Bug:_Builder_to_Builder_Load_may_not_reproduce_resource_detail_correctly | bug]] with "Use Theirs". See [[String ID]] for a discussion of sharing issues.

ResRefID is the identifier that the resource had in the database it was exported from. ResRefIDs must be unique within any given database, so these numbers will be reassigned automatically during the import process.

=== Resource name conflicts ===

The "Exists/New" column indicates whether a resource with the same name already exists within the destination database. This is a good way to identify common core resources that were included as dependencies on export but that you don't want to re-import.

In the event that you import a resource with the same name as an existing resource within your database, the default behavior is for the old resource within your database to be overwritten by the new resource coming in from the import. The last column, "create new", allows this behavior to be overridden. If you enable "create new" for such a resource, the imported resource will be renamed with "_1" (or a higher number as needed) and the old resource will be untouched. Any other new imported resources in the file that depend on the renamed resource will have their dependencies updated to refer to the new copy of the resource.

Note that if use "create new" when importing a resource's dependencies and then you later re-import the same resource the importer won't know that its dependencies have been renamed in this manner. It's best to avoid this situation as hard-to-debug problems can potentially result.

Resources with the same name that already exist in the destination database and that are checked out by other users aren't editable, so the "checked out" column will warn you of any resources that the import process will be unable to update. This is unlikely to be a concern when only a single user (yourself) has access to your database but may become significant in a more sophisticated multi-user collaborative environment.

== Copying a Module ==

You might want to copy a module to a new machine, a new data base, or another builder's data base.

Builder-to-Builder Create is a good way to backup your resources for transfer or recovery.

When you want to make a copy, create a new module in the target data base, entering the resource name and Name property manually.

If you have VO, you'll want to ensure string ids don't change during load (otherwise you'll have to rename all the VO files).

If you know what string range was defined for the original module, change the new module to the same range.

If you've lost the original module and have no independent record of the string range, you need to ensure that all the strings in the .dadbdata file are in range. Temporarily, you can set the start of the range to 1, and the end of the range to a very high value.

Now do the Builder-to-Builder Load, with the Use Theirs option for string ids.

If you have a temporary string id range, examine the new module in the String Editor to discover the lowest and highest string id values. Set the range start to the lowest, range next to one higher than the highest, and range end as high as you like.

Finally, change the other module properties, such as the start area / waypoint and the module script. That has to happen last, because you select from the resources you just loaded.

== Sharing a live database ==

If passing bundles of files around between builders proves to be a cumbersome means of collaborating, a more advanced alternative exists: sharing a single database repository.

With a default installation of the toolset on a user's computer, a database is installed on that local computer for that toolset's use. Using the toolset's configuration tool, however, it is possible to tell the toolset to use some other database instead - possibly on another machine entirely, provided it's accessible over a network. This is the collaboration mechanism that was used internally at BioWare during the development of the Dragon Age single-player campaign, along with a more traditional file repository for the art resources and 2DAs, and is the principal reason why the toolset supports the concept of "checking out" database resources for editing.

General considerations you'll need to take into account:
*Firewall and router issues - The computers of all the various collaborators will need to be able to contact the central database. This may require port forwarding and other potentially tricky configuration settings.
*Availability - If all work is being done on a single database, nobody will be able to do anything when that database is unavailable. It may be a good idea to set up a machine dedicated solely to running the database.
*Security - You'll be exposing your database to potential intrusion attempts from the outside world, so make sure you understand the risks and the steps that can be taken to ameliorate them.

Though this is fully possible in principle with the existing toolset, the specifics for how to accomplish this outside the BioWare intranet haven't been tested yet so we don't have documentation for it yet.

{{languages}}
[[Category:Database]]
[[category:modules]]

Builder to builder

2011-04-16T16:56:32Z

Proleric1: /* Importing database resources */

{{Infobox module}}
"Builder to builder" is a general term for the process of exchanging game resource information between builders, for example between several people who are collaborating on building a module. See [[builder to player]] for the process of packaging up finished works to distribute to players.

There are three basic sorts of game resources that might need to be exchanged in this manner:
*Art resources
*[[2DA]]s
*Database resources

Art resources are self-contained files stored in the computer's file system in the standard way, and so are straightforward to share between builders. 2DAs are generated from Excel files that are also straightforward to share, especially when the capabilities of M2DAs are taken advantage of (see the [[2DA]] page for more detail).

Database resources are trickier. Almost every computer user is familiar with how to manipulate files in their filesystem but fewer are familiar with databases, and there are many interdependencies within Dragon Age's database resources that need to be taken into account when making any edit. To simplify this process the toolset has the ability to save and load selected database resources and their dependencies into XML files, which are then bundled up into a single archive file for convenience.

'''Note:''' This is a different sort of export procedure than what's needed to make resources available for use in the game itself, either for testing by yourself or for distribution to players. For information on that see [[resource palette]].

== Creating resource files for transfer ==

To create a resource file archive, select the resources in the resource palette and then in the right-click menu select the "builder to builder create" command:

[[Image:B2B create menu command.png|center|thumb|300px]]

You'll be presented with a list of the resources to be exported:

[[Image:B2B_create_panel.png|center|]]

Normally, you'll restrict the selection to your own module (unless you have a specific reason for exporting core resources).

Once you're done reviewing your selection, click "Ok" to export. You'll be prompted for a filename to put the resources into.

You can select multiple resources before doing builder to builder creation and they'll all be included in the B2B package.

Also, you can open a builder to builder creation window with all of your available resources in it by going to the Tools menu and selecting Builder -> Builder to Builder Create.

[[File:Builder to builder create via tools menu.png|center|thumb|300px]]

As noted above, this only exports design resources from the database, so in addition to sharing the .dadbdata file created in this process, builders also need to exchange any simple files containing 2DAs and art resources.

== Importing database resources ==

See also [[Copying a Module]].

Importing resources is done via the "Builder to Builder Load" command under the "Tools" menu (there's also a B2B create command here, the same that can be reached via the palette right-click menu):

[[Image:B2B load menu command.png|center|]]

Again, note that this is a different set of commands than the main "export" commands.

You'll be prompted to select a database resource file generated by a previous export. When you do, you'll be presented with an options pane listing all of the resources present in the file:

[[File:B2B load panel 973.png|center|]]

You can choose to import or not to import specific resources from this panel with the leftmost checkbox. Note that if you only import some of the files you may break dependencies. However, many of the dependencies in any significant export are likely to be core resources that you already have in your database and it's wise to avoid re-importing such resources unless you have a specific reason to.

You have the option to assign new string ids, or retain the original string ids, which allows you to maintain integrity of reference to the talk table. There seems to be a [[Bug:_Builder_to_Builder_Load_may_not_reproduce_resource_detail_correctly | bug]] with "Use Theirs". See [[String ID]] for a discussion of sharing issues.

ResRefID is the identifier that the resource had in the database it was exported from. ResRefIDs must be unique within any given database, so these numbers will be reassigned automatically during the import process.

=== Resource name conflicts ===

The "Exists/New" column indicates whether a resource with the same name already exists within the destination database. This is a good way to identify common core resources that were included as dependencies on export but that you don't want to re-import.

In the event that you import a resource with the same name as an existing resource within your database, the default behavior is for the old resource within your database to be overwritten by the new resource coming in from the import. The last column, "create new", allows this behavior to be overridden. If you enable "create new" for such a resource, the imported resource will be renamed with "_1" (or a higher number as needed) and the old resource will be untouched. Any other new imported resources in the file that depend on the renamed resource will have their dependencies updated to refer to the new copy of the resource.

Note that if use "create new" when importing a resource's dependencies and then you later re-import the same resource the importer won't know that its dependencies have been renamed in this manner. It's best to avoid this situation as hard-to-debug problems can potentially result.

Resources with the same name that already exist in the destination database and that are checked out by other users aren't editable, so the "checked out" column will warn you of any resources that the import process will be unable to update. This is unlikely to be a concern when only a single user (yourself) has access to your database but may become significant in a more sophisticated multi-user collaborative environment.

== Copying a Module ==

You might want to copy a module to a new machine, a new data base, or another builder's data base.

Builder-to-Builder Create is a good way to backup your resources for transfer or recovery.

When you want to make a copy, create a new module in the target data base, entering the resource name and Name property manually.

If you have VO, you'll want to ensure string ids don't change during load (otherwise you'll have to rename all the VO files).

If you know what string range was defined for the original module, change the new module to the same range.

If you've lost the original module and have no independent record of the string range, you need to ensure that all the strings in the .dadbdata file are in range. Temporarily, you can set the start of the range to 1, and the end of the range to a very high value.

Now do the Builder-to-Builder Load, with the Use Theirs option for string ids.

If you have a temporary string id range, examine the new module in the String Editor to discover the lowest and highest string id values. Set the range start to the lowest, range next to one higher than the highest, and range end as high as you like.

Finally, change the other module properties, such as the start area / waypoint and the module script. That has to happen last, because you select from the resources you just loaded.

== Sharing a live database ==

If passing bundles of files around between builders proves to be a cumbersome means of collaborating, a more advanced alternative exists: sharing a single database repository.

With a default installation of the toolset on a user's computer, a database is installed on that local computer for that toolset's use. Using the toolset's configuration tool, however, it is possible to tell the toolset to use some other database instead - possibly on another machine entirely, provided it's accessible over a network. This is the collaboration mechanism that was used internally at BioWare during the development of the Dragon Age single-player campaign, along with a more traditional file repository for the art resources and 2DAs, and is the principal reason why the toolset supports the concept of "checking out" database resources for editing.

General considerations you'll need to take into account:
*Firewall and router issues - The computers of all the various collaborators will need to be able to contact the central database. This may require port forwarding and other potentially tricky configuration settings.
*Availability - If all work is being done on a single database, nobody will be able to do anything when that database is unavailable. It may be a good idea to set up a machine dedicated solely to running the database.
*Security - You'll be exposing your database to potential intrusion attempts from the outside world, so make sure you understand the risks and the steps that can be taken to ameliorate them.

Though this is fully possible in principle with the existing toolset, the specifics for how to accomplish this outside the BioWare intranet haven't been tested yet so we don't have documentation for it yet.

{{languages}}
[[Category:Database]]
[[category:modules]]

Builder to builder

2011-04-16T16:56:04Z

Proleric1: /* Importing database resources */

{{Infobox module}}
"Builder to builder" is a general term for the process of exchanging game resource information between builders, for example between several people who are collaborating on building a module. See [[builder to player]] for the process of packaging up finished works to distribute to players.

There are three basic sorts of game resources that might need to be exchanged in this manner:
*Art resources
*[[2DA]]s
*Database resources

Art resources are self-contained files stored in the computer's file system in the standard way, and so are straightforward to share between builders. 2DAs are generated from Excel files that are also straightforward to share, especially when the capabilities of M2DAs are taken advantage of (see the [[2DA]] page for more detail).

Database resources are trickier. Almost every computer user is familiar with how to manipulate files in their filesystem but fewer are familiar with databases, and there are many interdependencies within Dragon Age's database resources that need to be taken into account when making any edit. To simplify this process the toolset has the ability to save and load selected database resources and their dependencies into XML files, which are then bundled up into a single archive file for convenience.

'''Note:''' This is a different sort of export procedure than what's needed to make resources available for use in the game itself, either for testing by yourself or for distribution to players. For information on that see [[resource palette]].

== Creating resource files for transfer ==

To create a resource file archive, select the resources in the resource palette and then in the right-click menu select the "builder to builder create" command:

[[Image:B2B create menu command.png|center|thumb|300px]]

You'll be presented with a list of the resources to be exported:

[[Image:B2B_create_panel.png|center|]]

Normally, you'll restrict the selection to your own module (unless you have a specific reason for exporting core resources).

Once you're done reviewing your selection, click "Ok" to export. You'll be prompted for a filename to put the resources into.

You can select multiple resources before doing builder to builder creation and they'll all be included in the B2B package.

Also, you can open a builder to builder creation window with all of your available resources in it by going to the Tools menu and selecting Builder -> Builder to Builder Create.

[[File:Builder to builder create via tools menu.png|center|thumb|300px]]

As noted above, this only exports design resources from the database, so in addition to sharing the .dadbdata file created in this process, builders also need to exchange any simple files containing 2DAs and art resources.

== Importing database resources ==

See also [[Importing a Module]].

Importing resources is done via the "Builder to Builder Load" command under the "Tools" menu (there's also a B2B create command here, the same that can be reached via the palette right-click menu):

[[Image:B2B load menu command.png|center|]]

Again, note that this is a different set of commands than the main "export" commands.

You'll be prompted to select a database resource file generated by a previous export. When you do, you'll be presented with an options pane listing all of the resources present in the file:

[[File:B2B load panel 973.png|center|]]

You can choose to import or not to import specific resources from this panel with the leftmost checkbox. Note that if you only import some of the files you may break dependencies. However, many of the dependencies in any significant export are likely to be core resources that you already have in your database and it's wise to avoid re-importing such resources unless you have a specific reason to.

You have the option to assign new string ids, or retain the original string ids, which allows you to maintain integrity of reference to the talk table. There seems to be a [[Bug:_Builder_to_Builder_Load_may_not_reproduce_resource_detail_correctly | bug]] with "Use Theirs". See [[String ID]] for a discussion of sharing issues.

ResRefID is the identifier that the resource had in the database it was exported from. ResRefIDs must be unique within any given database, so these numbers will be reassigned automatically during the import process.

=== Resource name conflicts ===

The "Exists/New" column indicates whether a resource with the same name already exists within the destination database. This is a good way to identify common core resources that were included as dependencies on export but that you don't want to re-import.

In the event that you import a resource with the same name as an existing resource within your database, the default behavior is for the old resource within your database to be overwritten by the new resource coming in from the import. The last column, "create new", allows this behavior to be overridden. If you enable "create new" for such a resource, the imported resource will be renamed with "_1" (or a higher number as needed) and the old resource will be untouched. Any other new imported resources in the file that depend on the renamed resource will have their dependencies updated to refer to the new copy of the resource.

Note that if use "create new" when importing a resource's dependencies and then you later re-import the same resource the importer won't know that its dependencies have been renamed in this manner. It's best to avoid this situation as hard-to-debug problems can potentially result.

Resources with the same name that already exist in the destination database and that are checked out by other users aren't editable, so the "checked out" column will warn you of any resources that the import process will be unable to update. This is unlikely to be a concern when only a single user (yourself) has access to your database but may become significant in a more sophisticated multi-user collaborative environment.

== Copying a Module ==

You might want to copy a module to a new machine, a new data base, or another builder's data base.

Builder-to-Builder Create is a good way to backup your resources for transfer or recovery.

When you want to make a copy, create a new module in the target data base, entering the resource name and Name property manually.

If you have VO, you'll want to ensure string ids don't change during load (otherwise you'll have to rename all the VO files).

If you know what string range was defined for the original module, change the new module to the same range.

If you've lost the original module and have no independent record of the string range, you need to ensure that all the strings in the .dadbdata file are in range. Temporarily, you can set the start of the range to 1, and the end of the range to a very high value.

Now do the Builder-to-Builder Load, with the Use Theirs option for string ids.

If you have a temporary string id range, examine the new module in the String Editor to discover the lowest and highest string id values. Set the range start to the lowest, range next to one higher than the highest, and range end as high as you like.

Finally, change the other module properties, such as the start area / waypoint and the module script. That has to happen last, because you select from the resources you just loaded.

== Sharing a live database ==

If passing bundles of files around between builders proves to be a cumbersome means of collaborating, a more advanced alternative exists: sharing a single database repository.

With a default installation of the toolset on a user's computer, a database is installed on that local computer for that toolset's use. Using the toolset's configuration tool, however, it is possible to tell the toolset to use some other database instead - possibly on another machine entirely, provided it's accessible over a network. This is the collaboration mechanism that was used internally at BioWare during the development of the Dragon Age single-player campaign, along with a more traditional file repository for the art resources and 2DAs, and is the principal reason why the toolset supports the concept of "checking out" database resources for editing.

General considerations you'll need to take into account:
*Firewall and router issues - The computers of all the various collaborators will need to be able to contact the central database. This may require port forwarding and other potentially tricky configuration settings.
*Availability - If all work is being done on a single database, nobody will be able to do anything when that database is unavailable. It may be a good idea to set up a machine dedicated solely to running the database.
*Security - You'll be exposing your database to potential intrusion attempts from the outside world, so make sure you understand the risks and the steps that can be taken to ameliorate them.

Though this is fully possible in principle with the existing toolset, the specifics for how to accomplish this outside the BioWare intranet haven't been tested yet so we don't have documentation for it yet.

{{languages}}
[[Category:Database]]
[[category:modules]]

Builder to builder

2011-04-16T16:53:36Z

Proleric1: /* Importing database resources */

{{Infobox module}}
"Builder to builder" is a general term for the process of exchanging game resource information between builders, for example between several people who are collaborating on building a module. See [[builder to player]] for the process of packaging up finished works to distribute to players.

There are three basic sorts of game resources that might need to be exchanged in this manner:
*Art resources
*[[2DA]]s
*Database resources

Art resources are self-contained files stored in the computer's file system in the standard way, and so are straightforward to share between builders. 2DAs are generated from Excel files that are also straightforward to share, especially when the capabilities of M2DAs are taken advantage of (see the [[2DA]] page for more detail).

Database resources are trickier. Almost every computer user is familiar with how to manipulate files in their filesystem but fewer are familiar with databases, and there are many interdependencies within Dragon Age's database resources that need to be taken into account when making any edit. To simplify this process the toolset has the ability to save and load selected database resources and their dependencies into XML files, which are then bundled up into a single archive file for convenience.

'''Note:''' This is a different sort of export procedure than what's needed to make resources available for use in the game itself, either for testing by yourself or for distribution to players. For information on that see [[resource palette]].

== Creating resource files for transfer ==

To create a resource file archive, select the resources in the resource palette and then in the right-click menu select the "builder to builder create" command:

[[Image:B2B create menu command.png|center|thumb|300px]]

You'll be presented with a list of the resources to be exported:

[[Image:B2B_create_panel.png|center|]]

Normally, you'll restrict the selection to your own module (unless you have a specific reason for exporting core resources).

Once you're done reviewing your selection, click "Ok" to export. You'll be prompted for a filename to put the resources into.

You can select multiple resources before doing builder to builder creation and they'll all be included in the B2B package.

Also, you can open a builder to builder creation window with all of your available resources in it by going to the Tools menu and selecting Builder -> Builder to Builder Create.

[[File:Builder to builder create via tools menu.png|center|thumb|300px]]

As noted above, this only exports design resources from the database, so in addition to sharing the .dadbdata file created in this process, builders also need to exchange any simple files containing 2DAs and art resources.

== Importing database resources ==

Importing resources is done via the "Builder to Builder Load" command under the "Tools" menu (there's also a B2B create command here, the same that can be reached via the palette right-click menu):

[[Image:B2B load menu command.png|center|]]

Again, note that this is a different set of commands than the main "export" commands.

You'll be prompted to select a database resource file generated by a previous export. When you do, you'll be presented with an options pane listing all of the resources present in the file:

[[File:B2B load panel 973.png|center|]]

You can choose to import or not to import specific resources from this panel with the leftmost checkbox. Note that if you only import some of the files you may break dependencies. However, many of the dependencies in any significant export are likely to be core resources that you already have in your database and it's wise to avoid re-importing such resources unless you have a specific reason to.

You have the option to assign new string ids, or retain the original string ids, which allows you to maintain integrity of reference to the talk table. There seems to be a [[Bug:_Builder_to_Builder_Load_may_not_reproduce_resource_detail_correctly | bug]] with "Use Theirs". See [[String ID]] for a discussion of sharing issues.

ResRefID is the identifier that the resource had in the database it was exported from. ResRefIDs must be unique within any given database, so these numbers will be reassigned automatically during the import process.

=== Resource name conflicts ===

The "Exists/New" column indicates whether a resource with the same name already exists within the destination database. This is a good way to identify common core resources that were included as dependencies on export but that you don't want to re-import.

In the event that you import a resource with the same name as an existing resource within your database, the default behavior is for the old resource within your database to be overwritten by the new resource coming in from the import. The last column, "create new", allows this behavior to be overridden. If you enable "create new" for such a resource, the imported resource will be renamed with "_1" (or a higher number as needed) and the old resource will be untouched. Any other new imported resources in the file that depend on the renamed resource will have their dependencies updated to refer to the new copy of the resource.

Note that if use "create new" when importing a resource's dependencies and then you later re-import the same resource the importer won't know that its dependencies have been renamed in this manner. It's best to avoid this situation as hard-to-debug problems can potentially result.

Resources with the same name that already exist in the destination database and that are checked out by other users aren't editable, so the "checked out" column will warn you of any resources that the import process will be unable to update. This is unlikely to be a concern when only a single user (yourself) has access to your database but may become significant in a more sophisticated multi-user collaborative environment.

== Copying a Module ==

You might want to copy a module to a new machine, a new data base, or another builder's data base.

Builder-to-Builder Create is a good way to backup your resources for transfer or recovery.

When you want to make a copy, create a new module in the target data base, entering the resource name and Name property manually.

If you have VO, you'll want to ensure string ids don't change during load (otherwise you'll have to rename all the VO files).

If you know what string range was defined for the original module, change the new module to the same range.

If you've lost the original module and have no independent record of the string range, you need to ensure that all the strings in the .dadbdata file are in range. Temporarily, you can set the start of the range to 1, and the end of the range to a very high value.

Now do the Builder-to-Builder Load, with the Use Theirs option for string ids.

If you have a temporary string id range, examine the new module in the String Editor to discover the lowest and highest string id values. Set the range start to the lowest, range next to one higher than the highest, and range end as high as you like.

Finally, change the other module properties, such as the start area / waypoint and the module script. That has to happen last, because you select from the resources you just loaded.

== Sharing a live database ==

If passing bundles of files around between builders proves to be a cumbersome means of collaborating, a more advanced alternative exists: sharing a single database repository.

With a default installation of the toolset on a user's computer, a database is installed on that local computer for that toolset's use. Using the toolset's configuration tool, however, it is possible to tell the toolset to use some other database instead - possibly on another machine entirely, provided it's accessible over a network. This is the collaboration mechanism that was used internally at BioWare during the development of the Dragon Age single-player campaign, along with a more traditional file repository for the art resources and 2DAs, and is the principal reason why the toolset supports the concept of "checking out" database resources for editing.

General considerations you'll need to take into account:
*Firewall and router issues - The computers of all the various collaborators will need to be able to contact the central database. This may require port forwarding and other potentially tricky configuration settings.
*Availability - If all work is being done on a single database, nobody will be able to do anything when that database is unavailable. It may be a good idea to set up a machine dedicated solely to running the database.
*Security - You'll be exposing your database to potential intrusion attempts from the outside world, so make sure you understand the risks and the steps that can be taken to ameliorate them.

Though this is fully possible in principle with the existing toolset, the specifics for how to accomplish this outside the BioWare intranet haven't been tested yet so we don't have documentation for it yet.

{{languages}}
[[Category:Database]]
[[category:modules]]

Creating a module

2011-04-16T16:33:04Z

Proleric1: /* Creating a new Module */

{{Infobox module}}
To create and modify [[module]]s, select "Manage Modules" from the File menu. This will bring up a list of existing modules, with a "New" button for creating new modules and a "Properties" button for editing the properties of existing modules. You can only edit the properties of the module that's currently open.

== Creating a new Module ==

{| align=right
|-
| [[Image:Module menu command.png|frame|Select "Manage Modules"]]
| [[Image:Module manage module window.png|frame|Then click the "New" button to create a new module.]]
|}

#Open File/Manage Modules
#Click on "New" and the module properties window will open.
#Edit the "Name" field give the module a name (This is the name that will also be visible in Game as a Addin)
#Add a unique identifier string to the UID field. The File and Folder will appear in that name.
#Make an independent note of the StringID Begin value. This is vital information if you ever have to export the module to a new data base.
#Then click "OK"; the other properties can be changed later on once you have some content to set them to.

=== Opening the Module ===

#Select the module in the Manage Modules list
#Click the "Open" button.

*The Open Module is displayed in the Title Bar. Only resources that are available to the open module will be visible.

=== To create a standalone module: ===

#Select the module in the Manage Modules list
#Click on the "Hierarchy" button
#Unmark any parent module (is by default)

*The Extended Module property should be left as the default (None).
*You should use the default script "module_core" or your own custom script.

=== Extending the game with addins (common) ===

#Select the module in the Manage Modules list
#Click on the "Hierarchy" button
#Mark the parent module "Single Player"
#Hit OK

*The Extended Module property should be set to "Single Player".
*Note that as of toolset version 1.01 and game version 1.02b, you should NOT use "module_core" as the script (as found in module properties) for an add-in that extends an existing module, otherwise you will encounter issues that may include slow-downs during conversations and attribute allocation. The exact cause of these issues is not yet known, but using a blank script with an empty main function will eliminate these issues.
*Resources of "Single Player" will now become available to this module.

=== Advanced Properties ===

#Select the module in the Manage Modules list
#Click on the "Properties" button
The Settings can be changed at any later time. To set up your Module prior Exporting see [[Manage modules]]

*For a detailed explanation of the properties you will see here, See [[module|Module]].

----

The only module type that's supported by the toolset is "Addin". You can use addins in two basic ways; either to extend an existing campaign (such as the main campaign) or as a stand-alone campaign in its own right. Addins can be enabled and disabled by the user in the "Downloadable content" menu from the game. You can also create addins that add to or modify core resources, which are available to all modules of the game.

A module with no event script will start the player without going through character generation, which will leave the player with an almost unusable character to play with. See [[character generation]] for some simple character generation code you can use.

'''NOTE:''' Currently there is no way to delete a module within the toolset once it's been created. See [[Deleting a module]]

== Core resources: ==

One way of using the same object template in more than one module is to create a core resource.

When importing a character from one module to another, custom items in the player's inventory will be lost unless the resource template is available to both modules. A core resource is one way of doing this.

Note that core resources are visible to every campaign, so, for compatibility purposes, it's better to use alternate methods where available. For example, an add-in inherits resources from the parent module, so there's no need to use core resources in that case.

To create a core resource:
# Right click on properties for the resource in the Palette Window
# Change Module to: Core Game Resources
# Change Owner Module to: New Module Name
Be aware of dependencies between core and non-core resources; especially around scripts. If a core resource uses a non-core script, the script won't exist if you use the core resource in a different module.

There will be a separate [[talk table]] created for the Addin in its directories. When the game loads it will combine all the talk tables across all the addins that it knows about.

{{languages}}
[[category:modules]]

Backgrounds tutorial

2011-04-06T07:04:17Z

Proleric1: /* Creating the scripts */

== Introduction ==
This tutorial shows you how to modify the character backgrounds that can be selected during character generation. This is likely only of use if you are creating your own module or campaign as there would be no point to changing the background in the single player campaign unless you were also going to make extensive additions to support the new backgrounds (e.g a completely new origin story). So the example we will use for this tutorial is a new stand alone module in which we completely replace the existing backgrounds. Changing backgrounds is especially useful if your module is set in a different lore to the main Dragon Age game or if you simply want to reduce the scope of the number of different backgrounds.

We will also demonstrate some important principals that can be followed when modifying other core rules such as available races or classes. Most importantly we will add the new backgrounds in a way that doesn’t require any editing of core resources. By leaving the core resources alone we make our changes compatible with future patches which might otherwise overwrite our work. Furthermore keeping the core resources in tact allows us to make different modifications to different modules within the same toolset.

It is recommended that the reader should have some experience with scripting or coding in order to carry out the operations involved. The more you are relying on just copy pasting these instructions the more likely you are to make mistakes that you won’t know how to fix.

== The backgrounds demo module ==
Any basic module will do for the purposes of this tutorial. If you want to create a test module for this tutorial then just create a simple module with a single area and a starting location. Make sure that the only thing selected in the module’s hierarchy is ''Core game resources''. This will ensure that the module is a stand alone module rather than an add-in to the single player campaign or some other module. For the purposes of this tutorial we will assume the module is called ''Backgrounds demo'' and I will prefix my resources with ''bdm_'' to be sure that they are distinct from any that are already in existence.

We are going to completely replace the existing backgrounds with 3 new ones of our own. You can use new backgrounds in your module however you see fit. You could create entire origin stories for each one like in the single player campaign (possibly a major undertaking depending on length) or you can just use them to influence dialogue and plot options in the main part of your game.

For our demo we are creating a module in which the player starts off in a small human village (we will not be creating the details of this module so this is just for the purpose of an example). There is a wizard in this village who plays a pivotal role in the story. We allow the player to start as the wizard’s apprentice (if they are a mage) or as his servant (if they are human or elven and not a mage) or as a wandering traveller who has come to visit the wizard (if they are not human and not a mage). So the three backgrounds will be:

* Servant
* Apprentice
* Traveller

== Creating the background strings ==
Before we start modifying the 2DA files we are going to create some strings. Open the string editor in the toolset and create the following strings in your ‘Backgrounds demo’ talk table:

[[Image:Back_tut_talk_table.png]]

Your string IDs might be different to these so be sure to reference the right string ID in the instructions that follow. Simply replace these string Ids with your own.

'''IMPORTANT!''' ''There is currently a bug in the game that causes it to crash if a background description ID has a value greater than 109 912 680. To get around this you can go into your module’s properties and change the start and end IDs for strings to be less than that. After that the string editor will generate IDs in a range that won’t crash. You can always put those values back again after you create the background descriptions (that way you have less to alter once Bioware fix this). Hopefully Bioware will fix this bug soon as the official string range for non-Bioware / certified modules is over 610 000 000.''

You may have noticed that we have given two different names and descriptions for the traveller background depending on the PC’s race. We will say more about that in the following section.

{{TutorialRef|String editor}}

== Modifying the 2DAs ==
The next thing we need to do is to modify the worksheets in backgrounds.xls. Be sure to make a copy of the spreadsheet first so that you leave the original intact. See LINK for general information about editing 2DA files. The first worksheet is called ‘backgrounds’; modify it to look like the following:

[[Image:back_tut_backgrounds.png]]

Note that since 2DAs combine together to form M2DAs, and we don’t want the existing backgrounds in our game, we have overwritten the last two slots as unused1 and unused2, even though we won’t be using them. The name and desc string refs on this tab will be overwritten by the race specific ones on the names tab so we can leave those blank (AFAIK these string refs are not used providing the ones on the names tab are provided - also the tooltip string ref seems not to be used anywhere – if you prefer you can set these to something just to be safe).

The three race columns determine which backgrounds can be selected by which race and the 3 class columns determine which background can be selected by which class. So, as you can see from the picture our Servant background is accessible to elf or human warriors and rogues, the Apprentice background can be selected by elf or human mages and the Traveller background by elf or dwarf warriors and rogues.

The last three tabs indicate a starting ability for each background by race. Note that by default these columns are not hooked up into the character generation script (instead they are hard coded in the script) and are not used, but we will correct that later on when we do the scripting. You have to be careful here because the columns relate to the race IDs, so 1=dwarf, 2=elf and 3=human, which is in a different order to the other race columns in this table. The number in the column is an ability ID as given in ABI_base.xls. For this demo we have just given the same skill for each race for a given background. Servants get combat tactics, Apprentices get persuade and Travellers get survival.

The next tab table to modify is background_names.

[[Image:back_tut_bg_names.png]]

Make sure that the IDs here match the IDs in your string table. Note that for Apprentices and Servants we use the same strings regardless of race, but for the Traveller background we use different strings. This is to illustrate how you can divide a single background up into multiple names and descriptions. Internally they are both stored as the same background ID but during character generation a different name, description and icon can be shown to the player. In the single player game this was done with the Noble background by splitting it into human and dwarf Noble variations.

NOTE – you must be careful when splitting a single background into different parts for each race. You must make both the names and descriptions different! If you don’t make the descriptions different then the engine will not recognise them as different even if they have different names.

Now modify the background_desc table as follows

[[Image:back_tut_bg_desc.png]]

Again note the distinct descriptions for the Traveller background.

Now for the background_icons table. For this demo we will just use some of the existing icons but you may want to create your own icons to add here.

[[Image:back_tut_bg_icons.png]]

The background_defaults table must have an entry for each race, background and class combination that is allowed. The ID column must be calculated as follows:

(1000 * raceID) + (100 * classID) + backgroundID

[[Image:back_tute_bg_defaults.png]]

The label column should give a description of the row (AFAIK this is not used anywhere).
For this simple demo we will have each background combination spawn in the same place (the module default start location) but if you wanted different origins to spawn in different places then you can use the next two columns to specify this (AFAIK you have to write your own scripts to accomplish this though).

In the template column you can put the name of a creature resource that you want to use as a template for this race/background/class combination. In the picture you can see that we have just used some default templates that shipped with the toolset but you can easily create your own. Note that only the inventory is copied across to the PC so if you want to create your own templates you do not need to alter anything on the creature except for their inventory.

The name columns take string Ids. If you want to add your own names then you’ll have to create new strings in the string editor.

Finally we have the ability column. As with the skill columns in the backgrounds table these IDs correspond to entries in the ABI_base.xls file. It should be noted that race, class and background are all possible sources of starting abilities so before you decide what to put in this column you should familiarise yourself with what skills are already being added in different parts of character generation in order to ensure that you don’t duplicate an ability somewhere.

The final table is the chargen_preload table. The two columns here should exactly match the entries from the ID and Template columns of the previous table.

[[Image:back_tut_chargen_preload.png]]

{{TutorialRef|2DA|2DA#Excel file formatting|Background.xls}}

== Compiling and fixing the GDAs ==
Now compile backgrounds.xls and place the resulting GDAs into your ''AddIns\module_name\module\override'' directory.
Never place anything in your ''AddIns\module_name\core\override'' directory or it will affect other modules than the one you are editing.

There used to be a [[Bug: ExcelProcessor doesn't handle row IDs above 8.3 million correctly|bug]] that prevented large string IDs from compiling correctly. This is now fixed. For the record, the old workaround was to edit the GDA files in the toolset to correct the string IDs manually, but you should now see that the string IDs are correct.

{{TutorialRef|Compiling 2DAs|GDA}}

== Creating the backgrounds plot ==
The background plot is used for keeping track of a PC’s background and can be used to affect conversation options.

The single player game uses a plot called gen00pt_backgrounds to keep track of the PC background. You can find it in the ''\_Global\Generic'' folder of the plots tab if you want to take a look. We will create a similar plot for our custom backgrounds. Create a new plot and call it ''bdm_000pt_backgrounds'' (My naming convention is to use 000 to indicate a resource that isn’t tied to any particular area – feel free to use your own convention but remember to update any references later in the tutorial). Add main plot flags as indicated in the picture below:

[[Image:Back_tut_bg_plot.png]]

You could also add some defined flags if you wanted. Defined flags can be used to return some combination of the main flags such as TRAVELLER or add some extra condition like FEMALE_APPRENTICE or ELVEN_APPRENTICE. Defined flags are beyond the scope of this tutorial however.

{{TutorialRef|Designer Resources|Plot}}

== Creating the scripts ==
We are not going to edit any of the original core game scripts, we will only be adding new scripts of our own. As we discuss how to do this you should examine the core scripts that are referred to, but under no circumstances should you make any changes to those files. By leaving the core scripts as they are we make our modification more compatible with any future patches that may be released. If you modified the core scripts and then a patch was released that overwrote those scripts you would lose your changes. Also keeping your modification contained within your own module allows you to make different modifications to different modules within the one toolset.

Lets start off with a script to handle the character generation events that are normally handled by the module_core script. Create a new script called ''bdm_module_core''. It is up to you what directory structure to use for your scripts but it can be a good idea to keep all your scripts in a directory with your module name to make them distinct from the core scripts. Then if you are emulating the functionality of a particular core script you can mirror the original directory structure underneath your main module folder. So in this case the module_core script is contained in the ''\_Core Scripts'' folder so we will put our bdm_module_core in ''\Backgrounds demo\_Core Scripts'' (the underscore ensures the core directories come first – looks like Bioware accidentally created one without it! I’m pretty sure Core and _Core are meant to be the same directory). Organising things this way will really help with keeping track of your scripts.

The ''bdm_module_core'' script should contain the following code:

<dascript>
#include "global_objects_h"
void main(){
event ev = GetCurrentEvent();
int nEvent = GetEventType(ev); //extract event type from current event
int nEventHandled = FALSE; //keep track of whether the event has been handled
switch(nEvent){
case EVENT_TYPE_MODULE_START:{
// -----------------------------------------------------------------
// Initiate character generation.
// -----------------------------------------------------------------
PreloadCharGen(); //preloads resources for character generation
StartCharGen(GetHero(),0,TRUE); //initiates character generation
break;
}
default:
{
// -----------------------------------------------------------------
// Handle character generation events sent by the engine.
// -----------------------------------------------------------------
if ((nEvent >= EVENT_TYPE_CHARGEN_START && nEvent <= EVENT_TYPE_CHARGEN_END)
|| nEvent == EVENT_TYPE_PLAYERLEVELUP )
{
HandleEvent(ev, R"bdm_sys_chargen.ncs");
nEventHandled = TRUE;
}
break;
}

}
if (!nEventHandled) { //If this event wasn't handled by this script, let the core script try
HandleEvent(ev, RESOURCE_SCRIPT_MODULE_CORE);
}
}
</dascript>

Now go to ''file > manage modules'' and open the properties for your module and set the script property to point at this script.

Our new script handles some of the events that are usually handled by the module_core script. Once it has handled the event it chooses whether or not to pass the event on to module_core. The first event that we handle is EVENT_TYPE_MODULE_START, which is where we initiate character generation. In this case we pass the event on to the core script to handle after we have done what we need to.

NOTE : you may find that you don't need to change any other scripts. It's not clear what the scripts in the rest of this section are trying to do - see discussion.

The second thing we handle is actually a group of events. If you look in the module_core script you will see that right down the bottom in the default event handler is some code that looks just like the code we have added in our default event, with a couple of little differences. Instead of passing the character generation events to the sys_chargen.ncs script we are going to pass it to our own script called ''bdm_sys_chargen.ncs'' which we will write shortly. If we catch one of those character generation events then we want to handle it ourselves and prevent the core script from handling it so we set nEventHandled = TRUE. Note that any other event that is caught by the default handler but isn’t a character generation event is going to go straight on through to the core script.

Before we create the ''bdm_sys_chargen'' script we are going to need some new constants defined. Create a new script called ''bdm_2da_constants_h'' and put it in folder ''\Backgrounds demo\_Core Includes''. Now add the following to this script:

<dascript>
// -----------------------------------------------------------------------------
// Backgrounds - rules/backgrounds.xls
// -----------------------------------------------------------------------------
const int BACKGROUND_SERVANT = 1;
const int BACKGROUND_APPRENTICE = 2;
const int BACKGROUND_TRAVELLER = 3;
</dascript>

These constants provide a way for us to refer to the background IDs that we defined in the 2DA files without having to remember the numbers. Constants like this also make your code more readable. If you need to add more new items to 2DAs when you are modding something else you can also add constants for them here. From now on we will be using these background constants instead of the original single player background constants that you can find in the ''2da_constants_h'' script. That means we’d better find all the places where those constants are used and update them with our own scripts.

Create another new script and call it ''bdm_sys_chargen'' and put it in a folder called ''\Backgrounds demo\_Systems''. Put the following code in it:

<dascript>
#include "bdm_sys_chargen_h"
#include "log_h"

const int CHARGEN_QUICKSTART_QUICK = 0;
const int CHARGEN_QUICKSTART_NORMAL = 1;
const int CHARGEN_QUICKSTART_ADVANCED = 2;

void _RunChargen(int nRace, int nClass, object oChar, int nBackground)
{

Chargen_InitializeCharacter(oChar);
Chargen_SelectGender(oChar,GENDER_MALE);
Chargen_SelectRace(oChar,nRace);
Chargen_SelectCoreClass(oChar,nClass);
Chargen_SelectBackground(oChar, nBackground,FALSE);

int nEquipIdx = Chargen_GetEquipIndex(nRace, nClass, nBackground);
Chargen_InitInventory(oChar,0,nEquipIdx);
Chargen_SpendAttributePoints(oChar,PROPERTY_ATTRIBUTE_STRENGTH, 3,FALSE);
Chargen_SpendAttributePoints(oChar,PROPERTY_ATTRIBUTE_DEXTERITY, 2,FALSE);

}

void main(){
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev);
object oChar = GetEventObject(ev,0);

int nMode;
int nInt0 = GetEventInteger(ev,0);
int nInt1 = GetEventInteger(ev,1);
// -------------------------------------------------------------------------
// Debug Data.
// -------------------------------------------------------------------------
Log_Trace(LOG_CHANNEL_EVENTS_CHARGEN,"bdm_sys_chargen","Chargen Event:" + Log_GetEventNameById (nEventType)
+ " " + ToString(nInt0) + "," + ToString(nInt1), oChar);

int nEventHandled = FALSE;

switch (nEventType)
{
// ----------------------------------------------------------------------
// This fires when the player selects the icon corresponding to any of
// the available backgrounds
//
// nInt0 - Constant BACKGROUND_* integer
// ----------------------------------------------------------------------
case EVENT_TYPE_CHARGEN_SELECT_BACKGROUND: {
int nBackground = nInt0;
// -----------------------------------------------------------------
// Set the background on the player and reinitialize plot flags
// for the background
// -----------------------------------------------------------------
Chargen_InitializeCharacter(oChar,TRUE);
Chargen_SelectGender(oChar,GetCreatureGender(oChar));
Chargen_SelectRace(oChar,GetCreatureRacialType(oChar));
Chargen_SelectCoreClass(oChar,GetCreatureCoreClass(oChar));

bdm_Chargen_SelectBackground(oChar, nBackground, FALSE);
bdm_Chargen_SetupPlotFlags(oChar);

// -----------------------------------------------------------------
// Generate the index into the equipment template 2da and
// then load the starting equipment based on the data returned.
// -----------------------------------------------------------------
int nClass = GetCreatureCoreClass(oChar);
int nRace = GetCreatureRacialType(oChar);
int nEquipIdx = Chargen_GetEquipIndex(nRace, nClass, nBackground);
Chargen_InitInventory(oChar,0,nEquipIdx);
nEventHandled = TRUE;
break;
}
case EVENT_TYPE_CHARGEN_END: {
nMode = nInt0;
int nQuickStart = nInt1;
// 0 - quickstart
// 1 - normal \
// 2 - advanced / treat as the same
Log_Trace(LOG_CHANNEL_CHARACTER,"bdm_sys_chargen","MODE: " + IntToString(nMode)
+ ", Quick Start: " + IntToString(nQuickStart));
if (nMode == CHARGEN_MODE_CREATE && nQuickStart == CHARGEN_QUICKSTART_QUICK){
Log_Trace(LOG_CHANNEL_CHARACTER,"bdm_sys_chargen","Setting default values for player character");

int nRandClass = abs((GetLowResTimer()%3)+1);

if(nRandClass == CLASS_ROGUE || nRandClass == CLASS_WARRIOR)
{
_RunChargen(RACE_HUMAN, nRandClass, oChar, BACKGROUND_SERVANT );

WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_SERVANT, TRUE);
}
else // mage
{
_RunChargen(RACE_HUMAN, nRandClass, oChar, BACKGROUND_APPRENTICE );
WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_APPRENTICE, TRUE);
}
Chargen_SetNumTactics(oChar);
SetCanLevelUp(oChar,Chargen_HasPointsToSpend(oChar));
SendEventModuleChargenDone("", "");
nEventHandled = TRUE;
}
break;
}
} //end switch

if (!nEventHandled){
HandleEvent(ev, R"sys_chargen.ncs");
}

}
</dascript>

There are two events in the original sys_chargen script that we need to replace because they deal with backgrounds. The first of these is EVENT_TYPE_CHARGEN_SELECT_BACKGROUND and the other is EVENT_TYPE_CHARGEN_END. For the second event we only need to change the case where the character is being created in quickstart mode, so we just handle that section of the code. The objective here is to change only as much as we need to and then pass any remaining events through to the original sys_chargen script. Take some time to compare the new script with Bioware’s ''sys_chargen'' script .

You will notice that we include a script called ''bdm_sys_chargen_h'' and that we use some functions with a ''bdm_'' prefix. Those functions are contained in that include file which we’ll write now. Essentially these are modifications of a couple of functions from the ''sys_chargen_h'' include file. Create a new script and call it ''bdm_sys_chargen_h''. Put it in folder ''\Backgrounds demo\_Systems\Includes'' and add the following code:

<dascript>
#include "sys_chargen_h"
#include "bdm_2da_constants_h"
#include "wrappers_h"
#include "plt_bdm_000pt_backgrounds"

void bdm_Chargen_SelectBackground(object oChar, int nBackground, int bUnApply = FALSE)
{
Log_Chargen("bdm_Chargen_SelectBackground","-- " + (bUnApply?"Un":"") +"Selecting BG: " + ToString(nBackground),oChar);
// -------------------------------------------------------------------------
// 1. Set the background variable
// - Create creature property (or check what we used so far
// - We don't set backgrounds on non player generated chars.
// -------------------------------------------------------------------------
if (bUnApply)
{
SetCreatureProperty(oChar, PROPERTY_SIMPLE_BACKGROUND, 0.0, PROPERTY_VALUE_BASE);
}
else
{
SetCreatureProperty(oChar, PROPERTY_SIMPLE_BACKGROUND, IntToFloat(nBackground), PROPERTY_VALUE_BASE);
}
// -------------------------------------------------------------------------
// 2. Give one skill
// - retrieve the skill that is granted by the background from backgrounds.xls
// - give it to the player.
// -------------------------------------------------------------------------
int nAbility = ChargenGetBackgroundSkill(GetCreatureRacialType(oChar), nBackground);
if (nAbility)
{
_AddAbility (oChar, nAbility, bUnApply);
}
}

void bdm_Chargen_SetupPlotFlags(object oChar)
{
int nRace = GetCreatureRacialType(oChar);
int nBackground = GetPlayerBackground(oChar);

Log_Trace(LOG_CHANNEL_CHARACTER,"bdm_sys_chargen_h","Setting plot flags, race: "
+ IntToString(nRace) + ", background: " + IntToString(nBackground));

// First, init all flags (debug setup)
WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_SERVANT,FALSE);
WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_APPRENTICE,FALSE);
WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_DWARF_TRAVELLER,FALSE);
WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_ELF_TRAVELLER,FALSE);

switch (nBackground)
{
case BACKGROUND_SERVANT:
{
WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_SERVANT,TRUE); break;
break;
}
case BACKGROUND_APPRENTICE:
{
WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_APPRENTICE,TRUE); break;
break;
}
case BACKGROUND_TRAVELLER:
{
switch(nRace)
{
case RACE_DWARF: WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_DWARF_TRAVELLER,TRUE); break;
case RACE_ELF: WR_SetPlotFlag(PLT_BDM_000PT_BACKGROUNDS, BDM_GEN_BACK_ELF_TRAVELLER,TRUE); break;
}
break;
}
}
}
</dascript>

Lets examine these two functions. First you should compare them to their original versions. For ''bdm_Chargen_SelectBackground()'' we have actually made a more generic version of the function that should work with any backgrounds. We have removed the hard coded values for the background abilities and now use the function ChargenGetBackgroundSkill() which actually gets the background skill from the backgrounds 2DA file that we edited earlier (recall the last three columns that give a skill depending on background and race). If you need fancier logic than just reading the values form the GDA (e.g. like Bioware’s logic for the Noble background) then you can always go back to hard coding them the way Bioware did.

The second function is ''bdm_Chargen_SetupPlotFlags()'' which does just what it says. Remember the plot we created earlier? Here we set the appropriate flag based on race and background.

{{TutorialRef|Script}}

== Testing that everything works ==
Now compile your scripts and export your module. Also, make sure that you export your talk table.

'''IMPORTANT!''' ''Always make sure you empty your \Dragon Age\packages\core\override folder after doing an export. Due to a bug in the current toolset your single player game will become damaged if you don’t do this before playing.''

You should now be able to run your game and see the backgrounds you created appear in character generation. If you want to test that the background plots have been set correctly, add an NPC to the start area and create a conversation for them in which each line is switched according to a background plot flag. You can also check that the character is receiving the abilities that we set in the 2DAs.

'''NOTE''' ''There seems to be no way to change the popup message that comes up at the beginning of character generation. Altering the Pre-chargen string ID in the loadhints GDA does not seem to do anything.''

{{TutorialRef|Exporting a module}}

== Optional extras ==
There are a couple of other Bioware scripts that reference the background constants. They are not essential to modify because they are not used anywhere by default. The genev_tutorial script uses a background check but unless you plan on firing the tutorial from your module then you won’t have need of it. Also there is at least one debug script that makes use of the original single player backgrounds (to grant a background plot flag to the PC) so if you want similar debug functionality you may have to roll your own function.

== Race & Gender descriptions ==
If your module is not set in Ferelden, you may wish to change the descriptions of the Race and Gender buttons that appear during Character Creation.

The Race descriptions are in the Description column of the RACE_base 2DA, so you can replace them with new strings. As before, until the bug is fixed, use a string id in the 100000000 range.

Unfortunately, the gender description is hard-coded in the game as string id 377283. Fortunately, you can make a [[String_editor#Editing_a_string_with_a_specific_id | local version]] of this string, which only applies to your campaign.

Alternatively, if you an advanced user who is familar with the [[UI_Tutorial_%28draft%29 | UI Tutorial]], it's set in the GUI's Localization.as file as LOC_GENDER_DESCRIPTION = 377283, which is then used in the RaceGenderScene.as file. after editing the Localization.as file, you compile it and inject it into the appropriate .gfx'es.

== Conclusion ==
In this tutorial we have demonstrated a way to modify the backgrounds used in the game without altering any of the core scripts. It is expected that a similar approach could be taken to modding other aspects of the game such as adding classes or races. In these cases the scripts that were created in this tutorial could be extended to handle other parts of the character generation process such as class and race selection.

[[Category:Character generation]]
[[Category:Tutorials]]

Bug: Custom Placeables appear/disapear randomly

2011-04-06T06:38:53Z

Proleric1: /* Workarounds */

*'''Version found:''' 1.0.1008.0
*'''Status:''' Open

== Description ==
Custom Placeables appear/disappear randomly from the game between area exports from the Toolset. Sometimes when opening an area in the toolset an error message is printed in the log "''E: 16:31:34 - Could not get the name for the appearance: Resource "keystone.utp", Tag "keystone".''". Usually restarting the Toolset will make the error to go away but it's usual that a placeable doesn't appear in the game evenif there were no errors during export. Sometimes everything is working perfectly fine. Also the same error is sometimes displayed for Creatures using a custom appearance.

The problem will only appear with custom placeables/appearances those are brought to the toolset using the 2DA "system" like ''placeable_types_myplaceables.GDA'' or ''APR_myappearances.GDA''. I would presume that the Toolset somehow fails to collect and combine all these GDAs.

If the Toolset manage to export everything properly, I don't recall seeing anything to disappear from the game when restarting or reloading a saved game. I am aware of that some modifications doesn't appear in the game unless restart the module from a "clean table". But that's not the problem here.

== Workarounds ==
Restarting the Toolset before exporting anything will reduce the frequency of the problem and improves a chance of successful export.

This may well be a special case of the [[Bug:_Toolset_loses_M2DA_dropdown_selection,_resets_to_default | M2DA dropdown bug]]. Close the toolset as soon as the error message is encountered, and export the resource affected again on reopening.

[[Category:Toolset bugs]]

Bug: Custom Placeables appear/disapear randomly

2011-04-06T06:38:35Z

Proleric1:

*'''Version found:''' 1.0.1008.0
*'''Status:''' Open

== Description ==
Custom Placeables appear/disappear randomly from the game between area exports from the Toolset. Sometimes when opening an area in the toolset an error message is printed in the log "''E: 16:31:34 - Could not get the name for the appearance: Resource "keystone.utp", Tag "keystone".''". Usually restarting the Toolset will make the error to go away but it's usual that a placeable doesn't appear in the game evenif there were no errors during export. Sometimes everything is working perfectly fine. Also the same error is sometimes displayed for Creatures using a custom appearance.

The problem will only appear with custom placeables/appearances those are brought to the toolset using the 2DA "system" like ''placeable_types_myplaceables.GDA'' or ''APR_myappearances.GDA''. I would presume that the Toolset somehow fails to collect and combine all these GDAs.

If the Toolset manage to export everything properly, I don't recall seeing anything to disappear from the game when restarting or reloading a saved game. I am aware of that some modifications doesn't appear in the game unless restart the module from a "clean table". But that's not the problem here.

== Workarounds ==
Restarting the Toolset before exporting anything will reduce the frequency of the problem and improves a chance of successful export.

This may well be a special case of the [Bug:_Toolset_loses_M2DA_dropdown_selection,_resets_to_default | M2DA dropdown bug]. Close the toolset as soon as the error message is encountered, and export the resource affected again on reopening.

[[Category:Toolset bugs]]

Scripting overview

2011-04-05T14:48:07Z

Proleric1: /* Searching Scripts */

{{Infobox script}}

Scripting is used whenever the designers need control over the game's behaviour. The syntax for DA scripts is very similar to the C programming language.

Detailed documentation for the scripting language can be found in the "dascript.chm" file, available in your "Dragon Age\packages\core" directory.

The main uses for it are to:

*Trigger plot events
*Script conversation
*Handle creature and party member [[AI]]
*Script abilities - skills, talents, and spells

DA also has a client-side scripting language whose primary responsibility is automated testing of the game. See [[client script]]s for more details.

AI Scripts are event based. Objects will have only one event-handling script assigned to them that will be run whenever they receive a game event. This script will receive the event type as a parameter and will need to determine the appropriate response for itself.

There are several file extensions associated with scripts:
* NSS - script source file
* NCS - compiled script
* NDB - debug information file (required for using the script debugger to trace through this file)

== Script editor ==

Scripts are created in the Designer Toolset using the Script Editor. Once created, scripts must be assigned to such things as Creatures before they can be used. Once assigned, both the referencing object and the script must be exported in order to be viewed in the game. Exporting happens automatically or can be done manually by the designer during testing.

The script editor supports the following features:

*Undo and redo
*Find and replace
*Bookmarking: View -> Other Windows -> Bookmarks
*Function, variable, constant, and template browser (visible on the right-hand side of the screen).
*Auto-complete when typing function and variable names
*Syntax highlighting
*Auto-indention
*Brace matching/highlighting
*Ability to test compile a script
*Jump to definition

To the right of the script editor is a sidebar with a browser that can display all currently-defined functions, variables, or constants, or a set of 'template' scripts that can serve as a starting point when writing a script from scratch. The browser also has a filter field where you can type in a partial string and have the list automatically exclude everything that doesn't include it in the name.

This is the constant browser:

[[Image:Scripting constant browser.png]]

Here it is with "team" typed into the filter field, displaying only constants with names that contain the substring "team" (not case sensitive):

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

The templates that come with Dragon Age include frameworks for the most common event scripts found in the game. You can add your own templates quite easily, just create a text file with the template code in it and place it in the Dragon Age\Toolset\scripttemplates directory with the others.

[[Image:scripting template browser.png]]

Dragon Age's toolset supports Doxygen-style comments. If you double-click on a function name a help window will pop open to display its documentation. You can also jump to a function's definition (provided it isn't an engine-defined function in script.ldf) by right-clicking on it and selecting "go to definition".

[[Image:Scripting help window.png]]

== Writing scripts ==

For a script to compile, it needs a body:
<dascript>
void main()
{
}
</dascript>
The parameters on this can't be changed or the script won't compile.

Scripts associated with a dialog node take this alternate form:
<dascript>
int StartingConditional()
{
return 1;
}
</dascript>

=== Including files ===
Other script files can be included by using the #include directive.
<dascript>
#include "rules_h"

void main()
{
DoSomethingOrOther();
}
</dascript>
The included file is '''inserted''' into the main file before the script is compiled. Any number of files can be included.
'''Important:''' this means that whenever you change an "include file" you must export all script that include it before they will use the new version!

No other C-style preprocessor commands are supported.

=== Operators ===

The scripting language supports the following operators:

====Arithmetic Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Prefix Increment
| <dascript>while ( ++a < 10) { }</dascript>
|-
| Postfix Increment
| <dascript> for (i = 0; i < 10; i++) { } </dascript>
|-
| Assignment by addition
| <dascript>a += b;</dascript>
|-
| Subtraction (difference)
| <dascript>x = a - b;</dascript>
|-
| Addition (sum)
| <dascript>x = a + b;</dascript>
|-
| Prefix decrement
| <dascript>while (--a > 10) { }</dascript>
|-
| Postfix decrement
| <dascript>while (a-- > 10) { }</dascript>
|-
| Assignment by subtraction
| <dascript>a -= b;</dascript>
|-
| Multiplication (product)
| <dascript>x = a * b;</dascript>
|-
| Division (quotient)
| <dascript>x = a / b;</dascript>
|-
| Modulo (remainder)
| <dascript>if (a % b == 1) { }</dascript>
|}

====Comparison Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Less than
| <dascript>if (a < b) { }</dascript>
|-
| Less than or equal to
| <dascript>if (a <= b) { }</dascript>
|-
| Greater than
| <dascript>if (a > b) { }</dascript>
|-
| Greater than or equal to
| <dascript>if (a >= b) { }</dascript>
|-
| Not Equal to
| <dascript>if (a != b) { }</dascript>
|-
| Equal to
| <dascript>if (a == b) { }</dascript>
|}

====Logical Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Logical negation (NOT)
| <dascript>if (!a) { }</dascript>
|-
| Logical AND
| <dascript>if (a && b) { }</dascript>
|-
| Logical OR
| <dascript>if (a || b) { }</dascript>
|}

====Other Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Basic assignment
| <dascript>a = b;</dascript>
|-
| Function call
| <dascript>a();</dascript>
|-
| Array subscript
| <dascript>array[0] = 1;</dascript>
|-
| Member (on structures)
| <dascript>structure.member = 0;</dascript>
|-
| Ternary conditional
| <dascript>return a 
|}
=== Types & Variable ===

The scripting language natively supports:
* [[float]] - floating-point numbers. <dascript>float fFloat = 0.1234f;</dascript>
* [[int]] - integer numbers. <dascript>int nInteger = 1234;</dascript>
* [[object]] -game object files. <dascript>object oObject = GetObjectByTag("monster_001");</dascript>
* [[resource]] - game resource files. <dascript>resource rGameIntroCutscene = R"game_intro_.cut";</dascript>
* [[string]] - text strings. <dascript>string sString = "Hello World!";</dascript>
* [[vector]] - positions or directions. <dascript>vector vVector = Vector(0.0, 1.1, 2.2);</dascript>

The server language has been expanded to support these engine defined structures:
* [[Event (dascript type)|event]] - events are signals that are sent to scripts by other scripts or by the world engine.
* [[location]]
* [[command]] - a command for a creature or object to do something. Commands are constructed using functions that return them, and then are added to a target's command queue with the AddCommand function.
* [[effect]]
* [[itemproperty]]
* [[player]]

All of these types are always passed by value, which means a new copy is made whenever they are passed into a function or copied to another variable.

This means that most functions that are supposed to modify a structure in some way need to return the modified one:

<dascript>
void main()
{
effect e1 = Effect(100);
effect e2 = SetEffectType(e1, 101); // e1 != e2
}
</dascript>

==== Structures ====

Users can define their own structures using the [[struct]] keyword:

<dascript>
// user-defined type
struct quaternion
{
float w, x, y, z;
};

// constructor
struct quaternion Quaternion(float fW, float fX, float fY, float fZ)
{
struct quaternion q;

q.w = fW;
q.x = fX;
q.y = fY;
q.z = fZ;

return q;
}

void main()
{
struct quaternion q = Quaternion(0.0, 0.0, 0.0, 0.0);
}
</dascript>

==== Arrays ====
Variables can be declared as arrays for any type except user-defined structs. Designers can create their own arrays of any major data type (int, string, object). Many functions will also return arrays (for example, creatures in an area will be returned as an array, and the action queue will be returned as an array).

These are different from C-style arrays in that they can be resized like STL vectors, and their notation is slightly different.

Arrays also behave differently from other objects in the scripting language because they are passed by reference. If an array is passed into a function and modified:

<dascript>
void main()
{
int[] i; // new array of integers with a size of zero
i[0] = 5; // value of array position 0 is now 5
i[1] = -1; // value of array position 1 is now -1

int[] j = i; // i and j point to the same array
j[1] = 12; // value of array position 1 for both i and j is now 12!

SortArrayDescending(i); // i and j are both sorted now, this function has no return value
}
</dascript>

[[GetArraySize]] returns the size of an array.

==== Local Variables ====

In Neverwinter Nights, variables for various objects could be created and set with functions such as SetLocalInt(). Dragon Age does not have analogous functions. Instead, all of the variables that a given object is able to have values assigned to must be defined ahead of time in a 2DA. This more restrictive approach is intended to improve performance and reduce the opportunity for errors (for example, making a typo in the name of a variable and losing track of it as a result).

=== Functions ===

There are two ways to discover a function and what it does.

If you type in the name of a function that's been defined and then an opening bracket, a tooltip will pop up showing the function's parameter types and return type.

Alternately, if you have the help window open (View -> Other Windows -> Help Window), then whenever you select a function in the function browser a help page describing the function will be displayed.

=== Passing parameters to scripts ===

To pass parameters to scripts they must be called with the 'runscript' command. This can be useful for writing debug scripts or changing actions based on input. To accept parameters simply add this line to your script:

<dascript>
string sParams = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
</dascript>

You can then type 'runscript scriptname parameter1 parameter2 ... paramaterN' to pass parameters.

Some examples:

<dascript>

// Debug script: heals the object with the given tag. If tag is invalid, nothing happens
void main()
{

string sTag = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
object oCreature = GetObjectByTag(sTag);
effect eHeal = EffectHeal(25.0f)
//ApplyEffect...
}

</dascript>

<dascript>

// Debug script: applies the visual effect passed in as parameter to the player
void main()
{

string sEffect = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
int nEffect = StringToInt(sEffect);
effect eVfx = EffectVisualEffect(nEffect);
//ApplyEffect...
}

</dascript>

=== Error messages and logging ===

See [[Script error]] for details of how to correct errors in scripts.

To enable script logging, edit or create <DragonAgeInstallDirectory>\bin_ship\[[ECLog.ini]] and set Script=1 in the [LogTypes] section.

The [[PrintToLog]] function prints messages to the log file once logging is enabled.

== Timing ==

Commands, delayed events and object destruction all take place after the current script is finished running. Plot flags set in script are set in-line but the triggered plot script runs before the flag is actually set (this is clarified a bit in the plot script template).

Given that ExecuteScript is deprecated, HandleEvent should be used when you want the script to run in-line and DelayEvent should be used when you want to delay execution.

To delay execution when dealing with creatures, custom AI and (safe) command complete are nice tools. DelayEvent should be used whenever you know how long you want to wait before the event fires. (It can also be used in quite small time increments to give the illusion of smoothly sliding placeables with SetPosition or interpolate between two different atmosphere/lighting settings, but the overhead of this is noticeable if overused).

== Searching Scripts ==

To find examples of how Bioware does things, or simply to discover where a function or variable is used, it's useful to be able to search all the scripts in the data base for a string.

You'll need Microsoft SQL Server Management Studio Express - see [[Preparing_a_dialog_for_recording | Preparing a dialog for recording
]].

Enter the following query:

SELECT DISTINCT Module.Name, Resource.Name
FROM [bw_dragonage_content].[dbo].[t_Module] Module,
[bw_dragonage_content].[dbo].[t_ModuleResRefVersion] Resource,
[bw_dragonage_content].[dbo].[t_Script] Script
WHERE Module.ID = Resource.ModuleID
AND Resource.ID = Script.ModuleResRefVersionID
AND Script.Text LIKE '%######%'
ORDER BY 1, 2;

where ###### is the string you want to find.

This will list the name of every script that contains the string ######.
[[Category:Scripts]]
{{Languages}}

Scripting overview

2011-04-05T14:14:36Z

Proleric1: /* Searching Scripts */

{{Infobox script}}

Scripting is used whenever the designers need control over the game's behaviour. The syntax for DA scripts is very similar to the C programming language.

Detailed documentation for the scripting language can be found in the "dascript.chm" file, available in your "Dragon Age\packages\core" directory.

The main uses for it are to:

*Trigger plot events
*Script conversation
*Handle creature and party member [[AI]]
*Script abilities - skills, talents, and spells

DA also has a client-side scripting language whose primary responsibility is automated testing of the game. See [[client script]]s for more details.

AI Scripts are event based. Objects will have only one event-handling script assigned to them that will be run whenever they receive a game event. This script will receive the event type as a parameter and will need to determine the appropriate response for itself.

There are several file extensions associated with scripts:
* NSS - script source file
* NCS - compiled script
* NDB - debug information file (required for using the script debugger to trace through this file)

== Script editor ==

Scripts are created in the Designer Toolset using the Script Editor. Once created, scripts must be assigned to such things as Creatures before they can be used. Once assigned, both the referencing object and the script must be exported in order to be viewed in the game. Exporting happens automatically or can be done manually by the designer during testing.

The script editor supports the following features:

*Undo and redo
*Find and replace
*Bookmarking: View -> Other Windows -> Bookmarks
*Function, variable, constant, and template browser (visible on the right-hand side of the screen).
*Auto-complete when typing function and variable names
*Syntax highlighting
*Auto-indention
*Brace matching/highlighting
*Ability to test compile a script
*Jump to definition

To the right of the script editor is a sidebar with a browser that can display all currently-defined functions, variables, or constants, or a set of 'template' scripts that can serve as a starting point when writing a script from scratch. The browser also has a filter field where you can type in a partial string and have the list automatically exclude everything that doesn't include it in the name.

This is the constant browser:

[[Image:Scripting constant browser.png]]

Here it is with "team" typed into the filter field, displaying only constants with names that contain the substring "team" (not case sensitive):

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

The templates that come with Dragon Age include frameworks for the most common event scripts found in the game. You can add your own templates quite easily, just create a text file with the template code in it and place it in the Dragon Age\Toolset\scripttemplates directory with the others.

[[Image:scripting template browser.png]]

Dragon Age's toolset supports Doxygen-style comments. If you double-click on a function name a help window will pop open to display its documentation. You can also jump to a function's definition (provided it isn't an engine-defined function in script.ldf) by right-clicking on it and selecting "go to definition".

[[Image:Scripting help window.png]]

== Writing scripts ==

For a script to compile, it needs a body:
<dascript>
void main()
{
}
</dascript>
The parameters on this can't be changed or the script won't compile.

Scripts associated with a dialog node take this alternate form:
<dascript>
int StartingConditional()
{
return 1;
}
</dascript>

=== Including files ===
Other script files can be included by using the #include directive.
<dascript>
#include "rules_h"

void main()
{
DoSomethingOrOther();
}
</dascript>
The included file is '''inserted''' into the main file before the script is compiled. Any number of files can be included.
'''Important:''' this means that whenever you change an "include file" you must export all script that include it before they will use the new version!

No other C-style preprocessor commands are supported.

=== Operators ===

The scripting language supports the following operators:

====Arithmetic Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Prefix Increment
| <dascript>while ( ++a < 10) { }</dascript>
|-
| Postfix Increment
| <dascript> for (i = 0; i < 10; i++) { } </dascript>
|-
| Assignment by addition
| <dascript>a += b;</dascript>
|-
| Subtraction (difference)
| <dascript>x = a - b;</dascript>
|-
| Addition (sum)
| <dascript>x = a + b;</dascript>
|-
| Prefix decrement
| <dascript>while (--a > 10) { }</dascript>
|-
| Postfix decrement
| <dascript>while (a-- > 10) { }</dascript>
|-
| Assignment by subtraction
| <dascript>a -= b;</dascript>
|-
| Multiplication (product)
| <dascript>x = a * b;</dascript>
|-
| Division (quotient)
| <dascript>x = a / b;</dascript>
|-
| Modulo (remainder)
| <dascript>if (a % b == 1) { }</dascript>
|}

====Comparison Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Less than
| <dascript>if (a < b) { }</dascript>
|-
| Less than or equal to
| <dascript>if (a <= b) { }</dascript>
|-
| Greater than
| <dascript>if (a > b) { }</dascript>
|-
| Greater than or equal to
| <dascript>if (a >= b) { }</dascript>
|-
| Not Equal to
| <dascript>if (a != b) { }</dascript>
|-
| Equal to
| <dascript>if (a == b) { }</dascript>
|}

====Logical Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Logical negation (NOT)
| <dascript>if (!a) { }</dascript>
|-
| Logical AND
| <dascript>if (a && b) { }</dascript>
|-
| Logical OR
| <dascript>if (a || b) { }</dascript>
|}

====Other Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Basic assignment
| <dascript>a = b;</dascript>
|-
| Function call
| <dascript>a();</dascript>
|-
| Array subscript
| <dascript>array[0] = 1;</dascript>
|-
| Member (on structures)
| <dascript>structure.member = 0;</dascript>
|-
| Ternary conditional
| <dascript>return a 
|}
=== Types & Variable ===

The scripting language natively supports:
* [[float]] - floating-point numbers. <dascript>float fFloat = 0.1234f;</dascript>
* [[int]] - integer numbers. <dascript>int nInteger = 1234;</dascript>
* [[object]] -game object files. <dascript>object oObject = GetObjectByTag("monster_001");</dascript>
* [[resource]] - game resource files. <dascript>resource rGameIntroCutscene = R"game_intro_.cut";</dascript>
* [[string]] - text strings. <dascript>string sString = "Hello World!";</dascript>
* [[vector]] - positions or directions. <dascript>vector vVector = Vector(0.0, 1.1, 2.2);</dascript>

The server language has been expanded to support these engine defined structures:
* [[Event (dascript type)|event]] - events are signals that are sent to scripts by other scripts or by the world engine.
* [[location]]
* [[command]] - a command for a creature or object to do something. Commands are constructed using functions that return them, and then are added to a target's command queue with the AddCommand function.
* [[effect]]
* [[itemproperty]]
* [[player]]

All of these types are always passed by value, which means a new copy is made whenever they are passed into a function or copied to another variable.

This means that most functions that are supposed to modify a structure in some way need to return the modified one:

<dascript>
void main()
{
effect e1 = Effect(100);
effect e2 = SetEffectType(e1, 101); // e1 != e2
}
</dascript>

==== Structures ====

Users can define their own structures using the [[struct]] keyword:

<dascript>
// user-defined type
struct quaternion
{
float w, x, y, z;
};

// constructor
struct quaternion Quaternion(float fW, float fX, float fY, float fZ)
{
struct quaternion q;

q.w = fW;
q.x = fX;
q.y = fY;
q.z = fZ;

return q;
}

void main()
{
struct quaternion q = Quaternion(0.0, 0.0, 0.0, 0.0);
}
</dascript>

==== Arrays ====
Variables can be declared as arrays for any type except user-defined structs. Designers can create their own arrays of any major data type (int, string, object). Many functions will also return arrays (for example, creatures in an area will be returned as an array, and the action queue will be returned as an array).

These are different from C-style arrays in that they can be resized like STL vectors, and their notation is slightly different.

Arrays also behave differently from other objects in the scripting language because they are passed by reference. If an array is passed into a function and modified:

<dascript>
void main()
{
int[] i; // new array of integers with a size of zero
i[0] = 5; // value of array position 0 is now 5
i[1] = -1; // value of array position 1 is now -1

int[] j = i; // i and j point to the same array
j[1] = 12; // value of array position 1 for both i and j is now 12!

SortArrayDescending(i); // i and j are both sorted now, this function has no return value
}
</dascript>

[[GetArraySize]] returns the size of an array.

==== Local Variables ====

In Neverwinter Nights, variables for various objects could be created and set with functions such as SetLocalInt(). Dragon Age does not have analogous functions. Instead, all of the variables that a given object is able to have values assigned to must be defined ahead of time in a 2DA. This more restrictive approach is intended to improve performance and reduce the opportunity for errors (for example, making a typo in the name of a variable and losing track of it as a result).

=== Functions ===

There are two ways to discover a function and what it does.

If you type in the name of a function that's been defined and then an opening bracket, a tooltip will pop up showing the function's parameter types and return type.

Alternately, if you have the help window open (View -> Other Windows -> Help Window), then whenever you select a function in the function browser a help page describing the function will be displayed.

=== Passing parameters to scripts ===

To pass parameters to scripts they must be called with the 'runscript' command. This can be useful for writing debug scripts or changing actions based on input. To accept parameters simply add this line to your script:

<dascript>
string sParams = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
</dascript>

You can then type 'runscript scriptname parameter1 parameter2 ... paramaterN' to pass parameters.

Some examples:

<dascript>

// Debug script: heals the object with the given tag. If tag is invalid, nothing happens
void main()
{

string sTag = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
object oCreature = GetObjectByTag(sTag);
effect eHeal = EffectHeal(25.0f)
//ApplyEffect...
}

</dascript>

<dascript>

// Debug script: applies the visual effect passed in as parameter to the player
void main()
{

string sEffect = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
int nEffect = StringToInt(sEffect);
effect eVfx = EffectVisualEffect(nEffect);
//ApplyEffect...
}

</dascript>

=== Error messages and logging ===

See [[Script error]] for details of how to correct errors in scripts.

To enable script logging, edit or create <DragonAgeInstallDirectory>\bin_ship\[[ECLog.ini]] and set Script=1 in the [LogTypes] section.

The [[PrintToLog]] function prints messages to the log file once logging is enabled.

== Timing ==

Commands, delayed events and object destruction all take place after the current script is finished running. Plot flags set in script are set in-line but the triggered plot script runs before the flag is actually set (this is clarified a bit in the plot script template).

Given that ExecuteScript is deprecated, HandleEvent should be used when you want the script to run in-line and DelayEvent should be used when you want to delay execution.

To delay execution when dealing with creatures, custom AI and (safe) command complete are nice tools. DelayEvent should be used whenever you know how long you want to wait before the event fires. (It can also be used in quite small time increments to give the illusion of smoothly sliding placeables with SetPosition or interpolate between two different atmosphere/lighting settings, but the overhead of this is noticeable if overused).

== Searching Scripts ==

To find examples of how Bioware does things, or simply to discover where a function or variable is used, it's useful to be able to search all the scripts in the data base for a string.

You'll need Microsoft SQL Server Management Studio Express - see [[Preparing_a_dialog_for_recording | Preparing a dialog for recording
]].

Enter the following query:

SELECT DISTINCT Module.Name, Resource.Name
FROM [bw_dragonage_content].[dbo].[t_Module] Module,
[bw_dragonage_content].[dbo].[t_ModuleResRefVersion] Resource,
[bw_dragonage_content].[dbo].[t_Script] Script
WHERE Module.ID = Resource.ModuleID
AND Resource.ID = Script.ModuleResRefVersionID
AND Script.Text LIKE '%partypicker%'
ORDER BY 1, 2;

where ###### is the string you want to find.

This will list the name of every script that contains the string ######.
[[Category:Scripts]]
{{Languages}}

Scripting overview

2011-04-05T11:32:37Z

Proleric1: /* Searching Scripts */

{{Infobox script}}

Scripting is used whenever the designers need control over the game's behaviour. The syntax for DA scripts is very similar to the C programming language.

Detailed documentation for the scripting language can be found in the "dascript.chm" file, available in your "Dragon Age\packages\core" directory.

The main uses for it are to:

*Trigger plot events
*Script conversation
*Handle creature and party member [[AI]]
*Script abilities - skills, talents, and spells

DA also has a client-side scripting language whose primary responsibility is automated testing of the game. See [[client script]]s for more details.

AI Scripts are event based. Objects will have only one event-handling script assigned to them that will be run whenever they receive a game event. This script will receive the event type as a parameter and will need to determine the appropriate response for itself.

There are several file extensions associated with scripts:
* NSS - script source file
* NCS - compiled script
* NDB - debug information file (required for using the script debugger to trace through this file)

== Script editor ==

Scripts are created in the Designer Toolset using the Script Editor. Once created, scripts must be assigned to such things as Creatures before they can be used. Once assigned, both the referencing object and the script must be exported in order to be viewed in the game. Exporting happens automatically or can be done manually by the designer during testing.

The script editor supports the following features:

*Undo and redo
*Find and replace
*Bookmarking: View -> Other Windows -> Bookmarks
*Function, variable, constant, and template browser (visible on the right-hand side of the screen).
*Auto-complete when typing function and variable names
*Syntax highlighting
*Auto-indention
*Brace matching/highlighting
*Ability to test compile a script
*Jump to definition

To the right of the script editor is a sidebar with a browser that can display all currently-defined functions, variables, or constants, or a set of 'template' scripts that can serve as a starting point when writing a script from scratch. The browser also has a filter field where you can type in a partial string and have the list automatically exclude everything that doesn't include it in the name.

This is the constant browser:

[[Image:Scripting constant browser.png]]

Here it is with "team" typed into the filter field, displaying only constants with names that contain the substring "team" (not case sensitive):

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

The templates that come with Dragon Age include frameworks for the most common event scripts found in the game. You can add your own templates quite easily, just create a text file with the template code in it and place it in the Dragon Age\Toolset\scripttemplates directory with the others.

[[Image:scripting template browser.png]]

Dragon Age's toolset supports Doxygen-style comments. If you double-click on a function name a help window will pop open to display its documentation. You can also jump to a function's definition (provided it isn't an engine-defined function in script.ldf) by right-clicking on it and selecting "go to definition".

[[Image:Scripting help window.png]]

== Writing scripts ==

For a script to compile, it needs a body:
<dascript>
void main()
{
}
</dascript>
The parameters on this can't be changed or the script won't compile.

Scripts associated with a dialog node take this alternate form:
<dascript>
int StartingConditional()
{
return 1;
}
</dascript>

=== Including files ===
Other script files can be included by using the #include directive.
<dascript>
#include "rules_h"

void main()
{
DoSomethingOrOther();
}
</dascript>
The included file is '''inserted''' into the main file before the script is compiled. Any number of files can be included.
'''Important:''' this means that whenever you change an "include file" you must export all script that include it before they will use the new version!

No other C-style preprocessor commands are supported.

=== Operators ===

The scripting language supports the following operators:

====Arithmetic Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Prefix Increment
| <dascript>while ( ++a < 10) { }</dascript>
|-
| Postfix Increment
| <dascript> for (i = 0; i < 10; i++) { } </dascript>
|-
| Assignment by addition
| <dascript>a += b;</dascript>
|-
| Subtraction (difference)
| <dascript>x = a - b;</dascript>
|-
| Addition (sum)
| <dascript>x = a + b;</dascript>
|-
| Prefix decrement
| <dascript>while (--a > 10) { }</dascript>
|-
| Postfix decrement
| <dascript>while (a-- > 10) { }</dascript>
|-
| Assignment by subtraction
| <dascript>a -= b;</dascript>
|-
| Multiplication (product)
| <dascript>x = a * b;</dascript>
|-
| Division (quotient)
| <dascript>x = a / b;</dascript>
|-
| Modulo (remainder)
| <dascript>if (a % b == 1) { }</dascript>
|}

====Comparison Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Less than
| <dascript>if (a < b) { }</dascript>
|-
| Less than or equal to
| <dascript>if (a <= b) { }</dascript>
|-
| Greater than
| <dascript>if (a > b) { }</dascript>
|-
| Greater than or equal to
| <dascript>if (a >= b) { }</dascript>
|-
| Not Equal to
| <dascript>if (a != b) { }</dascript>
|-
| Equal to
| <dascript>if (a == b) { }</dascript>
|}

====Logical Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Logical negation (NOT)
| <dascript>if (!a) { }</dascript>
|-
| Logical AND
| <dascript>if (a && b) { }</dascript>
|-
| Logical OR
| <dascript>if (a || b) { }</dascript>
|}

====Other Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Basic assignment
| <dascript>a = b;</dascript>
|-
| Function call
| <dascript>a();</dascript>
|-
| Array subscript
| <dascript>array[0] = 1;</dascript>
|-
| Member (on structures)
| <dascript>structure.member = 0;</dascript>
|-
| Ternary conditional
| <dascript>return a 
|}
=== Types & Variable ===

The scripting language natively supports:
* [[float]] - floating-point numbers. <dascript>float fFloat = 0.1234f;</dascript>
* [[int]] - integer numbers. <dascript>int nInteger = 1234;</dascript>
* [[object]] -game object files. <dascript>object oObject = GetObjectByTag("monster_001");</dascript>
* [[resource]] - game resource files. <dascript>resource rGameIntroCutscene = R"game_intro_.cut";</dascript>
* [[string]] - text strings. <dascript>string sString = "Hello World!";</dascript>
* [[vector]] - positions or directions. <dascript>vector vVector = Vector(0.0, 1.1, 2.2);</dascript>

The server language has been expanded to support these engine defined structures:
* [[Event (dascript type)|event]] - events are signals that are sent to scripts by other scripts or by the world engine.
* [[location]]
* [[command]] - a command for a creature or object to do something. Commands are constructed using functions that return them, and then are added to a target's command queue with the AddCommand function.
* [[effect]]
* [[itemproperty]]
* [[player]]

All of these types are always passed by value, which means a new copy is made whenever they are passed into a function or copied to another variable.

This means that most functions that are supposed to modify a structure in some way need to return the modified one:

<dascript>
void main()
{
effect e1 = Effect(100);
effect e2 = SetEffectType(e1, 101); // e1 != e2
}
</dascript>

==== Structures ====

Users can define their own structures using the [[struct]] keyword:

<dascript>
// user-defined type
struct quaternion
{
float w, x, y, z;
};

// constructor
struct quaternion Quaternion(float fW, float fX, float fY, float fZ)
{
struct quaternion q;

q.w = fW;
q.x = fX;
q.y = fY;
q.z = fZ;

return q;
}

void main()
{
struct quaternion q = Quaternion(0.0, 0.0, 0.0, 0.0);
}
</dascript>

==== Arrays ====
Variables can be declared as arrays for any type except user-defined structs. Designers can create their own arrays of any major data type (int, string, object). Many functions will also return arrays (for example, creatures in an area will be returned as an array, and the action queue will be returned as an array).

These are different from C-style arrays in that they can be resized like STL vectors, and their notation is slightly different.

Arrays also behave differently from other objects in the scripting language because they are passed by reference. If an array is passed into a function and modified:

<dascript>
void main()
{
int[] i; // new array of integers with a size of zero
i[0] = 5; // value of array position 0 is now 5
i[1] = -1; // value of array position 1 is now -1

int[] j = i; // i and j point to the same array
j[1] = 12; // value of array position 1 for both i and j is now 12!

SortArrayDescending(i); // i and j are both sorted now, this function has no return value
}
</dascript>

[[GetArraySize]] returns the size of an array.

==== Local Variables ====

In Neverwinter Nights, variables for various objects could be created and set with functions such as SetLocalInt(). Dragon Age does not have analogous functions. Instead, all of the variables that a given object is able to have values assigned to must be defined ahead of time in a 2DA. This more restrictive approach is intended to improve performance and reduce the opportunity for errors (for example, making a typo in the name of a variable and losing track of it as a result).

=== Functions ===

There are two ways to discover a function and what it does.

If you type in the name of a function that's been defined and then an opening bracket, a tooltip will pop up showing the function's parameter types and return type.

Alternately, if you have the help window open (View -> Other Windows -> Help Window), then whenever you select a function in the function browser a help page describing the function will be displayed.

=== Passing parameters to scripts ===

To pass parameters to scripts they must be called with the 'runscript' command. This can be useful for writing debug scripts or changing actions based on input. To accept parameters simply add this line to your script:

<dascript>
string sParams = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
</dascript>

You can then type 'runscript scriptname parameter1 parameter2 ... paramaterN' to pass parameters.

Some examples:

<dascript>

// Debug script: heals the object with the given tag. If tag is invalid, nothing happens
void main()
{

string sTag = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
object oCreature = GetObjectByTag(sTag);
effect eHeal = EffectHeal(25.0f)
//ApplyEffect...
}

</dascript>

<dascript>

// Debug script: applies the visual effect passed in as parameter to the player
void main()
{

string sEffect = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
int nEffect = StringToInt(sEffect);
effect eVfx = EffectVisualEffect(nEffect);
//ApplyEffect...
}

</dascript>

=== Error messages and logging ===

See [[Script error]] for details of how to correct errors in scripts.

To enable script logging, edit or create <DragonAgeInstallDirectory>\bin_ship\[[ECLog.ini]] and set Script=1 in the [LogTypes] section.

The [[PrintToLog]] function prints messages to the log file once logging is enabled.

== Timing ==

Commands, delayed events and object destruction all take place after the current script is finished running. Plot flags set in script are set in-line but the triggered plot script runs before the flag is actually set (this is clarified a bit in the plot script template).

Given that ExecuteScript is deprecated, HandleEvent should be used when you want the script to run in-line and DelayEvent should be used when you want to delay execution.

To delay execution when dealing with creatures, custom AI and (safe) command complete are nice tools. DelayEvent should be used whenever you know how long you want to wait before the event fires. (It can also be used in quite small time increments to give the illusion of smoothly sliding placeables with SetPosition or interpolate between two different atmosphere/lighting settings, but the overhead of this is noticeable if overused).

== Searching Scripts ==

To find examples of how Bioware does things, or simply to discover where a function or variable is used, it's useful to be able to search all the scripts in the data base for a string.

You'll need Microsoft SQL Server Management Studio Express - see [[Preparing_a_dialog_for_recording | Preparing a dialog for recording
]].

Enter the following query:

SELECT [bw_dragonage_content].[dbo].[t_Module].Name, [bw_dragonage_content].[dbo].[t_ModuleResRefVersion].Name
FROM [bw_dragonage_content].[dbo].[t_Module], [bw_dragonage_content].[dbo].[t_ModuleResRefVersion],
[bw_dragonage_content].[dbo].[t_Script]
WHERE [bw_dragonage_content].[dbo].[t_Module].ID
= [bw_dragonage_content].[dbo].[t_ModuleResRefVersion].ModuleID
AND [bw_dragonage_content].[dbo].[t_ModuleResRefVersion].ID
= [bw_dragonage_content].[dbo].[t_Script].ModuleResRefVersionID
AND Text LIKE '%######%'
ORDER BY 1, 2;

where ###### is the string you want to find.

This will list the name of every script that contains the string ######.

There will be duplicates if the data base contains multiple versions of a script (maybe an SQL programmer can improve the query to eliminate this, but it's no big deal).

[[Category:Scripts]]
{{Languages}}

Scripting overview

2011-04-05T11:32:04Z

Proleric1: /* Searching Scripts */

{{Infobox script}}

Scripting is used whenever the designers need control over the game's behaviour. The syntax for DA scripts is very similar to the C programming language.

Detailed documentation for the scripting language can be found in the "dascript.chm" file, available in your "Dragon Age\packages\core" directory.

The main uses for it are to:

*Trigger plot events
*Script conversation
*Handle creature and party member [[AI]]
*Script abilities - skills, talents, and spells

DA also has a client-side scripting language whose primary responsibility is automated testing of the game. See [[client script]]s for more details.

AI Scripts are event based. Objects will have only one event-handling script assigned to them that will be run whenever they receive a game event. This script will receive the event type as a parameter and will need to determine the appropriate response for itself.

There are several file extensions associated with scripts:
* NSS - script source file
* NCS - compiled script
* NDB - debug information file (required for using the script debugger to trace through this file)

== Script editor ==

Scripts are created in the Designer Toolset using the Script Editor. Once created, scripts must be assigned to such things as Creatures before they can be used. Once assigned, both the referencing object and the script must be exported in order to be viewed in the game. Exporting happens automatically or can be done manually by the designer during testing.

The script editor supports the following features:

*Undo and redo
*Find and replace
*Bookmarking: View -> Other Windows -> Bookmarks
*Function, variable, constant, and template browser (visible on the right-hand side of the screen).
*Auto-complete when typing function and variable names
*Syntax highlighting
*Auto-indention
*Brace matching/highlighting
*Ability to test compile a script
*Jump to definition

To the right of the script editor is a sidebar with a browser that can display all currently-defined functions, variables, or constants, or a set of 'template' scripts that can serve as a starting point when writing a script from scratch. The browser also has a filter field where you can type in a partial string and have the list automatically exclude everything that doesn't include it in the name.

This is the constant browser:

[[Image:Scripting constant browser.png]]

Here it is with "team" typed into the filter field, displaying only constants with names that contain the substring "team" (not case sensitive):

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

The templates that come with Dragon Age include frameworks for the most common event scripts found in the game. You can add your own templates quite easily, just create a text file with the template code in it and place it in the Dragon Age\Toolset\scripttemplates directory with the others.

[[Image:scripting template browser.png]]

Dragon Age's toolset supports Doxygen-style comments. If you double-click on a function name a help window will pop open to display its documentation. You can also jump to a function's definition (provided it isn't an engine-defined function in script.ldf) by right-clicking on it and selecting "go to definition".

[[Image:Scripting help window.png]]

== Writing scripts ==

For a script to compile, it needs a body:
<dascript>
void main()
{
}
</dascript>
The parameters on this can't be changed or the script won't compile.

Scripts associated with a dialog node take this alternate form:
<dascript>
int StartingConditional()
{
return 1;
}
</dascript>

=== Including files ===
Other script files can be included by using the #include directive.
<dascript>
#include "rules_h"

void main()
{
DoSomethingOrOther();
}
</dascript>
The included file is '''inserted''' into the main file before the script is compiled. Any number of files can be included.
'''Important:''' this means that whenever you change an "include file" you must export all script that include it before they will use the new version!

No other C-style preprocessor commands are supported.

=== Operators ===

The scripting language supports the following operators:

====Arithmetic Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Prefix Increment
| <dascript>while ( ++a < 10) { }</dascript>
|-
| Postfix Increment
| <dascript> for (i = 0; i < 10; i++) { } </dascript>
|-
| Assignment by addition
| <dascript>a += b;</dascript>
|-
| Subtraction (difference)
| <dascript>x = a - b;</dascript>
|-
| Addition (sum)
| <dascript>x = a + b;</dascript>
|-
| Prefix decrement
| <dascript>while (--a > 10) { }</dascript>
|-
| Postfix decrement
| <dascript>while (a-- > 10) { }</dascript>
|-
| Assignment by subtraction
| <dascript>a -= b;</dascript>
|-
| Multiplication (product)
| <dascript>x = a * b;</dascript>
|-
| Division (quotient)
| <dascript>x = a / b;</dascript>
|-
| Modulo (remainder)
| <dascript>if (a % b == 1) { }</dascript>
|}

====Comparison Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Less than
| <dascript>if (a < b) { }</dascript>
|-
| Less than or equal to
| <dascript>if (a <= b) { }</dascript>
|-
| Greater than
| <dascript>if (a > b) { }</dascript>
|-
| Greater than or equal to
| <dascript>if (a >= b) { }</dascript>
|-
| Not Equal to
| <dascript>if (a != b) { }</dascript>
|-
| Equal to
| <dascript>if (a == b) { }</dascript>
|}

====Logical Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Logical negation (NOT)
| <dascript>if (!a) { }</dascript>
|-
| Logical AND
| <dascript>if (a && b) { }</dascript>
|-
| Logical OR
| <dascript>if (a || b) { }</dascript>
|}

====Other Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Basic assignment
| <dascript>a = b;</dascript>
|-
| Function call
| <dascript>a();</dascript>
|-
| Array subscript
| <dascript>array[0] = 1;</dascript>
|-
| Member (on structures)
| <dascript>structure.member = 0;</dascript>
|-
| Ternary conditional
| <dascript>return a 
|}
=== Types & Variable ===

The scripting language natively supports:
* [[float]] - floating-point numbers. <dascript>float fFloat = 0.1234f;</dascript>
* [[int]] - integer numbers. <dascript>int nInteger = 1234;</dascript>
* [[object]] -game object files. <dascript>object oObject = GetObjectByTag("monster_001");</dascript>
* [[resource]] - game resource files. <dascript>resource rGameIntroCutscene = R"game_intro_.cut";</dascript>
* [[string]] - text strings. <dascript>string sString = "Hello World!";</dascript>
* [[vector]] - positions or directions. <dascript>vector vVector = Vector(0.0, 1.1, 2.2);</dascript>

The server language has been expanded to support these engine defined structures:
* [[Event (dascript type)|event]] - events are signals that are sent to scripts by other scripts or by the world engine.
* [[location]]
* [[command]] - a command for a creature or object to do something. Commands are constructed using functions that return them, and then are added to a target's command queue with the AddCommand function.
* [[effect]]
* [[itemproperty]]
* [[player]]

All of these types are always passed by value, which means a new copy is made whenever they are passed into a function or copied to another variable.

This means that most functions that are supposed to modify a structure in some way need to return the modified one:

<dascript>
void main()
{
effect e1 = Effect(100);
effect e2 = SetEffectType(e1, 101); // e1 != e2
}
</dascript>

==== Structures ====

Users can define their own structures using the [[struct]] keyword:

<dascript>
// user-defined type
struct quaternion
{
float w, x, y, z;
};

// constructor
struct quaternion Quaternion(float fW, float fX, float fY, float fZ)
{
struct quaternion q;

q.w = fW;
q.x = fX;
q.y = fY;
q.z = fZ;

return q;
}

void main()
{
struct quaternion q = Quaternion(0.0, 0.0, 0.0, 0.0);
}
</dascript>

==== Arrays ====
Variables can be declared as arrays for any type except user-defined structs. Designers can create their own arrays of any major data type (int, string, object). Many functions will also return arrays (for example, creatures in an area will be returned as an array, and the action queue will be returned as an array).

These are different from C-style arrays in that they can be resized like STL vectors, and their notation is slightly different.

Arrays also behave differently from other objects in the scripting language because they are passed by reference. If an array is passed into a function and modified:

<dascript>
void main()
{
int[] i; // new array of integers with a size of zero
i[0] = 5; // value of array position 0 is now 5
i[1] = -1; // value of array position 1 is now -1

int[] j = i; // i and j point to the same array
j[1] = 12; // value of array position 1 for both i and j is now 12!

SortArrayDescending(i); // i and j are both sorted now, this function has no return value
}
</dascript>

[[GetArraySize]] returns the size of an array.

==== Local Variables ====

In Neverwinter Nights, variables for various objects could be created and set with functions such as SetLocalInt(). Dragon Age does not have analogous functions. Instead, all of the variables that a given object is able to have values assigned to must be defined ahead of time in a 2DA. This more restrictive approach is intended to improve performance and reduce the opportunity for errors (for example, making a typo in the name of a variable and losing track of it as a result).

=== Functions ===

There are two ways to discover a function and what it does.

If you type in the name of a function that's been defined and then an opening bracket, a tooltip will pop up showing the function's parameter types and return type.

Alternately, if you have the help window open (View -> Other Windows -> Help Window), then whenever you select a function in the function browser a help page describing the function will be displayed.

=== Passing parameters to scripts ===

To pass parameters to scripts they must be called with the 'runscript' command. This can be useful for writing debug scripts or changing actions based on input. To accept parameters simply add this line to your script:

<dascript>
string sParams = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
</dascript>

You can then type 'runscript scriptname parameter1 parameter2 ... paramaterN' to pass parameters.

Some examples:

<dascript>

// Debug script: heals the object with the given tag. If tag is invalid, nothing happens
void main()
{

string sTag = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
object oCreature = GetObjectByTag(sTag);
effect eHeal = EffectHeal(25.0f)
//ApplyEffect...
}

</dascript>

<dascript>

// Debug script: applies the visual effect passed in as parameter to the player
void main()
{

string sEffect = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
int nEffect = StringToInt(sEffect);
effect eVfx = EffectVisualEffect(nEffect);
//ApplyEffect...
}

</dascript>

=== Error messages and logging ===

See [[Script error]] for details of how to correct errors in scripts.

To enable script logging, edit or create <DragonAgeInstallDirectory>\bin_ship\[[ECLog.ini]] and set Script=1 in the [LogTypes] section.

The [[PrintToLog]] function prints messages to the log file once logging is enabled.

== Timing ==

Commands, delayed events and object destruction all take place after the current script is finished running. Plot flags set in script are set in-line but the triggered plot script runs before the flag is actually set (this is clarified a bit in the plot script template).

Given that ExecuteScript is deprecated, HandleEvent should be used when you want the script to run in-line and DelayEvent should be used when you want to delay execution.

To delay execution when dealing with creatures, custom AI and (safe) command complete are nice tools. DelayEvent should be used whenever you know how long you want to wait before the event fires. (It can also be used in quite small time increments to give the illusion of smoothly sliding placeables with SetPosition or interpolate between two different atmosphere/lighting settings, but the overhead of this is noticeable if overused).

== Searching Scripts ==

To find examples of how Bioware does things, or simply to discover where a function or variable is used, it's useful to be able to search all the scripts in the data base for a string.

You'll need Microsoft SQL Server Management Studio Express - see [[Preparing_a_dialog_for_recording]].

Enter the following query:

SELECT [bw_dragonage_content].[dbo].[t_Module].Name, [bw_dragonage_content].[dbo].[t_ModuleResRefVersion].Name
FROM [bw_dragonage_content].[dbo].[t_Module], [bw_dragonage_content].[dbo].[t_ModuleResRefVersion],
[bw_dragonage_content].[dbo].[t_Script]
WHERE [bw_dragonage_content].[dbo].[t_Module].ID
= [bw_dragonage_content].[dbo].[t_ModuleResRefVersion].ModuleID
AND [bw_dragonage_content].[dbo].[t_ModuleResRefVersion].ID
= [bw_dragonage_content].[dbo].[t_Script].ModuleResRefVersionID
AND Text LIKE '%######%'
ORDER BY 1, 2;

where ###### is the string you want to find.

This will list the name of every script that contains the string ######.

There will be duplicates if the data base contains multiple versions of a script (maybe an SQL programmer can improve the query to eliminate this, but it's no big deal).

[[Category:Scripts]]
{{Languages}}

Scripting overview

2011-04-05T11:30:58Z

Proleric1:

{{Infobox script}}

Scripting is used whenever the designers need control over the game's behaviour. The syntax for DA scripts is very similar to the C programming language.

Detailed documentation for the scripting language can be found in the "dascript.chm" file, available in your "Dragon Age\packages\core" directory.

The main uses for it are to:

*Trigger plot events
*Script conversation
*Handle creature and party member [[AI]]
*Script abilities - skills, talents, and spells

DA also has a client-side scripting language whose primary responsibility is automated testing of the game. See [[client script]]s for more details.

AI Scripts are event based. Objects will have only one event-handling script assigned to them that will be run whenever they receive a game event. This script will receive the event type as a parameter and will need to determine the appropriate response for itself.

There are several file extensions associated with scripts:
* NSS - script source file
* NCS - compiled script
* NDB - debug information file (required for using the script debugger to trace through this file)

== Script editor ==

Scripts are created in the Designer Toolset using the Script Editor. Once created, scripts must be assigned to such things as Creatures before they can be used. Once assigned, both the referencing object and the script must be exported in order to be viewed in the game. Exporting happens automatically or can be done manually by the designer during testing.

The script editor supports the following features:

*Undo and redo
*Find and replace
*Bookmarking: View -> Other Windows -> Bookmarks
*Function, variable, constant, and template browser (visible on the right-hand side of the screen).
*Auto-complete when typing function and variable names
*Syntax highlighting
*Auto-indention
*Brace matching/highlighting
*Ability to test compile a script
*Jump to definition

To the right of the script editor is a sidebar with a browser that can display all currently-defined functions, variables, or constants, or a set of 'template' scripts that can serve as a starting point when writing a script from scratch. The browser also has a filter field where you can type in a partial string and have the list automatically exclude everything that doesn't include it in the name.

This is the constant browser:

[[Image:Scripting constant browser.png]]

Here it is with "team" typed into the filter field, displaying only constants with names that contain the substring "team" (not case sensitive):

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

The templates that come with Dragon Age include frameworks for the most common event scripts found in the game. You can add your own templates quite easily, just create a text file with the template code in it and place it in the Dragon Age\Toolset\scripttemplates directory with the others.

[[Image:scripting template browser.png]]

Dragon Age's toolset supports Doxygen-style comments. If you double-click on a function name a help window will pop open to display its documentation. You can also jump to a function's definition (provided it isn't an engine-defined function in script.ldf) by right-clicking on it and selecting "go to definition".

[[Image:Scripting help window.png]]

== Writing scripts ==

For a script to compile, it needs a body:
<dascript>
void main()
{
}
</dascript>
The parameters on this can't be changed or the script won't compile.

Scripts associated with a dialog node take this alternate form:
<dascript>
int StartingConditional()
{
return 1;
}
</dascript>

=== Including files ===
Other script files can be included by using the #include directive.
<dascript>
#include "rules_h"

void main()
{
DoSomethingOrOther();
}
</dascript>
The included file is '''inserted''' into the main file before the script is compiled. Any number of files can be included.
'''Important:''' this means that whenever you change an "include file" you must export all script that include it before they will use the new version!

No other C-style preprocessor commands are supported.

=== Operators ===

The scripting language supports the following operators:

====Arithmetic Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Prefix Increment
| <dascript>while ( ++a < 10) { }</dascript>
|-
| Postfix Increment
| <dascript> for (i = 0; i < 10; i++) { } </dascript>
|-
| Assignment by addition
| <dascript>a += b;</dascript>
|-
| Subtraction (difference)
| <dascript>x = a - b;</dascript>
|-
| Addition (sum)
| <dascript>x = a + b;</dascript>
|-
| Prefix decrement
| <dascript>while (--a > 10) { }</dascript>
|-
| Postfix decrement
| <dascript>while (a-- > 10) { }</dascript>
|-
| Assignment by subtraction
| <dascript>a -= b;</dascript>
|-
| Multiplication (product)
| <dascript>x = a * b;</dascript>
|-
| Division (quotient)
| <dascript>x = a / b;</dascript>
|-
| Modulo (remainder)
| <dascript>if (a % b == 1) { }</dascript>
|}

====Comparison Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Less than
| <dascript>if (a < b) { }</dascript>
|-
| Less than or equal to
| <dascript>if (a <= b) { }</dascript>
|-
| Greater than
| <dascript>if (a > b) { }</dascript>
|-
| Greater than or equal to
| <dascript>if (a >= b) { }</dascript>
|-
| Not Equal to
| <dascript>if (a != b) { }</dascript>
|-
| Equal to
| <dascript>if (a == b) { }</dascript>
|}

====Logical Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Logical negation (NOT)
| <dascript>if (!a) { }</dascript>
|-
| Logical AND
| <dascript>if (a && b) { }</dascript>
|-
| Logical OR
| <dascript>if (a || b) { }</dascript>
|}

====Other Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Basic assignment
| <dascript>a = b;</dascript>
|-
| Function call
| <dascript>a();</dascript>
|-
| Array subscript
| <dascript>array[0] = 1;</dascript>
|-
| Member (on structures)
| <dascript>structure.member = 0;</dascript>
|-
| Ternary conditional
| <dascript>return a 
|}
=== Types & Variable ===

The scripting language natively supports:
* [[float]] - floating-point numbers. <dascript>float fFloat = 0.1234f;</dascript>
* [[int]] - integer numbers. <dascript>int nInteger = 1234;</dascript>
* [[object]] -game object files. <dascript>object oObject = GetObjectByTag("monster_001");</dascript>
* [[resource]] - game resource files. <dascript>resource rGameIntroCutscene = R"game_intro_.cut";</dascript>
* [[string]] - text strings. <dascript>string sString = "Hello World!";</dascript>
* [[vector]] - positions or directions. <dascript>vector vVector = Vector(0.0, 1.1, 2.2);</dascript>

The server language has been expanded to support these engine defined structures:
* [[Event (dascript type)|event]] - events are signals that are sent to scripts by other scripts or by the world engine.
* [[location]]
* [[command]] - a command for a creature or object to do something. Commands are constructed using functions that return them, and then are added to a target's command queue with the AddCommand function.
* [[effect]]
* [[itemproperty]]
* [[player]]

All of these types are always passed by value, which means a new copy is made whenever they are passed into a function or copied to another variable.

This means that most functions that are supposed to modify a structure in some way need to return the modified one:

<dascript>
void main()
{
effect e1 = Effect(100);
effect e2 = SetEffectType(e1, 101); // e1 != e2
}
</dascript>

==== Structures ====

Users can define their own structures using the [[struct]] keyword:

<dascript>
// user-defined type
struct quaternion
{
float w, x, y, z;
};

// constructor
struct quaternion Quaternion(float fW, float fX, float fY, float fZ)
{
struct quaternion q;

q.w = fW;
q.x = fX;
q.y = fY;
q.z = fZ;

return q;
}

void main()
{
struct quaternion q = Quaternion(0.0, 0.0, 0.0, 0.0);
}
</dascript>

==== Arrays ====
Variables can be declared as arrays for any type except user-defined structs. Designers can create their own arrays of any major data type (int, string, object). Many functions will also return arrays (for example, creatures in an area will be returned as an array, and the action queue will be returned as an array).

These are different from C-style arrays in that they can be resized like STL vectors, and their notation is slightly different.

Arrays also behave differently from other objects in the scripting language because they are passed by reference. If an array is passed into a function and modified:

<dascript>
void main()
{
int[] i; // new array of integers with a size of zero
i[0] = 5; // value of array position 0 is now 5
i[1] = -1; // value of array position 1 is now -1

int[] j = i; // i and j point to the same array
j[1] = 12; // value of array position 1 for both i and j is now 12!

SortArrayDescending(i); // i and j are both sorted now, this function has no return value
}
</dascript>

[[GetArraySize]] returns the size of an array.

==== Local Variables ====

In Neverwinter Nights, variables for various objects could be created and set with functions such as SetLocalInt(). Dragon Age does not have analogous functions. Instead, all of the variables that a given object is able to have values assigned to must be defined ahead of time in a 2DA. This more restrictive approach is intended to improve performance and reduce the opportunity for errors (for example, making a typo in the name of a variable and losing track of it as a result).

=== Functions ===

There are two ways to discover a function and what it does.

If you type in the name of a function that's been defined and then an opening bracket, a tooltip will pop up showing the function's parameter types and return type.

Alternately, if you have the help window open (View -> Other Windows -> Help Window), then whenever you select a function in the function browser a help page describing the function will be displayed.

=== Passing parameters to scripts ===

To pass parameters to scripts they must be called with the 'runscript' command. This can be useful for writing debug scripts or changing actions based on input. To accept parameters simply add this line to your script:

<dascript>
string sParams = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
</dascript>

You can then type 'runscript scriptname parameter1 parameter2 ... paramaterN' to pass parameters.

Some examples:

<dascript>

// Debug script: heals the object with the given tag. If tag is invalid, nothing happens
void main()
{

string sTag = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
object oCreature = GetObjectByTag(sTag);
effect eHeal = EffectHeal(25.0f)
//ApplyEffect...
}

</dascript>

<dascript>

// Debug script: applies the visual effect passed in as parameter to the player
void main()
{

string sEffect = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
int nEffect = StringToInt(sEffect);
effect eVfx = EffectVisualEffect(nEffect);
//ApplyEffect...
}

</dascript>

=== Error messages and logging ===

See [[Script error]] for details of how to correct errors in scripts.

To enable script logging, edit or create <DragonAgeInstallDirectory>\bin_ship\[[ECLog.ini]] and set Script=1 in the [LogTypes] section.

The [[PrintToLog]] function prints messages to the log file once logging is enabled.

== Timing ==

Commands, delayed events and object destruction all take place after the current script is finished running. Plot flags set in script are set in-line but the triggered plot script runs before the flag is actually set (this is clarified a bit in the plot script template).

Given that ExecuteScript is deprecated, HandleEvent should be used when you want the script to run in-line and DelayEvent should be used when you want to delay execution.

To delay execution when dealing with creatures, custom AI and (safe) command complete are nice tools. DelayEvent should be used whenever you know how long you want to wait before the event fires. (It can also be used in quite small time increments to give the illusion of smoothly sliding placeables with SetPosition or interpolate between two different atmosphere/lighting settings, but the overhead of this is noticeable if overused).

== Searching Scripts ==

To find examples of how Bioware does things, or simply to discover where a function or variable is used, it's useful to be able to search all the scripts in the data base for a string.

You'll need [[Preparing_a_dialog_for_recording | Microsoft SQL Server Management Studio Express]] for this.

Enter the following query:

SELECT [bw_dragonage_content].[dbo].[t_Module].Name, [bw_dragonage_content].[dbo].[t_ModuleResRefVersion].Name
FROM [bw_dragonage_content].[dbo].[t_Module], [bw_dragonage_content].[dbo].[t_ModuleResRefVersion],
[bw_dragonage_content].[dbo].[t_Script]
WHERE [bw_dragonage_content].[dbo].[t_Module].ID
= [bw_dragonage_content].[dbo].[t_ModuleResRefVersion].ModuleID
AND [bw_dragonage_content].[dbo].[t_ModuleResRefVersion].ID
= [bw_dragonage_content].[dbo].[t_Script].ModuleResRefVersionID
AND Text LIKE '%######%'
ORDER BY 1, 2;

where ###### is the string you want to find.

This will list the name of every script that contains the string ######.

There will be duplicates if the data base contains multiple versions of a script (maybe an SQL programmer can improve the query to eliminate this, but it's no big deal).

[[Category:Scripts]]
{{Languages}}

Scripting overview

2011-04-05T11:30:12Z

Proleric1: /* Timing */

{{Infobox script}}

Scripting is used whenever the designers need control over the game's behaviour. The syntax for DA scripts is very similar to the C programming language.

Detailed documentation for the scripting language can be found in the "dascript.chm" file, available in your "Dragon Age\packages\core" directory.

The main uses for it are to:

*Trigger plot events
*Script conversation
*Handle creature and party member [[AI]]
*Script abilities - skills, talents, and spells

DA also has a client-side scripting language whose primary responsibility is automated testing of the game. See [[client script]]s for more details.

AI Scripts are event based. Objects will have only one event-handling script assigned to them that will be run whenever they receive a game event. This script will receive the event type as a parameter and will need to determine the appropriate response for itself.

There are several file extensions associated with scripts:
* NSS - script source file
* NCS - compiled script
* NDB - debug information file (required for using the script debugger to trace through this file)

== Script editor ==

Scripts are created in the Designer Toolset using the Script Editor. Once created, scripts must be assigned to such things as Creatures before they can be used. Once assigned, both the referencing object and the script must be exported in order to be viewed in the game. Exporting happens automatically or can be done manually by the designer during testing.

The script editor supports the following features:

*Undo and redo
*Find and replace
*Bookmarking: View -> Other Windows -> Bookmarks
*Function, variable, constant, and template browser (visible on the right-hand side of the screen).
*Auto-complete when typing function and variable names
*Syntax highlighting
*Auto-indention
*Brace matching/highlighting
*Ability to test compile a script
*Jump to definition

To the right of the script editor is a sidebar with a browser that can display all currently-defined functions, variables, or constants, or a set of 'template' scripts that can serve as a starting point when writing a script from scratch. The browser also has a filter field where you can type in a partial string and have the list automatically exclude everything that doesn't include it in the name.

This is the constant browser:

[[Image:Scripting constant browser.png]]

Here it is with "team" typed into the filter field, displaying only constants with names that contain the substring "team" (not case sensitive):

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

The templates that come with Dragon Age include frameworks for the most common event scripts found in the game. You can add your own templates quite easily, just create a text file with the template code in it and place it in the Dragon Age\Toolset\scripttemplates directory with the others.

[[Image:scripting template browser.png]]

Dragon Age's toolset supports Doxygen-style comments. If you double-click on a function name a help window will pop open to display its documentation. You can also jump to a function's definition (provided it isn't an engine-defined function in script.ldf) by right-clicking on it and selecting "go to definition".

[[Image:Scripting help window.png]]

== Writing scripts ==

For a script to compile, it needs a body:
<dascript>
void main()
{
}
</dascript>
The parameters on this can't be changed or the script won't compile.

Scripts associated with a dialog node take this alternate form:
<dascript>
int StartingConditional()
{
return 1;
}
</dascript>

=== Including files ===
Other script files can be included by using the #include directive.
<dascript>
#include "rules_h"

void main()
{
DoSomethingOrOther();
}
</dascript>
The included file is '''inserted''' into the main file before the script is compiled. Any number of files can be included.
'''Important:''' this means that whenever you change an "include file" you must export all script that include it before they will use the new version!

No other C-style preprocessor commands are supported.

=== Operators ===

The scripting language supports the following operators:

====Arithmetic Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Prefix Increment
| <dascript>while ( ++a < 10) { }</dascript>
|-
| Postfix Increment
| <dascript> for (i = 0; i < 10; i++) { } </dascript>
|-
| Assignment by addition
| <dascript>a += b;</dascript>
|-
| Subtraction (difference)
| <dascript>x = a - b;</dascript>
|-
| Addition (sum)
| <dascript>x = a + b;</dascript>
|-
| Prefix decrement
| <dascript>while (--a > 10) { }</dascript>
|-
| Postfix decrement
| <dascript>while (a-- > 10) { }</dascript>
|-
| Assignment by subtraction
| <dascript>a -= b;</dascript>
|-
| Multiplication (product)
| <dascript>x = a * b;</dascript>
|-
| Division (quotient)
| <dascript>x = a / b;</dascript>
|-
| Modulo (remainder)
| <dascript>if (a % b == 1) { }</dascript>
|}

====Comparison Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Less than
| <dascript>if (a < b) { }</dascript>
|-
| Less than or equal to
| <dascript>if (a <= b) { }</dascript>
|-
| Greater than
| <dascript>if (a > b) { }</dascript>
|-
| Greater than or equal to
| <dascript>if (a >= b) { }</dascript>
|-
| Not Equal to
| <dascript>if (a != b) { }</dascript>
|-
| Equal to
| <dascript>if (a == b) { }</dascript>
|}

====Logical Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Logical negation (NOT)
| <dascript>if (!a) { }</dascript>
|-
| Logical AND
| <dascript>if (a && b) { }</dascript>
|-
| Logical OR
| <dascript>if (a || b) { }</dascript>
|}

====Other Operators====
{|style="width:100%;border:solid 1px black;"
! style="width:25%;background-color:#ffffcc;" | Operator Name
! style="width:75%;background-color:#ffffcc;" | Example
|-
| Basic assignment
| <dascript>a = b;</dascript>
|-
| Function call
| <dascript>a();</dascript>
|-
| Array subscript
| <dascript>array[0] = 1;</dascript>
|-
| Member (on structures)
| <dascript>structure.member = 0;</dascript>
|-
| Ternary conditional
| <dascript>return a 
|}
=== Types & Variable ===

The scripting language natively supports:
* [[float]] - floating-point numbers. <dascript>float fFloat = 0.1234f;</dascript>
* [[int]] - integer numbers. <dascript>int nInteger = 1234;</dascript>
* [[object]] -game object files. <dascript>object oObject = GetObjectByTag("monster_001");</dascript>
* [[resource]] - game resource files. <dascript>resource rGameIntroCutscene = R"game_intro_.cut";</dascript>
* [[string]] - text strings. <dascript>string sString = "Hello World!";</dascript>
* [[vector]] - positions or directions. <dascript>vector vVector = Vector(0.0, 1.1, 2.2);</dascript>

The server language has been expanded to support these engine defined structures:
* [[Event (dascript type)|event]] - events are signals that are sent to scripts by other scripts or by the world engine.
* [[location]]
* [[command]] - a command for a creature or object to do something. Commands are constructed using functions that return them, and then are added to a target's command queue with the AddCommand function.
* [[effect]]
* [[itemproperty]]
* [[player]]

All of these types are always passed by value, which means a new copy is made whenever they are passed into a function or copied to another variable.

This means that most functions that are supposed to modify a structure in some way need to return the modified one:

<dascript>
void main()
{
effect e1 = Effect(100);
effect e2 = SetEffectType(e1, 101); // e1 != e2
}
</dascript>

==== Structures ====

Users can define their own structures using the [[struct]] keyword:

<dascript>
// user-defined type
struct quaternion
{
float w, x, y, z;
};

// constructor
struct quaternion Quaternion(float fW, float fX, float fY, float fZ)
{
struct quaternion q;

q.w = fW;
q.x = fX;
q.y = fY;
q.z = fZ;

return q;
}

void main()
{
struct quaternion q = Quaternion(0.0, 0.0, 0.0, 0.0);
}
</dascript>

==== Arrays ====
Variables can be declared as arrays for any type except user-defined structs. Designers can create their own arrays of any major data type (int, string, object). Many functions will also return arrays (for example, creatures in an area will be returned as an array, and the action queue will be returned as an array).

These are different from C-style arrays in that they can be resized like STL vectors, and their notation is slightly different.

Arrays also behave differently from other objects in the scripting language because they are passed by reference. If an array is passed into a function and modified:

<dascript>
void main()
{
int[] i; // new array of integers with a size of zero
i[0] = 5; // value of array position 0 is now 5
i[1] = -1; // value of array position 1 is now -1

int[] j = i; // i and j point to the same array
j[1] = 12; // value of array position 1 for both i and j is now 12!

SortArrayDescending(i); // i and j are both sorted now, this function has no return value
}
</dascript>

[[GetArraySize]] returns the size of an array.

==== Local Variables ====

In Neverwinter Nights, variables for various objects could be created and set with functions such as SetLocalInt(). Dragon Age does not have analogous functions. Instead, all of the variables that a given object is able to have values assigned to must be defined ahead of time in a 2DA. This more restrictive approach is intended to improve performance and reduce the opportunity for errors (for example, making a typo in the name of a variable and losing track of it as a result).

=== Functions ===

There are two ways to discover a function and what it does.

If you type in the name of a function that's been defined and then an opening bracket, a tooltip will pop up showing the function's parameter types and return type.

Alternately, if you have the help window open (View -> Other Windows -> Help Window), then whenever you select a function in the function browser a help page describing the function will be displayed.

=== Passing parameters to scripts ===

To pass parameters to scripts they must be called with the 'runscript' command. This can be useful for writing debug scripts or changing actions based on input. To accept parameters simply add this line to your script:

<dascript>
string sParams = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
</dascript>

You can then type 'runscript scriptname parameter1 parameter2 ... paramaterN' to pass parameters.

Some examples:

<dascript>

// Debug script: heals the object with the given tag. If tag is invalid, nothing happens
void main()
{

string sTag = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
object oCreature = GetObjectByTag(sTag);
effect eHeal = EffectHeal(25.0f)
//ApplyEffect...
}

</dascript>

<dascript>

// Debug script: applies the visual effect passed in as parameter to the player
void main()
{

string sEffect = GetLocalString(GetModule(),"RUNSCRIPT_VAR");
int nEffect = StringToInt(sEffect);
effect eVfx = EffectVisualEffect(nEffect);
//ApplyEffect...
}

</dascript>

=== Error messages and logging ===

See [[Script error]] for details of how to correct errors in scripts.

To enable script logging, edit or create <DragonAgeInstallDirectory>\bin_ship\[[ECLog.ini]] and set Script=1 in the [LogTypes] section.

The [[PrintToLog]] function prints messages to the log file once logging is enabled.

== Timing ==

Commands, delayed events and object destruction all take place after the current script is finished running. Plot flags set in script are set in-line but the triggered plot script runs before the flag is actually set (this is clarified a bit in the plot script template).

Given that ExecuteScript is deprecated, HandleEvent should be used when you want the script to run in-line and DelayEvent should be used when you want to delay execution.

To delay execution when dealing with creatures, custom AI and (safe) command complete are nice tools. DelayEvent should be used whenever you know how long you want to wait before the event fires. (It can also be used in quite small time increments to give the illusion of smoothly sliding placeables with SetPosition or interpolate between two different atmosphere/lighting settings, but the overhead of this is noticeable if overused).

== Searching Scripts ==

To find examples of how Bioware does things, or simply to discover where a function or variable is used, it's useful to be able to search all the scripts in the data base for a string.

You'll need [Preparing_a_dialog_for_recording | Microsoft SQL Server Management Studio Express] for this.

Enter the following query:

SELECT [bw_dragonage_content].[dbo].[t_Module].Name, [bw_dragonage_content].[dbo].[t_ModuleResRefVersion].Name
FROM [bw_dragonage_content].[dbo].[t_Module], [bw_dragonage_content].[dbo].[t_ModuleResRefVersion],
[bw_dragonage_content].[dbo].[t_Script]
WHERE [bw_dragonage_content].[dbo].[t_Module].ID
= [bw_dragonage_content].[dbo].[t_ModuleResRefVersion].ModuleID
AND [bw_dragonage_content].[dbo].[t_ModuleResRefVersion].ID
= [bw_dragonage_content].[dbo].[t_Script].ModuleResRefVersionID
AND Text LIKE '%######%'
ORDER BY 1, 2;

where ###### is the string you want to find.

This will list the name of every script that contains the string ######.

There will be duplicates if the data base contains multiple versions of a script (maybe an SQL programmer can improve the query to eliminate this, but it's no big deal).

[[Category:Scripts]]
{{Languages}}