Dragon Age Toolset Wiki - User contributions [en]

Plot

2009-12-30T12:19:24Z

Innodil Ath Nathosh:

A plot is a bundle of boolean (true or false) values that can be used to track the state of the game world. They are most commonly used to control the flow of conversations and to control the contents of the player's journal.

They can also be used as a convenient way to run [[script]]s.

== Journal entries ==

Journal entries are created in the Plot Manager. When you open a Plot, you'll see a window called "Journal Text" at the bottom of the screen. Creating a journal entry is as simple as writing the text of the entry to that window while you have the appropriate flag selected.

For example, if you wanted to add a journal entry to the flag "JOURNAL_TEST" in the plot test_journal.plo, then you would check out test_journal, select "JOURNAL_TEST", and enter your journal text in the "Journal text" window.

For journal purposes, each plot file is a single journal topic, and so every flag that has an entry for a specific journal topic (say, "The Quest for the Golden Chicken") must be listed under the same plot file (say, "test_chicken"). You name the journal topic in the "Name" field in the Object Inspector when you have a Plot open.

For example, the Quest for the Golden Chicken has four parts:

*QUEST_GIVEN: Research the last known location of the Golden Chicken.
*RESEARCH_DONE: You know where the Chicken was last seen: the Museum of Precious Fowl. Talk to the curator of the museum to see if she heard anything about the whereabouts of the Golden Chicken.
*CURATOR_MET: You spoke to the curator of the Museum of Precious Fowl. She told you many things, of which the current location of the Chicken is one. Go to the Dungeon of Infinite Sorrows and find the Golden Chicken.
*CHICKEN_FOUND: You found the Golden Chicken. You are awesome.

As long as all relevant flags are in the same plot, each time a new flag is set, that flag's Journal Text will replace that of the previously set flag.

Only the latest Journal Text is displayed, but any previously set flags remain set (unless you explicitly switch them off). For example, when RESEARCH_DONE is set, QUEST_GIVEN will normally be set, too.

If you want to track steps within a subplot (say finding the Golden Chicken's last-known location involved several steps of researching places and visiting them in turn), you'll want to create multiple smaller plots and organize the flags within them, possibly naming them to indicate that they're subplots.

For example, if the Quest for the Golden Chicken had subplots of "Go to the dig site," "Speak with the Professor," and "Find the Tome of Finding Stuff," then you might want to create separate plots for each and begin each plot's name with "Golden Chicken: Go to the dig site" and so on. If you want to preserve the text of a journal entry when the next entry is given, you have to paste the original entry's text into the new entry or organize the new entry into a separate plot.

Currently there is a limit of 256 plot flags per plot. 128 of these flags are standard plot flags and the other 128 are "defined" plot flags whose state is determined by scripting each time they're read.

In addition to handling quest-related journal entries, plots also handle "codex" entries that provide background information about the world and other such details. See the Entry Type property for setting this.

Tags for italics (<i> and </i>) can be used in the journal text field. Text can be emphasized with the <emp> and </emp> tags.

When a plot flag with "Final" set to "Yes" is set, the journal entry for the plot will be moved into the completed quests section of the journal.

== Scripting ==

To interact with a plot's flags you'll need to include the plot in a script with a "plt_" prefix. For example, if you have a plot whose resource name is "kill_all_wolves", adding the following line at the top of your script would give it access to examine and change the flags in the "kill_all_wolves" plot:
<dascript>
#include "plt_kill_all_wolves"
</dascript>

You can then use the wrapper functions in wrappers_h (include "wrappers_h" to make them available) to get and set plot flags using the plot's name and flag's names as constants, like so:

<dascript>
int flag_value = WR_GetPlotFlag(PLT_KILL_ALL_WOLVES, FLAG_NAME);
WR_SetPlotFlag(PLT_KILL_ALL_WOLVES, FLAG_NAME, flag_value);
</dascript>

=== Plot event scripts ===

Many tasks in Dragon Age are accomplished by plot scripts triggered whenever a plot flag is read or set. A plot flag's ability to store a true/false value easily allows for "run once" situations without having to deal with local variables, but this is not strictly necessary and a plot's event script will run every time the plot flag is set regardless of whether it results in a change in the flag's value.

Unlike other event scripts, a plot script will have the function "int StartingConditional()" called when a plot flag is set or read. This allows the call to have a return value (an integer true/false result) that is most important when dealing with defined plot flags.

[[EVENT_TYPE_SET_PLOT]] is sent whenever a normal plot flag is set, with the event's integer 1 holding the identity of the plot flag that had been set. Note that the plot script is called ''before'' the plot flag itself is set; the plot flag's value doesn't change until after the script finishes running.

[[EVENT_TYPE_GET_PLOT]] is sent whenever a "defined" plot flag is read. The plot script's StartingConditional() function should return a result of TRUE or FALSE to indicate what the defined plot flag's value is.

To use a plot event script:
* create a script e.g. "kill_all_wolves.ncs"
* On your plot in the property inspector (bottom right of toolset) make sure to assign your script to your plot (instead of the default ''plot_core'')
* Set or get a plot flag, making sure to set the last parameter (nCallScript) to TRUE (see [[WR_GetPlotFlag]] and [[WR_SetPlotFlag]]
* Remember that your script is executed ''each time a flag is set/get''

If you want to trigger the plot (and thus the script) you can just call:
<dascript>
WR_SetPlotFlag(PLT_KILL_ALL_WOLVES, FLAG_NAME, flag_value, TRUE);
</dascript>

'''Important:''' Notice the last parameter '''TRUE'''. This parameter '''must''' be set to TRUE to have the function also call the plot script!

== Plot assist markers ==

Many quest givers in the single player campaign have a "!" symbol above their heads to indicate they can offer the player a quest. This will also appear on the area map. In order to have this present, you need to set the creature as a plot giver. This can be done in one of two ways, either within the creature properties, or via script using the following function:
<dascript>SetPlotGiver(oObject, TRUE);</dascript>
Once the player has received the quest, you need to disable this flag, unless you wish for the "!" symbol to remain over the character and on the world map. This can be done by using the plot's event handler script and adding the following line when handling the event that accepts the quest:
<dascript>SetPlotGiver(oObject, FALSE);</dascript>

In order to display intermediate plot markers (the downward pointing arrow symbol), you will need to modify the plot itself. For quest destinations you will want to add the tag of the creature or placeable to the Plot Assist list (bottom right) for the individual plot flags that are triggered when you want the destination marker to apear and disappear (Status set to Yes or No).

== Plot flag ordering ==

Order doesn't matter for standard plot files, but does matter for codex plots.

For standard plots, whichever journal flag was last set to true will be the one that shows up in the journal. (I don't remember for certain at the moment, but I believe if you set additional "final" flags true it won't update a completed quest.)

For codex plots all active flags are displayed in order from least to greatest. This is used in cases like character entries where several equivalent entries are plot-dependent.

For example:

:0: Cookie Monster is a devourer of cookies.
:1: Cookie Monster was a devourer of cookies.
:2: He threatened to destroy the kingdom.
:3: <FirstName/> dispatched him handily.
:4: But <FirstName/> bribed him with a cookie.
:5: But Big Bird made him play nice.

0 would be true initially and set to false (with 1 set to true) if Cookie monster died. 2 would always be true. Only one of 3,4, or 5 would be true, depending on the player's actions (killing, bribing, or ignoring Cookie Monster). If the player had not yet encountered the monster and chosen an action, flags 3, 4, and 5 would all be false.

== Granting rewards via plots ==

Each plot flag can have a reward associated with it, picked from a list defined by the [[rewards.xls]] [[2DA]]. This reward is given to the player when the plot flag is set.

== Properties ==

{{inspector start}}
{{inspector section|General}}
{{inspector row|Allow Pausing| }}
{{inspector row|Entry Type| }}
{{inspector row|GUID| Unique in-game identifier for a plot. }}
{{inspector row|Journal Image| An optional journal image that can appear in the journal for this plot. }}
{{inspector row|Name| Name of the plot as shown in the journal}}
{{inspector row|NameRequiresReTranslation| A true/false flag used during game development for localization work }}
{{inspector row|Parent Plot| Associates subplots with a main plot. }}
{{inspector row|Priority| Sorts the plots in the journal }}
{{inspector row|Resource Name| A unique string identifier the toolset and the game both use to refer to this resource }}
{{inspector row|Script| Event script assigned to the resource. }}
{{inspector end}}

[[Category:Plots]]

Event keyword

2009-12-30T11:13:25Z

Innodil Ath Nathosh:

__NOTOC__
The '''event''' type represents a package of information that can be passed around in the game to trigger some behaviour.

== Constructor ==

A constructor is a function that creates an instance of a [[DAScript_types|dascript type]].

The constructor for an event is [[Event]].

== Literals ==

A literal is a textual representation of a particular value of a type.

There is no literal for an event.

== Conversion ==

There is no explicit or implicit conversion to or from an event.

== Examples ==

<dascript>
void main()
{
// uninitialised
event evDefault;

// initialised using the constructor
event evConstructed = Event(EVENT_TYPE_USE);

// initialised using a function
event evCurrent = GetCurrentEvent();
}
</dascript>

== Remarks ==

Events are usually passed off to an [[object (dascript type)|object's]] [[event script]] for handling, but there are a few engine-only event types that are not exposed to the end-users.

Scripting Events have an integer type, target object, a time delay and a package of parameters (arbitrary number of [[int (dascript type)|ints]], [[object (dascript type)|objects]], [[float (dascript type)|floats]] and [[string (dascript type)|strings]]). Certain event types will be defined by the engine and referenced as #defines in the scripts.

Events are handled in the scripting language with the following types of commands:
* Event() Constructor — Scripters can create events of any type and signal them to other objects
* Signal Event commands — Events can be signalled to a single object, by proximity or to all objects with a certain group id
* Parameter access — All of the parameters on an event can be get and set through scripting.
* Event handling — Events can be passed to other script files through the HandleEvent command. This command will be run inline so that hierarchies of event-handling behaviour can be built.

A typical event-handling script would have the form

<dascript>
void main()
{
event ev = GetCurrentEvent();
int nEventType = GetEventType(ev); //extract event type from current event
int nEventHandled = FALSE; //keep track of whether the event has been handled
switch(nEventType)
{
case EVENT_TYPE_AREALOAD_SPECIAL:
{
...
nEventHandled = TRUE; //set this if no further action is required for this event
break;
}
}
if (!nEventHandled) //If this event wasn't handled by this script, let the core script try
{
HandleEvent(ev, RESOURCE_SCRIPT_AREA_CORE);
}
}
</dascript>

In the event that you want to intercept some events but leave others to be handled by a default script (for example if you're overriding one aspect of a creature's event response but the rest of the default creature_core responses responses are fine) you can pass execution to the default script with the following:

<dascript>
HandleEvent(ev, RESOURCE_SCRIPT_CREATURE_CORE);
</dascript>

(constants for referencing core script resources are available in the "global_objects_h" include file)

Below is a list of the event types that are defined within the core resources. Custom events can also be defined, and will also have documentation in this wiki; if you don't find an event here try browsing the [[:Category:Event types|event type categories]].

* '''Perception'''
** [[EVENT_TYPE_PERCEPTION_APPEAR]] - A creature enters the perception area of creature receiving the event
** [[EVENT_TYPE_PERCEPTION_DISAPPEAR]] - A creature exits the perception area of creature receiving the event
* '''Effects'''
**[[EVENT_TYPE_APPLY_EFFECT]] - an effect is applied to the receiving object
**[[EVENT_TYPE_REMOVE_EFFECT]] - an effect is removed from the receiving object
* '''Combat'''
**[[ EVENT_TYPE_COMBAT_INITIATED ]] - Fires whenever the attack command is added into the command queue. Used to set combat mode and combat camera/music. Also fires by scripting to trigger combat after being attacked or an ally is attack.
**[[ EVENT_TYPE_COMBAT_END ]] - a creature doesn't perceive any more hostiles.
**[[ EVENT_TYPE_MELEE_ATTACK_START ]] - {{undocumented}}
**[[ EVENT_TYPE_COMMAND_PENDING ]] - Fires at the beginning of the attack part of the attack command OR at the beginning of an ability execution.
**[[ EVENT_TYPE_COMMAND_COMPLETE ]] - creature finishes doing a command(attack, special ability, spell, conversation, etc)
**[[ EVENT_TYPE_ATTACK_IMPACT ]] -- An attack has impacted the target. This can be melee (sword hit), ranged (arrow hit) or spell (fireball explodes). Used for applying damage, and handling abilities that function on hit (Berserk etc').
**[[ EVENT_TYPE_ATTACKED ]] - another object tried attacking this creature using melee/ranged weapons (hit or miss), talents or spells.
**[[ EVENT_TYPE_ALLY_ATTACKED ]] - an ally has received the ATTACKED event. An ally is an object with the same group ID.
* '''Damage and death'''
**[[ EVENT_TYPE_DAMAGED ]] - an object loses 1 hit point or more
**[[ EVENT_TYPE_DOT_TICK ]] - Damage over time tick event.
**[[ EVENT_TYPE_DYING ]] - a creature received the killing blow.
**[[ EVENT_TYPE_DEATH ]] - creature or placeable have the death effect applied (regardless of hitpoints)
**[[ EVENT_TYPE_RESURRECTION ]] - Creature resurrected.
**[[ EVENT_TYPE_TEAM_DESTROYED ]] - Fires when an entire team of creatures is destroyed.
* '''Inventory '''
**[[ EVENT_TYPE_INVENTORY_ADDED ]] - An item is added to the personal inventory of the object receiving the event or the party inventory.
**[[ EVENT_TYPE_INVENTORY_REMOVED ]] - An item is removed from the personal inventory of the object receiving the event or the party inventory.
**[[ EVENT_TYPE_EQUIP ]] - The current creature has equipped an item
**[[ EVENT_TYPE_UNEQUIP ]] - The current creature has unequipped an item
**[[ EVENT_TYPE_CAMPAIGN_ITEM_ACQUIRED ]] - items with the ITEM_ACQUIRED_EVENT_ID variable set are picked up.
**[[ EVENT_TYPE_INVENTORY_FULL ]] - {{undocumented}}
**[[ EVENT_TYPE_OUT_OF_AMMO ]] - {{undocumented}}
* '''Movement'''
**[[ EVENT_TYPE_BLOCKED ]] - The current creature's path has been blocked while moving by a creature or door. This event will NOT fire when blocked by placeables who can not change the walk mesh or terrain.
**[[ EVENT_TYPE_ENTER ]] - A creature enters the object receiving the event
**[[ EVENT_TYPE_EXIT ]] - A creature exits the object receiving the event
**[[ EVENT_TYPE_REACHED_WAYPOINT ]] - {{undocumented}}
* '''Traps'''
**[[ EVENT_TYPE_APPROACH_TRAP ]] - Trap triggered and the creature receiving this event should approach the trap
**[[ EVENT_TYPE_TRAP_ARM ]] Sent by script to request that a trap arm itself.
**[[ EVENT_TYPE_TRAP_TRIGGER_ENTER ]] - {{undocumented}}
**[[ EVENT_TYPE_TRAP_DISARMED ]] - {{undocumented}}
**[[ EVENT_TYPE_TRAP_TRIGGER_ARMED ]] - {{undocumented}}
**[[ EVENT_TYPE_TRAP_TRIGGER_EXIT ]] - {{undocumented}}
**[[ EVENT_TYPE_TRAP_TRIGGERED ]] - {{undocumented}}
* '''Game state events'''
**[[ EVENT_TYPE_SPAWN ]] - an object spawns into the game. This event can fire only once per game for each object, regardless of save games.
**[[ EVENT_TYPE_MODULE_START ]] - The module starts. This can happen only once for a single game instance.
**[[ EVENT_TYPE_MODULE_LOAD ]] - The module loads from a save game. This event can fire more than once for a single module or game instance.
**[[ EVENT_TYPE_AREALOAD_SPECIAL ]]- for playing things like cutscenes and movies when you enter an area, things that do not involve AI or actual game play
**[[ EVENT_TYPE_AREALOAD_PRELOADEXIT ]] - for things you want to happen while the load screen is still up, things like moving creatures around
**[[ EVENT_TYPE_AREALOAD_POSTLOADEXIT ]] - fires at the same time that the load screen is going away, and can be used for things that you want to make sure the player sees.
**[[ EVENT_TYPE_AREALOADSAVE_POSTLOADEXIT ]] - fires at the same time that the load screen is going away, but only when loading a savegame.
**[[ EVENT_TYPE_GAMEMODE_CHANGE ]]
**[[ EVENT_TYPE_DELAYED_GM_CHANGE ]]
**[[ EVENT_TYPE_SET_GAME_MODE ]]
*'''Plots'''
**[[ EVENT_TYPE_SET_PLOT ]] - A plot is setting a plot flag
**[[ EVENT_TYPE_GET_PLOT ]] - A plot is setting a plot flag
*''' Dialogue'''
**[[ EVENT_TYPE_DIALOGUE ]] - An object tries to initiate dialog with the object receiving the event, either by clicking or by scripting
**[[ EVENT_TYPE_DELAYED_SHOUT ]] - Used to fire a dialog shout every few seconds.
**[[ EVENT_TYPE_AMBIENT_CONTINUE ]] - conversation ends or player is nearby to resume ambient behaviour
*'''Party management'''
**[[ EVENT_TYPE_PARTYMEMBER_ADDED ]] - Party member added to active party using the party GUI
**[[ EVENT_TYPE_PARTYMEMBER_DROPPED ]] - Party member removed from active party using the party GUI
**[[ EVENT_TYPE_PARTYPICKER_CLOSED ]] - {{undocumented}}
**[[ EVENT_TYPE_PARTY_MEMBER_HIRED ]] - Fires first time a party member is added to the party. For plot followers: follower recruited (added to pool). For other followers: UT_Hire called
**[[ EVENT_TYPE_PARTY_MEMBER_FIRED ]] - Fires when an active or locked-active party member is removed from the active party
**[[ EVENT_TYPE_PARTY_MEMBER_RES_TIMER ]] - Resurrection timer used if a creature dies in explore mode.
**[[ EVENT_TYPE_GIFT_ITEM ]]- {{undocumented}}
**[[ EVENT_TYPE_MODULE_HANDLE_FOLLOWER_DEATH ]] - {{undocumented}}
**[[ EVENT_TYPE_MODULE_HANDLE_GIFT ]] - {{undocumented}}
**[[ EVENT_TYPE_SUMMON_DIED ]] - {{undocumented}}
* '''Character generation and level advancement '''
**[[EVENT_TYPE_CHARGEN_START]] and [[EVENT_TYPE_CHARGEN_END ]] - A range of event constants (nEvent >= EVENT_TYPE_CHARGEN_START && nEvent <= EVENT_TYPE_CHARGEN_END) that occur during character generation.
**[[ EVENT_TYPE_PLAYER_LEVELUP ]] Fired by sys_rewards_h.RewardXP (the levelup system)
**[[ EVENT_TYPE_PLAYERLEVELUP ]]
**[[ EVENT_TYPE_CHARGEN_AUTOLEVEL ]]
**[[ EVENT_TYPE_MODULE_CHARGEN_DONE ]]
**[[ EVENT_TYPE_GUI_OPENED ]] - GUI tutorial calls
* '''World map'''
**[[ EVENT_TYPE_TRANSITION_TO_WORLD_MAP ]] - Player uses the generic transition system to open the world map
**[[ EVENT_TYPE_WORLD_MAP_CLOSED ]]
**[[ EVENT_TYPE_WORLD_MAP_USED ]] - the player clicks on a destination in the world map
** [[ EVENT_TYPE_BEGIN_TRAVEL ]]
** [[ EVENT_TYPE_WORLDMAP_PRETRANSITION ]]
**[[ EVENT_TYPE_WORLDMAP_POSTTRANSITION ]]
**[[ EVENT_TYPE_FINISH_TRAVEL ]]
*''' Found in placeable_core '''
**[[ EVENT_TYPE_PLACEABLE_ONCLICK ]] player clicks on object.
**[[ EVENT_TYPE_USE ]]
**[[ EVENT_TYPE_UNLOCKED ]] Sent by script when placeable is unlocked.
**[[ EVENT_TYPE_SET_OBJECT_ACTIVE ]] Sent by script to change active state. Needed since CommandDoFunction was removed and we're using CommandDoEvent
**[[ EVENT_TYPE_PLACEABLE_COLLISION ]] player collides with object (if EnableCollisionEvent column in placeables.xls is non-zero).
**[[ EVENT_TYPE_POPUP_RESULT ]]
* '''Found in rules_core'''
**[[ EVENT_TYPE_ITEM_ONHIT ]]
**[[ EVENT_TYPE_CONFUSION_CALLBACK ]]
**[[ EVENT_TYPE_DESTROY_OBJECT ]]
* '''Found in player_core'''
**[[ EVENT_TYPE_HEARTBEAT ]]
**[[ EVENT_TYPE_LOAD_TACTICS_PRESET ]]
*'''Spellcasting'''
**[[ EVENT_TYPE_ABILITY_CAST_START ]]
**[[ EVENT_TYPE_ABILITY_CAST_IMPACT ]]
**[[ EVENT_TYPE_CAST_AT ]]
**[[ EVENT_TYPE_COMBO_IGNITE ]]
**[[ EVENT_TYPE_SPELLCASTAT ]]
**[[ EVENT_TYPE_SPELLSCRIPT_CAST ]]
**[[ EVENT_TYPE_SPELLSCRIPT_DEACTIVATE ]]
**[[ EVENT_TYPE_SPELLSCRIPT_IMPACT ]]
**[[ EVENT_TYPE_SPELLSCRIPT_PENDING ]]
* '''Proving events'''
**[[ EVENT_TYPE_PROVING_ENTER ]]
**[[ EVENT_TYPE_PROVING_EXIT ]]
**[[ EVENT_TYPE_PROVING_LOSE ]]
**[[ EVENT_TYPE_PROVING_START ]]
**[[ EVENT_TYPE_PROVING_WIN ]]
* '''Debugging'''
** [[ EVENT_TYPE_DEBUG_KICKSTART_AI ]]
**[[ EVENT_TYPE_DEATH_RES_PARTY ]]
**[[ EVENT_TYPE_DEBUG_RESURRECTION ]]
* '''Stats'''
**[[ EVENT_TYPE_STAT_REGEN ]]
**[[ EVENT_TYPE_MANA_STAM_DEPLETED ]]
* '''Miscellaney'''
**[[ EVENT_TYPE_CLICK ]]
**[[ EVENT_TYPE_CUSTOM_COMMAND_COMPLETE ]]
**[[ EVENT_TYPE_FAILTOOPEN ]]
**[[ EVENT_TYPE_HANDLE_CUSTOM_AI ]]
**[[ EVENT_TYPE_INVALID ]]
**[[ EVENT_TYPE_LISTENER ]]
**[[ EVENT_TYPE_LOCKED ]]
**[[ EVENT_TYPE_QA_EVENT ]]
**[[ EVENT_TYPE_QA_EVENT_BLA ]]
**[[ EVENT_TYPE_STEALING_FAILURE ]]
**[[ EVENT_TYPE_STEALING_SUCCESS ]]
**[[ EVENT_TYPE_UNIQUE_POWER ]] - Fired when an item with ability "ITEM_ABILITY_UNIQUE_POWER_SINGLE_USE" or "ITEM_ABILITY_UNIQUE_POWER_UNLIMITED_USE" is "used". this event is sent to the '''module''' script. Fired by the core "item_unique_power.ncs" script.

== Shouts ==

Shouts (events) are used to make creatures communicate with one another. This is a list of all the shouts referenced in the AI documentation.

[[ Creature Shouts ]]

*SHOUT_TYPE_WASATTACKED When I am attacked, signal this event for all allies. What do the allies do? They will go into combat round, not specifically targeting this attacker but becoming combat ready.
*SHOUT_TYPE_SAWENEMY Attack enemy.
*SHOUT_TYPE_KILLEDME Attack enemy.
*SHOUT_TYPE_SWITCH_MELEE Will switch to melee weapons, useful for certain plot situations
*SHOUT_TYPE_WAKE_UP Any creature that hears this shout will wake up, if sleeping. This shout needs to be manually called.
*SHOUT_TYPE_FOUND_SOMEONE (YaronToDo) a scout sees someone they broadcasts this event. Allies go here. (NOT DONE)

[[ Commander-Specific Orders ]]

*SHOUT_TYPE_FINISHHIM Attacks a specified enemy till they are dead. A Commander issues order generally.
*SHOUT_TYPE_ATTACK_WIZARD (YaronToDo) Starting targeting wizard class enemies instead of others.
*SHOUT_TYPE_FLANK Rogues will get into a flanking position to an appropriate enemy
*SHOUT_TYPE_SWITCH_RANGED Will randomly choose one ally and ask them to switch to a ranged weapon. This is mostly done to even out the number of participants in melee battle for animation purposes (closer to even the sides are, the better things look)

== See Also ==

[[IsEventValid]], [[HandleEvent]], [[SignalEvent]]

[[Category: DAScript types]]
[[Category:Events]]

Scripting overview

2009-12-30T10:53:06Z

Innodil Ath Nathosh:

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 < b ? c : d;</dascript>
|}
=== 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]] - 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).

[[Category:Scripts]]