Divinity Engine Wiki - User contributions [en]

Osiris/API/CharacterFollowCharacter

2022-06-02T19:21:40Z

LaughingLeader: Added a link to CharacterSetFollowCharacter

===== Full Definition(s) =====
* call '''CharacterFollowCharacter'''(''(CHARACTERGUID)'''''_Character''', ''(CHARACTERGUID'')'''''_ToCharacter''')

===== Description =====
Makes '''_Character''' start following '''_ToCharacter'''.

===== Notes =====
* Preferably use [[Osiris/Shared/ProcCharacterFollowCharacter|ProcCharacterFollowCharacter]] from the Shared mod. This will ensure that '''_Character''''s following behaviour gets suspended when it enters combat, and resumed afterwards.
* Use [[Osiris/API/CharacterStopFollow|CharacterStopFollow]] to stop the following behaviour (or [[Osiris/Shared/ProcCharacterStopFollow|ProcCharacterStopFollow]] if you used [[Osiris/Shared/ProcCharacterFollowCharacter|ProcCharacterFollowCharacter]]).
* Make sure to stop following a previous character before starting to follow a new one. [[Osiris/Shared/ProcCharacterFollowCharacter|ProcCharacterFollowCharacter]] will automatically take care of this.
* Note that this call does ''not'' turn '''_Character''' in a so-called "party follower" or minion, which is done via [[Osiris/API/CharacterAddToPlayerCharacter|CharacterAddToPlayerCharacter]]. The difference between "regular followers" (as created by this routine) and party followers/minions is that regular followers simply follow any other character around (you can have one NPC follow another one, if you want), while party followers/minions always follow a player-controlled character and can be partially controlled by the [[Osiris/API/CharacterGetReservedUserID|user]] that controls this player character.

===== See Also =====
* [[Osiris/API/CharacterAddToPlayerCharacter|CharacterAddToPlayerCharacter]]
* [[Osiris/API/CharacterStopFollow|CharacterStopFollow]]
* [[Osiris/API/CharacterSetFollowCharacter|CharacterSetFollowCharacter]]
* Helper [[Osiris/Shared/ProcCharacterFollowCharacter|ProcCharacterFollowCharacter]]
* Helper [[Osiris/Shared/ProcCharacterStopFollow|ProcCharacterStopFollow]]

[[Category:Osiris Calls|CharacterFollowCharacter]]

Osiris/API/CharacterSetFollowCharacter

2022-06-02T19:20:50Z

LaughingLeader: Added definition information for CharacterSetFollowCharacter.

===== Full Definition(s) =====
* call '''CharacterSetFollowCharacter'''(''(CHARACTERGUID)'''''_Character''', ''(CHARACTERGUID'')'''''_CharacterToFollow''')

===== Description =====
Sets '''_CharacterToFollow''' as the target to follow for '''_Character''', which is used by the behavior scripting condition '''CharacterGetFollow'''.

===== Notes =====
* Use '''NULL_00000000-0000-0000-0000-000000000000''' as the '''_CharacterToFollow''' value to clear the internal follow target for '''_Character'''.
* The internal value set is used by the '''Base.charScript''' reactions '''StartFollow''' and '''StopFollow''', via the '''CharacterGetFollow''' condition. Every character automatically has this script attached via its inclusion in '''DefaultCharacter.charScript'''.
* [[Osiris/API/CharacterAddToPlayerCharacter|CharacterAddToPlayerCharacter]] sets the same internal follower value, except the character is visibly "attached" in the UI, like summoned characters.
* Preferably use [[Osiris/Shared/ProcCharacterFollowCharacter|ProcCharacterFollowCharacter]], as it automatically handles conditions where following may need to be started or stopped).

===== See Also =====
* [[Osiris/API/CharacterFollowCharacter|CharacterFollowCharacter]]
* [[Osiris/API/CharacterStopFollow|CharacterStopFollow]]
* [[Osiris/API/CharacterAddToPlayerCharacter|CharacterAddToPlayerCharacter]]
* Helper [[Osiris/Shared/ProcCharacterFollowCharacter|ProcCharacterFollowCharacter]]
* Helper [[Osiris/Shared/ProcCharacterStopFollow|ProcCharacterStopFollow]]

[[Category:Osiris Calls|CharacterSetFollowCharacter]]

Your First Story Script

2020-08-27T01:01:55Z

LaughingLeader: Added a screenshot for the content browser button.

Note: this tutorial assumes you have already [[Project browser|created a mod project]], and have a [[Osiris Overview|general idea on Osiris syntax]]. For the purposes of this tutorial, we will be using a basic "Addon" project that targets "Story".

== Required Reading ==
The following is required reading, as it covers the Story Editor, and Osiris syntax and concepts:
* [[Story_editor|Story Editor]]
* [[Osiris Overview]]

== Recommended Reading ==
* [[Osiris_Tips_and_Examples|Osiris Tips and Examples]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]

=== API Docs ===
* [[:Category:Osiris_APIs|Osiris APIs]]
* [[:Category:Osiris_Calls|Osiris Calls]]

== Overview ==
While some basic concepts are covered here, Osiris syntax and defintitions should be referred to in [[Osiris Overview]], as the goal of this tutorial is to guide you in creating a foundation for your code to run, via a parent script and child script.

=== Starting Tips ===
Before we get started, some basic tips to keep in mind:

==== Generate Definitions ====
When opening the story editor in a new project, always generate definitions (File -> Generate Definitions) and exit/re-open the story editor. This will generate the files necessary for auto-complete and syntax highlighting.

==== Prefixing ====
Prefix your goals (a.k.a. your script files), databases, queries, and procs in a way that will make then unique and least likely to conflict with other mods. For example, if our mod is called "Better Cupcakes", and our username is "SuperChef", we could prefix our mod entries with SCBC, or SC_BetterCupcakes, or some combination of the two.

''This concept also applies for entries in the stats editor, as multiple entries with the same name will conflict.''

== Implementing a Basic Story Script ==
=== Getting Started ===
----
# Open the [[Story editor]] by clicking the icon that looks like a book ([[File:StoryEditor_Icon.png|24px]]) under the "Editors" section, at the top-right of the Divinity Engine 2 editor.
# Inside the story editor, Click "File -> Generate Definitions and Build" on the top left.
#* This is an important step in generating the appropriate files. Any time you create new definitions (databases, PROCs, or queries), you need to generate definitions.
#* Building is as equally important, as your changes won't compile until you build.
#* Reloading the story is necessary to see your changes in-game. You can either do this from the story editor ("File -> Reload Story"), or from the main editor with "File -> Reload Level and Story".
# Close the story editor and open it again to essentially reload the syntax highlighting and auto-complete features.

=== Creating a Parent Goal ===
----
For organizational purposes, creating a parent story goal is recommended. For the sake of this tutorial, we'll be parenting our parent goal to __Start, which is a goal provided by Shared.

# Inside the story editor, at the goal list on the left, right click "__Start" and select "Add New Sub Item...".
[[File:FirstStoryScript_ParentingToStart.png|thumb|Right click the goal and click "Add New Sub Item..."]]
# Name this script something unique to your mod in a prefix format (Username_ModName), such as "SuperChef_BetterCupcakes". This has the best chance of not potentially conflicting with any other mod.
# After clicking OK, your script will automatically open. Hit CTRL+S to automatically save this script. Scripts with unsaved changes display and asterisk (*) next to their name.

==== Tip: Story Script Naming ====
----
Goals in the story are ran in alphabetical order. This is important to keep in mind if you use a particular story goal as a sort of "top-level" script that has methods and databases your other goals reference to.

With proper naming, you can control the order your scripts are run. For example, naming your top-level goal "WT_FS__Main", and your second goal "WT_FS_Skills" ensures "WT_FS__Main" will always run before "WT_FS_Skills".
[[File:FirstStoryScript_ScriptOrder.png|thumb|WT_FS__Main will always run before WT_FS_Skills.]]

=== Completing the Parent Goal ===
----
Parent goals need to "complete" before their sub-goals will run. This is done by calling "GoalCompleted;" within the parent script. We have a few options for how to go about this:

==== Parenting to a DOS2 Goal ====
----
Instead of handling the completion events yourself, simply parenting your parent goal to some specific goals provided by Larian is an easy way to ensure your goal runs at the right time.

;Parenting to __Start (No Origins Dependency)
:If your mod doesn't depend on Origins (see: [[Project_settings_window#The_Dependencies_Tab|Dependencies]], parenting your parent goal to __Start will ensure that it runs when the game is ready.

;Parenting to Start (Origins Dependency)
:Start (not to be confused with __Start) is a top-level goal in Origins that completes when character creation is ready, or if a mode other than "Campaign" is started. Parenting to this goal requires your mod to have Origins as a dependency.

;Manual Completion
:Rather than relying on an existing parent goal, it's possible to make a top-level goal that completes on its own. See more on that here: [[Your_First_Story_Script#Manually_Completing_Parent_Goals|Manually Completing Parent Goals]].

==== Parenting Example ====
----
Inside of the INIT section of our new goal, enter the following:
<pre>
DB_WikiTutorial_ModStarted(1);
</pre>

Next, inside the KB section of your goal, enter the following:
<pre>
IF
DB_WikiTutorial_ModStarted(1)
THEN
DebugBreak("[WT_FS] WikiTutorial_FirstStory has initialized.");
GoalCompleted;
</pre>

The goal should look like so:
[[File:FirstStoryScript_ParentGoal.png|thumb]]

# Save, then select "File -> Build and Reload".
# Minimize the story editor.
# Inside the message log, you should see the message we added with DebugBreak.
[[File:FirstStoryScript_ParentGoalComplete.png|thumb|The debug message appears in the message log once the game is started.]]

The way this example works is, as soon as __Start calls GoalCompleted; (which occurs when the event GameEventSet("GAMEEVENT_GameStarted") fires), our goal then sets a database value, which then triggers our own code for GoalCompleted.

Additionally, if this mod is added to an existing save, where __Start was already completed, our parent goal will complete as well, due to the way the parent-child goal relationship works (if a parent is already complete when a new child is added, that child will run).

=== Adding a Sub-Goal ===
----
With the parent goal completing properly, parented sub-goals will now run.

==== Creating a Sub-Goal ====
----
Let's create a basic script that will display some text when a skill is cast.

# Double click on your parent goal to have it selected.
#* Currently, there's a bug where not having your parent goal open may cause a sub-item created to not properly parent under the right goal. If this happens, simply click and drag the new goal to your parent goal, and it should move underneath it.
# Click "Add New Sub Item...", then name it something appropriate, like "WikiTutorial_FirstStory_Skills".
# Save the new script (CTRL+S).

==== Creating a Rule ====
----
In the KB section of our new script, add the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

IF
SkillCast(_Character, "Shout_InspireStart", _, _)
AND
DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Good job!");
CharacterResetCooldowns(_Character);
</pre>

This rule will run when the player casts "Encourage", displaying some text, and resetting their cooldowns. The Encourage skill is added automatically to the player if they lack it.

# Save, then "Generate Definitions and Build".
# In the main editor, select "File -> Reload Level and story".
# Hit the "Switch Game/Editor" button to get in-game. [[File:FirstStoryScript_GameEditorButton.png|thumb|Click this button to switch between game and editor mode.]]
# In whatever level you're working in, your provided dummy character should spawn and be given the Encourage skill.
# Cast the skill to test that your script is working properly.
[[File:FirstStoryScript_SkillCast_Result.png|thumb|Our script in action.]]

===== Notes =====
----
'''HTML Font Formatting'''
* HTML font formatting can be used in DisplayText, CharacterStatusText, and in various text entries (skill descriptions, status names/descriptions, book text, and more).

'''SkillCast '''
* This event runs when the skill's animation reaches the CastTextEvent value specified by the skill stats (which is "cast" in most cases).
* The textkey "cast" is a common textkey used in skill cast animations.
* To view the textkeys present in an animation, open it within the [[Content_browser|Content Browser]].
[[File:ContentBrowserButton.png|thumb|Open the Content Browser with this button.]]
* Example: Open the oontent browser and search for the "Humans_Hero_Female_ABC_Skill_Cast_Aoe_Air_01_Cast" animation under the Shared folder. Double click on the resource to open the animation preview to see the different textkeys. [[File:FirstStoryScript_SkillCast_Textkey.png|thumb|The cast textkey.]]

'''DB_IsPlayer'''
* This is a base game database that is populated with all the current player characters when the game is started.
* By passing in the _Character value from the event parameters to DB_IsPlayer, we're matching the character against the database of player characters, to have the following code only run if the caster is a player-controlled character.
* Using DB_IsPlayer as an event makes the subsequent code run when a character is added to the DB_IsPlayer database.

== Taking the Script Further ==
Now that we have a basic script heirarchy working, let's take the script further.

=== Randomization ===
----
We can add randomization to the displayed text in our previous script to make the result more interesting.

We'll do this by creating a custom procedure.

;Procedure Tips:
: Procedures are declared with a "PROC" at the top of the block, and follow the same flow as a rule.
: Parameters for a procedure can be customized. You must declare their type.
: Procedures are called within the "call" section of a rule or a custom query.

Add this to the INIT section:
<pre>
//DB_WikiTutorial_FirstStory_RandomText(_Ran, _Text, _FontColor, _FontSize)
DB_WikiTutorial_FirstStory_Skills_RandomText(0, "Woo!", "00CED1", "23");
DB_WikiTutorial_FirstStory_Skills_RandomText(1, "Good job!", "00FF00", "30");
DB_WikiTutorial_FirstStory_Skills_RandomText(2, "I did it!", "DEB887", "20");
DB_WikiTutorial_FirstStory_Skills_RandomText(3, "I'm da best!", "A52A2A", "26");
</pre>

Change the code in the KB section to the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

PROC
WikiTutorial_FirstStory_Skills_DisplayRandomMessage((CHARACTERGUID)_Character)
AND
Random(4, _Ran)
AND
DB_WikiTutorial_FirstStory_Skills_RandomText(_Ran, _Text, _FontColor, _FontSize)
AND
StringConcatenate("", _Str4)
AND
StringConcatenate(_Str4, _Text, _Str5)
AND
StringConcatenate(_Str5, "", _Message)
AND
IntegertoString(_Ran, _RanStr)
AND
StringConcatenate("[WT_FS] Rolled a ", _RanStr, _DebugMessage)
THEN
DisplayText(_Character, _Message);
DebugBreak(_DebugMessage);

IF
SkillCast(_Character, "Shout_InspireStart", _, _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload".
# Switch back to the main editor and hit the play button to get in-game.
# Cast the Encourage skill a few times in game mode to ensure the script is working properly. You should see the different messages, font colors, and font sizes.

===== Notes =====
----
'''Procedures'''
* WikiTutorial_FirstStory_Skills_DisplayRandomMessage is a custom subroutine call, called a PROC. By splitting our message logic off into a separate procedure, this ensures the calls for this rule are ran regardless of the result of our message logic (so CharacterResetCooldowns will always run if a player casts this skill). This also allows us to use this procedure elsewhere, and possible extend it further.

'''Databases'''
* We create our "RandomText" settings in the INIT section by using a database we create, called "DB_WikiTutorial_FirstStory_Skills_RandomText". Databases are a powerful tool for making your scripting logic extensible.

'''[[Osiris/API/Random|Random]]'''
* [[Osiris/API/Random|Random]] returns a random integer value between 0 and (_Modulo - 1). Since our DB_WikiTutorial_FirstStory_Skills_RandomText has 4 entries, we want our random number to be between 0 and 3, so we use 4 as our _Modulo.

=== Using Queries ===
----
Mastering queries is essential for creating complex conditions for your rules. "OR" logic is done within Osiris with multiple rules, subscribing to the same events, that look for different conditions through the use of queries.

Let's add to our skills script. Add this to the KB section, so your SkillCast rules look like this:

<pre>
IF
SkillCast(_Character, "Shout_InspireStart", _, _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);

IF
SkillCast(_Character, "Shout_InspireStart", _, _)
AND
NOT DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Win... Please! Ahhhh!");
ApplyStatus(_Character, "FEAR", 1.0, 1);
</pre>

By simpling adding a NOT before our database check, our second rule will now run on any character (who's not a player) that casts Encourage, and apply fear. You can test this by loading an inherited level that contains some human enemies, or adding human enemies yourself to your test level.

=== Creating a Custom Query ===
----
Taking this idea further, we'll create a custom query.

Custom queries are defined with the keyword "QRY" at the top of a block, and follow the same flow as a rule.

Add the following code to your KB section:

<pre>
QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "HUMAN", 1)
THEN
DB_NOOP(1);

QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "DWARF", 1)
THEN
DB_NOOP(1);
</pre>

By adding two query blocks with the same name, we're effectively adding an "OR" condition. This query will evaluate as true if the character is tagged as either a human or a dwarf.

"DB_NOOP(1);" is a dummy database fact. Since rules must have a call, DB_NOOP is used to have a rule succeed without using any actual calls.

==== Implementing the Custom Query ====
----

Below our query code, in the KB section, add the following:
<pre>
IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Perception_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Perception_Potion");

IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
NOT WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Constitution_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Constitution_Potion");

IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload". Since we added a query and another database, we must generate the definitions again.
# Go in-game and test out the changes by casting Encourage on an human or dwarf (it will work on yourself as well).

===== Notes =====
----
'''NOT'''
* By adding two rules for the same event, and checking for the opposite of our query, we're effectively adding an OR condition to this event.

'''CharacterConsume/CharacterUnconsume'''
* Since CharacterConsume returns a value, it's a query instead of a call. We store the out value from the query (_Handle) in a database to later unconsume the potion effect when ENCOURAGED ends.

'''Removing Database Entries'''
* When unconsuming the potion handle, notice we also remove that entry from the database by calling "NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);" as a call. Using NOT before a database entry (in the call section) removes that entry.
* By using DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion) in the query section, the _Handle and _Potion value is returned with all entries that match the value we pass in (_Character), effectively unconsuming every potion handle we added for that character to the database.

=== Using a Query as a Subroutine ===
----
While queries can be used as conditions, they can also be used to call specific procedures/calls before the main rule reaches that section of the flow.

Let's try a simple example that runs when we unconsume a potion. Change our status removed event code to this:

<pre>
IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_ZombieCheck(_Character)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "UNDEAD", 1)
AND
CharacterGetDisplayName(_Character, _, _Name)
AND
StringConcatenate("[WT_FS] ", _Name, _Str1)
AND
StringConcatenate(_Str1, " is a zombie! Ahh! Burn it!", _Message)
THEN
ApplyStatus(_Character, "BURNING", 1.0);
DebugBreak(_Message);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
THEN
DB_NOOP(1);
</pre>

Which this, our query will apply burning if the character is tagged as UNDEAD. Note how we added a second QRY rule that always evaluates as true - this is to keep the rest of our rule in the CharacterStatusRemoved event running, undead or not.

Practically speaking, using queries as subroutines is ideal when:
* You need specific calls/procedures to run before iterating through a database. Calling your query before retrieving variables from a database ensures that those calls will only run once.
* You need to debug a rule to ensure it reaches a certain section of the conditions. If you're not sure if a specific condition is passing, adding a query with a DebugBreak message right before/after it is a good way to debug that situation.

== Bonus Tips ==

* In the story editor, select "File -> Open Story Header" for a list of all available events, queries, and calls. Heavily reference this file when you find yourself unsure if a specifc method exists, as not all methods appear in the auto-complete.

* If you use databases to store global mod settings, and your mod users have played with that mod, changing that information post-mod install will not automatically remove that data from existing saves - you need to handle this update internally within your mod.
** More on implementing an update system here: [[Osiris_Tips#Updating_Databases|Manual Mod Updates]].

* By using custom procedures and queries, you can reduce your rule redundancy and extend desired calls/conditions to multiple rules.

* To make your life with Osiris easier, wrap your rule blocks in regions with the following:
<pre>
//REGION MY_REGION_NAME

//END_REGION
</pre>
* In the story editor, right click inside your script sections (INIT, KB, or EXIT) and "Expand All" or "Collapse All" to expand/collapse all regions, respectively.

* Procedures can be called from the EXIT and INIT section of scripts.

* Use the INIT section of your scripts as a way to store commented references to your databases. As an example from our previous script, placing this inside your INIT section is a good way to remember such a database exists (since we don't initialize it in the INIT section):
<pre>
//DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
</pre>
Then, when you wish to use this database, you have a quick way to copy/paste that code into other sections of your script.

=== Manually Completing Parent Goals ===
----
Instead of parenting your parent goal to one of the Start goals, it's possible to handle goal completion yourself, using a few different events:

The following events are recommended to use for completing your parent goals:
; [[Osiris/API/GameStarted|GameStarted]]
: Thrown when a level has been loaded and is ready at both the server and client side. This will ensure all the base game scripts have already initialized.
; [[Osiris/API/RegionStarted|RegionStarted]]
: Thrown when the level has been loaded and is ready at the server side, but not yet at the client side.
Both of these events can be used with specific level names, as a way to make your goal only complete once that level is loaded (as a way to create level-specific logic).
;[[Osiris/API/GameEventSet|GameEventSet("GAMEEVENT_GameStarted")]]
: The first story event that gets thrown after the game engine has been initialised when starting a new game. This particular event will only fire the first time a new game is started, so additional rules are needed for cases where your mod is added to an existing save.
;[[Osiris/API/Osiris/API/SavegameLoaded|Osiris/API/SavegameLoaded]]
: Fires when a save is being loaded on an existing save. This can be used to complete your goal on existing saves that just added your mod.

==== Example Goal Completion ====
----
The following is an example of handling initial goal completion yourself:

INIT:
<pre>
MyMod_Internal_CompleteIfStarted();
</pre>

KB:
<pre>
PROC
MyMod_Internal_Start()
THEN
DebugBreak("[MyMod] Parent goal complete.");
GoalCompleted;

IF
GameEventSet("GAMEEVENT_GameStarted")
THEN
MyMod_Internal_Start();

PROC
MyMod_Internal_CompleteIfStarted()
AND
DB_StoryStarted(_)
THEN
DebugBreak("[MyMod:CompleteIfStarted] Story was already started.");
MyMod_Internal_Start();

// For saves where this goal is active, but wasn't completed
IF
SavegameLoaded(_,_,_,_)
AND
DB_StoryStarted(_)
THEN
DebugBreak("[MyMod:SavegameLoaded] Mod added to an existing save.");
MyMod_Internal_Start();
</pre>

[[Category:Osiris]]

File:ContentBrowserButton.png

2020-08-27T00:50:09Z

LaughingLeader: Shows where the content browser button is in the DOS2 Definitive Edition engine.

Shows where the content browser button is in the DOS2 Definitive Edition engine.

Character and Item Script Triggers, Calls, and Queries

2019-10-17T21:13:01Z

LaughingLeader: Typo fix

This is a list of almost every character and item script event trigger, call, and query. An event is what triggers the script, and always begin with ''On''. Queries provide information and are always inside an ''IF'' or ''CHECK.'' Calls are actions that are always after THEN.

CharScript/ItemScript Functions

= Divinity: Original Sin 2 Classic=
== CALLS ==

'''Set(OUT OBJECT:variable, OBJECT:value)'''

Set the value of a variable

'''SetVar(CHARACTER|ITEM:object, FIXEDSTRING:variableName, OBJECT:value)'''

Set the value of a global variable

'''Cast(OUT OBJECT variable, OBJECT value)'''

Casts the value to the variable

'''Print(OUT STRING:output, STRING:text)'''

Prints the text to the output with possible parameters: [1], [2], ...

'''Add(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT|FLOAT3:value)'''

Adds both values and stores it in the first variable

'''Subtract(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT|FLOAT3:value)'''

Subtracts both values and stores it in the first variable

'''Multiply(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT:value)'''

Multiplies both values and stores it in the first variable

'''Divide(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT:value)'''

Divides both values and stores it in the first variable

'''Abs(INOUT INT|FLOAT:variable)'''

Takes the absolute value of a variable

'''Clamp(INOUT INT|FLOAT:variable, INT|FLOAT:min, INT|FLOAT:max)'''

Clamps a variable between min and max

'''GetRandom(OUT OBJECT:variable, OBJECT:value, OBJECT:value, OBJECT:value)'''

Fills in the variable with random one of the values.

'''GetWeightedRandom(OUT OBJECT:variable, OBJECT:value, INT|FLOAT:weight, ...)'''

Gets a weighted random of the given values!

'''GetRandomBetween(OUT INT|FLOAT:variable, INT|FLOAT:min, INT|FLOAT:max)'''

Gets a random value between min and max (both included)

'''GetRandomPositionInTrigger(OUT FLOAT3:variable, TRIGGER:areaTrigger)'''

Get a random position in a trigger area

'''GetElement(OUT OBJECT:variable, INT:index, OBJECT:value, OBJECT:value, OBJECT:value)'''

Fills in the variable with the index one of the values (starting from 0)

'''SetPriority(FIXEDSTRING:reactionName, INT:priority)'''

Changes the priority of a reaction. Priority 0 and below are not executed!

'''DelayReaction(FIXEDSTRING:reactionName, FLOAT:timeInSeconds)'''

The reaction will not be chosen for the specified time

'''SetScriptFrame(CHARACTER:character, FIXEDSTRING:frame)'''

Sets the scriptframe on the character.

'''ClearScriptFrame(CHARACTER:character)'''

Clears the scriptframe on the character.

'''Goto(FIXEDSTRING:labelName)'''

Jumps to the label. Two label names are built-in: "Start" for the first instruction of the reaction, and "End" for the last one.

'''GotoIfEqual(OBJECT:variable, OBJECT:value, FIXEDSTRING:labelName)'''

Jumps to the label if the 2 objects are equal

'''GotoRand(FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName)'''

Jumps to a random label in the list

'''CreatePuddleAt(GAMEOBJECT|FLOAT3:target, SURFACE:type, INT:cellAmountMin, INT:cellAmountMax, INT:growAmountMin, INT:growAmountMax, )'''

Spawn a puddle at the target's position for a certain lifetime (in turns)

'''CreateSurfaceAt(GAMEOBJECT|FLOAT3:target, SURFACE:type, FLOAT:radius, INT:lifeTime[, GAMEOBJECT:owner])'''

Spawn a surface at the target's position for a certain lifetime (in turns)

'''CreateSurfaceInPolygon(GAMEOBJECT:owner, SURFACE:type, FLOAT:duration, FLOAT:growTimer, INT:growStep, GAMEOBJECT|FLOAT3:point1, GAMEOBJECT|FLOAT3:point2, GAMEOBJECT|FLOAT3:point3, ...)'''

Spawn a polygon surface at the target's position. Grows <growStep> every <growTimer>.

'''CreateSurfaceInAreaTrigger(GAMEOBJECT:owner, SURFACE:type, FLOAT:duration, FLOAT:growTimer, INT:growStep, TRIGGER:areaTrigger)'''

Spawn a surface within <areaTrigger>. Grows <growStep> every <growTimer>.

'''CreateConeSurfaceAt(GAMEOBJECT|FLOAT3:start, GAMEOBJECT|FLOAT3:target, SURFACE:type, FLOAT:radius, FLOAT:angle, FLOAT:duration)'''

Spawn a Cone surface at the target's position

'''PlayEffectAt(GAMEOBJECT|FLOAT3:target, STRING:effectName)'''

Plays an effect at the target's position

'''PlayLoopEffectAt(OUT INT64:effectHandle, GAMEOBJECT|FLOAT3:target, STRING:effectName)'''

Plays an effect at the target's position

'''ExplodeAt(GAMEOBJECT|FLOAT3:target, SKILL:projectileSkill, [INT:casterLevel=-1, CHARACTER|ITEM:cause])'''

Trigger an explosion of a projectile skill at the target's position. The cause will trigger NPC behavior as if the cause casted the projectile

'''DisplayText(CHARACTER|ITEM:target, FIXEDSTRING:text, FLOAT:timeInSeconds)'''

Displays text above the character/item for a certain amount of time. It will replace the current text, including dialogtext

'''DisplayCombatInfoText(CHARACTER|ITEM:target, FIXEDSTRING:text, FLOAT:timeInSeconds)'''

Displays text above the character/item for a certain amount of time. It will replace the current text, including dialogtext

'''StatusText(CHARACTER|ITEM:target, FIXEDSTRING:text)'''

Adds statustext above the character/item for a short amount of time. Will not replace texts or dialogtexts

'''DebugText(CHARACTER|ITEM:target, STRING:text)'''

Adds debugtext above the character/item for a short amount of time.

'''CombatLogText(CHARACTER|ITEM:target, FIXEDSTRING:text, INT:filterID, INT:broadcastID)'''

Adds combatlog text inside the combat log window. Color-/SizeFormatting should already be applied, if not color and size of the string will be NORMAL. filterID determines what filter shows/hides the text. broadcastID determines who will be able to see the message (0 hearingrange. 1 party. 2 all)

'''Log(STRING:text, ...)'''

Log's the the scriptlog. (for debugging purposes)

'''Output(STRING:text, ...)'''

Pass text with optional parameters to the output panel (e.g. Output("An int [1]", INT:10))

'''Assert(STRING:text, ...)'''

Pass text with optional parameters to display as an assert message (e.g. Assert("This number is wrong: [1]", INT:666))

'''Label(FIXEDSTRING:name)'''

Marks this line as a label where Goto actions can jump to

'''StartTimer(FIXEDSTRING:timerName, FLOAT:timeInSeconds, INT:repeatCount)'''

Start a timer which will throw the timer event. Set repeatcount < 0 for a permanent timer.

'''StopTimer(FIXEDSTRING:timerName)'''

Stop a timer which will throw the timer event

'''DialogStart(OUT INT:instanceId, STRING:dialog, CHARACTER|ITEM:target, CHARACTER|ITEM:target, CHARACTER|ITEM:target, CHARACTER|ITEM:target)'''

Start a dialog between the targets. You can specify fewer targets than the maximum number.

{{warning|Starting a dialog from behaviour script will always start it as an [[Dialog_editor#Automated|Automated Dialog]]. Interactive dialogs can only be started from [[Osiris]].}}

'''DialogRequestStop(CHARACTER|ITEM:speaker, STRING:dialog)'''

Stops a certain dialog on a certain speaker

'''Check(-)'''

Reevaluate the conditions in the CHECK section of this reaction

'''Reset(-)'''

Resets the current reaction. It will start from the beginning again

'''Interrupt(FIXEDSTRING:reactionName)'''

Interrupt the reaction.

'''GlobalSetEvent(FIXEDSTRING:eventName)'''

Sets a global event. Scripts and Story can catch it.

'''GlobalClearEvent(FIXEDSTRING:eventName)'''

Clears a global event. Scripts and Story can catch it.

'''StopLoopEffect(INT64:fxHandle)'''

Stops a looping effect

'''IterateItems(FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item. If you pass a tag, it has to have that tag.

'''IterateItemsNear(GAMEOBJECT:source, FLOAT:radius, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item in range. If you pass a tag, it has to have that tag.

'''IterateItemsOnObject(CHARACTER|ITEM:source, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item standing on the source. If you pass a tag, it has to have that tag.

'''IterateParty(FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, CHARACTER:partyMember, FIXEDSTRING:tag])'''

Launch iterate event for each member of all parties. If you pass a party member only members of that party will be considered. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharacters(FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersNear(GAMEOBJECT:source, FLOAT:radius, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character in range. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersOnObject(CHARACTER|ITEM:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''
Launch iterate event for each character standing on the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersInCombat(CHARACTER|ITEM:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character in combat with the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateHostilesFor(CHARACTER:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character who is targetting the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''SpawnCharacter(OUT CHARACTER:result, CHARACTERTEMPLATE:rootTemplate, GAMEOBJECT|FLOAT3:position, INT:playSpawn, [INT:isSummon=0, CHARACTER:summonOwner=null, INT:overrideLevel=-1])'''

Spawns a character

'''SpawnItem(ITEMTEMPLATE:rootTemplate,GAMEOBJECT|FLOAT3:position, OUT ITEM:result)'''

Spawns an item

'''ShootLocalProjectile(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,FLOAT3:direction,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Spawns a projectile at the source (with offset, can be null) shooting at the target

'''ShootLocalProjectileAt(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,GAMEOBJECT|FLOAT3:target,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Spawns a projectile at the source (with offset, can be null) shooting at the target

'''ShootWorldProjectile(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,FLOAT3:direction,[INT:casterLevel])'''

Spawns a projectile at worldPos shooting at the target. Source can be null.

'''ShootWorldProjectileAt(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,GAMEOBJECT|FLOAT3:target,[INT:casterLevel])'''

Spawns a projectile at worldPos shooting at the target. Source can be null.

'''ShootLocalCone(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,FLOAT3:direction,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Shoots a cone from source (with offset, can be null) in a direction

'''ShootLocalConeAt(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,GAMEOBJECT|FLOAT3:target,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Shoots a cone from source (with offset, can be null) at the target

'''ShootWorldCone(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,FLOAT3:direction,[INT:casterLevel])'''

Shoots a cone from worldPos in a direction. Source can be null.

'''ShootWorldConeAt(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,GAMEOBJECT|FLOAT3:target,[INT:casterLevel])'''

Shoots a cone from worldPos at the target. Source can be null.

'''SetVisible(CHARACTER|ITEM:object, INT:visible)'''

Sets a character or item visible or not.

'''RotateY(INOUT FLOAT3:vector, FLOAT:degrees)'''

Rotate the vector around the Y-axis for a certain angle (in degrees)

'''SetHealth(CHARACTER|ITEM:target, FLOAT:percent)'''

Set a characters or items health on the given percentage. (percentage between 0 and 1)

'''PlaySound(CHARACTER|ITEM:target, STRING:soundEvent)'''

Plays a sound event at the target

'''PlayMusicForEveryone(STRING:musicEvent)'''

Plays a music event on all the clients

'''PlayMusicOnCharacter(CHARACTER:target, STRING:musicEvent)'''

Plays a music event on a character for all peers (3D)

'''PlayMusicForPeer(CHARACTER:target, STRING:musicEvent)'''

Plays a music event on the peer of the character

'''PlayMusicForPeerWithInstrument(CHARACTER:target, CHARACTER:charInstrument, STRING:musicEvent)'''

Plays a music event on the peer of the character concated with _INSTRUMENT

'''SetX(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the X component of the FLOAT3

'''SetY(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the Y component of the FLOAT3

'''SetZ(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the Z component of the FLOAT3

'''SetAtmosphere(FIXEDSTRING:atmosphereTriggerUUID, FIXEDSTRING:atmosphere)'''

Changes the atmosphere of the trigger

'''ResetAtmosphere(FIXEDSTRING:atmosphereTriggerUUID)'''

Resets the atmosphere of the trigger

'''AddStatusInfluence(CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1], [INT:force=1])'''

Adds the status influence strength on the object.

'''RemoveStatusInfluence(CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1])'''

Removes the status influence strength on the object.

'''AddTemporaryStatusInfluence(CHARACTER|ITEM:source, CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1])'''

Adds a temporary status influence strength on the object.. It will be gone in a few seconds if it's not set again

'''CallFunction(FIXEDSTRING:functionName)'''

Calls a function with the ID

'''SetMaterial(CHARACTER|ITEM:object, FIXEDSTRING:materialUUID, INT:duration, INT:applyOnBody, INT:applyOnArmor, INT:applyOnWings, INT:applyOnHorns, INT:applyOnOverhead, INT:applyOnWeapon[,INT:applyNormalMap, INT:overlay, INT:fading])'''

Changes the material of the object for a set time (in turns), -1 is infinite. applyNormalMap: Copy the original materials normal map

'''TeleportTo(CHARACTER|ITEM:object, GAMEOBJECT|FLOAT3:target, [INT:Force=0])'''

Teleport object to or near the target

'''Transform(CHARACTER|ITEM:object, CHARACTERTEMPLATE|ITEMTEMPLATE:root [, FIXEDSTRING:fx, INT:replaceScripts=1, OUT FLOAT:currentHP])'''

Transforms <object> using <root>, returns <currentHP>, plays <fx>.

'''SaveGame(FIXEDSTRING:saveGameName)'''

Save the savegame with name <saveGameName>

'''LoadGame(FIXEDSTRING:saveGameName)'''

Load the savegame with name <saveGameName>

'''LoadLevel(FIXEDSTRING:levelName)'''

Load the level with name <levelName>

'''KillCombat(CHARACTER:character)'''

Kill all the enemies in the combat which contains <character>

'''SetTag(CHARACTER|ITEM:object, FIXEDSTRING:tag)'''

Sets the Tag on the Object

'''ClearTag(CHARACTER|ITEM:object, FIXEDSTRING:tag)'''

Clears the Tag on the Object

'''SetGlobalFlag(FIXEDSTRING:flagname)'''

Sets the Global Flag

'''ClearGlobalFlag(FIXEDSTRING:flagname)'''

Clears the Global Flag

'''SetFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Sets the Flag on the Object

'''ClearFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the Object

'''SetUserFlag(CHARACTER:object, FIXEDSTRING:flagname)'''

Sets the Flag on the user's characters

'''ClearUserFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the user's characters

'''SetPartyFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Sets the Flag on the party's characters

'''ClearPartyFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the party's characters

'''StartVoiceBark(STRING:barkName, CHARACTER:character)'''

Start a voicebark on character

'''ConfrontationDone(INT: CrimeID, CHARACTER:lead, CHARACTER:criminal, ...)'''

Resolve the crime with id CrimeID for the specified criminals

'''CrimesceneInvestigationDone(CHARACTER:investigator)'''

Crimescene is considered investigated by this NPC, start looking for culprits

'''ListAdd(LIST<OBJECT>:list, OBJECT:entry)'''

Add <entry> at the back of <list>

'''ListRemove(LIST<OBJECT>:list, INT:index)'''

Remove the entry at <index> of <list>

'''ListSet(LIST<OBJECT>:list, INT:index, OBJECT:entry)'''

Set the entry at <index> of <list> to <entry>

'''ListClear(LIST<OBJECT>:list)'''

Remove all entries of <list>

'''EndTurn(CHARACTER|ITEM:Target)'''

Ends the object's current turn

'''SetCanFight(CHARACTER|ITEM:entity, INT:enabled[, INT:wholeGroup=0])'''

Enables/Disables the fact if the entity can fight. Optional for the whole group

'''SetCanJoinCombat(CHARACTER|ITEM:entity, INT:enabled[, INT:wholeGroup=0])'''

Enables/Disables the fact if the entity can join combats. Optional for the whole group

'''SetIsBoss(CHARACTER|ITEM:entity, INT:enabled)'''

Enables/Disables the fact if the entity is a boss.

'''GetAIHintTriggers(OUT LIST<TRIGGER>:triggers[, [LIST]FIXEDSTRING:tags, INT:needsAllTags = -1)'''

Returns all AIHintAreaTriggers in <triggers>. Uses contraints if set.

'''SetCombatTimeout(CHARACTER|ITEM:entity, FLOAT:timer)'''

Overwrites the entity's combat timeout check.

'''ResetCombatTimeout(CHARACTER|ITEM:entity)'''

Resets the entity's combat timeout check.

'''EnterCombat(CHARACTER|ITEM:source, CHARACTER|ITEM:target)'''

Enters combat with target

'''LeaveCombat(CHARACTER|ITEM:source)'''

Leaves the combat

'''SetFaction(CHARACTER|ITEM:target, FIXEDSTRING:faction)'''

Changes the faction of a character or item

'''SetInvulnerable(CHARACTER|ITEM:target, INT:bool)'''

Makes the character or item invulnerable or not. (Allow damage)

'''JumpToTurn(CHARACTER|ITEM:Target)'''

Jumps to targets turn (ends the current turn)

'''Sleep(FLOAT:timeInSeconds)'''

Sleeps for a certain amount of time

'''CharacterAttack(CHARACTER|ITEM|FLOAT3:target [,INT:alwaysHit])'''

Moves in weapon range and attacks the target

'''CharacterAttackWithoutMove(CHARACTER|ITEM|FLOAT3:target [,INT:alwaysHit])'''

Attacks the target without checking weaponranges and without moving

'''CharacterMoveTo(GAMEOBJECT|FLOAT3:target, [INT:running=0, INT:shouldArrive=0, INT:longPath=0, FLOAT:minDistance=1.5, FLOAT:maxDistance=minDistance+2.5])'''

Move to the target. Set shouldArrive to 1 if you want a guaranteed move. (teleports on fail)

'''CharacterAiMove(FLOAT3:target, CHARACTER:targetCharacter, ITEM:targetItem)'''

Moves to the target, calculated by the AI. Should only be used with results from the AI!

'''CharacterMoveInRange(GAMEOBJECT|FLOAT3:target, FLOAT:rangeMin, FLOAT:rangeMax, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within a certain range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveInWeaponRange(GAMEOBJECT|FLOAT3:target, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within weapon range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveInSkillRange(GAMEOBJECT|FLOAT3:target, SKILL:skill, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within skill range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveOutOfSight(FLOAT:angle)'''

Move out of screen

'''CharacterPlayAnimation(FIXEDSTRING:animation [, INT:exitOnFinish=1, INT:waitForCompletion=1], INT:noBlend=0])'''

Plays a certain animation.

ExitOnFinish means if the exit will kill itself after it was played (revert back to still).

WaitForCompletion means if the action will wait for the animation to be played at least once.

noBlend means no blending will be performed when doing this animation.

'''CharacterStopAnimation(-)'''

Stops all animations.

'''CharacterPickUpItem(ITEM:item)'''

Moves close enough to the item if necessary and picks it up

'''CharacterUseItem(ITEM:item [, INTEGER:LongPath])'''

Moves close enough to the item if necessary and uses it

'''CharacterMoveItem(ITEM:item, INTEGER:ignoreWeight, INTEGER:ignoreAPCost [, INTEGER:ignoreDangerousSurfaces=1, INT:amount=-1, GAMEOBJECT|FLOAT3:destination])'''

Moves close enough to the item if necessary and moves it to the destination. Will try to find a destination if not supplied.

'''CharacterAddSkill(CHARACTER:character, SKILL:skill[, INT:ShowNotification=0])'''

Adds <skill> to <character>

'''CharacterRemoveSkill(CHARACTER:character, SKILL:skill)'''

Removes <skill> from <character>

'''CharacterUseSkill(SKILL:skill, GAMEOBJECT|FLOAT3:target [, GAMEOBJECT|FLOAT3:target2, ITEM:skillItem, INT:ignoreHasSkill=0])'''

Cast a skill

'''CharacterAppearAt(GAMEOBJECT|FLOAT3:target, INT:playspawn)'''

Appear at the target

'''CharacterAppearOutOfSightTo(GAMEOBJECT:target, FLOAT:angle, INT:playspawn)'''

Appears out of sight to the players from a certain angle while being able to reach target

'''CharacterAppearOnTrailOutOfSightTo(CHARACTER:target, FLOAT:angle, INT:playspawn)'''

Appears out of sight to the players, on its previous locations, from a certain angle while being able to reach target

'''CharacterDisappear(FLOAT:angle[, INTEGER:isRunning=0])'''

Move out of screen and go of stage, will run if <isRunning> is not 0

'''CharacterSetOffStage(-)'''

Set Off Stage

'''CharacterSetOnStage(-)'''

Set On Stage

'''CharacterLookAt(GAMEOBJECT|FLOAT3|SPLINE:target[, INT:snapToTarget=0, INT:angleTolerance=0])'''

Rotates the character to look at the target (Closest spline point in case of a spline).

'''CharacterLookFrom(GAMEOBJECT|SPLINE:target[, INT:snapToTarget=0])'''

Rotates to the character so it has the same rotation as the target (Closest spline point in case of a spline).

'''CharacterFollow(CHARACTER:target, FLOAT:durationInSeconds, INT:run)'''

Follow the target for a certain time

'''CharacterFollowOwnerOrLeader(FLOAT:durationInSeconds, INT:run)'''

Follow the leader or owner for a certain time

'''CharacterWander(FLOAT|TRIGGER:range, FLOAT:durationInSeconds [, INT:run, GAMEOBJECT:anchor])'''

Wander around for a certain time

'''CharacterSwitchWeaponType(WEAPON:type)'''

If necessary switch to the new weapon type

'''CharacterFleeFrom(RELATION:relation, FLOAT:range)'''

Run away from certain characters if necessary
'''
CharacterFleeFromSurface(SURFACE:surface)'''

Run away from a certain surface if necessary

'''CharacterFleeFromDangerousSurface(-)'''

Run away from a dangerous surfaces if necessary

'''CharacterAddSourcePoints(CHARACTER:character, INT:amount)'''

Adds x source points (x can be negative to substract)

'''CharacterDie(CHARACTER:character[, DEATH:type=DoT])'''

Kills the character

'''CharacterHeal(CHARACTER:character, FLOAT:percentage)'''

Heals the character

'''CharacterConsume(CHARACTER:character, POTION:potion)'''

Makes the character consume a potion. Doesn't cost any AP and will just execute the result of the potion.

'''CharacterDisableAllCrimes(CHARACTER:target)'''

Disables all generic behaviours for <target>.

'''CharacterEnableAllCrimes(CHARACTER:target)'''

Enables all generic behaviours for <target>.
'''
CharacterEnableCrime(CHARACTER:target, STRING:crime, ...)'''

Enables the specified generic behaviours for <target>.

'''CharacterDisableCrime(CHARACTER:target, STRING:crime, ...)'''

Disables the specified generic behaviours for <target>.

'''CharacterSetLongInvestigationDuration(CHARACTER:target)'''

Doubles the time it takes for the investigation to time out. Use this when the character needs to move a long path before investigating.

'''CharacterAiCalculate(-)'''

Calculate the AI of the character

'''CharacterAiStopCalculate(-)'''

Stop the calculation of the AI of the character

'''CharacterAiFinishMoveSkill(-)'''

Finish the current MoveSkill.
'''
CharacterAiAddInterestingItem(CHARACTER:character, ITEM:item)'''

Make it interesting for the AI to destroy that Item

'''CharacterAiRemoveInterestingItem(CHARACTER:character, ITEM:item)'''

Make it no longer interesting for the AI to destroy that Item

'''CharacterSetArchetype(CHARACTER:character, ARCHETYPE:archetype)'''

Sets the archetype of the character, used in AI calculations

'''CharacterSetStoryNPC(CHARACTER:character, INT:bool)'''

Makes the character storyNPC or not.
'''
CharacterAddActionPoints(CHARACTER:character, INT:amount)'''

Give character some action points

'''CharacterSetImmortal(CHARACTER:character, INT:bool)'''

Makes the character immortal or not. (Allow dying)

'''CharacterPlayEffect(CHARACTER:character, STRING:effect [,FIXEDSTRING:boneName])'''

Plays an effect on the character and it follows the character

'''CharacterPlayLoopEffect(OUT INT64:effectHandle, CHARACTER:character, STRING:effect [,FIXEDSTRING:boneName])'''

Plays a looping effect on the character and it follows the character

'''CharacterEvent(CHARACTER:character, STRING:eventName)'''

Throw a character event which you can catch in scripts and story

'''CharacterItemEvent(CHARACTER:character, ITEM:item, STRING:eventName)'''

Throw a character/item event which you can catch in scripts and story

'''CharacterCharacterEvent(CHARACTER:character1, CHARACTER:character2, STRING:eventName)'''

Throw a character/character event which you can catch in scripts and story

'''CharacterSetRelationIndivToIndiv(CHARACTER:source, CHARACTER:target, INT:relation)'''

Changes the relationship between 2 characters.
'''
CharacterForceUpdate(INT:forceUpdate)'''

Makes sure the attached character is always being update or not.
'''
CharacterSetEnemy(CHARACTER:character, CHARACTER:enemy)'''

Sets the current enemy of character

'''CharacterApplyStatus(CHARACTER:character, STATUS:statusId [, INT:turns=null, INT:force=0])'''

Applies the status to the character When turns is -1 it's a permanent status When turns is -2 it's a keep alive status (which means it will die if it's not applied again within 1 second)

'''CharacterRemoveStatus(CHARACTER:character, STATUS:statusId [, STATUS:reasonStatusID=null, INT:notify=1])'''

Removes the status from the character

'''CharacterDestroy(CHARACTER:character)'''

Destroys the character

'''CharacterSetCanSpotSneakers(CHARACTER:character, INT:enabled)'''

Enables/Disables the fact if the character can spot sneaking characters.

'''CharacterSetAttackOfOpportunity(CHARACTER:character, INT:enabled)'''

Enables/Disables the fact if the character can do attack of opportunities.

'''CharacterResurrect(CHARACTER:character [, INT:Percentage = 100])'''

Resurrects the character at [2]% health.

'''CharacterAddToInventory(CHARACTER:character, FIXEDSTRING:itemStatsObject[, INT:amount, INT:showInTrade=1])'''

Add the item to the character

'''CharacterRemoveFromInventory(CHARACTER:character, FIXEDSTRING:itemStatsObject[, INT:amount])'''

Remove the item from the character. If Amount is -1, then all are removed

'''CharacterDrinkPotion(FIXEDSTRING:statID)'''

Makes the character drink a potion from the inventory.

'''CharacterSetAnimationOverride(CHARACTER:character, FIXEDSTRING:animation)'''

Sets an animation override, only walk/run/die animations can override it.

'''CharacterUseActionPoints(CHARACTER:character, INT:amount [, OUT INT:succeeded])'''

Uses x action points

'''CharacterAddTreasureTable(CHARACTER:character, FIXEDSTRING:treasureTable)'''

Adds <treasureTable> to the treasure list of <character>

'''CharacterRemoveTreasureTable(CHARACTER:character, FIXEDSTRING:treasureTable)'''

Removes <treasureTable> from the treasure list of <character>

'''CharacterClearTreasureTables(CHARACTER:character)'''

Removes all treasure tables from <character>

'''CharacterSetTemporaryHostileRelation(CHARACTER:character, CHARACTER:otherCharacter)'''

Creates a temporary hostile relation between the 2 characters!

'''CharacterSetFightMode(CHARACTER:character, INT:fight [, INT:force=0])'''

Set the character in sheath/unsheated mode.

'''CharacterSetStats(CHARACTER:character, FIXEDSTRING:statsEntry [, INT:keepVitality=0, INT:keepAP=0, INT:keepLevel=0, OUT FLOAT:currentHP])'''

Applies <statsEntry> from character.xlsm to <character>, returns <currentHP>.

'''CharacterSetWalkSpeedOverride(CHARACTER:character, INTEGER:override [, FLOAT:walkSpeed])'''

Sets walk speed override of <character>, removes it if <override> is 0

'''CharacterSetRunSpeedOverride(CHARACTER:character, INTEGER:override [, FLOAT:runSpeed])'''

Sets run speed override of <character>, removes it if <override> is 0

'''CharacterSetHasDialog(CHARACTER:character, INTEGER:bool)'''

Enables/Disables the dialog of the character

'''CharacterInitPatrol(SPLINE:spline, INT:splineIndex, INT:reversed, INT:running)'''

Start patroling from the given index along the given spline with the given character.

'''CharacterStartPatrol(SPLINE:spline, INT:splineIndex, INT:reversed, INT:running)'''

Start patroling from the given index along the given spline with the given character.

'''CharacterStopPatrol(-)'''

Let the character stop patrolling whatever spline he's on!

'''CharacterInterruptPatrol(-)'''

Call when the patrol should interrupt so the guard stops moving to the next spline. If this is called when the character is deactivated, a caret will take his place.

'''CharacterSetAnimationSetOverride(CHARACTER:source, FIXEDSTRING:override)'''

Sets an animation set override for a character. Empty fixedstring clears the override.

'''CharacterSetFloating(CHARACTER:target, INTEGER:isFloating)'''

Sets <target> floating if <isFloating> is not 0

'''CharacterResetCooldowns(CHARACTER:target)'''

Resets the skill cooldowns for <target>

'''ItemEvent(ITEM:item, STRING:eventName)'''

Throw an item event which you can catch in scripts and story

'''ItemPlayAnimation(FIXEDSTRING:animation)'''

Plays an animation on the item

'''ItemPlayAnimationTo(FIXEDSTRING:animation, FLOAT:targetPercentage, [FLOAT:speed])'''

Plays an animation on the item to the target time (percentage of the total duration)

'''ItemPlayEffect(ITEM:item, STRING:effect [,FIXEDSTRING:boneName])'''

Plays an effect on the item and it follows the item

'''ItemPlayLoopEffect(OUT INT:effectHandle, ITEM:item, STRING:effect [,FIXEDSTRING:boneName])'''

Plays a looping effect on the item and it follows the item

'''ItemSetOnStage(ITEM:item, INTEGER:bool)'''

Sets an item on or offstage

'''ItemSetCanInteract(ITEM:item, INTEGER:bool)'''

Sets an item (not) interactible

'''ItemClose(ITEM:item)'''

Close an item

'''ItemOpen(ITEM:item)'''

Open an item

'''ItemDrop(ITEM:item)'''

Drop an item

'''ItemLock(ITEM:item, FIXEDSTRING:key)'''

Lock an item

'''ItemUnlock(ITEM:item)'''

Unlock an item

'''ItemApplyStatus(ITEM:item, STATUS:statusId [, INT:turns=null, INT:force=0])'''

Applies the status to the item When turns is -1 it's a permanent status When turns is -2 it's a keep alive status (which means it will die if it's not applied again within 1 second)

'''ItemRemoveStatus(ITEM:item, STATUS:statusId)'''

Removes the status from the item

'''ItemDie(ITEM:item)'''

Kills the item

'''ItemMoveTo(GAMEOBJECT|FLOAT3:target, FLOAT:velocity, FLOAT:acceleration, INTEGER:matchTargetRotation)'''

Moves the item to the target

'''ItemToInventory(ITEM:item, CHARACTER|ITEM:target [,INT:amount=-1])'''

Moves the item to the target's inventory

'''ItemLookAt(GAMEOBJECT:target, FLOAT:degreesPerSecond)'''

Rotates the item to look at the target

'''ItemDestroy(ITEM:item)'''

Destroys the item

'''ItemSetAmount(ITEM:item, INT:amount)'''

Change the amount of the item

'''IterateItemsInInventory(CHARACTER|ITEM:source, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each iten in source's inventory. If you pass a tag, it has to have that tag.

'''ItemAddCharges(ITEM:TargetItem, INT:charges)'''

Add/subtract charges from an item

'''ItemResetChargesToInitial(ITEM:TargetItem)'''

Resets charges from item to initial state

'''MakePeace(CHARACTER:Source, CHARACTER:Target[, INT:IgnoreVote = 1])'''

Make peace between users of the characters

'''MakeWar(CHARACTER:Source, CHARACTER:Target[, INT:IgnoreVote = 1])'''

Make war between users of the characters

'''FindSurface(OUT FLOAT3:result, GAMEOBJECT|FLOAT3:source, FLOAT:minRange, FLOAT:maxRange, SURFACE:type [,CHARACTER:alignSource, INT:minEnemiesInSurface, INT:maxAlliesInSurface, INT:minimumCellCount])'''

Finds the closest surface of a specific type.

'''FindValidPosition(INOUT FLOAT3:position, FLOAT:radius[, CHARACTER|ITEM:object=null])'''

Finds the closest valid position (where the object can stand.)

'''FindPosition(INOUT FLOAT3:position, CHARACTER:source, INT:canStand, INT:checkSight, FLOAT:minRadius, FLOAT:maxRadius, FLOAT:rangeCheck, CHARACTER:alignSource, INT:minAllies, INT:maxAllies, INT:minEnemies, INT:maxEnemies [,FIXEDSTRING:AiHintTag=null, INT:forceHint=0, FLOAT3:SourcePosition])'''

Finds the closest position from the source (within radius) where the conditions are matched.

'''Cast(OUT OBJECT variable, OBJECT value)'''

Casts the value to the variable.

'''StringConcatenate(STRING:stringA, STRING:stringB, OUT STRING:resultingString)'''

Appends stringB to stringA. Resulting string is stored in the third parameter.

== QUERIES ==

'''GetPosition(GAMEOBJECT:object,OUT FLOAT3:src)''' 

Get the current position of an object

'''GetForwardDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current forward direction of an object

'''GetRightDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current right direction of an object

'''GetUpDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current up direction of an object

'''GetDirection(GAMEOBJECT|FLOAT3:src,GAMEOBJECT|FLOAT3:target,OUT FLOAT3:direction[, OUT FLOAT:distance])''' 

Get the direction from src to target (optional: returns the distance between the objects as well)

'''GetRotation(GAMEOBJECT:object, OUT FLOAT3:vector)''' 

Get the rotation of an object

'''CharacterGetTargetSpline(INT: SplineIndex)''' 

Returns the spline index the character is currently walking towards, or -1 if he is not active on a spline.

'''IsEqual(OBJECT:variable, OBJECT:variable)''' 

Compares both objects and see if they are equal.

'''IsLessThen(INT|FLOAT:variable, INT|FLOAT:variable)''' 

Compares both objects and see if the first one is smaller.

'''IsGreaterThen(INT|FLOAT:variable, INT|FLOAT:variable)''' 

Compares both objects and see if the first one is bigger.

'''IsRandom(FLOAT:percentage)''' 

Each time this condition is checked, it will succeed with a chance of the percentage (between 0 and 1)

'''IsRound(INT:roundNumber)''' 

Checks if we are currently in combat in round x

'''IsInSurface(OBJECT|FLOAT3:target, SURFACE:type[, FLOAT:radius])''' 

Check if the character, item, trigger or position is currently within the specific surface.

'''IsInDangerousSurface(OBJECT|FLOAT3:target[, CHARACTER:character, FLOAT:radius])''' 

Check if <target> is currently in on a dangerous surface. Uses <character> for path influences if provided (is necessary with non-character targets)

'''IsInDialog(CHARACTER|ITEM:target[, INT:ignoreAutomatedDialogs=0])''' 

Check if the character or item is currently in a dialog, optionally ignoring automated dialogs

'''IsInAutomatedDialog(CHARACTER|ITEM:target)''' 

Check if the character or item is currently in an automated dialog

'''GetDistance(OUT FLOAT:distance, GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 

Returns the distance between 2 positions

'''GetDistance2D(OUT FLOAT:distance, GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 

Returns the 2D distance between 2 positions (ignores height)

'''GetInnerDistance(OUT FLOAT:distance, GAMEOBJECT:source, GAMEOBJECT:target)''' 

Returns the distance between 2 gameobjects (character, item, trigger, ...) Their bounds are already subtracted.

'''GetPosition(GAMEOBJECT:object, OUT FLOAT3:position)''' 

Returns the position of a gameobject (character, item, trigger, ...)

'''GetVar(OUT OBJECT:returnValue, CHARACTER|ITEM:target, FIXEDSTRING:varName)''' 

Gets a global variable from the target

'''GetClosestPlayer(OUT CHARACTER:player, GAMEOBJECT|FLOAT3:source)''' 

Gets the closest player near the source, default being being the object itself

'''GetPlayerCount(OUT INT:playerCount)''' 

Gets the number of players in the party

'''GetPlayerByIndex(OUT CHARACTER:returnCharacter, INT:playerIndex)''' 

Gets a player from the party by index

'''GetRandomCharacter(OUT CHARACTER:returnCharacter, [INT:canBeSelf=0, INT:canBePlayer=0])''' 

Gets a random character in the current level

'''ContainsSurface(GAMEOBJECT|FLOAT3:source, FLOAT:radius, SURFACE:type,)''' 

Checks if there is any surface of the type within a radius of the source

'''IsSurface(GAMEOBJECT|FLOAT3:source, FLOAT:radius, SURFACE:type)''' 

Checks if the whole radius around the source is the specified surface type

'''IsObjectOnObject(CHARACTER|ITEM:source,CHARACTER|ITEM:target)''' 

Checks if the source is standing on the target

'''GetX(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the X component of the vector

'''GetY(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the Y component of the vector

'''GetZ(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the Z component of the vector

'''CanSee(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target[, INT:addProjectileTargetGroundOffset=0])''' 

Check if the sight is blocked between 2 points.

'''IsVisible(CHARACTER|ITEM:object)''' 

Check if the object is set invisible or not with SetVisible.

'''GetTextDuration(CHARACTER|ITEM:object, FIXEDSRTING:key, OUT FLOAT:duration)''' 

Gets how long a text needs to be displayed

'''IsCasual(-)''' 

Returns if the current game mode is Casual

'''IsHardcore(-)''' 

Returns if the current game mode is Hardcore

'''IsTagged(GAMEOBJECT:object, FIXEDSTRING:tag)''' 

Check if the object is tagged.

'''TranslatedStringKeyExists(FIXEDSTRING:key)''' 

Check if the TranslatedString key exists.

'''IsInCombat(CHARACTER|ITEM:object)''' 

Returns true if the object is in combat.

'''IsInCombatWith(CHARACTER|ITEM:object, CHARACTER|ITEM:object)''' 

Returns true if the objects are in combat with each other.

'''IsFacing(GAMEOBJECT:source, GAMEOBJECT|FLOAT3:target, [INT:angle=90])''' 

Returns true if the object is facing the position within the given angle.

'''GameIsSaving(-)''' 

Returns true if the game is saving.

'''GameIsLoading(-)''' 

Returns true if the game is loading.

'''GetUserCount(OUT INT:userCount)''' 

Returns the user count.

'''GetCurrentCharacter(OUT CHARACTER:character, INT:user)''' 

Returns the character currently being controlled by the specified user.

'''GetCurrentLevel(OUT FIXEDSTRING:currentLevel)''' 

Returns the current levelname

'''GetAIBounds(CHARACTER|ITEM:source, OUT FLOAT:bounds)''' 

Returns AI bounds of <source> in <bounds>

'''HasGlobalFlag(FIXEDSTRING:flagName)''' 

Returns if the Global Flag is set

'''HasFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the Object

'''HasUserFlag(CHARACTER:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the user's characters

'''HasPartyFlag(CHARACTER:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the party's characters

'''DialogExists(STRING:dialogue)''' 

Returns true if the dialogue exists.

'''IsActive(CHARACTER|ITEM:Object)''' 

Returns if the character or item is currently active.

'''ListGetSize(LIST<OBJECT>:list, out INT:size)''' 

Returns the number of elements in <list>

'''ListGet(LIST<OBJECT>:list, INT:index, out OBJECT:entry)''' 

Returns <entry> at <index> of <list>

'''ListGetRandom(LIST<OBJECT>:list, out OBJECT:entry)''' 

Returns a random <entry> of <list>

'''IsBoss(CHARACTER|ITEM:Object)''' 

Returns true if the entity is tagged as a boss

'''IsProjectileSkill(SKILL:skill)''' 

Returns true if the skill is a ranged skill (uses a projectile)

'''IsValidSkillTarget(CHARACTER:source, OBJECT|FLOAT3:target, SKILLID:skill[, INTEGER:ignoreRangeCheck=0])''' 

Checks whether <target> is a valid target for <skill> at <source>

'''GetFaction(OUT FIXEDSTRING:faction, CHARACTER|ITEM:character)''' 

Returns the faction of the provided character or item

'''IsInActiveTurn(CHARACTER|ITEM:target)''' 

Returns true if it's the character's or item's turn in combat.

'''IsSkillActive(CHARACTER:character, SKILL:skillId)''' 

Returns true if <character> has <skillId> active (in memory).

'''HasSkillAi(SKILLID:skillId)''' 

Returns true if the skill is using the new Ai system

'''IsInArena(CHARACTER::character)''' 

Returns true if the character is in an arena fight

'''CrimeGetType(INTEGER:crimeId, OUT STRING:crimeType)''' 

Returns the type of the crime with this id.

'''CrimeGetCriminals(INTEGER:crimeId, OUT CHARACTER:criminal1, OUT CHARACTER:criminal2, OUT CHARACTER:criminal3, OUT CHARACTER:criminal4)''' 

Returns the criminals of that crime. They might all be null.

'''IsSourceSkill(SKILL:skill)''' 

Returns true if the skill is a source skill.

'''IsInGameMasterMode(-)''' 

Returns true if the game in game master mode.

'''CharacterGet(OUT CHARACTER:character, GAMEOBJECT|FLOAT3:src, FLOAT:range, COMPARE:howTo, COMPAREFUNC:compareFunc[, RELATION: relation, SURFACE:surface, STATUS:status, TALENT:talent, CHARACTER:inSightOf, FIXEDSTRING:tag])''' 

Get a character within a certain range conforming to the filled in restraints.

'''CharacterCount(OUT INT:count, GAMEOBJECT|FLOAT3:src, FLOAT:range, [RELATION: relation, SURFACE:surface, STATUS:status, TALENT:talent, CHARACTER:inSightOf])''' 

Counts the characters within a certain range conforming to the filled in restraints.

'''CharacterGetOwner(OUT CHARACTER:owner, CHARACTER:source)''' 

Get the character's owner

'''CharacterGetFollow(OUT CHARACTER:to follow, CHARACTER:source)''' 

Get the character to follow

'''CharacterGetEnemy(OUT CHARACTER:current enemy, CHARACTER:source)''' 

Get current enemy of character

'''CharacterCanCast(CHARACTER:source, SKILL:skillId, [ITEM:skillItem=null, INT:ignoreActionPoints=0])''' 

Check if the character source can cast the skill: will check cooldown, actionpoints

'''CharacterCanSitOnItem(CHARACTER:source, ITEM:item)''' 

Check if the character source can sit or lie on an item.

'''CharacterCanDrinkPotion(CHARACTER:source, FIXEDSTRING:potionID[, INT:ignoreActionPoints=0])''' 

Check if the character source can drink the potion: will check inv and actionpoints

'''CharacterCanUseItem(CHARACTER:source, ITEM:item[, INT:ignoreActionPoints=0])''' 

Check if the character source can use the item in the world

'''CharacterCanUseItemInInventory(CHARACTER:source, ITEM:item[, INT:ignoreActionPoints=0])''' 

Check if the character source can use the item in his inventory

'''CharacterCanSee(CHARACTER:watchingChar, CHARACTER|ITEM:target [, INT:forceUpdate=0])''' 

Check if character has target in his line of sight.

'''CharacterCanShoot(CHARACTER:source, GAMEOBJECT|FLOAT3:target)''' 

Check if the character can shoot the target.

'''CharacterIsPlayer(CHARACTER:character)''' 

Check if the character is a player

'''CharacterIsInParty(CHARACTER:character)''' 

Check if the character is in the party

'''CharacterIsEnemy(CHARACTER:source, CHARACTER:target)''' 

Check if target is enemy of source

'''CharacterIsAlly(CHARACTER:source, CHARACTER:target)''' 

Check if target is ally of source

'''CharacterIsNeutral(CHARACTER:source, CHARACTER:target)''' 

Check if target is neutral of source

'''CharacterIsDead(CHARACTER:character)''' 

Check if character is dead

'''CharacterIsMoving(CHARACTER:character)''' 

Check if character is moving (speed > 0)

'''CharacterIsSummon(CHARACTER:character)''' 

Check if character is a summon

'''CharacterIsPartyFollower(CHARACTER:character)''' 

Check if character is a party follower

'''CharacterIsStoryNPC(CHARACTER:character)''' 

Check if character is a story NPC

'''CharacterInWeaponRange(CHARACTER:character, CHARACTER:target)''' 

Check if target is in the current's weapon range

'''CharacterInTouchRange(CHARACTER:character, CHARACTER:targetChar)''' 

Check if target is in the character's touch range

'''CharacterHasStatus(CHARACTER:character, STATUS:statusId[, FIXEDSTRING:extraData])''' 

Check if character currently has the status. ExtraData can be filled in for some statuses: - Consume: statsid of the item - Shield: skillid of the shield

'''CharacterGetStatusSourceCharacter(CHARACTER:character, STATUS:statusId, OUT CHARACTER:source[, FIXEDSTRING:extraData])''' 

Get the source character of a status

'''CharacterGetStatusSourceItem(CHARACTER:character, STATUS:statusId, OUT ITEM:source[, FIXEDSTRING:extraData])''' 

Get the source item of a status

'''CharacterHasTalent(CHARACTER:character, TALENT:talent)''' 

Check if character currently has the talent

'''CharacterHasSkill(CHARACTER:character, SKILL:skillId)''' 

Check if character currently has the skill

'''CharacterHasWeaponType(CHARACTER:character, WEAPON:weaponTYPE [, INT:equipped])''' 

Check if character currently has a weapon of this type in his inventory or equipped

'''CharacterGetStat(OUT FLOAT:statValue, CHARACTER:character, CHARACTERSTAT:statType)''' 

Returns the current value of the stat (Vitality, ...)

'''CharacterGetSightRange(OUT FLOAT:range, CHARACTER:character)''' 

Returns the character's sight range

'''CharacterGetWeaponRange(OUT FLOAT:minRange, OUT FLOAT:maxRange, CHARACTER:character)''' 

Returns the character's current weapon range

'''CharacterGetTouchRange(OUT FLOAT:touchRange, CHARACTER:character)''' 

Returns the character's current touch range

'''CharacterGetSkillRange(OUT FLOAT:minRange, OUT FLOAT:maxRange,CHARACTER:character, SKILL:skillId)''' 

Returns the character's skill range

'''CharacterGetSkillImpactRange(OUT FLOAT:areaRange, CHARACTER:character, SKILL:skillId)''' 

Returns the character's skill range

'''CharacterIsInTrigger(CHARACTER:character, TRIGGER:trigger)''' 

Check if character is in given trigger

'''CharacterGetAbility(OUT INT:value, CHARACTER:character, ABILITY:ability)''' 

Returns the character's value of the specified ability

'''CharacterGetHostileCount(OUT INT:value, CHARACTER:character)''' 

Returns how many characters are targeting this character right now... You can iterate over them with IterateEnemiesOf.

'''CharacterCanFight(CHARACTER:character)''' 

Returns true if the character can fight.

'''CharacterGetTemplate(CHARACTER:character, OUT CHARACTERTEMPLATE:root)''' 

Returns the roottemplate of the character.

'''CharacterCanSpotSneakers(CHARACTER:character)''' 

Returns true if the character can spot sneaking characters

'''CharacterIsFloating(CHARACTER:character)''' 

Check if character is a floating character

'''CharacterInCreation(CHARACTER:character)''' 

Returns true if the character is in character creation

'''CharacterAvoidsTraps(CHARACTER:character)''' 

Returns true if the character avoids traps

'''CharacterCheckRelation(CHARACTER:character, RELATION:relation)''' 

Returns true if relation check succeeds

'''CharacterIsBetterOrEqualClass(CHARACTER:character, INT:currentScore, OUT INT:newScore, INT warriorScore, INT rogueScore, INT mageScore, INT clericScore, INT rangerScore)''' 

Returns true if score is higher or equal than the current score

'''CharacterHasBeenHitBy(CHARACTER:character, DAMAGE_TYPE:damageType)''' 

Returns true if the character was hit by this type.

'''CharacterHasCastedSpellLastTurn(CHARACTER:character)''' 

Returns true if the character has casted a spell in his last turn.

'''CharacterHasHadStatus(CHARACTER:character, STATUS:status)''' 

Returns true if the character has had a specific status this combat.

'''CharacterHasAnimationOverride(CHARACTER:character)''' 

Returns true if the character has an animation override.

'''CharacterCanUnlock(CHARACTER:character, ITEM:item)''' 

Returns true if the character can unlock the item (if the item is already unlocked it returns true!)

'''CharacterGetReservedUserID(OUT INT:user, CHARACTER:character)''' 

Returns the character's reserved User id.

'''CharacterGetRace(CHARACTER:character, OUT FIXEDSTRING:race)''' 

Returns the <character>'s race in <race>.

'''CharacterIsRace(CHARACTER:character, FIXEDSTRING:race)''' 

Returns true if <character>'s race is <race>.

'''CharacterCanMoveItem(CHARACTER:character, ITEM:item, FLOAT:minRadius, FLOAT:maxRadius [, OUT FLOAT3:destination])''' 

Returns true + <destination> if <character> can move <item> somewhere between <minRadius> and <maxRadius>.

'''CharacterGetDeathType(CHARACTER:character, OUT FIXEDSTRING:deathType)''' 

Returns death type of <character> in <deathType>.

'''CharacterGetStillAnimation(CHARACTER:object, OUT FIXEDSTRING:stillAnimation)''' 

Returns the still animation to play

'''CrimeTransferLeadership(INT: CrimeID[, FIXEDSTRING:Tag1,...])''' 

Try and transfer the leadership of this crime to someone else.

'''CrimeGetLeadInvestigator(OUT CHARACTER:lead, INT: CrimeID)''' 

Returns the lead investigator for the crime.

'''CharacterCanHitTargetWithRangedWeapon(CHARACTER:source, OBJECT|FLOAT3:target[, SKILL:skill = null])''' 

Returns true if <source> can hit <target> with currently equipped ranged weapon. Will use <skill> instead of equipped weapon if provided.

'''CharacterHasRangedWeapon(CHARACTER:character[, INT:checkInventory = 0])''' 

Returns true if <character> has has ranged weapon. Checks for non-wielded weapons if <checkInventory> is 1

'''CheckInteractionReach(CHARACTER:character, CHARACTER|ITEM: target)''' 

Returns true if <character> could interact with <target>. This is not checking ranges, but checking if there's too much of a height difference or too many obstacles in between.

'''CharacterGetSourcePoints(CHARACTER:character, OUT INT: amount)''' 

Returns the amount of sourcepoints of <character>.

'''CharacterAiIsCalculating(-)''' 

Returns if the character is still calculating the AI.

'''CharacterAiFetchMoveSkillCommand(OUT SKILL:skill, OUT ITEM:skillItem, OUT FLOAT3:target)''' 

Returns if the character has a Move Skill command to execute according to the AI.

'''CharacterAiFetchSkillCommand(OUT SKILL:skill, OUT ITEM:skillItem, OUT FLOAT3 endPosition, OUT FLOAT3:target, OUT CHARACTER:target, OUT ITEM:target, OUT FLOAT3:target2, OUT CHARACTER:target2, OUT ITEM:target)''' 

Returns if the character has a Skill command to execute according to the AI.

'''CharacterAiFetchConsumeCommand(OUT ITEM:item)''' 

Returns if the character has a Consume command to execute according to the AI.

'''CharacterAiFetchAttackCommand(OUT FLOAT3:endPosition, OUT FLOAT3:target, OUT CHARACTER:target, OUT ITEM:target)''' 

Returns if the character has a Attack command to execute according to the AI.

'''CharacterAiFetchFallbackCommand(OUT FLOAT3:targetPosition, OUT FLOAT3:lookAtPosition)''' 

Returns if the character has a Fallback command to execute according to the AI.

'''CharacterGetArchetype(CHARACTER:character, OUT ARCHETYPE:archetype)''' 

Returns the archetype of the character.

'''CharacterIsPolymorphedInto(CHARACTER:character, FIXEDSTRING:race)''' 

Returns true if <character> is polymorphed into <race>. Race can be a race (like HUMAN), but also a template (in case of a polymorph skill like Chicken Touch).

'''CharacterIsPolymorphInteractionDisabled(CHARACTER:character)''' 

Returns true if <character> has his interaction disabled because of a polymorph.

'''ItemGet(OUT ITEM:item, GAMEOBJECT|FLOAT3:src, FLOAT:range, COMPARE:howTo [, COMPAREFUNC:compareFunc, FIXEDSTRING:rootTemplate, FIXEDSTRING:tag])''' 

Get an item within a certain range conforming to the filled in restraints.

'''ItemGetFromInventory(OUT ITEM:item, CHARACTER|ITEM:object [, FIXEDSTRING:statsId, FIXEDSTRING:tag, INT:isEquiped])''' 

Returns the first item in the inventory conforming to the filled in restraints.

'''ItemIsInCharacterInventory(ITEM:item, CHARACTER:object)''' 

Returns if the item is in the inventory of the character

'''ItemIsInTrigger(ITEM:item, TRIGGER:trigger)''' 

Check if item is in given trigger

'''ItemGetStat(OUT FLOAT:statValue, ITEM:item, ITEMSTAT:statType)''' 

Returns the current value of the stat (Weight, ...)

'''ItemIsMoving(ITEM:item)''' 

Returns if the item is moving or not.

'''ItemIsFalling(ITEM:item)''' 

Returns if the item is falling or not. (after teleport)

'''ItemIsOpening(ITEM:item)''' 

Returns if the item is opening or not.

'''ItemIsClosing(ITEM:item)''' 

Returns if the item is closing or not.

'''ItemIsLocked(ITEM:item)''' 

Returns if the item is locked or not.

'''ItemIsMovable(ITEM:item)''' 

Returns if the item is movable or not.

'''ItemCanBeLockPicked(ITEM:item)''' 

Returns if the item is can be opened by lockpicking.

'''ItemIsOpen(ITEM:item)''' 

Returns if the item is open or not.

'''IsStoryItem(ITEM:item)''' 

Returns if the item is a story item.

'''ItemHasStatus(ITEM:item, STATUS:statusId)''' 

Returns if the item has the status.

'''ItemIsDestroyed(ITEM:item)''' 

Returns if the item is destroyed.

'''ItemGetTemplate(ITEM:item, OUT ITEMTEMPLATE:root)''' 

Returns the roottemplate of the item.

'''ItemGetSkillId(ITEM:item, OUT SKILL:root)''' 

Returns the skillid of the item if it has one.

'''ItemGetItemType(ITEM:item, OUT FIXEDSTRING:itemType)''' 

Returns the itemtype of the item: common, unique, rare, ...

'''ItemGetStatusSourceCharacter(ITEM:item, STATUS:statusId, OUT CHARACTER:source)''' 

Get the source character of a status

'''ItemGetStatusSourceItem(ITEM:item, STATUS:statusId, OUT ITEM:source)''' 

Get the source item of a status

'''ItemCanBeMoved(ITEM:item)''' 

Returns if the item can be moved.

'''GetStatusTurns(CHARACTER|ITEM:object, STATUS:statusId, OUT INT:turnsLeft)''' 

Returns true if the object has the given status, and returns the amount of turns still left

== EVENTS ==

'''OnCharacterEvent(CHARACTER:character, STRING:eventName)''' 
Thrown from scripts or story

'''OnCharacterItemEvent(CHARACTER:character, ITEM:item, STRING:eventName)''' 
Thrown from scripts or story

'''OnCharacterCharacterEvent(CHARACTER:character, CHARACTER:character, STRING:eventName)''' 
Thrown from scripts or story

'''OnItemEvent(ITEM:item, STRING:eventName)''' 
Thrown from scripts or story

'''OnItemDestroyed(ITEM:item)''' 
Thrown when an item is destroyed

'''OnItemDestroying(ITEM:item)''' 
Thrown when an item is being destroyed

'''OnItemOpened(ITEM:item)''' 
Thrown when an item is opened

'''OnItemClosed(ITEM:item)''' 
Thrown when an item is closed

'''OnItemDropped(ITEM:item, STRING:itemTemplate)''' 
Thrown when an item is dropped

'''OnGlobalFlagSet(FIXEDSTRING:eventName)''' 
Thrown when a global event is set

'''OnGlobalFlagCleared(FIXEDSTRING:eventName)''' 
Thrown when a global event is cleared

'''OnCharacterFlagSet(FIXEDSTRING:eventName, CHARACTER:character)''' 
Thrown when a dialog event is set on a character

'''OnCharacterFlagCleared(FIXEDSTRING:eventName, CHARACTER:character)''' 
Thrown when a dialog event is cleared on a character

'''OnItemFlagSet(FIXEDSTRING:eventName, ITEM:item)''' 
Thrown when a dialog event is set on an item

'''OItemFlagCleared(FIXEDSTRING:eventName, ITEM:item)''' 
Thrown when a dialog event is cleared on an item

'''OnTimer(FIXEDSTRING:timerName)''' 
Thrown when a timer has ended

'''OnInit(-)''' 
Thrown when the script is set

'''OnLoaded(INT:major, INT:minor, INT:revision, INT:build)''' 
Thrown when the script is loaded from the savegame

'''OnShutdown(-)''' 
Thrown when the character's script is removed

'''OnVariableCleared(FIXEDSTRING:varName)''' 
Thrown when this object's script variable is cleared from Osiris with ClearVarObject

'''OnCombatStarted(INT:combatID)''' 
Thrown when combat starts

'''OnCombatSwitched(CHARACTER:source, ITEM:source)''' 
Thrown when the character switch from one combat to another

'''OnLeftCombat(CHARACTER:source, ITEM:source)''' 
Thrown when the character or item left the combat

'''OnTurn(CHARACTER:source, ITEM:source)''' 
Thrown when the character's turn starts

'''OnTurnEnded(CHARACTER:source, ITEM:source)''' 
Thrown when the character's turn ended

'''OnCharacterVitalityChanged(CHARACTER:character, FLOAT:percentage)''' 
Thrown when the characters's vitality changed

'''OnItemVitalityChanged(ITEM:item, FLOAT:percentage)''' 
Thrown when the item's vitality changed

'''OnAttackOfOpportunity(CHARACTER:target)''' 
Thrown when the characters gets an attack of opportunity on an enemy

'''OnClearAttackOfOpportunity(-)''' 
Thrown when the characters attack of opportunity is cleared

'''OnDamage(DAMAGE:type, FLOAT:percentage, CHARACTER:source, ITEM:source)''' 
Thrown when the object receives damage

'''OnMiss(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character dodges something

'''OnCriticalHit(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character is critical hit

'''OnPreBlock(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown before the character blocks something (at the start of the attack animation)

'''OnBlock(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character blocks something

'''OnDie(CHARACTER:character, DAMAGE:type, CHARACTER:source, ITEM:source)''' 
Thrown when the character dies

'''OnCharacterStatusAttempt(CHARACTER:character, STATUS:status)''' 
Thrown when the character attempts to gain a status

'''OnCharacterStatusApplied(CHARACTER:character, STATUS:status)''' 
Thrown when the character gains a status

'''OnCharacterStatusRemoved(CHARACTER:character, STATUS:status)''' 
Thrown when the character loses a status

'''OnItemStatusAttempt(ITEM:item, STATUS:status)''' 
Thrown when the item attempts to gain a status

'''OnItemStatus(ITEM:item, STATUS:status)''' 
Thrown when the item gains a status

'''OnItemStatusRemoved(ITEM:item, STATUS:status)''' 
Thrown when the item loses a status

'''OnStatusCreateVisuals(STATUS:status)''' 
Thrown when the item should create the visuals for this status

'''OnStatusDestroyVisuals(STATUS:status)''' 
Thrown when the item should destroy the visuals for this status

'''OnSight(CHARACTER:character)''' 
Thrown when the character sees another character

'''OnLostSight(CHARACTER:character)''' 
Thrown when the character doesn't see another character anymore

'''OnUseItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character uses an item

'''OnPickupItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character picks up an item

'''OnCharacterPreMovedItem(CHARACTER:source, ITEM:item)''' 
Event thrown just before a character moves an item. No difference whether it is in the world or in their inventory

'''OnCharacterMovedItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character moved an item

'''OnItemEquipped(CHARACTER:source, ITEM:item)''' 
Thrown when a character equips an item

'''OnItemUnequipped(CHARACTER:source, ITEM:item)''' 
Thrown when a character unequips an item

'''OnIterateCharacter(CHARACTER:character, FIXEDSTRING:eventId)''' 
Thrown by iterators

'''OnIterateItem(ITEM:source, FIXEDSTRING:eventId)''' 
Thrown by iterators

'''OnIterateCount(FIXEDSTRING:eventId, INTEGER:Count)''' 
Thrown by iterators after all iterations to inform you of the count.

'''OnStoryOverride(-)''' 
Throw when story overrides what the character was doing: teleport, movement, on/offstage

'''OnTriggerEnter(CHARACTER:character, ITEM:item, FIXEDSTRING:eventId)''' 
Thrown by a character or item entering an EventTrigger

'''OnTriggerLeave(CHARACTER:character, ITEM:item, FIXEDSTRING:eventId)''' 
Thrown by a character or item leaving an EventTrigger

'''OnEnemyChanged(CHARACTER:character, CHARACTER:newEnemy)''' 
Thrown when the character's currentenemy changes

'''OnTalentUnlocked(CHARACTER:character, TALENT:newTalent)''' 
Thrown when the character unlocks a new talent

'''OnTalentLocked(CHARACTER:character, TALENT:removedTalent)''' 
Thrown when the there's a talent removed from a character

'''OnCharacterClassChanged(CHARACTER:character, FIXEDSTRING:class)''' 
Thrown when the character changes class in the character creation screen

'''OnCharacterCreationStarted(CHARACTER:character, TRIGGER:creationPoint)''' 
Thrown when the character creation has started, and gives where the character should walk to

'''OnCharacterCreationStopped(CHARACTER:character)''' 
Thrown when the character creation has stopped

'''OnFunction(FIXEDSTRING:functionName)''' 
Throws an event on itself with the functionName. This is to fake function calls

'''OnSkillCast(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when the character casts a skill

'''OnSkillCombatComment(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when the character needs to make a comment

'''OnCharacterUsedSkillOnMe(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when you are hit by a skill from a character

'''OnItemUnlocked(ITEM: item, CHARACTER:character, ITEM:key)''' 
Thrown when an item gets unlocked by a character.

'''OnAutomatedDialogEnded(STRING:dialogName, INT:instanceID)''' 
Thrown when a automated dialog is ended for this speaker

'''OnAutomatedDialogStarted(STRING:dialogName, INT:instanceID)''' 
Thrown when a automated dialog is started for this speaker

'''OnDialogStarted(STRING:dialogName, INT:instanceID)''' 
Thrown when a dialog is started for this speaker

'''OnDialogEnded(STRING:dialogName, INT:instanceID)''' 
Thrown when a dialog is ended for this speaker

'''OnCrimeSensibleAction(FIXEDSTRING:regionID, INT:crimeID, FIXEDSTRING:reactionName, STRING:primaryDialog, CHARACTER:criminal1, CHARACTER:criminal2, CHARACTER:criminal3, CHARACTER:criminal4, INT:IsPrimary)''' 
Thrown when a character needs to perform a sensible action against criminals

'''OnCrimeInterrogationRequest(FIXEDSTRING:regionID, INT:crimeID, CHARACTER:criminal1, CHARACTER:criminal2, CHARACTER:criminal3, CHARACTER:criminal4, STRING:interrogationDialog)''' 
Thrown when a character needs to perform an interrogation against criminals

'''OnCrimeInvestigate(FLOAT3:CrimePosition, INT:crimeID)''' 
One NPC investigates a crimescene

'''OnCrimeAlarmed(FLOAT3:CrimePosition, INT:crimeID)''' 
All NPCs in a crimearea start looking around.

'''OnCrimeReturnToNormal(-)''' 
Investigation or Alarm timed out.

'''OnCrimeAborted(-)''' 
The game interrupted the sensible action of this NPC.

'''OnSplineControlPointReached(INT:Index, INT:EndReached, STRING:EventString)''' 
Thrown when a character reached a spline node.

''''OnFinishCalculationAi(-)''' 
Thrown when the calculation of the AI is finished.

'''OnGrenadeLand(INT:hitObstacle, CHARACTER:caster)''' 
Thrown when the grenades lands

'''FetchCharacterApplyStatusData(CHARACTER:character, STATUS:status) RETURN(LIST<STATUS>:removeStatuses, STATUS:applyStatus, INT:turns)''' 
Fetch from script which statuses to remove and apply.

'''FetchItemApplyStatusData(ITEM:item, STATUS:status) RETURN(LIST<STATUS>:removeStatuses, STATUS:applyStatus, INT:turns)''' 
Fetch from script which statuses to remove and apply.

'''FetchItemSkillOnDamage(INT:damage, DAMAGE_TYPE:damageType) RETURN(INT:hasSkill, SKILL_ID:skillID, INT:casterLevel)''' 
Fetch from script what skill to execute on damage.

'''FetchSkillScore(SKILL_ID:skillId, CHARACTER:sourceCharacter, CHARACTER:targetCharacter1, ITEM:targetItem1, FLOAT3:targetPosition1, CHARACTER:targetCharacter2, ITEM:targetItem2, FLOAT3:targetPosition2) RETURN(FLOAT:score) 
Fetch from script the score of a skill with set source and target

'''OnActivate(-)''' 
Thrown when a character/item activates

'''OnDeactivate(-)''' 
Thrown when a character/item deactivates

'''OnCharacterUsedSourcePoint(CHARACTER:character)''' 
Thrown when a character uses a source point

'''OnSkillAdded(CHARACTER:character, SKILL_ID:skillId, INT:learned)''' 
Thrown when a character learns a skill

'''OnSkillActivated(CHARACTER:character, SKILL_ID:skillId)''' 
Thrown when a character activates (=adds to memory) a skill

'''OnSkillDeactivated(CHARACTER:character, SKILL_ID:skillId)''' 
Thrown when a character deactivates (=removes from memory) a skill

'''OnItemFlagShared(FIXEDSTRING:eventName, ITEM:item, INT:newValue)''' 
Thrown when a dialog event is shared with an item

'''OnCharacterFlagShared(FIXEDSTRING:eventName, CHARACTER:character, INT:newValue)''' 
Thrown when a dialog event is shared with a character

'''OnItemOffStageChanged(CHARACTER:character, INT:offstage)''' 
Thrown when a character is set on/off stage

'''OnCharacterOffStageChanged(ITEM:item, INT:offstage)''' 
Thrown when a item is set on/off stage

'''OnCharacterTeleported(CHARACTER:target, CHARACTER:cause, FLOAT3:oldPosition, FLOAT3:newPosition, SKILL_ID:skillId)''' 
Thrown when a character gets teleported with a teleport skill

'''OnCombatTick(-)''' 
Thrown when this object ticks in combat. Only thrown for objects that don't get a turn.

'''OnCombatRoundStarted(INT:combatID, INT:roundID) 
Thrown when a round in a combat starts

'''OnReadyInCombat(CHARACTER:character, ITEM:item, INT:combatID)''' 
Thrown when a character or item is ready in combat

'''OnRegionLeft(CHARACTER:character, ITEM:item, FIXEDSTRING:region)''' 
Thrown when a character or item leaves a region

'''OnRegionEntered(CHARACTER:character, ITEM:item, FIXEDSTRING:region)''' 
Thrown when a character or item enters a region

'''OnRuneInserted(CHARACTER:character, ITEM:item, ITEMTEMPLATE:runeItemTemplate, INT:slot)''' 
Thrown when a <character> inserts a rune with roottemplate <runeItemTemplate> from an <item> at a specified <slot>

'''OnRuneRemoved(CHARACTER:character, ITEM:item, ITEM:rune, INT:slot)''' 
Thrown when a <character> removes a <rune> from an <item> at a specified <slot>

'''OnCharacterStartAttackObject(CHARACTER:defenderCharacter, ITEM:defenderItem, CHARACTER:attackerOwner, CHARACTER:attacker)''' 
Thrown when a character attacks a character or item with default attack

'''OnCharacterStartAttackPosition(FLOAT3:position, CHARACTER:attackerOwner, CHARACTER:attacker)''' 
Thrown when a character attacks a position with default attack

== INTERRUPTS ==

'''OnMovementFailed(FLOAT3:targetPos)''' 
Thrown when the reaction is interrupted by a move action failing

'''OnException(-)''' 
Thrown when the reaction is interrupted by an exception

'''OnBetterReactionFound(FIXEDSTRING:reactionName)''' 
Thrown when the reaction is interrupted by another reaction

'''OnNoReactionFound(-)''' 
Thrown when the reaction is interrupted because no reaction is valid

'''OnScriptDisabled(-)''' 
Thrown when the reaction is interrupted because the scriptcontroller is disabled

'''OnManualInterrupt(FIXEDSTRING:reactionName)''' 
Thrown when the reaction is interrupted using the interrupt action

'''OnRegionSwap(FIXEDSTRING:oldLevel, FIXEDSTRING:newLevel)''' 
Thrown when the reaction is interrupted by a region swap

= Divinity: Original Sin 2 Definitive Edition =
The following was added/changed for the Definitive Edition.

== CALLS ==
'''ItemDrop(ITEM:item)''' 
Drops an item from it's owner's inventory. Only characters are treated as owners.

'''RemoveSurfaceLayerAt(GAMEOBJECT|FLOAT3:target, INT:layer, FLOAT:radius)''' 
Removes surface (ground or cloud) at object/position. (Layer 0 for surface, otherwise - cloud) (Radius for cleanup)

'''SurfaceCreateLink(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 
Makes surfaces at 2 locations/positions interact as if they were adjacent.

'''SurfaceRemoveLink(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 
Stops surfaces at 2 distinctive locations/positions from interacting.

== QUERIES ==
'''AttributeGetDifficultyLevelMappedValue(FIXEDSTRING:difficulty, INT:level, OUT INT:levelMappedValue)''' 
Returns a level-mapped value of a primary attribute. (Difficulty = "Easy", "Normal" or "Hard")

'''CharacterGetCreationClass(CHARACTER:character, OUT FIXEDSTRING: class)''' 
During character creation returns character class. Fails outside of character creation.

'''CharacterGetEquippedItem(CHARACTER:character, FIXEDSTRING:slot, OUT ITEM:seatingItem)''' 
Returns item equipped into slot. (Slot = "Helmet", "Breast", "Leggings", "Weapon", "Shield", "Ring", "Ring2", "Belt", "Boots", "Gloves", "Amulet" or "Wings")

(CHANGED) '''CharacterInCreation(CHARACTER:character, OUT INT:CharacterIndex)''' 
Checks if character is in character creation currently. (CharacterIndex: assigned index of the player character during character creation)

Character and Item Script Triggers, Calls, and Queries

2019-10-17T21:12:26Z

LaughingLeader: Line break fix

This is a list of almost every character and item script event trigger, call, and query. An event is what triggers the script, and always begin with ''On''. Queries provide information and are always inside an ''IF'' or ''CHECK.'' Calls are actions that are always after THEN.

CharScript/ItemScript Functions

= Divinity: Original Sin 2 Classic=
== CALLS ==

'''Set(OUT OBJECT:variable, OBJECT:value)'''

Set the value of a variable

'''SetVar(CHARACTER|ITEM:object, FIXEDSTRING:variableName, OBJECT:value)'''

Set the value of a global variable

'''Cast(OUT OBJECT variable, OBJECT value)'''

Casts the value to the variable

'''Print(OUT STRING:output, STRING:text)'''

Prints the text to the output with possible parameters: [1], [2], ...

'''Add(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT|FLOAT3:value)'''

Adds both values and stores it in the first variable

'''Subtract(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT|FLOAT3:value)'''

Subtracts both values and stores it in the first variable

'''Multiply(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT:value)'''

Multiplies both values and stores it in the first variable

'''Divide(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT:value)'''

Divides both values and stores it in the first variable

'''Abs(INOUT INT|FLOAT:variable)'''

Takes the absolute value of a variable

'''Clamp(INOUT INT|FLOAT:variable, INT|FLOAT:min, INT|FLOAT:max)'''

Clamps a variable between min and max

'''GetRandom(OUT OBJECT:variable, OBJECT:value, OBJECT:value, OBJECT:value)'''

Fills in the variable with random one of the values.

'''GetWeightedRandom(OUT OBJECT:variable, OBJECT:value, INT|FLOAT:weight, ...)'''

Gets a weighted random of the given values!

'''GetRandomBetween(OUT INT|FLOAT:variable, INT|FLOAT:min, INT|FLOAT:max)'''

Gets a random value between min and max (both included)

'''GetRandomPositionInTrigger(OUT FLOAT3:variable, TRIGGER:areaTrigger)'''

Get a random position in a trigger area

'''GetElement(OUT OBJECT:variable, INT:index, OBJECT:value, OBJECT:value, OBJECT:value)'''

Fills in the variable with the index one of the values (starting from 0)

'''SetPriority(FIXEDSTRING:reactionName, INT:priority)'''

Changes the priority of a reaction. Priority 0 and below are not executed!

'''DelayReaction(FIXEDSTRING:reactionName, FLOAT:timeInSeconds)'''

The reaction will not be chosen for the specified time

'''SetScriptFrame(CHARACTER:character, FIXEDSTRING:frame)'''

Sets the scriptframe on the character.

'''ClearScriptFrame(CHARACTER:character)'''

Clears the scriptframe on the character.

'''Goto(FIXEDSTRING:labelName)'''

Jumps to the label. Two label names are built-in: "Start" for the first instruction of the reaction, and "End" for the last one.

'''GotoIfEqual(OBJECT:variable, OBJECT:value, FIXEDSTRING:labelName)'''

Jumps to the label if the 2 objects are equal

'''GotoRand(FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName)'''

Jumps to a random label in the list

'''CreatePuddleAt(GAMEOBJECT|FLOAT3:target, SURFACE:type, INT:cellAmountMin, INT:cellAmountMax, INT:growAmountMin, INT:growAmountMax, )'''

Spawn a puddle at the target's position for a certain lifetime (in turns)

'''CreateSurfaceAt(GAMEOBJECT|FLOAT3:target, SURFACE:type, FLOAT:radius, INT:lifeTime[, GAMEOBJECT:owner])'''

Spawn a surface at the target's position for a certain lifetime (in turns)

'''CreateSurfaceInPolygon(GAMEOBJECT:owner, SURFACE:type, FLOAT:duration, FLOAT:growTimer, INT:growStep, GAMEOBJECT|FLOAT3:point1, GAMEOBJECT|FLOAT3:point2, GAMEOBJECT|FLOAT3:point3, ...)'''

Spawn a polygon surface at the target's position. Grows <growStep> every <growTimer>.

'''CreateSurfaceInAreaTrigger(GAMEOBJECT:owner, SURFACE:type, FLOAT:duration, FLOAT:growTimer, INT:growStep, TRIGGER:areaTrigger)'''

Spawn a surface within <areaTrigger>. Grows <growStep> every <growTimer>.

'''CreateConeSurfaceAt(GAMEOBJECT|FLOAT3:start, GAMEOBJECT|FLOAT3:target, SURFACE:type, FLOAT:radius, FLOAT:angle, FLOAT:duration)'''

Spawn a Cone surface at the target's position

'''PlayEffectAt(GAMEOBJECT|FLOAT3:target, STRING:effectName)'''

Plays an effect at the target's position

'''PlayLoopEffectAt(OUT INT64:effectHandle, GAMEOBJECT|FLOAT3:target, STRING:effectName)'''

Plays an effect at the target's position

'''ExplodeAt(GAMEOBJECT|FLOAT3:target, SKILL:projectileSkill, [INT:casterLevel=-1, CHARACTER|ITEM:cause])'''

Trigger an explosion of a projectile skill at the target's position. The cause will trigger NPC behavior as if the cause casted the projectile

'''DisplayText(CHARACTER|ITEM:target, FIXEDSTRING:text, FLOAT:timeInSeconds)'''

Displays text above the character/item for a certain amount of time. It will replace the current text, including dialogtext

'''DisplayCombatInfoText(CHARACTER|ITEM:target, FIXEDSTRING:text, FLOAT:timeInSeconds)'''

Displays text above the character/item for a certain amount of time. It will replace the current text, including dialogtext

'''StatusText(CHARACTER|ITEM:target, FIXEDSTRING:text)'''

Adds statustext above the character/item for a short amount of time. Will not replace texts or dialogtexts

'''DebugText(CHARACTER|ITEM:target, STRING:text)'''

Adds debugtext above the character/item for a short amount of time.

'''CombatLogText(CHARACTER|ITEM:target, FIXEDSTRING:text, INT:filterID, INT:broadcastID)'''

Adds combatlog text inside the combat log window. Color-/SizeFormatting should already be applied, if not color and size of the string will be NORMAL. filterID determines what filter shows/hides the text. broadcastID determines who will be able to see the message (0 hearingrange. 1 party. 2 all)

'''Log(STRING:text, ...)'''

Log's the the scriptlog. (for debugging purposes)

'''Output(STRING:text, ...)'''

Pass text with optional parameters to the output panel (e.g. Output("An int [1]", INT:10))

'''Assert(STRING:text, ...)'''

Pass text with optional parameters to display as an assert message (e.g. Assert("This number is wrong: [1]", INT:666))

'''Label(FIXEDSTRING:name)'''

Marks this line as a label where Goto actions can jump to

'''StartTimer(FIXEDSTRING:timerName, FLOAT:timeInSeconds, INT:repeatCount)'''

Start a timer which will throw the timer event. Set repeatcount < 0 for a permanent timer.

'''StopTimer(FIXEDSTRING:timerName)'''

Stop a timer which will throw the timer event

'''DialogStart(OUT INT:instanceId, STRING:dialog, CHARACTER|ITEM:target, CHARACTER|ITEM:target, CHARACTER|ITEM:target, CHARACTER|ITEM:target)'''

Start a dialog between the targets. You can specify fewer targets than the maximum number.

{{warning|Starting a dialog from behaviour script will always start it as an [[Dialog_editor#Automated|Automated Dialog]]. Interactive dialogs can only be started from [[Osiris]].}}

'''DialogRequestStop(CHARACTER|ITEM:speaker, STRING:dialog)'''

Stops a certain dialog on a certain speaker

'''Check(-)'''

Reevaluate the conditions in the CHECK section of this reaction

'''Reset(-)'''

Resets the current reaction. It will start from the beginning again

'''Interrupt(FIXEDSTRING:reactionName)'''

Interrupt the reaction.

'''GlobalSetEvent(FIXEDSTRING:eventName)'''

Sets a global event. Scripts and Story can catch it.

'''GlobalClearEvent(FIXEDSTRING:eventName)'''

Clears a global event. Scripts and Story can catch it.

'''StopLoopEffect(INT64:fxHandle)'''

Stops a looping effect

'''IterateItems(FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item. If you pass a tag, it has to have that tag.

'''IterateItemsNear(GAMEOBJECT:source, FLOAT:radius, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item in range. If you pass a tag, it has to have that tag.

'''IterateItemsOnObject(CHARACTER|ITEM:source, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item standing on the source. If you pass a tag, it has to have that tag.

'''IterateParty(FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, CHARACTER:partyMember, FIXEDSTRING:tag])'''

Launch iterate event for each member of all parties. If you pass a party member only members of that party will be considered. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharacters(FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersNear(GAMEOBJECT:source, FLOAT:radius, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character in range. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersOnObject(CHARACTER|ITEM:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''
Launch iterate event for each character standing on the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersInCombat(CHARACTER|ITEM:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character in combat with the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateHostilesFor(CHARACTER:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character who is targetting the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''SpawnCharacter(OUT CHARACTER:result, CHARACTERTEMPLATE:rootTemplate, GAMEOBJECT|FLOAT3:position, INT:playSpawn, [INT:isSummon=0, CHARACTER:summonOwner=null, INT:overrideLevel=-1])'''

Spawns a character

'''SpawnItem(ITEMTEMPLATE:rootTemplate,GAMEOBJECT|FLOAT3:position, OUT ITEM:result)'''

Spawns an item

'''ShootLocalProjectile(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,FLOAT3:direction,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Spawns a projectile at the source (with offset, can be null) shooting at the target

'''ShootLocalProjectileAt(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,GAMEOBJECT|FLOAT3:target,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Spawns a projectile at the source (with offset, can be null) shooting at the target

'''ShootWorldProjectile(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,FLOAT3:direction,[INT:casterLevel])'''

Spawns a projectile at worldPos shooting at the target. Source can be null.

'''ShootWorldProjectileAt(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,GAMEOBJECT|FLOAT3:target,[INT:casterLevel])'''

Spawns a projectile at worldPos shooting at the target. Source can be null.

'''ShootLocalCone(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,FLOAT3:direction,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Shoots a cone from source (with offset, can be null) in a direction

'''ShootLocalConeAt(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,GAMEOBJECT|FLOAT3:target,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Shoots a cone from source (with offset, can be null) at the target

'''ShootWorldCone(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,FLOAT3:direction,[INT:casterLevel])'''

Shoots a cone from worldPos in a direction. Source can be null.

'''ShootWorldConeAt(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,GAMEOBJECT|FLOAT3:target,[INT:casterLevel])'''

Shoots a cone from worldPos at the target. Source can be null.

'''SetVisible(CHARACTER|ITEM:object, INT:visible)'''

Sets a character or item visible or not.

'''RotateY(INOUT FLOAT3:vector, FLOAT:degrees)'''

Rotate the vector around the Y-axis for a certain angle (in degrees)

'''SetHealth(CHARACTER|ITEM:target, FLOAT:percent)'''

Set a characters or items health on the given percentage. (percentage between 0 and 1)

'''PlaySound(CHARACTER|ITEM:target, STRING:soundEvent)'''

Plays a sound event at the target

'''PlayMusicForEveryone(STRING:musicEvent)'''

Plays a music event on all the clients

'''PlayMusicOnCharacter(CHARACTER:target, STRING:musicEvent)'''

Plays a music event on a character for all peers (3D)

'''PlayMusicForPeer(CHARACTER:target, STRING:musicEvent)'''

Plays a music event on the peer of the character

'''PlayMusicForPeerWithInstrument(CHARACTER:target, CHARACTER:charInstrument, STRING:musicEvent)'''

Plays a music event on the peer of the character concated with _INSTRUMENT

'''SetX(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the X component of the FLOAT3

'''SetY(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the Y component of the FLOAT3

'''SetZ(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the Z component of the FLOAT3

'''SetAtmosphere(FIXEDSTRING:atmosphereTriggerUUID, FIXEDSTRING:atmosphere)'''

Changes the atmosphere of the trigger

'''ResetAtmosphere(FIXEDSTRING:atmosphereTriggerUUID)'''

Resets the atmosphere of the trigger

'''AddStatusInfluence(CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1], [INT:force=1])'''

Adds the status influence strength on the object.

'''RemoveStatusInfluence(CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1])'''

Removes the status influence strength on the object.

'''AddTemporaryStatusInfluence(CHARACTER|ITEM:source, CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1])'''

Adds a temporary status influence strength on the object.. It will be gone in a few seconds if it's not set again

'''CallFunction(FIXEDSTRING:functionName)'''

Calls a function with the ID

'''SetMaterial(CHARACTER|ITEM:object, FIXEDSTRING:materialUUID, INT:duration, INT:applyOnBody, INT:applyOnArmor, INT:applyOnWings, INT:applyOnHorns, INT:applyOnOverhead, INT:applyOnWeapon[,INT:applyNormalMap, INT:overlay, INT:fading])'''

Changes the material of the object for a set time (in turns), -1 is infinite. applyNormalMap: Copy the original materials normal map

'''TeleportTo(CHARACTER|ITEM:object, GAMEOBJECT|FLOAT3:target, [INT:Force=0])'''

Teleport object to or near the target

'''Transform(CHARACTER|ITEM:object, CHARACTERTEMPLATE|ITEMTEMPLATE:root [, FIXEDSTRING:fx, INT:replaceScripts=1, OUT FLOAT:currentHP])'''

Transforms <object> using <root>, returns <currentHP>, plays <fx>.

'''SaveGame(FIXEDSTRING:saveGameName)'''

Save the savegame with name <saveGameName>

'''LoadGame(FIXEDSTRING:saveGameName)'''

Load the savegame with name <saveGameName>

'''LoadLevel(FIXEDSTRING:levelName)'''

Load the level with name <levelName>

'''KillCombat(CHARACTER:character)'''

Kill all the enemies in the combat which contains <character>

'''SetTag(CHARACTER|ITEM:object, FIXEDSTRING:tag)'''

Sets the Tag on the Object

'''ClearTag(CHARACTER|ITEM:object, FIXEDSTRING:tag)'''

Clears the Tag on the Object

'''SetGlobalFlag(FIXEDSTRING:flagname)'''

Sets the Global Flag

'''ClearGlobalFlag(FIXEDSTRING:flagname)'''

Clears the Global Flag

'''SetFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Sets the Flag on the Object

'''ClearFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the Object

'''SetUserFlag(CHARACTER:object, FIXEDSTRING:flagname)'''

Sets the Flag on the user's characters

'''ClearUserFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the user's characters

'''SetPartyFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Sets the Flag on the party's characters

'''ClearPartyFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the party's characters

'''StartVoiceBark(STRING:barkName, CHARACTER:character)'''

Start a voicebark on character

'''ConfrontationDone(INT: CrimeID, CHARACTER:lead, CHARACTER:criminal, ...)'''

Resolve the crime with id CrimeID for the specified criminals

'''CrimesceneInvestigationDone(CHARACTER:investigator)'''

Crimescene is considered investigated by this NPC, start looking for culprits

'''ListAdd(LIST<OBJECT>:list, OBJECT:entry)'''

Add <entry> at the back of <list>

'''ListRemove(LIST<OBJECT>:list, INT:index)'''

Remove the entry at <index> of <list>

'''ListSet(LIST<OBJECT>:list, INT:index, OBJECT:entry)'''

Set the entry at <index> of <list> to <entry>

'''ListClear(LIST<OBJECT>:list)'''

Remove all entries of <list>

'''EndTurn(CHARACTER|ITEM:Target)'''

Ends the object's current turn

'''SetCanFight(CHARACTER|ITEM:entity, INT:enabled[, INT:wholeGroup=0])'''

Enables/Disables the fact if the entity can fight. Optional for the whole group

'''SetCanJoinCombat(CHARACTER|ITEM:entity, INT:enabled[, INT:wholeGroup=0])'''

Enables/Disables the fact if the entity can join combats. Optional for the whole group

'''SetIsBoss(CHARACTER|ITEM:entity, INT:enabled)'''

Enables/Disables the fact if the entity is a boss.

'''GetAIHintTriggers(OUT LIST<TRIGGER>:triggers[, [LIST]FIXEDSTRING:tags, INT:needsAllTags = -1)'''

Returns all AIHintAreaTriggers in <triggers>. Uses contraints if set.

'''SetCombatTimeout(CHARACTER|ITEM:entity, FLOAT:timer)'''

Overwrites the entity's combat timeout check.

'''ResetCombatTimeout(CHARACTER|ITEM:entity)'''

Resets the entity's combat timeout check.

'''EnterCombat(CHARACTER|ITEM:source, CHARACTER|ITEM:target)'''

Enters combat with target

'''LeaveCombat(CHARACTER|ITEM:source)'''

Leaves the combat

'''SetFaction(CHARACTER|ITEM:target, FIXEDSTRING:faction)'''

Changes the faction of a character or item

'''SetInvulnerable(CHARACTER|ITEM:target, INT:bool)'''

Makes the character or item invulnerable or not. (Allow damage)

'''JumpToTurn(CHARACTER|ITEM:Target)'''

Jumps to targets turn (ends the current turn)

'''Sleep(FLOAT:timeInSeconds)'''

Sleeps for a certain amount of time

'''CharacterAttack(CHARACTER|ITEM|FLOAT3:target [,INT:alwaysHit])'''

Moves in weapon range and attacks the target

'''CharacterAttackWithoutMove(CHARACTER|ITEM|FLOAT3:target [,INT:alwaysHit])'''

Attacks the target without checking weaponranges and without moving

'''CharacterMoveTo(GAMEOBJECT|FLOAT3:target, [INT:running=0, INT:shouldArrive=0, INT:longPath=0, FLOAT:minDistance=1.5, FLOAT:maxDistance=minDistance+2.5])'''

Move to the target. Set shouldArrive to 1 if you want a guaranteed move. (teleports on fail)

'''CharacterAiMove(FLOAT3:target, CHARACTER:targetCharacter, ITEM:targetItem)'''

Moves to the target, calculated by the AI. Should only be used with results from the AI!

'''CharacterMoveInRange(GAMEOBJECT|FLOAT3:target, FLOAT:rangeMin, FLOAT:rangeMax, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within a certain range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveInWeaponRange(GAMEOBJECT|FLOAT3:target, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within weapon range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveInSkillRange(GAMEOBJECT|FLOAT3:target, SKILL:skill, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within skill range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveOutOfSight(FLOAT:angle)'''

Move out of screen

'''CharacterPlayAnimation(FIXEDSTRING:animation [, INT:exitOnFinish=1, INT:waitForCompletion=1], INT:noBlend=0])'''

Plays a certain animation.

ExitOnFinish means if the exit will kill itself after it was played (revert back to still).

WaitForCompletion means if the action will wait for the animation to be played at least once.

noBlend means no blending will be performaed when doing this animation.

'''CharacterStopAnimation(-)'''

Stops all animations.

'''CharacterPickUpItem(ITEM:item)'''

Moves close enough to the item if necessary and picks it up

'''CharacterUseItem(ITEM:item [, INTEGER:LongPath])'''

Moves close enough to the item if necessary and uses it

'''CharacterMoveItem(ITEM:item, INTEGER:ignoreWeight, INTEGER:ignoreAPCost [, INTEGER:ignoreDangerousSurfaces=1, INT:amount=-1, GAMEOBJECT|FLOAT3:destination])'''

Moves close enough to the item if necessary and moves it to the destination. Will try to find a destination if not supplied.

'''CharacterAddSkill(CHARACTER:character, SKILL:skill[, INT:ShowNotification=0])'''

Adds <skill> to <character>

'''CharacterRemoveSkill(CHARACTER:character, SKILL:skill)'''

Removes <skill> from <character>

'''CharacterUseSkill(SKILL:skill, GAMEOBJECT|FLOAT3:target [, GAMEOBJECT|FLOAT3:target2, ITEM:skillItem, INT:ignoreHasSkill=0])'''

Cast a skill

'''CharacterAppearAt(GAMEOBJECT|FLOAT3:target, INT:playspawn)'''

Appear at the target

'''CharacterAppearOutOfSightTo(GAMEOBJECT:target, FLOAT:angle, INT:playspawn)'''

Appears out of sight to the players from a certain angle while being able to reach target

'''CharacterAppearOnTrailOutOfSightTo(CHARACTER:target, FLOAT:angle, INT:playspawn)'''

Appears out of sight to the players, on its previous locations, from a certain angle while being able to reach target

'''CharacterDisappear(FLOAT:angle[, INTEGER:isRunning=0])'''

Move out of screen and go of stage, will run if <isRunning> is not 0

'''CharacterSetOffStage(-)'''

Set Off Stage

'''CharacterSetOnStage(-)'''

Set On Stage

'''CharacterLookAt(GAMEOBJECT|FLOAT3|SPLINE:target[, INT:snapToTarget=0, INT:angleTolerance=0])'''

Rotates the character to look at the target (Closest spline point in case of a spline).

'''CharacterLookFrom(GAMEOBJECT|SPLINE:target[, INT:snapToTarget=0])'''

Rotates to the character so it has the same rotation as the target (Closest spline point in case of a spline).

'''CharacterFollow(CHARACTER:target, FLOAT:durationInSeconds, INT:run)'''

Follow the target for a certain time

'''CharacterFollowOwnerOrLeader(FLOAT:durationInSeconds, INT:run)'''

Follow the leader or owner for a certain time

'''CharacterWander(FLOAT|TRIGGER:range, FLOAT:durationInSeconds [, INT:run, GAMEOBJECT:anchor])'''

Wander around for a certain time

'''CharacterSwitchWeaponType(WEAPON:type)'''

If necessary switch to the new weapon type

'''CharacterFleeFrom(RELATION:relation, FLOAT:range)'''

Run away from certain characters if necessary
'''
CharacterFleeFromSurface(SURFACE:surface)'''

Run away from a certain surface if necessary

'''CharacterFleeFromDangerousSurface(-)'''

Run away from a dangerous surfaces if necessary

'''CharacterAddSourcePoints(CHARACTER:character, INT:amount)'''

Adds x source points (x can be negative to substract)

'''CharacterDie(CHARACTER:character[, DEATH:type=DoT])'''

Kills the character

'''CharacterHeal(CHARACTER:character, FLOAT:percentage)'''

Heals the character

'''CharacterConsume(CHARACTER:character, POTION:potion)'''

Makes the character consume a potion. Doesn't cost any AP and will just execute the result of the potion.

'''CharacterDisableAllCrimes(CHARACTER:target)'''

Disables all generic behaviours for <target>.

'''CharacterEnableAllCrimes(CHARACTER:target)'''

Enables all generic behaviours for <target>.
'''
CharacterEnableCrime(CHARACTER:target, STRING:crime, ...)'''

Enables the specified generic behaviours for <target>.

'''CharacterDisableCrime(CHARACTER:target, STRING:crime, ...)'''

Disables the specified generic behaviours for <target>.

'''CharacterSetLongInvestigationDuration(CHARACTER:target)'''

Doubles the time it takes for the investigation to time out. Use this when the character needs to move a long path before investigating.

'''CharacterAiCalculate(-)'''

Calculate the AI of the character

'''CharacterAiStopCalculate(-)'''

Stop the calculation of the AI of the character

'''CharacterAiFinishMoveSkill(-)'''

Finish the current MoveSkill.
'''
CharacterAiAddInterestingItem(CHARACTER:character, ITEM:item)'''

Make it interesting for the AI to destroy that Item

'''CharacterAiRemoveInterestingItem(CHARACTER:character, ITEM:item)'''

Make it no longer interesting for the AI to destroy that Item

'''CharacterSetArchetype(CHARACTER:character, ARCHETYPE:archetype)'''

Sets the archetype of the character, used in AI calculations

'''CharacterSetStoryNPC(CHARACTER:character, INT:bool)'''

Makes the character storyNPC or not.
'''
CharacterAddActionPoints(CHARACTER:character, INT:amount)'''

Give character some action points

'''CharacterSetImmortal(CHARACTER:character, INT:bool)'''

Makes the character immortal or not. (Allow dying)

'''CharacterPlayEffect(CHARACTER:character, STRING:effect [,FIXEDSTRING:boneName])'''

Plays an effect on the character and it follows the character

'''CharacterPlayLoopEffect(OUT INT64:effectHandle, CHARACTER:character, STRING:effect [,FIXEDSTRING:boneName])'''

Plays a looping effect on the character and it follows the character

'''CharacterEvent(CHARACTER:character, STRING:eventName)'''

Throw a character event which you can catch in scripts and story

'''CharacterItemEvent(CHARACTER:character, ITEM:item, STRING:eventName)'''

Throw a character/item event which you can catch in scripts and story

'''CharacterCharacterEvent(CHARACTER:character1, CHARACTER:character2, STRING:eventName)'''

Throw a character/character event which you can catch in scripts and story

'''CharacterSetRelationIndivToIndiv(CHARACTER:source, CHARACTER:target, INT:relation)'''

Changes the relationship between 2 characters.
'''
CharacterForceUpdate(INT:forceUpdate)'''

Makes sure the attached character is always being update or not.
'''
CharacterSetEnemy(CHARACTER:character, CHARACTER:enemy)'''

Sets the current enemy of character

'''CharacterApplyStatus(CHARACTER:character, STATUS:statusId [, INT:turns=null, INT:force=0])'''

Applies the status to the character When turns is -1 it's a permanent status When turns is -2 it's a keep alive status (which means it will die if it's not applied again within 1 second)

'''CharacterRemoveStatus(CHARACTER:character, STATUS:statusId [, STATUS:reasonStatusID=null, INT:notify=1])'''

Removes the status from the character

'''CharacterDestroy(CHARACTER:character)'''

Destroys the character

'''CharacterSetCanSpotSneakers(CHARACTER:character, INT:enabled)'''

Enables/Disables the fact if the character can spot sneaking characters.

'''CharacterSetAttackOfOpportunity(CHARACTER:character, INT:enabled)'''

Enables/Disables the fact if the character can do attack of opportunities.

'''CharacterResurrect(CHARACTER:character [, INT:Percentage = 100])'''

Resurrects the character at [2]% health.

'''CharacterAddToInventory(CHARACTER:character, FIXEDSTRING:itemStatsObject[, INT:amount, INT:showInTrade=1])'''

Add the item to the character

'''CharacterRemoveFromInventory(CHARACTER:character, FIXEDSTRING:itemStatsObject[, INT:amount])'''

Remove the item from the character. If Amount is -1, then all are removed

'''CharacterDrinkPotion(FIXEDSTRING:statID)'''

Makes the character drink a potion from the inventory.

'''CharacterSetAnimationOverride(CHARACTER:character, FIXEDSTRING:animation)'''

Sets an animation override, only walk/run/die animations can override it.

'''CharacterUseActionPoints(CHARACTER:character, INT:amount [, OUT INT:succeeded])'''

Uses x action points

'''CharacterAddTreasureTable(CHARACTER:character, FIXEDSTRING:treasureTable)'''

Adds <treasureTable> to the treasure list of <character>

'''CharacterRemoveTreasureTable(CHARACTER:character, FIXEDSTRING:treasureTable)'''

Removes <treasureTable> from the treasure list of <character>

'''CharacterClearTreasureTables(CHARACTER:character)'''

Removes all treasure tables from <character>

'''CharacterSetTemporaryHostileRelation(CHARACTER:character, CHARACTER:otherCharacter)'''

Creates a temporary hostile relation between the 2 characters!

'''CharacterSetFightMode(CHARACTER:character, INT:fight [, INT:force=0])'''

Set the character in sheath/unsheated mode.

'''CharacterSetStats(CHARACTER:character, FIXEDSTRING:statsEntry [, INT:keepVitality=0, INT:keepAP=0, INT:keepLevel=0, OUT FLOAT:currentHP])'''

Applies <statsEntry> from character.xlsm to <character>, returns <currentHP>.

'''CharacterSetWalkSpeedOverride(CHARACTER:character, INTEGER:override [, FLOAT:walkSpeed])'''

Sets walk speed override of <character>, removes it if <override> is 0

'''CharacterSetRunSpeedOverride(CHARACTER:character, INTEGER:override [, FLOAT:runSpeed])'''

Sets run speed override of <character>, removes it if <override> is 0

'''CharacterSetHasDialog(CHARACTER:character, INTEGER:bool)'''

Enables/Disables the dialog of the character

'''CharacterInitPatrol(SPLINE:spline, INT:splineIndex, INT:reversed, INT:running)'''

Start patroling from the given index along the given spline with the given character.

'''CharacterStartPatrol(SPLINE:spline, INT:splineIndex, INT:reversed, INT:running)'''

Start patroling from the given index along the given spline with the given character.

'''CharacterStopPatrol(-)'''

Let the character stop patrolling whatever spline he's on!

'''CharacterInterruptPatrol(-)'''

Call when the patrol should interrupt so the guard stops moving to the next spline. If this is called when the character is deactivated, a caret will take his place.

'''CharacterSetAnimationSetOverride(CHARACTER:source, FIXEDSTRING:override)'''

Sets an animation set override for a character. Empty fixedstring clears the override.

'''CharacterSetFloating(CHARACTER:target, INTEGER:isFloating)'''

Sets <target> floating if <isFloating> is not 0

'''CharacterResetCooldowns(CHARACTER:target)'''

Resets the skill cooldowns for <target>

'''ItemEvent(ITEM:item, STRING:eventName)'''

Throw an item event which you can catch in scripts and story

'''ItemPlayAnimation(FIXEDSTRING:animation)'''

Plays an animation on the item

'''ItemPlayAnimationTo(FIXEDSTRING:animation, FLOAT:targetPercentage, [FLOAT:speed])'''

Plays an animation on the item to the target time (percentage of the total duration)

'''ItemPlayEffect(ITEM:item, STRING:effect [,FIXEDSTRING:boneName])'''

Plays an effect on the item and it follows the item

'''ItemPlayLoopEffect(OUT INT:effectHandle, ITEM:item, STRING:effect [,FIXEDSTRING:boneName])'''

Plays a looping effect on the item and it follows the item

'''ItemSetOnStage(ITEM:item, INTEGER:bool)'''

Sets an item on or offstage

'''ItemSetCanInteract(ITEM:item, INTEGER:bool)'''

Sets an item (not) interactible

'''ItemClose(ITEM:item)'''

Close an item

'''ItemOpen(ITEM:item)'''

Open an item

'''ItemDrop(ITEM:item)'''

Drop an item

'''ItemLock(ITEM:item, FIXEDSTRING:key)'''

Lock an item

'''ItemUnlock(ITEM:item)'''

Unlock an item

'''ItemApplyStatus(ITEM:item, STATUS:statusId [, INT:turns=null, INT:force=0])'''

Applies the status to the item When turns is -1 it's a permanent status When turns is -2 it's a keep alive status (which means it will die if it's not applied again within 1 second)

'''ItemRemoveStatus(ITEM:item, STATUS:statusId)'''

Removes the status from the item

'''ItemDie(ITEM:item)'''

Kills the item

'''ItemMoveTo(GAMEOBJECT|FLOAT3:target, FLOAT:velocity, FLOAT:acceleration, INTEGER:matchTargetRotation)'''

Moves the item to the target

'''ItemToInventory(ITEM:item, CHARACTER|ITEM:target [,INT:amount=-1])'''

Moves the item to the target's inventory

'''ItemLookAt(GAMEOBJECT:target, FLOAT:degreesPerSecond)'''

Rotates the item to look at the target

'''ItemDestroy(ITEM:item)'''

Destroys the item

'''ItemSetAmount(ITEM:item, INT:amount)'''

Change the amount of the item

'''IterateItemsInInventory(CHARACTER|ITEM:source, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each iten in source's inventory. If you pass a tag, it has to have that tag.

'''ItemAddCharges(ITEM:TargetItem, INT:charges)'''

Add/subtract charges from an item

'''ItemResetChargesToInitial(ITEM:TargetItem)'''

Resets charges from item to initial state

'''MakePeace(CHARACTER:Source, CHARACTER:Target[, INT:IgnoreVote = 1])'''

Make peace between users of the characters

'''MakeWar(CHARACTER:Source, CHARACTER:Target[, INT:IgnoreVote = 1])'''

Make war between users of the characters

'''FindSurface(OUT FLOAT3:result, GAMEOBJECT|FLOAT3:source, FLOAT:minRange, FLOAT:maxRange, SURFACE:type [,CHARACTER:alignSource, INT:minEnemiesInSurface, INT:maxAlliesInSurface, INT:minimumCellCount])'''

Finds the closest surface of a specific type.

'''FindValidPosition(INOUT FLOAT3:position, FLOAT:radius[, CHARACTER|ITEM:object=null])'''

Finds the closest valid position (where the object can stand.)

'''FindPosition(INOUT FLOAT3:position, CHARACTER:source, INT:canStand, INT:checkSight, FLOAT:minRadius, FLOAT:maxRadius, FLOAT:rangeCheck, CHARACTER:alignSource, INT:minAllies, INT:maxAllies, INT:minEnemies, INT:maxEnemies [,FIXEDSTRING:AiHintTag=null, INT:forceHint=0, FLOAT3:SourcePosition])'''

Finds the closest position from the source (within radius) where the conditions are matched.

'''Cast(OUT OBJECT variable, OBJECT value)'''

Casts the value to the variable.

'''StringConcatenate(STRING:stringA, STRING:stringB, OUT STRING:resultingString)'''

Appends stringB to stringA. Resulting string is stored in the third parameter.

== QUERIES ==

'''GetPosition(GAMEOBJECT:object,OUT FLOAT3:src)''' 

Get the current position of an object

'''GetForwardDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current forward direction of an object

'''GetRightDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current right direction of an object

'''GetUpDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current up direction of an object

'''GetDirection(GAMEOBJECT|FLOAT3:src,GAMEOBJECT|FLOAT3:target,OUT FLOAT3:direction[, OUT FLOAT:distance])''' 

Get the direction from src to target (optional: returns the distance between the objects as well)

'''GetRotation(GAMEOBJECT:object, OUT FLOAT3:vector)''' 

Get the rotation of an object

'''CharacterGetTargetSpline(INT: SplineIndex)''' 

Returns the spline index the character is currently walking towards, or -1 if he is not active on a spline.

'''IsEqual(OBJECT:variable, OBJECT:variable)''' 

Compares both objects and see if they are equal.

'''IsLessThen(INT|FLOAT:variable, INT|FLOAT:variable)''' 

Compares both objects and see if the first one is smaller.

'''IsGreaterThen(INT|FLOAT:variable, INT|FLOAT:variable)''' 

Compares both objects and see if the first one is bigger.

'''IsRandom(FLOAT:percentage)''' 

Each time this condition is checked, it will succeed with a chance of the percentage (between 0 and 1)

'''IsRound(INT:roundNumber)''' 

Checks if we are currently in combat in round x

'''IsInSurface(OBJECT|FLOAT3:target, SURFACE:type[, FLOAT:radius])''' 

Check if the character, item, trigger or position is currently within the specific surface.

'''IsInDangerousSurface(OBJECT|FLOAT3:target[, CHARACTER:character, FLOAT:radius])''' 

Check if <target> is currently in on a dangerous surface. Uses <character> for path influences if provided (is necessary with non-character targets)

'''IsInDialog(CHARACTER|ITEM:target[, INT:ignoreAutomatedDialogs=0])''' 

Check if the character or item is currently in a dialog, optionally ignoring automated dialogs

'''IsInAutomatedDialog(CHARACTER|ITEM:target)''' 

Check if the character or item is currently in an automated dialog

'''GetDistance(OUT FLOAT:distance, GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 

Returns the distance between 2 positions

'''GetDistance2D(OUT FLOAT:distance, GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 

Returns the 2D distance between 2 positions (ignores height)

'''GetInnerDistance(OUT FLOAT:distance, GAMEOBJECT:source, GAMEOBJECT:target)''' 

Returns the distance between 2 gameobjects (character, item, trigger, ...) Their bounds are already subtracted.

'''GetPosition(GAMEOBJECT:object, OUT FLOAT3:position)''' 

Returns the position of a gameobject (character, item, trigger, ...)

'''GetVar(OUT OBJECT:returnValue, CHARACTER|ITEM:target, FIXEDSTRING:varName)''' 

Gets a global variable from the target

'''GetClosestPlayer(OUT CHARACTER:player, GAMEOBJECT|FLOAT3:source)''' 

Gets the closest player near the source, default being being the object itself

'''GetPlayerCount(OUT INT:playerCount)''' 

Gets the number of players in the party

'''GetPlayerByIndex(OUT CHARACTER:returnCharacter, INT:playerIndex)''' 

Gets a player from the party by index

'''GetRandomCharacter(OUT CHARACTER:returnCharacter, [INT:canBeSelf=0, INT:canBePlayer=0])''' 

Gets a random character in the current level

'''ContainsSurface(GAMEOBJECT|FLOAT3:source, FLOAT:radius, SURFACE:type,)''' 

Checks if there is any surface of the type within a radius of the source

'''IsSurface(GAMEOBJECT|FLOAT3:source, FLOAT:radius, SURFACE:type)''' 

Checks if the whole radius around the source is the specified surface type

'''IsObjectOnObject(CHARACTER|ITEM:source,CHARACTER|ITEM:target)''' 

Checks if the source is standing on the target

'''GetX(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the X component of the vector

'''GetY(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the Y component of the vector

'''GetZ(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the Z component of the vector

'''CanSee(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target[, INT:addProjectileTargetGroundOffset=0])''' 

Check if the sight is blocked between 2 points.

'''IsVisible(CHARACTER|ITEM:object)''' 

Check if the object is set invisible or not with SetVisible.

'''GetTextDuration(CHARACTER|ITEM:object, FIXEDSRTING:key, OUT FLOAT:duration)''' 

Gets how long a text needs to be displayed

'''IsCasual(-)''' 

Returns if the current game mode is Casual

'''IsHardcore(-)''' 

Returns if the current game mode is Hardcore

'''IsTagged(GAMEOBJECT:object, FIXEDSTRING:tag)''' 

Check if the object is tagged.

'''TranslatedStringKeyExists(FIXEDSTRING:key)''' 

Check if the TranslatedString key exists.

'''IsInCombat(CHARACTER|ITEM:object)''' 

Returns true if the object is in combat.

'''IsInCombatWith(CHARACTER|ITEM:object, CHARACTER|ITEM:object)''' 

Returns true if the objects are in combat with each other.

'''IsFacing(GAMEOBJECT:source, GAMEOBJECT|FLOAT3:target, [INT:angle=90])''' 

Returns true if the object is facing the position within the given angle.

'''GameIsSaving(-)''' 

Returns true if the game is saving.

'''GameIsLoading(-)''' 

Returns true if the game is loading.

'''GetUserCount(OUT INT:userCount)''' 

Returns the user count.

'''GetCurrentCharacter(OUT CHARACTER:character, INT:user)''' 

Returns the character currently being controlled by the specified user.

'''GetCurrentLevel(OUT FIXEDSTRING:currentLevel)''' 

Returns the current levelname

'''GetAIBounds(CHARACTER|ITEM:source, OUT FLOAT:bounds)''' 

Returns AI bounds of <source> in <bounds>

'''HasGlobalFlag(FIXEDSTRING:flagName)''' 

Returns if the Global Flag is set

'''HasFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the Object

'''HasUserFlag(CHARACTER:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the user's characters

'''HasPartyFlag(CHARACTER:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the party's characters

'''DialogExists(STRING:dialogue)''' 

Returns true if the dialogue exists.

'''IsActive(CHARACTER|ITEM:Object)''' 

Returns if the character or item is currently active.

'''ListGetSize(LIST<OBJECT>:list, out INT:size)''' 

Returns the number of elements in <list>

'''ListGet(LIST<OBJECT>:list, INT:index, out OBJECT:entry)''' 

Returns <entry> at <index> of <list>

'''ListGetRandom(LIST<OBJECT>:list, out OBJECT:entry)''' 

Returns a random <entry> of <list>

'''IsBoss(CHARACTER|ITEM:Object)''' 

Returns true if the entity is tagged as a boss

'''IsProjectileSkill(SKILL:skill)''' 

Returns true if the skill is a ranged skill (uses a projectile)

'''IsValidSkillTarget(CHARACTER:source, OBJECT|FLOAT3:target, SKILLID:skill[, INTEGER:ignoreRangeCheck=0])''' 

Checks whether <target> is a valid target for <skill> at <source>

'''GetFaction(OUT FIXEDSTRING:faction, CHARACTER|ITEM:character)''' 

Returns the faction of the provided character or item

'''IsInActiveTurn(CHARACTER|ITEM:target)''' 

Returns true if it's the character's or item's turn in combat.

'''IsSkillActive(CHARACTER:character, SKILL:skillId)''' 

Returns true if <character> has <skillId> active (in memory).

'''HasSkillAi(SKILLID:skillId)''' 

Returns true if the skill is using the new Ai system

'''IsInArena(CHARACTER::character)''' 

Returns true if the character is in an arena fight

'''CrimeGetType(INTEGER:crimeId, OUT STRING:crimeType)''' 

Returns the type of the crime with this id.

'''CrimeGetCriminals(INTEGER:crimeId, OUT CHARACTER:criminal1, OUT CHARACTER:criminal2, OUT CHARACTER:criminal3, OUT CHARACTER:criminal4)''' 

Returns the criminals of that crime. They might all be null.

'''IsSourceSkill(SKILL:skill)''' 

Returns true if the skill is a source skill.

'''IsInGameMasterMode(-)''' 

Returns true if the game in game master mode.

'''CharacterGet(OUT CHARACTER:character, GAMEOBJECT|FLOAT3:src, FLOAT:range, COMPARE:howTo, COMPAREFUNC:compareFunc[, RELATION: relation, SURFACE:surface, STATUS:status, TALENT:talent, CHARACTER:inSightOf, FIXEDSTRING:tag])''' 

Get a character within a certain range conforming to the filled in restraints.

'''CharacterCount(OUT INT:count, GAMEOBJECT|FLOAT3:src, FLOAT:range, [RELATION: relation, SURFACE:surface, STATUS:status, TALENT:talent, CHARACTER:inSightOf])''' 

Counts the characters within a certain range conforming to the filled in restraints.

'''CharacterGetOwner(OUT CHARACTER:owner, CHARACTER:source)''' 

Get the character's owner

'''CharacterGetFollow(OUT CHARACTER:to follow, CHARACTER:source)''' 

Get the character to follow

'''CharacterGetEnemy(OUT CHARACTER:current enemy, CHARACTER:source)''' 

Get current enemy of character

'''CharacterCanCast(CHARACTER:source, SKILL:skillId, [ITEM:skillItem=null, INT:ignoreActionPoints=0])''' 

Check if the character source can cast the skill: will check cooldown, actionpoints

'''CharacterCanSitOnItem(CHARACTER:source, ITEM:item)''' 

Check if the character source can sit or lie on an item.

'''CharacterCanDrinkPotion(CHARACTER:source, FIXEDSTRING:potionID[, INT:ignoreActionPoints=0])''' 

Check if the character source can drink the potion: will check inv and actionpoints

'''CharacterCanUseItem(CHARACTER:source, ITEM:item[, INT:ignoreActionPoints=0])''' 

Check if the character source can use the item in the world

'''CharacterCanUseItemInInventory(CHARACTER:source, ITEM:item[, INT:ignoreActionPoints=0])''' 

Check if the character source can use the item in his inventory

'''CharacterCanSee(CHARACTER:watchingChar, CHARACTER|ITEM:target [, INT:forceUpdate=0])''' 

Check if character has target in his line of sight.

'''CharacterCanShoot(CHARACTER:source, GAMEOBJECT|FLOAT3:target)''' 

Check if the character can shoot the target.

'''CharacterIsPlayer(CHARACTER:character)''' 

Check if the character is a player

'''CharacterIsInParty(CHARACTER:character)''' 

Check if the character is in the party

'''CharacterIsEnemy(CHARACTER:source, CHARACTER:target)''' 

Check if target is enemy of source

'''CharacterIsAlly(CHARACTER:source, CHARACTER:target)''' 

Check if target is ally of source

'''CharacterIsNeutral(CHARACTER:source, CHARACTER:target)''' 

Check if target is neutral of source

'''CharacterIsDead(CHARACTER:character)''' 

Check if character is dead

'''CharacterIsMoving(CHARACTER:character)''' 

Check if character is moving (speed > 0)

'''CharacterIsSummon(CHARACTER:character)''' 

Check if character is a summon

'''CharacterIsPartyFollower(CHARACTER:character)''' 

Check if character is a party follower

'''CharacterIsStoryNPC(CHARACTER:character)''' 

Check if character is a story NPC

'''CharacterInWeaponRange(CHARACTER:character, CHARACTER:target)''' 

Check if target is in the current's weapon range

'''CharacterInTouchRange(CHARACTER:character, CHARACTER:targetChar)''' 

Check if target is in the character's touch range

'''CharacterHasStatus(CHARACTER:character, STATUS:statusId[, FIXEDSTRING:extraData])''' 

Check if character currently has the status. ExtraData can be filled in for some statuses: - Consume: statsid of the item - Shield: skillid of the shield

'''CharacterGetStatusSourceCharacter(CHARACTER:character, STATUS:statusId, OUT CHARACTER:source[, FIXEDSTRING:extraData])''' 

Get the source character of a status

'''CharacterGetStatusSourceItem(CHARACTER:character, STATUS:statusId, OUT ITEM:source[, FIXEDSTRING:extraData])''' 

Get the source item of a status

'''CharacterHasTalent(CHARACTER:character, TALENT:talent)''' 

Check if character currently has the talent

'''CharacterHasSkill(CHARACTER:character, SKILL:skillId)''' 

Check if character currently has the skill

'''CharacterHasWeaponType(CHARACTER:character, WEAPON:weaponTYPE [, INT:equipped])''' 

Check if character currently has a weapon of this type in his inventory or equipped

'''CharacterGetStat(OUT FLOAT:statValue, CHARACTER:character, CHARACTERSTAT:statType)''' 

Returns the current value of the stat (Vitality, ...)

'''CharacterGetSightRange(OUT FLOAT:range, CHARACTER:character)''' 

Returns the character's sight range

'''CharacterGetWeaponRange(OUT FLOAT:minRange, OUT FLOAT:maxRange, CHARACTER:character)''' 

Returns the character's current weapon range

'''CharacterGetTouchRange(OUT FLOAT:touchRange, CHARACTER:character)''' 

Returns the character's current touch range

'''CharacterGetSkillRange(OUT FLOAT:minRange, OUT FLOAT:maxRange,CHARACTER:character, SKILL:skillId)''' 

Returns the character's skill range

'''CharacterGetSkillImpactRange(OUT FLOAT:areaRange, CHARACTER:character, SKILL:skillId)''' 

Returns the character's skill range

'''CharacterIsInTrigger(CHARACTER:character, TRIGGER:trigger)''' 

Check if character is in given trigger

'''CharacterGetAbility(OUT INT:value, CHARACTER:character, ABILITY:ability)''' 

Returns the character's value of the specified ability

'''CharacterGetHostileCount(OUT INT:value, CHARACTER:character)''' 

Returns how many characters are targeting this character right now... You can iterate over them with IterateEnemiesOf.

'''CharacterCanFight(CHARACTER:character)''' 

Returns true if the character can fight.

'''CharacterGetTemplate(CHARACTER:character, OUT CHARACTERTEMPLATE:root)''' 

Returns the roottemplate of the character.

'''CharacterCanSpotSneakers(CHARACTER:character)''' 

Returns true if the character can spot sneaking characters

'''CharacterIsFloating(CHARACTER:character)''' 

Check if character is a floating character

'''CharacterInCreation(CHARACTER:character)''' 

Returns true if the character is in character creation

'''CharacterAvoidsTraps(CHARACTER:character)''' 

Returns true if the character avoids traps

'''CharacterCheckRelation(CHARACTER:character, RELATION:relation)''' 

Returns true if relation check succeeds

'''CharacterIsBetterOrEqualClass(CHARACTER:character, INT:currentScore, OUT INT:newScore, INT warriorScore, INT rogueScore, INT mageScore, INT clericScore, INT rangerScore)''' 

Returns true if score is higher or equal than the current score

'''CharacterHasBeenHitBy(CHARACTER:character, DAMAGE_TYPE:damageType)''' 

Returns true if the character was hit by this type.

'''CharacterHasCastedSpellLastTurn(CHARACTER:character)''' 

Returns true if the character has casted a spell in his last turn.

'''CharacterHasHadStatus(CHARACTER:character, STATUS:status)''' 

Returns true if the character has had a specific status this combat.

'''CharacterHasAnimationOverride(CHARACTER:character)''' 

Returns true if the character has an animation override.

'''CharacterCanUnlock(CHARACTER:character, ITEM:item)''' 

Returns true if the character can unlock the item (if the item is already unlocked it returns true!)

'''CharacterGetReservedUserID(OUT INT:user, CHARACTER:character)''' 

Returns the character's reserved User id.

'''CharacterGetRace(CHARACTER:character, OUT FIXEDSTRING:race)''' 

Returns the <character>'s race in <race>.

'''CharacterIsRace(CHARACTER:character, FIXEDSTRING:race)''' 

Returns true if <character>'s race is <race>.

'''CharacterCanMoveItem(CHARACTER:character, ITEM:item, FLOAT:minRadius, FLOAT:maxRadius [, OUT FLOAT3:destination])''' 

Returns true + <destination> if <character> can move <item> somewhere between <minRadius> and <maxRadius>.

'''CharacterGetDeathType(CHARACTER:character, OUT FIXEDSTRING:deathType)''' 

Returns death type of <character> in <deathType>.

'''CharacterGetStillAnimation(CHARACTER:object, OUT FIXEDSTRING:stillAnimation)''' 

Returns the still animation to play

'''CrimeTransferLeadership(INT: CrimeID[, FIXEDSTRING:Tag1,...])''' 

Try and transfer the leadership of this crime to someone else.

'''CrimeGetLeadInvestigator(OUT CHARACTER:lead, INT: CrimeID)''' 

Returns the lead investigator for the crime.

'''CharacterCanHitTargetWithRangedWeapon(CHARACTER:source, OBJECT|FLOAT3:target[, SKILL:skill = null])''' 

Returns true if <source> can hit <target> with currently equipped ranged weapon. Will use <skill> instead of equipped weapon if provided.

'''CharacterHasRangedWeapon(CHARACTER:character[, INT:checkInventory = 0])''' 

Returns true if <character> has has ranged weapon. Checks for non-wielded weapons if <checkInventory> is 1

'''CheckInteractionReach(CHARACTER:character, CHARACTER|ITEM: target)''' 

Returns true if <character> could interact with <target>. This is not checking ranges, but checking if there's too much of a height difference or too many obstacles in between.

'''CharacterGetSourcePoints(CHARACTER:character, OUT INT: amount)''' 

Returns the amount of sourcepoints of <character>.

'''CharacterAiIsCalculating(-)''' 

Returns if the character is still calculating the AI.

'''CharacterAiFetchMoveSkillCommand(OUT SKILL:skill, OUT ITEM:skillItem, OUT FLOAT3:target)''' 

Returns if the character has a Move Skill command to execute according to the AI.

'''CharacterAiFetchSkillCommand(OUT SKILL:skill, OUT ITEM:skillItem, OUT FLOAT3 endPosition, OUT FLOAT3:target, OUT CHARACTER:target, OUT ITEM:target, OUT FLOAT3:target2, OUT CHARACTER:target2, OUT ITEM:target)''' 

Returns if the character has a Skill command to execute according to the AI.

'''CharacterAiFetchConsumeCommand(OUT ITEM:item)''' 

Returns if the character has a Consume command to execute according to the AI.

'''CharacterAiFetchAttackCommand(OUT FLOAT3:endPosition, OUT FLOAT3:target, OUT CHARACTER:target, OUT ITEM:target)''' 

Returns if the character has a Attack command to execute according to the AI.

'''CharacterAiFetchFallbackCommand(OUT FLOAT3:targetPosition, OUT FLOAT3:lookAtPosition)''' 

Returns if the character has a Fallback command to execute according to the AI.

'''CharacterGetArchetype(CHARACTER:character, OUT ARCHETYPE:archetype)''' 

Returns the archetype of the character.

'''CharacterIsPolymorphedInto(CHARACTER:character, FIXEDSTRING:race)''' 

Returns true if <character> is polymorphed into <race>. Race can be a race (like HUMAN), but also a template (in case of a polymorph skill like Chicken Touch).

'''CharacterIsPolymorphInteractionDisabled(CHARACTER:character)''' 

Returns true if <character> has his interaction disabled because of a polymorph.

'''ItemGet(OUT ITEM:item, GAMEOBJECT|FLOAT3:src, FLOAT:range, COMPARE:howTo [, COMPAREFUNC:compareFunc, FIXEDSTRING:rootTemplate, FIXEDSTRING:tag])''' 

Get an item within a certain range conforming to the filled in restraints.

'''ItemGetFromInventory(OUT ITEM:item, CHARACTER|ITEM:object [, FIXEDSTRING:statsId, FIXEDSTRING:tag, INT:isEquiped])''' 

Returns the first item in the inventory conforming to the filled in restraints.

'''ItemIsInCharacterInventory(ITEM:item, CHARACTER:object)''' 

Returns if the item is in the inventory of the character

'''ItemIsInTrigger(ITEM:item, TRIGGER:trigger)''' 

Check if item is in given trigger

'''ItemGetStat(OUT FLOAT:statValue, ITEM:item, ITEMSTAT:statType)''' 

Returns the current value of the stat (Weight, ...)

'''ItemIsMoving(ITEM:item)''' 

Returns if the item is moving or not.

'''ItemIsFalling(ITEM:item)''' 

Returns if the item is falling or not. (after teleport)

'''ItemIsOpening(ITEM:item)''' 

Returns if the item is opening or not.

'''ItemIsClosing(ITEM:item)''' 

Returns if the item is closing or not.

'''ItemIsLocked(ITEM:item)''' 

Returns if the item is locked or not.

'''ItemIsMovable(ITEM:item)''' 

Returns if the item is movable or not.

'''ItemCanBeLockPicked(ITEM:item)''' 

Returns if the item is can be opened by lockpicking.

'''ItemIsOpen(ITEM:item)''' 

Returns if the item is open or not.

'''IsStoryItem(ITEM:item)''' 

Returns if the item is a story item.

'''ItemHasStatus(ITEM:item, STATUS:statusId)''' 

Returns if the item has the status.

'''ItemIsDestroyed(ITEM:item)''' 

Returns if the item is destroyed.

'''ItemGetTemplate(ITEM:item, OUT ITEMTEMPLATE:root)''' 

Returns the roottemplate of the item.

'''ItemGetSkillId(ITEM:item, OUT SKILL:root)''' 

Returns the skillid of the item if it has one.

'''ItemGetItemType(ITEM:item, OUT FIXEDSTRING:itemType)''' 

Returns the itemtype of the item: common, unique, rare, ...

'''ItemGetStatusSourceCharacter(ITEM:item, STATUS:statusId, OUT CHARACTER:source)''' 

Get the source character of a status

'''ItemGetStatusSourceItem(ITEM:item, STATUS:statusId, OUT ITEM:source)''' 

Get the source item of a status

'''ItemCanBeMoved(ITEM:item)''' 

Returns if the item can be moved.

'''GetStatusTurns(CHARACTER|ITEM:object, STATUS:statusId, OUT INT:turnsLeft)''' 

Returns true if the object has the given status, and returns the amount of turns still left

== EVENTS ==

'''OnCharacterEvent(CHARACTER:character, STRING:eventName)''' 
Thrown from scripts or story

'''OnCharacterItemEvent(CHARACTER:character, ITEM:item, STRING:eventName)''' 
Thrown from scripts or story

'''OnCharacterCharacterEvent(CHARACTER:character, CHARACTER:character, STRING:eventName)''' 
Thrown from scripts or story

'''OnItemEvent(ITEM:item, STRING:eventName)''' 
Thrown from scripts or story

'''OnItemDestroyed(ITEM:item)''' 
Thrown when an item is destroyed

'''OnItemDestroying(ITEM:item)''' 
Thrown when an item is being destroyed

'''OnItemOpened(ITEM:item)''' 
Thrown when an item is opened

'''OnItemClosed(ITEM:item)''' 
Thrown when an item is closed

'''OnItemDropped(ITEM:item, STRING:itemTemplate)''' 
Thrown when an item is dropped

'''OnGlobalFlagSet(FIXEDSTRING:eventName)''' 
Thrown when a global event is set

'''OnGlobalFlagCleared(FIXEDSTRING:eventName)''' 
Thrown when a global event is cleared

'''OnCharacterFlagSet(FIXEDSTRING:eventName, CHARACTER:character)''' 
Thrown when a dialog event is set on a character

'''OnCharacterFlagCleared(FIXEDSTRING:eventName, CHARACTER:character)''' 
Thrown when a dialog event is cleared on a character

'''OnItemFlagSet(FIXEDSTRING:eventName, ITEM:item)''' 
Thrown when a dialog event is set on an item

'''OItemFlagCleared(FIXEDSTRING:eventName, ITEM:item)''' 
Thrown when a dialog event is cleared on an item

'''OnTimer(FIXEDSTRING:timerName)''' 
Thrown when a timer has ended

'''OnInit(-)''' 
Thrown when the script is set

'''OnLoaded(INT:major, INT:minor, INT:revision, INT:build)''' 
Thrown when the script is loaded from the savegame

'''OnShutdown(-)''' 
Thrown when the character's script is removed

'''OnVariableCleared(FIXEDSTRING:varName)''' 
Thrown when this object's script variable is cleared from Osiris with ClearVarObject

'''OnCombatStarted(INT:combatID)''' 
Thrown when combat starts

'''OnCombatSwitched(CHARACTER:source, ITEM:source)''' 
Thrown when the character switch from one combat to another

'''OnLeftCombat(CHARACTER:source, ITEM:source)''' 
Thrown when the character or item left the combat

'''OnTurn(CHARACTER:source, ITEM:source)''' 
Thrown when the character's turn starts

'''OnTurnEnded(CHARACTER:source, ITEM:source)''' 
Thrown when the character's turn ended

'''OnCharacterVitalityChanged(CHARACTER:character, FLOAT:percentage)''' 
Thrown when the characters's vitality changed

'''OnItemVitalityChanged(ITEM:item, FLOAT:percentage)''' 
Thrown when the item's vitality changed

'''OnAttackOfOpportunity(CHARACTER:target)''' 
Thrown when the characters gets an attack of opportunity on an enemy

'''OnClearAttackOfOpportunity(-)''' 
Thrown when the characters attack of opportunity is cleared

'''OnDamage(DAMAGE:type, FLOAT:percentage, CHARACTER:source, ITEM:source)''' 
Thrown when the object receives damage

'''OnMiss(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character dodges something

'''OnCriticalHit(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character is critical hit

'''OnPreBlock(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown before the character blocks something (at the start of the attack animation)

'''OnBlock(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character blocks something

'''OnDie(CHARACTER:character, DAMAGE:type, CHARACTER:source, ITEM:source)''' 
Thrown when the character dies

'''OnCharacterStatusAttempt(CHARACTER:character, STATUS:status)''' 
Thrown when the character attempts to gain a status

'''OnCharacterStatusApplied(CHARACTER:character, STATUS:status)''' 
Thrown when the character gains a status

'''OnCharacterStatusRemoved(CHARACTER:character, STATUS:status)''' 
Thrown when the character loses a status

'''OnItemStatusAttempt(ITEM:item, STATUS:status)''' 
Thrown when the item attempts to gain a status

'''OnItemStatus(ITEM:item, STATUS:status)''' 
Thrown when the item gains a status

'''OnItemStatusRemoved(ITEM:item, STATUS:status)''' 
Thrown when the item loses a status

'''OnStatusCreateVisuals(STATUS:status)''' 
Thrown when the item should create the visuals for this status

'''OnStatusDestroyVisuals(STATUS:status)''' 
Thrown when the item should destroy the visuals for this status

'''OnSight(CHARACTER:character)''' 
Thrown when the character sees another character

'''OnLostSight(CHARACTER:character)''' 
Thrown when the character doesn't see another character anymore

'''OnUseItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character uses an item

'''OnPickupItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character picks up an item

'''OnCharacterPreMovedItem(CHARACTER:source, ITEM:item)''' 
Event thrown just before a character moves an item. No difference whether it is in the world or in their inventory

'''OnCharacterMovedItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character moved an item

'''OnItemEquipped(CHARACTER:source, ITEM:item)''' 
Thrown when a character equips an item

'''OnItemUnequipped(CHARACTER:source, ITEM:item)''' 
Thrown when a character unequips an item

'''OnIterateCharacter(CHARACTER:character, FIXEDSTRING:eventId)''' 
Thrown by iterators

'''OnIterateItem(ITEM:source, FIXEDSTRING:eventId)''' 
Thrown by iterators

'''OnIterateCount(FIXEDSTRING:eventId, INTEGER:Count)''' 
Thrown by iterators after all iterations to inform you of the count.

'''OnStoryOverride(-)''' 
Throw when story overrides what the character was doing: teleport, movement, on/offstage

'''OnTriggerEnter(CHARACTER:character, ITEM:item, FIXEDSTRING:eventId)''' 
Thrown by a character or item entering an EventTrigger

'''OnTriggerLeave(CHARACTER:character, ITEM:item, FIXEDSTRING:eventId)''' 
Thrown by a character or item leaving an EventTrigger

'''OnEnemyChanged(CHARACTER:character, CHARACTER:newEnemy)''' 
Thrown when the character's currentenemy changes

'''OnTalentUnlocked(CHARACTER:character, TALENT:newTalent)''' 
Thrown when the character unlocks a new talent

'''OnTalentLocked(CHARACTER:character, TALENT:removedTalent)''' 
Thrown when the there's a talent removed from a character

'''OnCharacterClassChanged(CHARACTER:character, FIXEDSTRING:class)''' 
Thrown when the character changes class in the character creation screen

'''OnCharacterCreationStarted(CHARACTER:character, TRIGGER:creationPoint)''' 
Thrown when the character creation has started, and gives where the character should walk to

'''OnCharacterCreationStopped(CHARACTER:character)''' 
Thrown when the character creation has stopped

'''OnFunction(FIXEDSTRING:functionName)''' 
Throws an event on itself with the functionName. This is to fake function calls

'''OnSkillCast(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when the character casts a skill

'''OnSkillCombatComment(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when the character needs to make a comment

'''OnCharacterUsedSkillOnMe(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when you are hit by a skill from a character

'''OnItemUnlocked(ITEM: item, CHARACTER:character, ITEM:key)''' 
Thrown when an item gets unlocked by a character.

'''OnAutomatedDialogEnded(STRING:dialogName, INT:instanceID)''' 
Thrown when a automated dialog is ended for this speaker

'''OnAutomatedDialogStarted(STRING:dialogName, INT:instanceID)''' 
Thrown when a automated dialog is started for this speaker

'''OnDialogStarted(STRING:dialogName, INT:instanceID)''' 
Thrown when a dialog is started for this speaker

'''OnDialogEnded(STRING:dialogName, INT:instanceID)''' 
Thrown when a dialog is ended for this speaker

'''OnCrimeSensibleAction(FIXEDSTRING:regionID, INT:crimeID, FIXEDSTRING:reactionName, STRING:primaryDialog, CHARACTER:criminal1, CHARACTER:criminal2, CHARACTER:criminal3, CHARACTER:criminal4, INT:IsPrimary)''' 
Thrown when a character needs to perform a sensible action against criminals

'''OnCrimeInterrogationRequest(FIXEDSTRING:regionID, INT:crimeID, CHARACTER:criminal1, CHARACTER:criminal2, CHARACTER:criminal3, CHARACTER:criminal4, STRING:interrogationDialog)''' 
Thrown when a character needs to perform an interrogation against criminals

'''OnCrimeInvestigate(FLOAT3:CrimePosition, INT:crimeID)''' 
One NPC investigates a crimescene

'''OnCrimeAlarmed(FLOAT3:CrimePosition, INT:crimeID)''' 
All NPCs in a crimearea start looking around.

'''OnCrimeReturnToNormal(-)''' 
Investigation or Alarm timed out.

'''OnCrimeAborted(-)''' 
The game interrupted the sensible action of this NPC.

'''OnSplineControlPointReached(INT:Index, INT:EndReached, STRING:EventString)''' 
Thrown when a character reached a spline node.

''''OnFinishCalculationAi(-)''' 
Thrown when the calculation of the AI is finished.

'''OnGrenadeLand(INT:hitObstacle, CHARACTER:caster)''' 
Thrown when the grenades lands

'''FetchCharacterApplyStatusData(CHARACTER:character, STATUS:status) RETURN(LIST<STATUS>:removeStatuses, STATUS:applyStatus, INT:turns)''' 
Fetch from script which statuses to remove and apply.

'''FetchItemApplyStatusData(ITEM:item, STATUS:status) RETURN(LIST<STATUS>:removeStatuses, STATUS:applyStatus, INT:turns)''' 
Fetch from script which statuses to remove and apply.

'''FetchItemSkillOnDamage(INT:damage, DAMAGE_TYPE:damageType) RETURN(INT:hasSkill, SKILL_ID:skillID, INT:casterLevel)''' 
Fetch from script what skill to execute on damage.

'''FetchSkillScore(SKILL_ID:skillId, CHARACTER:sourceCharacter, CHARACTER:targetCharacter1, ITEM:targetItem1, FLOAT3:targetPosition1, CHARACTER:targetCharacter2, ITEM:targetItem2, FLOAT3:targetPosition2) RETURN(FLOAT:score) 
Fetch from script the score of a skill with set source and target

'''OnActivate(-)''' 
Thrown when a character/item activates

'''OnDeactivate(-)''' 
Thrown when a character/item deactivates

'''OnCharacterUsedSourcePoint(CHARACTER:character)''' 
Thrown when a character uses a source point

'''OnSkillAdded(CHARACTER:character, SKILL_ID:skillId, INT:learned)''' 
Thrown when a character learns a skill

'''OnSkillActivated(CHARACTER:character, SKILL_ID:skillId)''' 
Thrown when a character activates (=adds to memory) a skill

'''OnSkillDeactivated(CHARACTER:character, SKILL_ID:skillId)''' 
Thrown when a character deactivates (=removes from memory) a skill

'''OnItemFlagShared(FIXEDSTRING:eventName, ITEM:item, INT:newValue)''' 
Thrown when a dialog event is shared with an item

'''OnCharacterFlagShared(FIXEDSTRING:eventName, CHARACTER:character, INT:newValue)''' 
Thrown when a dialog event is shared with a character

'''OnItemOffStageChanged(CHARACTER:character, INT:offstage)''' 
Thrown when a character is set on/off stage

'''OnCharacterOffStageChanged(ITEM:item, INT:offstage)''' 
Thrown when a item is set on/off stage

'''OnCharacterTeleported(CHARACTER:target, CHARACTER:cause, FLOAT3:oldPosition, FLOAT3:newPosition, SKILL_ID:skillId)''' 
Thrown when a character gets teleported with a teleport skill

'''OnCombatTick(-)''' 
Thrown when this object ticks in combat. Only thrown for objects that don't get a turn.

'''OnCombatRoundStarted(INT:combatID, INT:roundID) 
Thrown when a round in a combat starts

'''OnReadyInCombat(CHARACTER:character, ITEM:item, INT:combatID)''' 
Thrown when a character or item is ready in combat

'''OnRegionLeft(CHARACTER:character, ITEM:item, FIXEDSTRING:region)''' 
Thrown when a character or item leaves a region

'''OnRegionEntered(CHARACTER:character, ITEM:item, FIXEDSTRING:region)''' 
Thrown when a character or item enters a region

'''OnRuneInserted(CHARACTER:character, ITEM:item, ITEMTEMPLATE:runeItemTemplate, INT:slot)''' 
Thrown when a <character> inserts a rune with roottemplate <runeItemTemplate> from an <item> at a specified <slot>

'''OnRuneRemoved(CHARACTER:character, ITEM:item, ITEM:rune, INT:slot)''' 
Thrown when a <character> removes a <rune> from an <item> at a specified <slot>

'''OnCharacterStartAttackObject(CHARACTER:defenderCharacter, ITEM:defenderItem, CHARACTER:attackerOwner, CHARACTER:attacker)''' 
Thrown when a character attacks a character or item with default attack

'''OnCharacterStartAttackPosition(FLOAT3:position, CHARACTER:attackerOwner, CHARACTER:attacker)''' 
Thrown when a character attacks a position with default attack

== INTERRUPTS ==

'''OnMovementFailed(FLOAT3:targetPos)''' 
Thrown when the reaction is interrupted by a move action failing

'''OnException(-)''' 
Thrown when the reaction is interrupted by an exception

'''OnBetterReactionFound(FIXEDSTRING:reactionName)''' 
Thrown when the reaction is interrupted by another reaction

'''OnNoReactionFound(-)''' 
Thrown when the reaction is interrupted because no reaction is valid

'''OnScriptDisabled(-)''' 
Thrown when the reaction is interrupted because the scriptcontroller is disabled

'''OnManualInterrupt(FIXEDSTRING:reactionName)''' 
Thrown when the reaction is interrupted using the interrupt action

'''OnRegionSwap(FIXEDSTRING:oldLevel, FIXEDSTRING:newLevel)''' 
Thrown when the reaction is interrupted by a region swap

= Divinity: Original Sin 2 Definitive Edition =
The following was added/changed for the Definitive Edition.

== CALLS ==
'''ItemDrop(ITEM:item)''' 
Drops an item from it's owner's inventory. Only characters are treated as owners.

'''RemoveSurfaceLayerAt(GAMEOBJECT|FLOAT3:target, INT:layer, FLOAT:radius)''' 
Removes surface (ground or cloud) at object/position. (Layer 0 for surface, otherwise - cloud) (Radius for cleanup)

'''SurfaceCreateLink(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 
Makes surfaces at 2 locations/positions interact as if they were adjacent.

'''SurfaceRemoveLink(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 
Stops surfaces at 2 distinctive locations/positions from interacting.

== QUERIES ==
'''AttributeGetDifficultyLevelMappedValue(FIXEDSTRING:difficulty, INT:level, OUT INT:levelMappedValue)''' 
Returns a level-mapped value of a primary attribute. (Difficulty = "Easy", "Normal" or "Hard")

'''CharacterGetCreationClass(CHARACTER:character, OUT FIXEDSTRING: class)''' 
During character creation returns character class. Fails outside of character creation.

'''CharacterGetEquippedItem(CHARACTER:character, FIXEDSTRING:slot, OUT ITEM:seatingItem)''' 
Returns item equipped into slot. (Slot = "Helmet", "Breast", "Leggings", "Weapon", "Shield", "Ring", "Ring2", "Belt", "Boots", "Gloves", "Amulet" or "Wings")

(CHANGED) '''CharacterInCreation(CHARACTER:character, OUT INT:CharacterIndex)''' 
Checks if character is in character creation currently. (CharacterIndex: assigned index of the player character during character creation)

Character and Item Script Triggers, Calls, and Queries

2019-10-17T21:11:10Z

LaughingLeader: Updated CharacterPlayAnimation with a missing parameter

This is a list of almost every character and item script event trigger, call, and query. An event is what triggers the script, and always begin with ''On''. Queries provide information and are always inside an ''IF'' or ''CHECK.'' Calls are actions that are always after THEN.

CharScript/ItemScript Functions

= Divinity: Original Sin 2 Classic=
== CALLS ==

'''Set(OUT OBJECT:variable, OBJECT:value)'''

Set the value of a variable

'''SetVar(CHARACTER|ITEM:object, FIXEDSTRING:variableName, OBJECT:value)'''

Set the value of a global variable

'''Cast(OUT OBJECT variable, OBJECT value)'''

Casts the value to the variable

'''Print(OUT STRING:output, STRING:text)'''

Prints the text to the output with possible parameters: [1], [2], ...

'''Add(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT|FLOAT3:value)'''

Adds both values and stores it in the first variable

'''Subtract(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT|FLOAT3:value)'''

Subtracts both values and stores it in the first variable

'''Multiply(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT:value)'''

Multiplies both values and stores it in the first variable

'''Divide(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT:value)'''

Divides both values and stores it in the first variable

'''Abs(INOUT INT|FLOAT:variable)'''

Takes the absolute value of a variable

'''Clamp(INOUT INT|FLOAT:variable, INT|FLOAT:min, INT|FLOAT:max)'''

Clamps a variable between min and max

'''GetRandom(OUT OBJECT:variable, OBJECT:value, OBJECT:value, OBJECT:value)'''

Fills in the variable with random one of the values.

'''GetWeightedRandom(OUT OBJECT:variable, OBJECT:value, INT|FLOAT:weight, ...)'''

Gets a weighted random of the given values!

'''GetRandomBetween(OUT INT|FLOAT:variable, INT|FLOAT:min, INT|FLOAT:max)'''

Gets a random value between min and max (both included)

'''GetRandomPositionInTrigger(OUT FLOAT3:variable, TRIGGER:areaTrigger)'''

Get a random position in a trigger area

'''GetElement(OUT OBJECT:variable, INT:index, OBJECT:value, OBJECT:value, OBJECT:value)'''

Fills in the variable with the index one of the values (starting from 0)

'''SetPriority(FIXEDSTRING:reactionName, INT:priority)'''

Changes the priority of a reaction. Priority 0 and below are not executed!

'''DelayReaction(FIXEDSTRING:reactionName, FLOAT:timeInSeconds)'''

The reaction will not be chosen for the specified time

'''SetScriptFrame(CHARACTER:character, FIXEDSTRING:frame)'''

Sets the scriptframe on the character.

'''ClearScriptFrame(CHARACTER:character)'''

Clears the scriptframe on the character.

'''Goto(FIXEDSTRING:labelName)'''

Jumps to the label. Two label names are built-in: "Start" for the first instruction of the reaction, and "End" for the last one.

'''GotoIfEqual(OBJECT:variable, OBJECT:value, FIXEDSTRING:labelName)'''

Jumps to the label if the 2 objects are equal

'''GotoRand(FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName)'''

Jumps to a random label in the list

'''CreatePuddleAt(GAMEOBJECT|FLOAT3:target, SURFACE:type, INT:cellAmountMin, INT:cellAmountMax, INT:growAmountMin, INT:growAmountMax, )'''

Spawn a puddle at the target's position for a certain lifetime (in turns)

'''CreateSurfaceAt(GAMEOBJECT|FLOAT3:target, SURFACE:type, FLOAT:radius, INT:lifeTime[, GAMEOBJECT:owner])'''

Spawn a surface at the target's position for a certain lifetime (in turns)

'''CreateSurfaceInPolygon(GAMEOBJECT:owner, SURFACE:type, FLOAT:duration, FLOAT:growTimer, INT:growStep, GAMEOBJECT|FLOAT3:point1, GAMEOBJECT|FLOAT3:point2, GAMEOBJECT|FLOAT3:point3, ...)'''

Spawn a polygon surface at the target's position. Grows <growStep> every <growTimer>.

'''CreateSurfaceInAreaTrigger(GAMEOBJECT:owner, SURFACE:type, FLOAT:duration, FLOAT:growTimer, INT:growStep, TRIGGER:areaTrigger)'''

Spawn a surface within <areaTrigger>. Grows <growStep> every <growTimer>.

'''CreateConeSurfaceAt(GAMEOBJECT|FLOAT3:start, GAMEOBJECT|FLOAT3:target, SURFACE:type, FLOAT:radius, FLOAT:angle, FLOAT:duration)'''

Spawn a Cone surface at the target's position

'''PlayEffectAt(GAMEOBJECT|FLOAT3:target, STRING:effectName)'''

Plays an effect at the target's position

'''PlayLoopEffectAt(OUT INT64:effectHandle, GAMEOBJECT|FLOAT3:target, STRING:effectName)'''

Plays an effect at the target's position

'''ExplodeAt(GAMEOBJECT|FLOAT3:target, SKILL:projectileSkill, [INT:casterLevel=-1, CHARACTER|ITEM:cause])'''

Trigger an explosion of a projectile skill at the target's position. The cause will trigger NPC behavior as if the cause casted the projectile

'''DisplayText(CHARACTER|ITEM:target, FIXEDSTRING:text, FLOAT:timeInSeconds)'''

Displays text above the character/item for a certain amount of time. It will replace the current text, including dialogtext

'''DisplayCombatInfoText(CHARACTER|ITEM:target, FIXEDSTRING:text, FLOAT:timeInSeconds)'''

Displays text above the character/item for a certain amount of time. It will replace the current text, including dialogtext

'''StatusText(CHARACTER|ITEM:target, FIXEDSTRING:text)'''

Adds statustext above the character/item for a short amount of time. Will not replace texts or dialogtexts

'''DebugText(CHARACTER|ITEM:target, STRING:text)'''

Adds debugtext above the character/item for a short amount of time.

'''CombatLogText(CHARACTER|ITEM:target, FIXEDSTRING:text, INT:filterID, INT:broadcastID)'''

Adds combatlog text inside the combat log window. Color-/SizeFormatting should already be applied, if not color and size of the string will be NORMAL. filterID determines what filter shows/hides the text. broadcastID determines who will be able to see the message (0 hearingrange. 1 party. 2 all)

'''Log(STRING:text, ...)'''

Log's the the scriptlog. (for debugging purposes)

'''Output(STRING:text, ...)'''

Pass text with optional parameters to the output panel (e.g. Output("An int [1]", INT:10))

'''Assert(STRING:text, ...)'''

Pass text with optional parameters to display as an assert message (e.g. Assert("This number is wrong: [1]", INT:666))

'''Label(FIXEDSTRING:name)'''

Marks this line as a label where Goto actions can jump to

'''StartTimer(FIXEDSTRING:timerName, FLOAT:timeInSeconds, INT:repeatCount)'''

Start a timer which will throw the timer event. Set repeatcount < 0 for a permanent timer.

'''StopTimer(FIXEDSTRING:timerName)'''

Stop a timer which will throw the timer event

'''DialogStart(OUT INT:instanceId, STRING:dialog, CHARACTER|ITEM:target, CHARACTER|ITEM:target, CHARACTER|ITEM:target, CHARACTER|ITEM:target)'''

Start a dialog between the targets. You can specify fewer targets than the maximum number.

{{warning|Starting a dialog from behaviour script will always start it as an [[Dialog_editor#Automated|Automated Dialog]]. Interactive dialogs can only be started from [[Osiris]].}}

'''DialogRequestStop(CHARACTER|ITEM:speaker, STRING:dialog)'''

Stops a certain dialog on a certain speaker

'''Check(-)'''

Reevaluate the conditions in the CHECK section of this reaction

'''Reset(-)'''

Resets the current reaction. It will start from the beginning again

'''Interrupt(FIXEDSTRING:reactionName)'''

Interrupt the reaction.

'''GlobalSetEvent(FIXEDSTRING:eventName)'''

Sets a global event. Scripts and Story can catch it.

'''GlobalClearEvent(FIXEDSTRING:eventName)'''

Clears a global event. Scripts and Story can catch it.

'''StopLoopEffect(INT64:fxHandle)'''

Stops a looping effect

'''IterateItems(FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item. If you pass a tag, it has to have that tag.

'''IterateItemsNear(GAMEOBJECT:source, FLOAT:radius, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item in range. If you pass a tag, it has to have that tag.

'''IterateItemsOnObject(CHARACTER|ITEM:source, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item standing on the source. If you pass a tag, it has to have that tag.

'''IterateParty(FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, CHARACTER:partyMember, FIXEDSTRING:tag])'''

Launch iterate event for each member of all parties. If you pass a party member only members of that party will be considered. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharacters(FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersNear(GAMEOBJECT:source, FLOAT:radius, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character in range. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersOnObject(CHARACTER|ITEM:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''
Launch iterate event for each character standing on the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersInCombat(CHARACTER|ITEM:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character in combat with the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateHostilesFor(CHARACTER:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character who is targetting the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''SpawnCharacter(OUT CHARACTER:result, CHARACTERTEMPLATE:rootTemplate, GAMEOBJECT|FLOAT3:position, INT:playSpawn, [INT:isSummon=0, CHARACTER:summonOwner=null, INT:overrideLevel=-1])'''

Spawns a character

'''SpawnItem(ITEMTEMPLATE:rootTemplate,GAMEOBJECT|FLOAT3:position, OUT ITEM:result)'''

Spawns an item

'''ShootLocalProjectile(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,FLOAT3:direction,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Spawns a projectile at the source (with offset, can be null) shooting at the target

'''ShootLocalProjectileAt(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,GAMEOBJECT|FLOAT3:target,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Spawns a projectile at the source (with offset, can be null) shooting at the target

'''ShootWorldProjectile(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,FLOAT3:direction,[INT:casterLevel])'''

Spawns a projectile at worldPos shooting at the target. Source can be null.

'''ShootWorldProjectileAt(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,GAMEOBJECT|FLOAT3:target,[INT:casterLevel])'''

Spawns a projectile at worldPos shooting at the target. Source can be null.

'''ShootLocalCone(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,FLOAT3:direction,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Shoots a cone from source (with offset, can be null) in a direction

'''ShootLocalConeAt(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,GAMEOBJECT|FLOAT3:target,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Shoots a cone from source (with offset, can be null) at the target

'''ShootWorldCone(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,FLOAT3:direction,[INT:casterLevel])'''

Shoots a cone from worldPos in a direction. Source can be null.

'''ShootWorldConeAt(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,GAMEOBJECT|FLOAT3:target,[INT:casterLevel])'''

Shoots a cone from worldPos at the target. Source can be null.

'''SetVisible(CHARACTER|ITEM:object, INT:visible)'''

Sets a character or item visible or not.

'''RotateY(INOUT FLOAT3:vector, FLOAT:degrees)'''

Rotate the vector around the Y-axis for a certain angle (in degrees)

'''SetHealth(CHARACTER|ITEM:target, FLOAT:percent)'''

Set a characters or items health on the given percentage. (percentage between 0 and 1)

'''PlaySound(CHARACTER|ITEM:target, STRING:soundEvent)'''

Plays a sound event at the target

'''PlayMusicForEveryone(STRING:musicEvent)'''

Plays a music event on all the clients

'''PlayMusicOnCharacter(CHARACTER:target, STRING:musicEvent)'''

Plays a music event on a character for all peers (3D)

'''PlayMusicForPeer(CHARACTER:target, STRING:musicEvent)'''

Plays a music event on the peer of the character

'''PlayMusicForPeerWithInstrument(CHARACTER:target, CHARACTER:charInstrument, STRING:musicEvent)'''

Plays a music event on the peer of the character concated with _INSTRUMENT

'''SetX(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the X component of the FLOAT3

'''SetY(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the Y component of the FLOAT3

'''SetZ(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the Z component of the FLOAT3

'''SetAtmosphere(FIXEDSTRING:atmosphereTriggerUUID, FIXEDSTRING:atmosphere)'''

Changes the atmosphere of the trigger

'''ResetAtmosphere(FIXEDSTRING:atmosphereTriggerUUID)'''

Resets the atmosphere of the trigger

'''AddStatusInfluence(CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1], [INT:force=1])'''

Adds the status influence strength on the object.

'''RemoveStatusInfluence(CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1])'''

Removes the status influence strength on the object.

'''AddTemporaryStatusInfluence(CHARACTER|ITEM:source, CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1])'''

Adds a temporary status influence strength on the object.. It will be gone in a few seconds if it's not set again

'''CallFunction(FIXEDSTRING:functionName)'''

Calls a function with the ID

'''SetMaterial(CHARACTER|ITEM:object, FIXEDSTRING:materialUUID, INT:duration, INT:applyOnBody, INT:applyOnArmor, INT:applyOnWings, INT:applyOnHorns, INT:applyOnOverhead, INT:applyOnWeapon[,INT:applyNormalMap, INT:overlay, INT:fading])'''

Changes the material of the object for a set time (in turns), -1 is infinite. applyNormalMap: Copy the original materials normal map

'''TeleportTo(CHARACTER|ITEM:object, GAMEOBJECT|FLOAT3:target, [INT:Force=0])'''

Teleport object to or near the target

'''Transform(CHARACTER|ITEM:object, CHARACTERTEMPLATE|ITEMTEMPLATE:root [, FIXEDSTRING:fx, INT:replaceScripts=1, OUT FLOAT:currentHP])'''

Transforms <object> using <root>, returns <currentHP>, plays <fx>.

'''SaveGame(FIXEDSTRING:saveGameName)'''

Save the savegame with name <saveGameName>

'''LoadGame(FIXEDSTRING:saveGameName)'''

Load the savegame with name <saveGameName>

'''LoadLevel(FIXEDSTRING:levelName)'''

Load the level with name <levelName>

'''KillCombat(CHARACTER:character)'''

Kill all the enemies in the combat which contains <character>

'''SetTag(CHARACTER|ITEM:object, FIXEDSTRING:tag)'''

Sets the Tag on the Object

'''ClearTag(CHARACTER|ITEM:object, FIXEDSTRING:tag)'''

Clears the Tag on the Object

'''SetGlobalFlag(FIXEDSTRING:flagname)'''

Sets the Global Flag

'''ClearGlobalFlag(FIXEDSTRING:flagname)'''

Clears the Global Flag

'''SetFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Sets the Flag on the Object

'''ClearFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the Object

'''SetUserFlag(CHARACTER:object, FIXEDSTRING:flagname)'''

Sets the Flag on the user's characters

'''ClearUserFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the user's characters

'''SetPartyFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Sets the Flag on the party's characters

'''ClearPartyFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the party's characters

'''StartVoiceBark(STRING:barkName, CHARACTER:character)'''

Start a voicebark on character

'''ConfrontationDone(INT: CrimeID, CHARACTER:lead, CHARACTER:criminal, ...)'''

Resolve the crime with id CrimeID for the specified criminals

'''CrimesceneInvestigationDone(CHARACTER:investigator)'''

Crimescene is considered investigated by this NPC, start looking for culprits

'''ListAdd(LIST<OBJECT>:list, OBJECT:entry)'''

Add <entry> at the back of <list>

'''ListRemove(LIST<OBJECT>:list, INT:index)'''

Remove the entry at <index> of <list>

'''ListSet(LIST<OBJECT>:list, INT:index, OBJECT:entry)'''

Set the entry at <index> of <list> to <entry>

'''ListClear(LIST<OBJECT>:list)'''

Remove all entries of <list>

'''EndTurn(CHARACTER|ITEM:Target)'''

Ends the object's current turn

'''SetCanFight(CHARACTER|ITEM:entity, INT:enabled[, INT:wholeGroup=0])'''

Enables/Disables the fact if the entity can fight. Optional for the whole group

'''SetCanJoinCombat(CHARACTER|ITEM:entity, INT:enabled[, INT:wholeGroup=0])'''

Enables/Disables the fact if the entity can join combats. Optional for the whole group

'''SetIsBoss(CHARACTER|ITEM:entity, INT:enabled)'''

Enables/Disables the fact if the entity is a boss.

'''GetAIHintTriggers(OUT LIST<TRIGGER>:triggers[, [LIST]FIXEDSTRING:tags, INT:needsAllTags = -1)'''

Returns all AIHintAreaTriggers in <triggers>. Uses contraints if set.

'''SetCombatTimeout(CHARACTER|ITEM:entity, FLOAT:timer)'''

Overwrites the entity's combat timeout check.

'''ResetCombatTimeout(CHARACTER|ITEM:entity)'''

Resets the entity's combat timeout check.

'''EnterCombat(CHARACTER|ITEM:source, CHARACTER|ITEM:target)'''

Enters combat with target

'''LeaveCombat(CHARACTER|ITEM:source)'''

Leaves the combat

'''SetFaction(CHARACTER|ITEM:target, FIXEDSTRING:faction)'''

Changes the faction of a character or item

'''SetInvulnerable(CHARACTER|ITEM:target, INT:bool)'''

Makes the character or item invulnerable or not. (Allow damage)

'''JumpToTurn(CHARACTER|ITEM:Target)'''

Jumps to targets turn (ends the current turn)

'''Sleep(FLOAT:timeInSeconds)'''

Sleeps for a certain amount of time

'''CharacterAttack(CHARACTER|ITEM|FLOAT3:target [,INT:alwaysHit])'''

Moves in weapon range and attacks the target

'''CharacterAttackWithoutMove(CHARACTER|ITEM|FLOAT3:target [,INT:alwaysHit])'''

Attacks the target without checking weaponranges and without moving

'''CharacterMoveTo(GAMEOBJECT|FLOAT3:target, [INT:running=0, INT:shouldArrive=0, INT:longPath=0, FLOAT:minDistance=1.5, FLOAT:maxDistance=minDistance+2.5])'''

Move to the target. Set shouldArrive to 1 if you want a guaranteed move. (teleports on fail)

'''CharacterAiMove(FLOAT3:target, CHARACTER:targetCharacter, ITEM:targetItem)'''

Moves to the target, calculated by the AI. Should only be used with results from the AI!

'''CharacterMoveInRange(GAMEOBJECT|FLOAT3:target, FLOAT:rangeMin, FLOAT:rangeMax, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within a certain range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveInWeaponRange(GAMEOBJECT|FLOAT3:target, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within weapon range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveInSkillRange(GAMEOBJECT|FLOAT3:target, SKILL:skill, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within skill range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveOutOfSight(FLOAT:angle)'''

Move out of screen

'''CharacterPlayAnimation(FIXEDSTRING:animation [, INT:exitOnFinish=1, INT:waitForCompletion=1], INT:noBlend=0])'''

Plays a certain animation
ExitOnFinish means if the exit will kill itself after it was played (revert back to still)
WaitForCompletion means if the action will wait for the animation to be played at least once.
noBlend means no blending will be performaed when doing this animation.

'''CharacterStopAnimation(-)'''

Stops all animations.

'''CharacterPickUpItem(ITEM:item)'''

Moves close enough to the item if necessary and picks it up

'''CharacterUseItem(ITEM:item [, INTEGER:LongPath])'''

Moves close enough to the item if necessary and uses it

'''CharacterMoveItem(ITEM:item, INTEGER:ignoreWeight, INTEGER:ignoreAPCost [, INTEGER:ignoreDangerousSurfaces=1, INT:amount=-1, GAMEOBJECT|FLOAT3:destination])'''

Moves close enough to the item if necessary and moves it to the destination. Will try to find a destination if not supplied.

'''CharacterAddSkill(CHARACTER:character, SKILL:skill[, INT:ShowNotification=0])'''

Adds <skill> to <character>

'''CharacterRemoveSkill(CHARACTER:character, SKILL:skill)'''

Removes <skill> from <character>

'''CharacterUseSkill(SKILL:skill, GAMEOBJECT|FLOAT3:target [, GAMEOBJECT|FLOAT3:target2, ITEM:skillItem, INT:ignoreHasSkill=0])'''

Cast a skill

'''CharacterAppearAt(GAMEOBJECT|FLOAT3:target, INT:playspawn)'''

Appear at the target

'''CharacterAppearOutOfSightTo(GAMEOBJECT:target, FLOAT:angle, INT:playspawn)'''

Appears out of sight to the players from a certain angle while being able to reach target

'''CharacterAppearOnTrailOutOfSightTo(CHARACTER:target, FLOAT:angle, INT:playspawn)'''

Appears out of sight to the players, on its previous locations, from a certain angle while being able to reach target

'''CharacterDisappear(FLOAT:angle[, INTEGER:isRunning=0])'''

Move out of screen and go of stage, will run if <isRunning> is not 0

'''CharacterSetOffStage(-)'''

Set Off Stage

'''CharacterSetOnStage(-)'''

Set On Stage

'''CharacterLookAt(GAMEOBJECT|FLOAT3|SPLINE:target[, INT:snapToTarget=0, INT:angleTolerance=0])'''

Rotates the character to look at the target (Closest spline point in case of a spline).

'''CharacterLookFrom(GAMEOBJECT|SPLINE:target[, INT:snapToTarget=0])'''

Rotates to the character so it has the same rotation as the target (Closest spline point in case of a spline).

'''CharacterFollow(CHARACTER:target, FLOAT:durationInSeconds, INT:run)'''

Follow the target for a certain time

'''CharacterFollowOwnerOrLeader(FLOAT:durationInSeconds, INT:run)'''

Follow the leader or owner for a certain time

'''CharacterWander(FLOAT|TRIGGER:range, FLOAT:durationInSeconds [, INT:run, GAMEOBJECT:anchor])'''

Wander around for a certain time

'''CharacterSwitchWeaponType(WEAPON:type)'''

If necessary switch to the new weapon type

'''CharacterFleeFrom(RELATION:relation, FLOAT:range)'''

Run away from certain characters if necessary
'''
CharacterFleeFromSurface(SURFACE:surface)'''

Run away from a certain surface if necessary

'''CharacterFleeFromDangerousSurface(-)'''

Run away from a dangerous surfaces if necessary

'''CharacterAddSourcePoints(CHARACTER:character, INT:amount)'''

Adds x source points (x can be negative to substract)

'''CharacterDie(CHARACTER:character[, DEATH:type=DoT])'''

Kills the character

'''CharacterHeal(CHARACTER:character, FLOAT:percentage)'''

Heals the character

'''CharacterConsume(CHARACTER:character, POTION:potion)'''

Makes the character consume a potion. Doesn't cost any AP and will just execute the result of the potion.

'''CharacterDisableAllCrimes(CHARACTER:target)'''

Disables all generic behaviours for <target>.

'''CharacterEnableAllCrimes(CHARACTER:target)'''

Enables all generic behaviours for <target>.
'''
CharacterEnableCrime(CHARACTER:target, STRING:crime, ...)'''

Enables the specified generic behaviours for <target>.

'''CharacterDisableCrime(CHARACTER:target, STRING:crime, ...)'''

Disables the specified generic behaviours for <target>.

'''CharacterSetLongInvestigationDuration(CHARACTER:target)'''

Doubles the time it takes for the investigation to time out. Use this when the character needs to move a long path before investigating.

'''CharacterAiCalculate(-)'''

Calculate the AI of the character

'''CharacterAiStopCalculate(-)'''

Stop the calculation of the AI of the character

'''CharacterAiFinishMoveSkill(-)'''

Finish the current MoveSkill.
'''
CharacterAiAddInterestingItem(CHARACTER:character, ITEM:item)'''

Make it interesting for the AI to destroy that Item

'''CharacterAiRemoveInterestingItem(CHARACTER:character, ITEM:item)'''

Make it no longer interesting for the AI to destroy that Item

'''CharacterSetArchetype(CHARACTER:character, ARCHETYPE:archetype)'''

Sets the archetype of the character, used in AI calculations

'''CharacterSetStoryNPC(CHARACTER:character, INT:bool)'''

Makes the character storyNPC or not.
'''
CharacterAddActionPoints(CHARACTER:character, INT:amount)'''

Give character some action points

'''CharacterSetImmortal(CHARACTER:character, INT:bool)'''

Makes the character immortal or not. (Allow dying)

'''CharacterPlayEffect(CHARACTER:character, STRING:effect [,FIXEDSTRING:boneName])'''

Plays an effect on the character and it follows the character

'''CharacterPlayLoopEffect(OUT INT64:effectHandle, CHARACTER:character, STRING:effect [,FIXEDSTRING:boneName])'''

Plays a looping effect on the character and it follows the character

'''CharacterEvent(CHARACTER:character, STRING:eventName)'''

Throw a character event which you can catch in scripts and story

'''CharacterItemEvent(CHARACTER:character, ITEM:item, STRING:eventName)'''

Throw a character/item event which you can catch in scripts and story

'''CharacterCharacterEvent(CHARACTER:character1, CHARACTER:character2, STRING:eventName)'''

Throw a character/character event which you can catch in scripts and story

'''CharacterSetRelationIndivToIndiv(CHARACTER:source, CHARACTER:target, INT:relation)'''

Changes the relationship between 2 characters.
'''
CharacterForceUpdate(INT:forceUpdate)'''

Makes sure the attached character is always being update or not.
'''
CharacterSetEnemy(CHARACTER:character, CHARACTER:enemy)'''

Sets the current enemy of character

'''CharacterApplyStatus(CHARACTER:character, STATUS:statusId [, INT:turns=null, INT:force=0])'''

Applies the status to the character When turns is -1 it's a permanent status When turns is -2 it's a keep alive status (which means it will die if it's not applied again within 1 second)

'''CharacterRemoveStatus(CHARACTER:character, STATUS:statusId [, STATUS:reasonStatusID=null, INT:notify=1])'''

Removes the status from the character

'''CharacterDestroy(CHARACTER:character)'''

Destroys the character

'''CharacterSetCanSpotSneakers(CHARACTER:character, INT:enabled)'''

Enables/Disables the fact if the character can spot sneaking characters.

'''CharacterSetAttackOfOpportunity(CHARACTER:character, INT:enabled)'''

Enables/Disables the fact if the character can do attack of opportunities.

'''CharacterResurrect(CHARACTER:character [, INT:Percentage = 100])'''

Resurrects the character at [2]% health.

'''CharacterAddToInventory(CHARACTER:character, FIXEDSTRING:itemStatsObject[, INT:amount, INT:showInTrade=1])'''

Add the item to the character

'''CharacterRemoveFromInventory(CHARACTER:character, FIXEDSTRING:itemStatsObject[, INT:amount])'''

Remove the item from the character. If Amount is -1, then all are removed

'''CharacterDrinkPotion(FIXEDSTRING:statID)'''

Makes the character drink a potion from the inventory.

'''CharacterSetAnimationOverride(CHARACTER:character, FIXEDSTRING:animation)'''

Sets an animation override, only walk/run/die animations can override it.

'''CharacterUseActionPoints(CHARACTER:character, INT:amount [, OUT INT:succeeded])'''

Uses x action points

'''CharacterAddTreasureTable(CHARACTER:character, FIXEDSTRING:treasureTable)'''

Adds <treasureTable> to the treasure list of <character>

'''CharacterRemoveTreasureTable(CHARACTER:character, FIXEDSTRING:treasureTable)'''

Removes <treasureTable> from the treasure list of <character>

'''CharacterClearTreasureTables(CHARACTER:character)'''

Removes all treasure tables from <character>

'''CharacterSetTemporaryHostileRelation(CHARACTER:character, CHARACTER:otherCharacter)'''

Creates a temporary hostile relation between the 2 characters!

'''CharacterSetFightMode(CHARACTER:character, INT:fight [, INT:force=0])'''

Set the character in sheath/unsheated mode.

'''CharacterSetStats(CHARACTER:character, FIXEDSTRING:statsEntry [, INT:keepVitality=0, INT:keepAP=0, INT:keepLevel=0, OUT FLOAT:currentHP])'''

Applies <statsEntry> from character.xlsm to <character>, returns <currentHP>.

'''CharacterSetWalkSpeedOverride(CHARACTER:character, INTEGER:override [, FLOAT:walkSpeed])'''

Sets walk speed override of <character>, removes it if <override> is 0

'''CharacterSetRunSpeedOverride(CHARACTER:character, INTEGER:override [, FLOAT:runSpeed])'''

Sets run speed override of <character>, removes it if <override> is 0

'''CharacterSetHasDialog(CHARACTER:character, INTEGER:bool)'''

Enables/Disables the dialog of the character

'''CharacterInitPatrol(SPLINE:spline, INT:splineIndex, INT:reversed, INT:running)'''

Start patroling from the given index along the given spline with the given character.

'''CharacterStartPatrol(SPLINE:spline, INT:splineIndex, INT:reversed, INT:running)'''

Start patroling from the given index along the given spline with the given character.

'''CharacterStopPatrol(-)'''

Let the character stop patrolling whatever spline he's on!

'''CharacterInterruptPatrol(-)'''

Call when the patrol should interrupt so the guard stops moving to the next spline. If this is called when the character is deactivated, a caret will take his place.

'''CharacterSetAnimationSetOverride(CHARACTER:source, FIXEDSTRING:override)'''

Sets an animation set override for a character. Empty fixedstring clears the override.

'''CharacterSetFloating(CHARACTER:target, INTEGER:isFloating)'''

Sets <target> floating if <isFloating> is not 0

'''CharacterResetCooldowns(CHARACTER:target)'''

Resets the skill cooldowns for <target>

'''ItemEvent(ITEM:item, STRING:eventName)'''

Throw an item event which you can catch in scripts and story

'''ItemPlayAnimation(FIXEDSTRING:animation)'''

Plays an animation on the item

'''ItemPlayAnimationTo(FIXEDSTRING:animation, FLOAT:targetPercentage, [FLOAT:speed])'''

Plays an animation on the item to the target time (percentage of the total duration)

'''ItemPlayEffect(ITEM:item, STRING:effect [,FIXEDSTRING:boneName])'''

Plays an effect on the item and it follows the item

'''ItemPlayLoopEffect(OUT INT:effectHandle, ITEM:item, STRING:effect [,FIXEDSTRING:boneName])'''

Plays a looping effect on the item and it follows the item

'''ItemSetOnStage(ITEM:item, INTEGER:bool)'''

Sets an item on or offstage

'''ItemSetCanInteract(ITEM:item, INTEGER:bool)'''

Sets an item (not) interactible

'''ItemClose(ITEM:item)'''

Close an item

'''ItemOpen(ITEM:item)'''

Open an item

'''ItemDrop(ITEM:item)'''

Drop an item

'''ItemLock(ITEM:item, FIXEDSTRING:key)'''

Lock an item

'''ItemUnlock(ITEM:item)'''

Unlock an item

'''ItemApplyStatus(ITEM:item, STATUS:statusId [, INT:turns=null, INT:force=0])'''

Applies the status to the item When turns is -1 it's a permanent status When turns is -2 it's a keep alive status (which means it will die if it's not applied again within 1 second)

'''ItemRemoveStatus(ITEM:item, STATUS:statusId)'''

Removes the status from the item

'''ItemDie(ITEM:item)'''

Kills the item

'''ItemMoveTo(GAMEOBJECT|FLOAT3:target, FLOAT:velocity, FLOAT:acceleration, INTEGER:matchTargetRotation)'''

Moves the item to the target

'''ItemToInventory(ITEM:item, CHARACTER|ITEM:target [,INT:amount=-1])'''

Moves the item to the target's inventory

'''ItemLookAt(GAMEOBJECT:target, FLOAT:degreesPerSecond)'''

Rotates the item to look at the target

'''ItemDestroy(ITEM:item)'''

Destroys the item

'''ItemSetAmount(ITEM:item, INT:amount)'''

Change the amount of the item

'''IterateItemsInInventory(CHARACTER|ITEM:source, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each iten in source's inventory. If you pass a tag, it has to have that tag.

'''ItemAddCharges(ITEM:TargetItem, INT:charges)'''

Add/subtract charges from an item

'''ItemResetChargesToInitial(ITEM:TargetItem)'''

Resets charges from item to initial state

'''MakePeace(CHARACTER:Source, CHARACTER:Target[, INT:IgnoreVote = 1])'''

Make peace between users of the characters

'''MakeWar(CHARACTER:Source, CHARACTER:Target[, INT:IgnoreVote = 1])'''

Make war between users of the characters

'''FindSurface(OUT FLOAT3:result, GAMEOBJECT|FLOAT3:source, FLOAT:minRange, FLOAT:maxRange, SURFACE:type [,CHARACTER:alignSource, INT:minEnemiesInSurface, INT:maxAlliesInSurface, INT:minimumCellCount])'''

Finds the closest surface of a specific type.

'''FindValidPosition(INOUT FLOAT3:position, FLOAT:radius[, CHARACTER|ITEM:object=null])'''

Finds the closest valid position (where the object can stand.)

'''FindPosition(INOUT FLOAT3:position, CHARACTER:source, INT:canStand, INT:checkSight, FLOAT:minRadius, FLOAT:maxRadius, FLOAT:rangeCheck, CHARACTER:alignSource, INT:minAllies, INT:maxAllies, INT:minEnemies, INT:maxEnemies [,FIXEDSTRING:AiHintTag=null, INT:forceHint=0, FLOAT3:SourcePosition])'''

Finds the closest position from the source (within radius) where the conditions are matched.

'''Cast(OUT OBJECT variable, OBJECT value)'''

Casts the value to the variable.

'''StringConcatenate(STRING:stringA, STRING:stringB, OUT STRING:resultingString)'''

Appends stringB to stringA. Resulting string is stored in the third parameter.

== QUERIES ==

'''GetPosition(GAMEOBJECT:object,OUT FLOAT3:src)''' 

Get the current position of an object

'''GetForwardDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current forward direction of an object

'''GetRightDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current right direction of an object

'''GetUpDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current up direction of an object

'''GetDirection(GAMEOBJECT|FLOAT3:src,GAMEOBJECT|FLOAT3:target,OUT FLOAT3:direction[, OUT FLOAT:distance])''' 

Get the direction from src to target (optional: returns the distance between the objects as well)

'''GetRotation(GAMEOBJECT:object, OUT FLOAT3:vector)''' 

Get the rotation of an object

'''CharacterGetTargetSpline(INT: SplineIndex)''' 

Returns the spline index the character is currently walking towards, or -1 if he is not active on a spline.

'''IsEqual(OBJECT:variable, OBJECT:variable)''' 

Compares both objects and see if they are equal.

'''IsLessThen(INT|FLOAT:variable, INT|FLOAT:variable)''' 

Compares both objects and see if the first one is smaller.

'''IsGreaterThen(INT|FLOAT:variable, INT|FLOAT:variable)''' 

Compares both objects and see if the first one is bigger.

'''IsRandom(FLOAT:percentage)''' 

Each time this condition is checked, it will succeed with a chance of the percentage (between 0 and 1)

'''IsRound(INT:roundNumber)''' 

Checks if we are currently in combat in round x

'''IsInSurface(OBJECT|FLOAT3:target, SURFACE:type[, FLOAT:radius])''' 

Check if the character, item, trigger or position is currently within the specific surface.

'''IsInDangerousSurface(OBJECT|FLOAT3:target[, CHARACTER:character, FLOAT:radius])''' 

Check if <target> is currently in on a dangerous surface. Uses <character> for path influences if provided (is necessary with non-character targets)

'''IsInDialog(CHARACTER|ITEM:target[, INT:ignoreAutomatedDialogs=0])''' 

Check if the character or item is currently in a dialog, optionally ignoring automated dialogs

'''IsInAutomatedDialog(CHARACTER|ITEM:target)''' 

Check if the character or item is currently in an automated dialog

'''GetDistance(OUT FLOAT:distance, GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 

Returns the distance between 2 positions

'''GetDistance2D(OUT FLOAT:distance, GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 

Returns the 2D distance between 2 positions (ignores height)

'''GetInnerDistance(OUT FLOAT:distance, GAMEOBJECT:source, GAMEOBJECT:target)''' 

Returns the distance between 2 gameobjects (character, item, trigger, ...) Their bounds are already subtracted.

'''GetPosition(GAMEOBJECT:object, OUT FLOAT3:position)''' 

Returns the position of a gameobject (character, item, trigger, ...)

'''GetVar(OUT OBJECT:returnValue, CHARACTER|ITEM:target, FIXEDSTRING:varName)''' 

Gets a global variable from the target

'''GetClosestPlayer(OUT CHARACTER:player, GAMEOBJECT|FLOAT3:source)''' 

Gets the closest player near the source, default being being the object itself

'''GetPlayerCount(OUT INT:playerCount)''' 

Gets the number of players in the party

'''GetPlayerByIndex(OUT CHARACTER:returnCharacter, INT:playerIndex)''' 

Gets a player from the party by index

'''GetRandomCharacter(OUT CHARACTER:returnCharacter, [INT:canBeSelf=0, INT:canBePlayer=0])''' 

Gets a random character in the current level

'''ContainsSurface(GAMEOBJECT|FLOAT3:source, FLOAT:radius, SURFACE:type,)''' 

Checks if there is any surface of the type within a radius of the source

'''IsSurface(GAMEOBJECT|FLOAT3:source, FLOAT:radius, SURFACE:type)''' 

Checks if the whole radius around the source is the specified surface type

'''IsObjectOnObject(CHARACTER|ITEM:source,CHARACTER|ITEM:target)''' 

Checks if the source is standing on the target

'''GetX(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the X component of the vector

'''GetY(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the Y component of the vector

'''GetZ(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the Z component of the vector

'''CanSee(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target[, INT:addProjectileTargetGroundOffset=0])''' 

Check if the sight is blocked between 2 points.

'''IsVisible(CHARACTER|ITEM:object)''' 

Check if the object is set invisible or not with SetVisible.

'''GetTextDuration(CHARACTER|ITEM:object, FIXEDSRTING:key, OUT FLOAT:duration)''' 

Gets how long a text needs to be displayed

'''IsCasual(-)''' 

Returns if the current game mode is Casual

'''IsHardcore(-)''' 

Returns if the current game mode is Hardcore

'''IsTagged(GAMEOBJECT:object, FIXEDSTRING:tag)''' 

Check if the object is tagged.

'''TranslatedStringKeyExists(FIXEDSTRING:key)''' 

Check if the TranslatedString key exists.

'''IsInCombat(CHARACTER|ITEM:object)''' 

Returns true if the object is in combat.

'''IsInCombatWith(CHARACTER|ITEM:object, CHARACTER|ITEM:object)''' 

Returns true if the objects are in combat with each other.

'''IsFacing(GAMEOBJECT:source, GAMEOBJECT|FLOAT3:target, [INT:angle=90])''' 

Returns true if the object is facing the position within the given angle.

'''GameIsSaving(-)''' 

Returns true if the game is saving.

'''GameIsLoading(-)''' 

Returns true if the game is loading.

'''GetUserCount(OUT INT:userCount)''' 

Returns the user count.

'''GetCurrentCharacter(OUT CHARACTER:character, INT:user)''' 

Returns the character currently being controlled by the specified user.

'''GetCurrentLevel(OUT FIXEDSTRING:currentLevel)''' 

Returns the current levelname

'''GetAIBounds(CHARACTER|ITEM:source, OUT FLOAT:bounds)''' 

Returns AI bounds of <source> in <bounds>

'''HasGlobalFlag(FIXEDSTRING:flagName)''' 

Returns if the Global Flag is set

'''HasFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the Object

'''HasUserFlag(CHARACTER:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the user's characters

'''HasPartyFlag(CHARACTER:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the party's characters

'''DialogExists(STRING:dialogue)''' 

Returns true if the dialogue exists.

'''IsActive(CHARACTER|ITEM:Object)''' 

Returns if the character or item is currently active.

'''ListGetSize(LIST<OBJECT>:list, out INT:size)''' 

Returns the number of elements in <list>

'''ListGet(LIST<OBJECT>:list, INT:index, out OBJECT:entry)''' 

Returns <entry> at <index> of <list>

'''ListGetRandom(LIST<OBJECT>:list, out OBJECT:entry)''' 

Returns a random <entry> of <list>

'''IsBoss(CHARACTER|ITEM:Object)''' 

Returns true if the entity is tagged as a boss

'''IsProjectileSkill(SKILL:skill)''' 

Returns true if the skill is a ranged skill (uses a projectile)

'''IsValidSkillTarget(CHARACTER:source, OBJECT|FLOAT3:target, SKILLID:skill[, INTEGER:ignoreRangeCheck=0])''' 

Checks whether <target> is a valid target for <skill> at <source>

'''GetFaction(OUT FIXEDSTRING:faction, CHARACTER|ITEM:character)''' 

Returns the faction of the provided character or item

'''IsInActiveTurn(CHARACTER|ITEM:target)''' 

Returns true if it's the character's or item's turn in combat.

'''IsSkillActive(CHARACTER:character, SKILL:skillId)''' 

Returns true if <character> has <skillId> active (in memory).

'''HasSkillAi(SKILLID:skillId)''' 

Returns true if the skill is using the new Ai system

'''IsInArena(CHARACTER::character)''' 

Returns true if the character is in an arena fight

'''CrimeGetType(INTEGER:crimeId, OUT STRING:crimeType)''' 

Returns the type of the crime with this id.

'''CrimeGetCriminals(INTEGER:crimeId, OUT CHARACTER:criminal1, OUT CHARACTER:criminal2, OUT CHARACTER:criminal3, OUT CHARACTER:criminal4)''' 

Returns the criminals of that crime. They might all be null.

'''IsSourceSkill(SKILL:skill)''' 

Returns true if the skill is a source skill.

'''IsInGameMasterMode(-)''' 

Returns true if the game in game master mode.

'''CharacterGet(OUT CHARACTER:character, GAMEOBJECT|FLOAT3:src, FLOAT:range, COMPARE:howTo, COMPAREFUNC:compareFunc[, RELATION: relation, SURFACE:surface, STATUS:status, TALENT:talent, CHARACTER:inSightOf, FIXEDSTRING:tag])''' 

Get a character within a certain range conforming to the filled in restraints.

'''CharacterCount(OUT INT:count, GAMEOBJECT|FLOAT3:src, FLOAT:range, [RELATION: relation, SURFACE:surface, STATUS:status, TALENT:talent, CHARACTER:inSightOf])''' 

Counts the characters within a certain range conforming to the filled in restraints.

'''CharacterGetOwner(OUT CHARACTER:owner, CHARACTER:source)''' 

Get the character's owner

'''CharacterGetFollow(OUT CHARACTER:to follow, CHARACTER:source)''' 

Get the character to follow

'''CharacterGetEnemy(OUT CHARACTER:current enemy, CHARACTER:source)''' 

Get current enemy of character

'''CharacterCanCast(CHARACTER:source, SKILL:skillId, [ITEM:skillItem=null, INT:ignoreActionPoints=0])''' 

Check if the character source can cast the skill: will check cooldown, actionpoints

'''CharacterCanSitOnItem(CHARACTER:source, ITEM:item)''' 

Check if the character source can sit or lie on an item.

'''CharacterCanDrinkPotion(CHARACTER:source, FIXEDSTRING:potionID[, INT:ignoreActionPoints=0])''' 

Check if the character source can drink the potion: will check inv and actionpoints

'''CharacterCanUseItem(CHARACTER:source, ITEM:item[, INT:ignoreActionPoints=0])''' 

Check if the character source can use the item in the world

'''CharacterCanUseItemInInventory(CHARACTER:source, ITEM:item[, INT:ignoreActionPoints=0])''' 

Check if the character source can use the item in his inventory

'''CharacterCanSee(CHARACTER:watchingChar, CHARACTER|ITEM:target [, INT:forceUpdate=0])''' 

Check if character has target in his line of sight.

'''CharacterCanShoot(CHARACTER:source, GAMEOBJECT|FLOAT3:target)''' 

Check if the character can shoot the target.

'''CharacterIsPlayer(CHARACTER:character)''' 

Check if the character is a player

'''CharacterIsInParty(CHARACTER:character)''' 

Check if the character is in the party

'''CharacterIsEnemy(CHARACTER:source, CHARACTER:target)''' 

Check if target is enemy of source

'''CharacterIsAlly(CHARACTER:source, CHARACTER:target)''' 

Check if target is ally of source

'''CharacterIsNeutral(CHARACTER:source, CHARACTER:target)''' 

Check if target is neutral of source

'''CharacterIsDead(CHARACTER:character)''' 

Check if character is dead

'''CharacterIsMoving(CHARACTER:character)''' 

Check if character is moving (speed > 0)

'''CharacterIsSummon(CHARACTER:character)''' 

Check if character is a summon

'''CharacterIsPartyFollower(CHARACTER:character)''' 

Check if character is a party follower

'''CharacterIsStoryNPC(CHARACTER:character)''' 

Check if character is a story NPC

'''CharacterInWeaponRange(CHARACTER:character, CHARACTER:target)''' 

Check if target is in the current's weapon range

'''CharacterInTouchRange(CHARACTER:character, CHARACTER:targetChar)''' 

Check if target is in the character's touch range

'''CharacterHasStatus(CHARACTER:character, STATUS:statusId[, FIXEDSTRING:extraData])''' 

Check if character currently has the status. ExtraData can be filled in for some statuses: - Consume: statsid of the item - Shield: skillid of the shield

'''CharacterGetStatusSourceCharacter(CHARACTER:character, STATUS:statusId, OUT CHARACTER:source[, FIXEDSTRING:extraData])''' 

Get the source character of a status

'''CharacterGetStatusSourceItem(CHARACTER:character, STATUS:statusId, OUT ITEM:source[, FIXEDSTRING:extraData])''' 

Get the source item of a status

'''CharacterHasTalent(CHARACTER:character, TALENT:talent)''' 

Check if character currently has the talent

'''CharacterHasSkill(CHARACTER:character, SKILL:skillId)''' 

Check if character currently has the skill

'''CharacterHasWeaponType(CHARACTER:character, WEAPON:weaponTYPE [, INT:equipped])''' 

Check if character currently has a weapon of this type in his inventory or equipped

'''CharacterGetStat(OUT FLOAT:statValue, CHARACTER:character, CHARACTERSTAT:statType)''' 

Returns the current value of the stat (Vitality, ...)

'''CharacterGetSightRange(OUT FLOAT:range, CHARACTER:character)''' 

Returns the character's sight range

'''CharacterGetWeaponRange(OUT FLOAT:minRange, OUT FLOAT:maxRange, CHARACTER:character)''' 

Returns the character's current weapon range

'''CharacterGetTouchRange(OUT FLOAT:touchRange, CHARACTER:character)''' 

Returns the character's current touch range

'''CharacterGetSkillRange(OUT FLOAT:minRange, OUT FLOAT:maxRange,CHARACTER:character, SKILL:skillId)''' 

Returns the character's skill range

'''CharacterGetSkillImpactRange(OUT FLOAT:areaRange, CHARACTER:character, SKILL:skillId)''' 

Returns the character's skill range

'''CharacterIsInTrigger(CHARACTER:character, TRIGGER:trigger)''' 

Check if character is in given trigger

'''CharacterGetAbility(OUT INT:value, CHARACTER:character, ABILITY:ability)''' 

Returns the character's value of the specified ability

'''CharacterGetHostileCount(OUT INT:value, CHARACTER:character)''' 

Returns how many characters are targeting this character right now... You can iterate over them with IterateEnemiesOf.

'''CharacterCanFight(CHARACTER:character)''' 

Returns true if the character can fight.

'''CharacterGetTemplate(CHARACTER:character, OUT CHARACTERTEMPLATE:root)''' 

Returns the roottemplate of the character.

'''CharacterCanSpotSneakers(CHARACTER:character)''' 

Returns true if the character can spot sneaking characters

'''CharacterIsFloating(CHARACTER:character)''' 

Check if character is a floating character

'''CharacterInCreation(CHARACTER:character)''' 

Returns true if the character is in character creation

'''CharacterAvoidsTraps(CHARACTER:character)''' 

Returns true if the character avoids traps

'''CharacterCheckRelation(CHARACTER:character, RELATION:relation)''' 

Returns true if relation check succeeds

'''CharacterIsBetterOrEqualClass(CHARACTER:character, INT:currentScore, OUT INT:newScore, INT warriorScore, INT rogueScore, INT mageScore, INT clericScore, INT rangerScore)''' 

Returns true if score is higher or equal than the current score

'''CharacterHasBeenHitBy(CHARACTER:character, DAMAGE_TYPE:damageType)''' 

Returns true if the character was hit by this type.

'''CharacterHasCastedSpellLastTurn(CHARACTER:character)''' 

Returns true if the character has casted a spell in his last turn.

'''CharacterHasHadStatus(CHARACTER:character, STATUS:status)''' 

Returns true if the character has had a specific status this combat.

'''CharacterHasAnimationOverride(CHARACTER:character)''' 

Returns true if the character has an animation override.

'''CharacterCanUnlock(CHARACTER:character, ITEM:item)''' 

Returns true if the character can unlock the item (if the item is already unlocked it returns true!)

'''CharacterGetReservedUserID(OUT INT:user, CHARACTER:character)''' 

Returns the character's reserved User id.

'''CharacterGetRace(CHARACTER:character, OUT FIXEDSTRING:race)''' 

Returns the <character>'s race in <race>.

'''CharacterIsRace(CHARACTER:character, FIXEDSTRING:race)''' 

Returns true if <character>'s race is <race>.

'''CharacterCanMoveItem(CHARACTER:character, ITEM:item, FLOAT:minRadius, FLOAT:maxRadius [, OUT FLOAT3:destination])''' 

Returns true + <destination> if <character> can move <item> somewhere between <minRadius> and <maxRadius>.

'''CharacterGetDeathType(CHARACTER:character, OUT FIXEDSTRING:deathType)''' 

Returns death type of <character> in <deathType>.

'''CharacterGetStillAnimation(CHARACTER:object, OUT FIXEDSTRING:stillAnimation)''' 

Returns the still animation to play

'''CrimeTransferLeadership(INT: CrimeID[, FIXEDSTRING:Tag1,...])''' 

Try and transfer the leadership of this crime to someone else.

'''CrimeGetLeadInvestigator(OUT CHARACTER:lead, INT: CrimeID)''' 

Returns the lead investigator for the crime.

'''CharacterCanHitTargetWithRangedWeapon(CHARACTER:source, OBJECT|FLOAT3:target[, SKILL:skill = null])''' 

Returns true if <source> can hit <target> with currently equipped ranged weapon. Will use <skill> instead of equipped weapon if provided.

'''CharacterHasRangedWeapon(CHARACTER:character[, INT:checkInventory = 0])''' 

Returns true if <character> has has ranged weapon. Checks for non-wielded weapons if <checkInventory> is 1

'''CheckInteractionReach(CHARACTER:character, CHARACTER|ITEM: target)''' 

Returns true if <character> could interact with <target>. This is not checking ranges, but checking if there's too much of a height difference or too many obstacles in between.

'''CharacterGetSourcePoints(CHARACTER:character, OUT INT: amount)''' 

Returns the amount of sourcepoints of <character>.

'''CharacterAiIsCalculating(-)''' 

Returns if the character is still calculating the AI.

'''CharacterAiFetchMoveSkillCommand(OUT SKILL:skill, OUT ITEM:skillItem, OUT FLOAT3:target)''' 

Returns if the character has a Move Skill command to execute according to the AI.

'''CharacterAiFetchSkillCommand(OUT SKILL:skill, OUT ITEM:skillItem, OUT FLOAT3 endPosition, OUT FLOAT3:target, OUT CHARACTER:target, OUT ITEM:target, OUT FLOAT3:target2, OUT CHARACTER:target2, OUT ITEM:target)''' 

Returns if the character has a Skill command to execute according to the AI.

'''CharacterAiFetchConsumeCommand(OUT ITEM:item)''' 

Returns if the character has a Consume command to execute according to the AI.

'''CharacterAiFetchAttackCommand(OUT FLOAT3:endPosition, OUT FLOAT3:target, OUT CHARACTER:target, OUT ITEM:target)''' 

Returns if the character has a Attack command to execute according to the AI.

'''CharacterAiFetchFallbackCommand(OUT FLOAT3:targetPosition, OUT FLOAT3:lookAtPosition)''' 

Returns if the character has a Fallback command to execute according to the AI.

'''CharacterGetArchetype(CHARACTER:character, OUT ARCHETYPE:archetype)''' 

Returns the archetype of the character.

'''CharacterIsPolymorphedInto(CHARACTER:character, FIXEDSTRING:race)''' 

Returns true if <character> is polymorphed into <race>. Race can be a race (like HUMAN), but also a template (in case of a polymorph skill like Chicken Touch).

'''CharacterIsPolymorphInteractionDisabled(CHARACTER:character)''' 

Returns true if <character> has his interaction disabled because of a polymorph.

'''ItemGet(OUT ITEM:item, GAMEOBJECT|FLOAT3:src, FLOAT:range, COMPARE:howTo [, COMPAREFUNC:compareFunc, FIXEDSTRING:rootTemplate, FIXEDSTRING:tag])''' 

Get an item within a certain range conforming to the filled in restraints.

'''ItemGetFromInventory(OUT ITEM:item, CHARACTER|ITEM:object [, FIXEDSTRING:statsId, FIXEDSTRING:tag, INT:isEquiped])''' 

Returns the first item in the inventory conforming to the filled in restraints.

'''ItemIsInCharacterInventory(ITEM:item, CHARACTER:object)''' 

Returns if the item is in the inventory of the character

'''ItemIsInTrigger(ITEM:item, TRIGGER:trigger)''' 

Check if item is in given trigger

'''ItemGetStat(OUT FLOAT:statValue, ITEM:item, ITEMSTAT:statType)''' 

Returns the current value of the stat (Weight, ...)

'''ItemIsMoving(ITEM:item)''' 

Returns if the item is moving or not.

'''ItemIsFalling(ITEM:item)''' 

Returns if the item is falling or not. (after teleport)

'''ItemIsOpening(ITEM:item)''' 

Returns if the item is opening or not.

'''ItemIsClosing(ITEM:item)''' 

Returns if the item is closing or not.

'''ItemIsLocked(ITEM:item)''' 

Returns if the item is locked or not.

'''ItemIsMovable(ITEM:item)''' 

Returns if the item is movable or not.

'''ItemCanBeLockPicked(ITEM:item)''' 

Returns if the item is can be opened by lockpicking.

'''ItemIsOpen(ITEM:item)''' 

Returns if the item is open or not.

'''IsStoryItem(ITEM:item)''' 

Returns if the item is a story item.

'''ItemHasStatus(ITEM:item, STATUS:statusId)''' 

Returns if the item has the status.

'''ItemIsDestroyed(ITEM:item)''' 

Returns if the item is destroyed.

'''ItemGetTemplate(ITEM:item, OUT ITEMTEMPLATE:root)''' 

Returns the roottemplate of the item.

'''ItemGetSkillId(ITEM:item, OUT SKILL:root)''' 

Returns the skillid of the item if it has one.

'''ItemGetItemType(ITEM:item, OUT FIXEDSTRING:itemType)''' 

Returns the itemtype of the item: common, unique, rare, ...

'''ItemGetStatusSourceCharacter(ITEM:item, STATUS:statusId, OUT CHARACTER:source)''' 

Get the source character of a status

'''ItemGetStatusSourceItem(ITEM:item, STATUS:statusId, OUT ITEM:source)''' 

Get the source item of a status

'''ItemCanBeMoved(ITEM:item)''' 

Returns if the item can be moved.

'''GetStatusTurns(CHARACTER|ITEM:object, STATUS:statusId, OUT INT:turnsLeft)''' 

Returns true if the object has the given status, and returns the amount of turns still left

== EVENTS ==

'''OnCharacterEvent(CHARACTER:character, STRING:eventName)''' 
Thrown from scripts or story

'''OnCharacterItemEvent(CHARACTER:character, ITEM:item, STRING:eventName)''' 
Thrown from scripts or story

'''OnCharacterCharacterEvent(CHARACTER:character, CHARACTER:character, STRING:eventName)''' 
Thrown from scripts or story

'''OnItemEvent(ITEM:item, STRING:eventName)''' 
Thrown from scripts or story

'''OnItemDestroyed(ITEM:item)''' 
Thrown when an item is destroyed

'''OnItemDestroying(ITEM:item)''' 
Thrown when an item is being destroyed

'''OnItemOpened(ITEM:item)''' 
Thrown when an item is opened

'''OnItemClosed(ITEM:item)''' 
Thrown when an item is closed

'''OnItemDropped(ITEM:item, STRING:itemTemplate)''' 
Thrown when an item is dropped

'''OnGlobalFlagSet(FIXEDSTRING:eventName)''' 
Thrown when a global event is set

'''OnGlobalFlagCleared(FIXEDSTRING:eventName)''' 
Thrown when a global event is cleared

'''OnCharacterFlagSet(FIXEDSTRING:eventName, CHARACTER:character)''' 
Thrown when a dialog event is set on a character

'''OnCharacterFlagCleared(FIXEDSTRING:eventName, CHARACTER:character)''' 
Thrown when a dialog event is cleared on a character

'''OnItemFlagSet(FIXEDSTRING:eventName, ITEM:item)''' 
Thrown when a dialog event is set on an item

'''OItemFlagCleared(FIXEDSTRING:eventName, ITEM:item)''' 
Thrown when a dialog event is cleared on an item

'''OnTimer(FIXEDSTRING:timerName)''' 
Thrown when a timer has ended

'''OnInit(-)''' 
Thrown when the script is set

'''OnLoaded(INT:major, INT:minor, INT:revision, INT:build)''' 
Thrown when the script is loaded from the savegame

'''OnShutdown(-)''' 
Thrown when the character's script is removed

'''OnVariableCleared(FIXEDSTRING:varName)''' 
Thrown when this object's script variable is cleared from Osiris with ClearVarObject

'''OnCombatStarted(INT:combatID)''' 
Thrown when combat starts

'''OnCombatSwitched(CHARACTER:source, ITEM:source)''' 
Thrown when the character switch from one combat to another

'''OnLeftCombat(CHARACTER:source, ITEM:source)''' 
Thrown when the character or item left the combat

'''OnTurn(CHARACTER:source, ITEM:source)''' 
Thrown when the character's turn starts

'''OnTurnEnded(CHARACTER:source, ITEM:source)''' 
Thrown when the character's turn ended

'''OnCharacterVitalityChanged(CHARACTER:character, FLOAT:percentage)''' 
Thrown when the characters's vitality changed

'''OnItemVitalityChanged(ITEM:item, FLOAT:percentage)''' 
Thrown when the item's vitality changed

'''OnAttackOfOpportunity(CHARACTER:target)''' 
Thrown when the characters gets an attack of opportunity on an enemy

'''OnClearAttackOfOpportunity(-)''' 
Thrown when the characters attack of opportunity is cleared

'''OnDamage(DAMAGE:type, FLOAT:percentage, CHARACTER:source, ITEM:source)''' 
Thrown when the object receives damage

'''OnMiss(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character dodges something

'''OnCriticalHit(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character is critical hit

'''OnPreBlock(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown before the character blocks something (at the start of the attack animation)

'''OnBlock(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character blocks something

'''OnDie(CHARACTER:character, DAMAGE:type, CHARACTER:source, ITEM:source)''' 
Thrown when the character dies

'''OnCharacterStatusAttempt(CHARACTER:character, STATUS:status)''' 
Thrown when the character attempts to gain a status

'''OnCharacterStatusApplied(CHARACTER:character, STATUS:status)''' 
Thrown when the character gains a status

'''OnCharacterStatusRemoved(CHARACTER:character, STATUS:status)''' 
Thrown when the character loses a status

'''OnItemStatusAttempt(ITEM:item, STATUS:status)''' 
Thrown when the item attempts to gain a status

'''OnItemStatus(ITEM:item, STATUS:status)''' 
Thrown when the item gains a status

'''OnItemStatusRemoved(ITEM:item, STATUS:status)''' 
Thrown when the item loses a status

'''OnStatusCreateVisuals(STATUS:status)''' 
Thrown when the item should create the visuals for this status

'''OnStatusDestroyVisuals(STATUS:status)''' 
Thrown when the item should destroy the visuals for this status

'''OnSight(CHARACTER:character)''' 
Thrown when the character sees another character

'''OnLostSight(CHARACTER:character)''' 
Thrown when the character doesn't see another character anymore

'''OnUseItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character uses an item

'''OnPickupItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character picks up an item

'''OnCharacterPreMovedItem(CHARACTER:source, ITEM:item)''' 
Event thrown just before a character moves an item. No difference whether it is in the world or in their inventory

'''OnCharacterMovedItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character moved an item

'''OnItemEquipped(CHARACTER:source, ITEM:item)''' 
Thrown when a character equips an item

'''OnItemUnequipped(CHARACTER:source, ITEM:item)''' 
Thrown when a character unequips an item

'''OnIterateCharacter(CHARACTER:character, FIXEDSTRING:eventId)''' 
Thrown by iterators

'''OnIterateItem(ITEM:source, FIXEDSTRING:eventId)''' 
Thrown by iterators

'''OnIterateCount(FIXEDSTRING:eventId, INTEGER:Count)''' 
Thrown by iterators after all iterations to inform you of the count.

'''OnStoryOverride(-)''' 
Throw when story overrides what the character was doing: teleport, movement, on/offstage

'''OnTriggerEnter(CHARACTER:character, ITEM:item, FIXEDSTRING:eventId)''' 
Thrown by a character or item entering an EventTrigger

'''OnTriggerLeave(CHARACTER:character, ITEM:item, FIXEDSTRING:eventId)''' 
Thrown by a character or item leaving an EventTrigger

'''OnEnemyChanged(CHARACTER:character, CHARACTER:newEnemy)''' 
Thrown when the character's currentenemy changes

'''OnTalentUnlocked(CHARACTER:character, TALENT:newTalent)''' 
Thrown when the character unlocks a new talent

'''OnTalentLocked(CHARACTER:character, TALENT:removedTalent)''' 
Thrown when the there's a talent removed from a character

'''OnCharacterClassChanged(CHARACTER:character, FIXEDSTRING:class)''' 
Thrown when the character changes class in the character creation screen

'''OnCharacterCreationStarted(CHARACTER:character, TRIGGER:creationPoint)''' 
Thrown when the character creation has started, and gives where the character should walk to

'''OnCharacterCreationStopped(CHARACTER:character)''' 
Thrown when the character creation has stopped

'''OnFunction(FIXEDSTRING:functionName)''' 
Throws an event on itself with the functionName. This is to fake function calls

'''OnSkillCast(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when the character casts a skill

'''OnSkillCombatComment(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when the character needs to make a comment

'''OnCharacterUsedSkillOnMe(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when you are hit by a skill from a character

'''OnItemUnlocked(ITEM: item, CHARACTER:character, ITEM:key)''' 
Thrown when an item gets unlocked by a character.

'''OnAutomatedDialogEnded(STRING:dialogName, INT:instanceID)''' 
Thrown when a automated dialog is ended for this speaker

'''OnAutomatedDialogStarted(STRING:dialogName, INT:instanceID)''' 
Thrown when a automated dialog is started for this speaker

'''OnDialogStarted(STRING:dialogName, INT:instanceID)''' 
Thrown when a dialog is started for this speaker

'''OnDialogEnded(STRING:dialogName, INT:instanceID)''' 
Thrown when a dialog is ended for this speaker

'''OnCrimeSensibleAction(FIXEDSTRING:regionID, INT:crimeID, FIXEDSTRING:reactionName, STRING:primaryDialog, CHARACTER:criminal1, CHARACTER:criminal2, CHARACTER:criminal3, CHARACTER:criminal4, INT:IsPrimary)''' 
Thrown when a character needs to perform a sensible action against criminals

'''OnCrimeInterrogationRequest(FIXEDSTRING:regionID, INT:crimeID, CHARACTER:criminal1, CHARACTER:criminal2, CHARACTER:criminal3, CHARACTER:criminal4, STRING:interrogationDialog)''' 
Thrown when a character needs to perform an interrogation against criminals

'''OnCrimeInvestigate(FLOAT3:CrimePosition, INT:crimeID)''' 
One NPC investigates a crimescene

'''OnCrimeAlarmed(FLOAT3:CrimePosition, INT:crimeID)''' 
All NPCs in a crimearea start looking around.

'''OnCrimeReturnToNormal(-)''' 
Investigation or Alarm timed out.

'''OnCrimeAborted(-)''' 
The game interrupted the sensible action of this NPC.

'''OnSplineControlPointReached(INT:Index, INT:EndReached, STRING:EventString)''' 
Thrown when a character reached a spline node.

''''OnFinishCalculationAi(-)''' 
Thrown when the calculation of the AI is finished.

'''OnGrenadeLand(INT:hitObstacle, CHARACTER:caster)''' 
Thrown when the grenades lands

'''FetchCharacterApplyStatusData(CHARACTER:character, STATUS:status) RETURN(LIST<STATUS>:removeStatuses, STATUS:applyStatus, INT:turns)''' 
Fetch from script which statuses to remove and apply.

'''FetchItemApplyStatusData(ITEM:item, STATUS:status) RETURN(LIST<STATUS>:removeStatuses, STATUS:applyStatus, INT:turns)''' 
Fetch from script which statuses to remove and apply.

'''FetchItemSkillOnDamage(INT:damage, DAMAGE_TYPE:damageType) RETURN(INT:hasSkill, SKILL_ID:skillID, INT:casterLevel)''' 
Fetch from script what skill to execute on damage.

'''FetchSkillScore(SKILL_ID:skillId, CHARACTER:sourceCharacter, CHARACTER:targetCharacter1, ITEM:targetItem1, FLOAT3:targetPosition1, CHARACTER:targetCharacter2, ITEM:targetItem2, FLOAT3:targetPosition2) RETURN(FLOAT:score) 
Fetch from script the score of a skill with set source and target

'''OnActivate(-)''' 
Thrown when a character/item activates

'''OnDeactivate(-)''' 
Thrown when a character/item deactivates

'''OnCharacterUsedSourcePoint(CHARACTER:character)''' 
Thrown when a character uses a source point

'''OnSkillAdded(CHARACTER:character, SKILL_ID:skillId, INT:learned)''' 
Thrown when a character learns a skill

'''OnSkillActivated(CHARACTER:character, SKILL_ID:skillId)''' 
Thrown when a character activates (=adds to memory) a skill

'''OnSkillDeactivated(CHARACTER:character, SKILL_ID:skillId)''' 
Thrown when a character deactivates (=removes from memory) a skill

'''OnItemFlagShared(FIXEDSTRING:eventName, ITEM:item, INT:newValue)''' 
Thrown when a dialog event is shared with an item

'''OnCharacterFlagShared(FIXEDSTRING:eventName, CHARACTER:character, INT:newValue)''' 
Thrown when a dialog event is shared with a character

'''OnItemOffStageChanged(CHARACTER:character, INT:offstage)''' 
Thrown when a character is set on/off stage

'''OnCharacterOffStageChanged(ITEM:item, INT:offstage)''' 
Thrown when a item is set on/off stage

'''OnCharacterTeleported(CHARACTER:target, CHARACTER:cause, FLOAT3:oldPosition, FLOAT3:newPosition, SKILL_ID:skillId)''' 
Thrown when a character gets teleported with a teleport skill

'''OnCombatTick(-)''' 
Thrown when this object ticks in combat. Only thrown for objects that don't get a turn.

'''OnCombatRoundStarted(INT:combatID, INT:roundID) 
Thrown when a round in a combat starts

'''OnReadyInCombat(CHARACTER:character, ITEM:item, INT:combatID)''' 
Thrown when a character or item is ready in combat

'''OnRegionLeft(CHARACTER:character, ITEM:item, FIXEDSTRING:region)''' 
Thrown when a character or item leaves a region

'''OnRegionEntered(CHARACTER:character, ITEM:item, FIXEDSTRING:region)''' 
Thrown when a character or item enters a region

'''OnRuneInserted(CHARACTER:character, ITEM:item, ITEMTEMPLATE:runeItemTemplate, INT:slot)''' 
Thrown when a <character> inserts a rune with roottemplate <runeItemTemplate> from an <item> at a specified <slot>

'''OnRuneRemoved(CHARACTER:character, ITEM:item, ITEM:rune, INT:slot)''' 
Thrown when a <character> removes a <rune> from an <item> at a specified <slot>

'''OnCharacterStartAttackObject(CHARACTER:defenderCharacter, ITEM:defenderItem, CHARACTER:attackerOwner, CHARACTER:attacker)''' 
Thrown when a character attacks a character or item with default attack

'''OnCharacterStartAttackPosition(FLOAT3:position, CHARACTER:attackerOwner, CHARACTER:attacker)''' 
Thrown when a character attacks a position with default attack

== INTERRUPTS ==

'''OnMovementFailed(FLOAT3:targetPos)''' 
Thrown when the reaction is interrupted by a move action failing

'''OnException(-)''' 
Thrown when the reaction is interrupted by an exception

'''OnBetterReactionFound(FIXEDSTRING:reactionName)''' 
Thrown when the reaction is interrupted by another reaction

'''OnNoReactionFound(-)''' 
Thrown when the reaction is interrupted because no reaction is valid

'''OnScriptDisabled(-)''' 
Thrown when the reaction is interrupted because the scriptcontroller is disabled

'''OnManualInterrupt(FIXEDSTRING:reactionName)''' 
Thrown when the reaction is interrupted using the interrupt action

'''OnRegionSwap(FIXEDSTRING:oldLevel, FIXEDSTRING:newLevel)''' 
Thrown when the reaction is interrupted by a region swap

= Divinity: Original Sin 2 Definitive Edition =
The following was added/changed for the Definitive Edition.

== CALLS ==
'''ItemDrop(ITEM:item)''' 
Drops an item from it's owner's inventory. Only characters are treated as owners.

'''RemoveSurfaceLayerAt(GAMEOBJECT|FLOAT3:target, INT:layer, FLOAT:radius)''' 
Removes surface (ground or cloud) at object/position. (Layer 0 for surface, otherwise - cloud) (Radius for cleanup)

'''SurfaceCreateLink(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 
Makes surfaces at 2 locations/positions interact as if they were adjacent.

'''SurfaceRemoveLink(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 
Stops surfaces at 2 distinctive locations/positions from interacting.

== QUERIES ==
'''AttributeGetDifficultyLevelMappedValue(FIXEDSTRING:difficulty, INT:level, OUT INT:levelMappedValue)''' 
Returns a level-mapped value of a primary attribute. (Difficulty = "Easy", "Normal" or "Hard")

'''CharacterGetCreationClass(CHARACTER:character, OUT FIXEDSTRING: class)''' 
During character creation returns character class. Fails outside of character creation.

'''CharacterGetEquippedItem(CHARACTER:character, FIXEDSTRING:slot, OUT ITEM:seatingItem)''' 
Returns item equipped into slot. (Slot = "Helmet", "Breast", "Leggings", "Weapon", "Shield", "Ring", "Ring2", "Belt", "Boots", "Gloves", "Amulet" or "Wings")

(CHANGED) '''CharacterInCreation(CHARACTER:character, OUT INT:CharacterIndex)''' 
Checks if character is in character creation currently. (CharacterIndex: assigned index of the player character during character creation)

Talk:Triggers

2019-09-11T22:06:55Z

LaughingLeader: /* Suggestions / Requests */ new section

The section for event triggers should be updated, the description should include items as event triggers also generate item events:

=== [[File:TemplateType_Trigger_Event.png|32px]] Event Trigger ===
A trigger that broadcasts an event entered or exited. These triggers are automatically [[Osiris/API/TriggerRegisterForCharacter|registered]] for all characters (player or not) and items in the game.
:Thanks, fixed! [[User:Tinkerer|Tinkerer]] ([[User talk:Tinkerer|talk]])

== Suggestions / Requests ==

Could we get a blurb about how polygon shape triggers need control points to form their shape, and you create these by clicking the + button with the trigger selected, then clicking in the scene?

Additionally the "View -> Trigger Shapes" option is gone from the view menu in the DE version of the editor, replaced with the Show selected/Show/hide all triggers visibility buttons to the side of the game view. This makes the current View -> Trigger Shapes screenshot a bit outdated.
Thanks.

[[User:LaughingLeader|LaughingLeader]] ([[User talk:LaughingLeader|talk]]) 00:06, 12 September 2019 (CEST)

Character and Item Script Triggers, Calls, and Queries

2019-01-29T20:59:26Z

LaughingLeader: Added missing parameters for SetMaterial.

This is a list of almost every character and item script event trigger, call, and query. An event is what triggers the script, and always begin with ''On''. Queries provide information and are always inside an ''IF'' or ''CHECK.'' Calls are actions that are always after THEN.

CharScript/ItemScript Functions

= Divinity: Original Sin 2 Classic=
== CALLS ==

'''Set(OUT OBJECT:variable, OBJECT:value)'''

Set the value of a variable

'''SetVar(CHARACTER|ITEM:object, FIXEDSTRING:variableName, OBJECT:value)'''

Set the value of a global variable

'''Cast(OUT OBJECT variable, OBJECT value)'''

Casts the value to the variable

'''Print(OUT STRING:output, STRING:text)'''

Prints the text to the output with possible parameters: [1], [2], ...

'''Add(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT|FLOAT3:value)'''

Adds both values and stores it in the first variable

'''Subtract(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT|FLOAT3:value)'''

Subtracts both values and stores it in the first variable

'''Multiply(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT:value)'''

Multiplies both values and stores it in the first variable

'''Divide(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT:value)'''

Divides both values and stores it in the first variable

'''Abs(INOUT INT|FLOAT:variable)'''

Takes the absolute value of a variable

'''Clamp(INOUT INT|FLOAT:variable, INT|FLOAT:min, INT|FLOAT:max)'''

Clamps a variable between min and max

'''GetRandom(OUT OBJECT:variable, OBJECT:value, OBJECT:value, OBJECT:value)'''

Fills in the variable with random one of the values.

'''GetWeightedRandom(OUT OBJECT:variable, OBJECT:value, INT|FLOAT:weight, ...)'''

Gets a weighted random of the given values!

'''GetRandomBetween(OUT INT|FLOAT:variable, INT|FLOAT:min, INT|FLOAT:max)'''

Gets a random value between min and max (both included)

'''GetRandomPositionInTrigger(OUT FLOAT3:variable, TRIGGER:areaTrigger)'''

Get a random position in a trigger area

'''GetElement(OUT OBJECT:variable, INT:index, OBJECT:value, OBJECT:value, OBJECT:value)'''

Fills in the variable with the index one of the values (starting from 0)

'''SetPriority(FIXEDSTRING:reactionName, INT:priority)'''

Changes the priority of a reaction. Priority 0 and below are not executed!

'''DelayReaction(FIXEDSTRING:reactionName, FLOAT:timeInSeconds)'''

The reaction will not be chosen for the specified time

'''SetScriptFrame(CHARACTER:character, FIXEDSTRING:frame)'''

Sets the scriptframe on the character.

'''ClearScriptFrame(CHARACTER:character)'''

Clears the scriptframe on the character.

'''Goto(FIXEDSTRING:labelName)'''

Jumps to the label. Two label names are built-in: "Start" for the first instruction of the reaction, and "End" for the last one.

'''GotoIfEqual(OBJECT:variable, OBJECT:value, FIXEDSTRING:labelName)'''

Jumps to the label if the 2 objects are equal

'''GotoRand(FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName)'''

Jumps to a random label in the list

'''CreatePuddleAt(GAMEOBJECT|FLOAT3:target, SURFACE:type, INT:cellAmountMin, INT:cellAmountMax, INT:growAmountMin, INT:growAmountMax, )'''

Spawn a puddle at the target's position for a certain lifetime (in turns)

'''CreateSurfaceAt(GAMEOBJECT|FLOAT3:target, SURFACE:type, FLOAT:radius, INT:lifeTime[, GAMEOBJECT:owner])'''

Spawn a surface at the target's position for a certain lifetime (in turns)

'''CreateSurfaceInPolygon(GAMEOBJECT:owner, SURFACE:type, FLOAT:duration, FLOAT:growTimer, INT:growStep, GAMEOBJECT|FLOAT3:point1, GAMEOBJECT|FLOAT3:point2, GAMEOBJECT|FLOAT3:point3, ...)'''

Spawn a polygon surface at the target's position. Grows <growStep> every <growTimer>.

'''CreateSurfaceInAreaTrigger(GAMEOBJECT:owner, SURFACE:type, FLOAT:duration, FLOAT:growTimer, INT:growStep, TRIGGER:areaTrigger)'''

Spawn a surface within <areaTrigger>. Grows <growStep> every <growTimer>.

'''CreateConeSurfaceAt(GAMEOBJECT|FLOAT3:start, GAMEOBJECT|FLOAT3:target, SURFACE:type, FLOAT:radius, FLOAT:angle, FLOAT:duration)'''

Spawn a Cone surface at the target's position

'''PlayEffectAt(GAMEOBJECT|FLOAT3:target, STRING:effectName)'''

Plays an effect at the target's position

'''PlayLoopEffectAt(OUT INT64:effectHandle, GAMEOBJECT|FLOAT3:target, STRING:effectName)'''

Plays an effect at the target's position

'''ExplodeAt(GAMEOBJECT|FLOAT3:target, SKILL:projectileSkill, [INT:casterLevel=-1, CHARACTER|ITEM:cause])'''

Trigger an explosion of a projectile skill at the target's position. The cause will trigger NPC behavior as if the cause casted the projectile

'''DisplayText(CHARACTER|ITEM:target, FIXEDSTRING:text, FLOAT:timeInSeconds)'''

Displays text above the character/item for a certain amount of time. It will replace the current text, including dialogtext

'''DisplayCombatInfoText(CHARACTER|ITEM:target, FIXEDSTRING:text, FLOAT:timeInSeconds)'''

Displays text above the character/item for a certain amount of time. It will replace the current text, including dialogtext

'''StatusText(CHARACTER|ITEM:target, FIXEDSTRING:text)'''

Adds statustext above the character/item for a short amount of time. Will not replace texts or dialogtexts

'''DebugText(CHARACTER|ITEM:target, STRING:text)'''

Adds debugtext above the character/item for a short amount of time.

'''CombatLogText(CHARACTER|ITEM:target, FIXEDSTRING:text, INT:filterID, INT:broadcastID)'''

Adds combatlog text inside the combat log window. Color-/SizeFormatting should already be applied, if not color and size of the string will be NORMAL. filterID determines what filter shows/hides the text. broadcastID determines who will be able to see the message (0 hearingrange. 1 party. 2 all)

'''Log(STRING:text, ...)'''

Log's the the scriptlog. (for debugging purposes)

'''Output(STRING:text, ...)'''

Pass text with optional parameters to the output panel (e.g. Output("An int [1]", INT:10))

'''Assert(STRING:text, ...)'''

Pass text with optional parameters to display as an assert message (e.g. Assert("This number is wrong: [1]", INT:666))

'''Label(FIXEDSTRING:name)'''

Marks this line as a label where Goto actions can jump to

'''StartTimer(FIXEDSTRING:timerName, FLOAT:timeInSeconds, INT:repeatCount)'''

Start a timer which will throw the timer event. Set repeatcount < 0 for a permanent timer.

'''StopTimer(FIXEDSTRING:timerName)'''

Stop a timer which will throw the timer event

'''DialogStart(OUT INT:instanceId, STRING:dialog, CHARACTER|ITEM:target, CHARACTER|ITEM:target, CHARACTER|ITEM:target, CHARACTER|ITEM:target)'''

Start a dialog between the targets. You can specify fewer targets than the maximum number.

{{warning|Starting a dialog from behaviour script will always start it as an [[Dialog_editor#Automated|Automated Dialog]]. Interactive dialogs can only be started from [[Osiris]].}}

'''DialogRequestStop(CHARACTER|ITEM:speaker, STRING:dialog)'''

Stops a certain dialog on a certain speaker

'''Check(-)'''

Reevaluate the conditions in the CHECK section of this reaction

'''Reset(-)'''

Resets the current reaction. It will start from the beginning again

'''Interrupt(FIXEDSTRING:reactionName)'''

Interrupt the reaction.

'''GlobalSetEvent(FIXEDSTRING:eventName)'''

Sets a global event. Scripts and Story can catch it.

'''GlobalClearEvent(FIXEDSTRING:eventName)'''

Clears a global event. Scripts and Story can catch it.

'''StopLoopEffect(INT64:fxHandle)'''

Stops a looping effect

'''IterateItems(FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item. If you pass a tag, it has to have that tag.

'''IterateItemsNear(GAMEOBJECT:source, FLOAT:radius, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item in range. If you pass a tag, it has to have that tag.

'''IterateItemsOnObject(CHARACTER|ITEM:source, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item standing on the source. If you pass a tag, it has to have that tag.

'''IterateParty(FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, CHARACTER:partyMember, FIXEDSTRING:tag])'''

Launch iterate event for each member of all parties. If you pass a party member only members of that party will be considered. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharacters(FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersNear(GAMEOBJECT:source, FLOAT:radius, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character in range. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersOnObject(CHARACTER|ITEM:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''
Launch iterate event for each character standing on the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersInCombat(CHARACTER|ITEM:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character in combat with the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateHostilesFor(CHARACTER:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character who is targetting the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''SpawnCharacter(OUT CHARACTER:result, CHARACTERTEMPLATE:rootTemplate, GAMEOBJECT|FLOAT3:position, INT:playSpawn, [INT:isSummon=0, CHARACTER:summonOwner=null, INT:overrideLevel=-1])'''

Spawns a character

'''SpawnItem(ITEMTEMPLATE:rootTemplate,GAMEOBJECT|FLOAT3:position, OUT ITEM:result)'''

Spawns an item

'''ShootLocalProjectile(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,FLOAT3:direction,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Spawns a projectile at the source (with offset, can be null) shooting at the target

'''ShootLocalProjectileAt(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,GAMEOBJECT|FLOAT3:target,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Spawns a projectile at the source (with offset, can be null) shooting at the target

'''ShootWorldProjectile(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,FLOAT3:direction,[INT:casterLevel])'''

Spawns a projectile at worldPos shooting at the target. Source can be null.

'''ShootWorldProjectileAt(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,GAMEOBJECT|FLOAT3:target,[INT:casterLevel])'''

Spawns a projectile at worldPos shooting at the target. Source can be null.

'''ShootLocalCone(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,FLOAT3:direction,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Shoots a cone from source (with offset, can be null) in a direction

'''ShootLocalConeAt(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,GAMEOBJECT|FLOAT3:target,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Shoots a cone from source (with offset, can be null) at the target

'''ShootWorldCone(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,FLOAT3:direction,[INT:casterLevel])'''

Shoots a cone from worldPos in a direction. Source can be null.

'''ShootWorldConeAt(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,GAMEOBJECT|FLOAT3:target,[INT:casterLevel])'''

Shoots a cone from worldPos at the target. Source can be null.

'''SetVisible(CHARACTER|ITEM:object, INT:visible)'''

Sets a character or item visible or not.

'''RotateY(INOUT FLOAT3:vector, FLOAT:degrees)'''

Rotate the vector around the Y-axis for a certain angle (in degrees)

'''SetHealth(CHARACTER|ITEM:target, FLOAT:percent)'''

Set a characters or items health on the given percentage. (percentage between 0 and 1)

'''PlaySound(CHARACTER|ITEM:target, STRING:soundEvent)'''

Plays a sound event at the target

'''PlayMusicForEveryone(STRING:musicEvent)'''

Plays a music event on all the clients

'''PlayMusicOnCharacter(CHARACTER:target, STRING:musicEvent)'''

Plays a music event on a character for all peers (3D)

'''PlayMusicForPeer(CHARACTER:target, STRING:musicEvent)'''

Plays a music event on the peer of the character

'''PlayMusicForPeerWithInstrument(CHARACTER:target, CHARACTER:charInstrument, STRING:musicEvent)'''

Plays a music event on the peer of the character concated with _INSTRUMENT

'''SetX(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the X component of the FLOAT3

'''SetY(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the Y component of the FLOAT3

'''SetZ(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the Z component of the FLOAT3

'''SetAtmosphere(FIXEDSTRING:atmosphereTriggerUUID, FIXEDSTRING:atmosphere)'''

Changes the atmosphere of the trigger

'''ResetAtmosphere(FIXEDSTRING:atmosphereTriggerUUID)'''

Resets the atmosphere of the trigger

'''AddStatusInfluence(CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1], [INT:force=1])'''

Adds the status influence strength on the object.

'''RemoveStatusInfluence(CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1])'''

Removes the status influence strength on the object.

'''AddTemporaryStatusInfluence(CHARACTER|ITEM:source, CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1])'''

Adds a temporary status influence strength on the object.. It will be gone in a few seconds if it's not set again

'''CallFunction(FIXEDSTRING:functionName)'''

Calls a function with the ID

'''SetMaterial(CHARACTER|ITEM:object, FIXEDSTRING:materialUUID, INT:duration, INT:applyOnBody, INT:applyOnArmor, INT:applyOnWings, INT:applyOnHorns, INT:applyOnOverhead, INT:applyOnWeapon[,INT:applyNormalMap, INT:overlay, INT:fading])'''

Changes the material of the object for a set time (in turns), -1 is infinite. applyNormalMap: Copy the original materials normal map

'''TeleportTo(CHARACTER|ITEM:object, GAMEOBJECT|FLOAT3:target, [INT:Force=0])'''

Teleport object to or near the target

'''Transform(CHARACTER|ITEM:object, CHARACTERTEMPLATE|ITEMTEMPLATE:root [, FIXEDSTRING:fx, INT:replaceScripts=1, OUT FLOAT:currentHP])'''

Transforms <object> using <root>, returns <currentHP>, plays <fx>.

'''SaveGame(FIXEDSTRING:saveGameName)'''

Save the savegame with name <saveGameName>

'''LoadGame(FIXEDSTRING:saveGameName)'''

Load the savegame with name <saveGameName>

'''LoadLevel(FIXEDSTRING:levelName)'''

Load the level with name <levelName>

'''KillCombat(CHARACTER:character)'''

Kill all the enemies in the combat which contains <character>

'''SetTag(CHARACTER|ITEM:object, FIXEDSTRING:tag)'''

Sets the Tag on the Object

'''ClearTag(CHARACTER|ITEM:object, FIXEDSTRING:tag)'''

Clears the Tag on the Object

'''SetGlobalFlag(FIXEDSTRING:flagname)'''

Sets the Global Flag

'''ClearGlobalFlag(FIXEDSTRING:flagname)'''

Clears the Global Flag

'''SetFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Sets the Flag on the Object

'''ClearFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the Object

'''SetUserFlag(CHARACTER:object, FIXEDSTRING:flagname)'''

Sets the Flag on the user's characters

'''ClearUserFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the user's characters

'''SetPartyFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Sets the Flag on the party's characters

'''ClearPartyFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the party's characters

'''StartVoiceBark(STRING:barkName, CHARACTER:character)'''

Start a voicebark on character

'''ConfrontationDone(INT: CrimeID, CHARACTER:lead, CHARACTER:criminal, ...)'''

Resolve the crime with id CrimeID for the specified criminals

'''CrimesceneInvestigationDone(CHARACTER:investigator)'''

Crimescene is considered investigated by this NPC, start looking for culprits

'''ListAdd(LIST<OBJECT>:list, OBJECT:entry)'''

Add <entry> at the back of <list>

'''ListRemove(LIST<OBJECT>:list, INT:index)'''

Remove the entry at <index> of <list>

'''ListSet(LIST<OBJECT>:list, INT:index, OBJECT:entry)'''

Set the entry at <index> of <list> to <entry>

'''ListClear(LIST<OBJECT>:list)'''

Remove all entries of <list>

'''EndTurn(CHARACTER|ITEM:Target)'''

Ends the object's current turn

'''SetCanFight(CHARACTER|ITEM:entity, INT:enabled[, INT:wholeGroup=0])'''

Enables/Disables the fact if the entity can fight. Optional for the whole group

'''SetCanJoinCombat(CHARACTER|ITEM:entity, INT:enabled[, INT:wholeGroup=0])'''

Enables/Disables the fact if the entity can join combats. Optional for the whole group

'''SetIsBoss(CHARACTER|ITEM:entity, INT:enabled)'''

Enables/Disables the fact if the entity is a boss.

'''GetAIHintTriggers(OUT LIST<TRIGGER>:triggers[, [LIST]FIXEDSTRING:tags, INT:needsAllTags = -1)'''

Returns all AIHintAreaTriggers in <triggers>. Uses contraints if set.

'''SetCombatTimeout(CHARACTER|ITEM:entity, FLOAT:timer)'''

Overwrites the entity's combat timeout check.

'''ResetCombatTimeout(CHARACTER|ITEM:entity)'''

Resets the entity's combat timeout check.

'''EnterCombat(CHARACTER|ITEM:source, CHARACTER|ITEM:target)'''

Enters combat with target

'''LeaveCombat(CHARACTER|ITEM:source)'''

Leaves the combat

'''SetFaction(CHARACTER|ITEM:target, FIXEDSTRING:faction)'''

Changes the faction of a character or item

'''SetInvulnerable(CHARACTER|ITEM:target, INT:bool)'''

Makes the character or item invulnerable or not. (Allow damage)

'''JumpToTurn(CHARACTER|ITEM:Target)'''

Jumps to targets turn (ends the current turn)

'''Sleep(FLOAT:timeInSeconds)'''

Sleeps for a certain amount of time

'''CharacterAttack(CHARACTER|ITEM|FLOAT3:target [,INT:alwaysHit])'''

Moves in weapon range and attacks the target

'''CharacterAttackWithoutMove(CHARACTER|ITEM|FLOAT3:target [,INT:alwaysHit])'''

Attacks the target without checking weaponranges and without moving

'''CharacterMoveTo(GAMEOBJECT|FLOAT3:target, [INT:running=0, INT:shouldArrive=0, INT:longPath=0, FLOAT:minDistance=1.5, FLOAT:maxDistance=minDistance+2.5])'''

Move to the target. Set shouldArrive to 1 if you want a guaranteed move. (teleports on fail)

'''CharacterAiMove(FLOAT3:target, CHARACTER:targetCharacter, ITEM:targetItem)'''

Moves to the target, calculated by the AI. Should only be used with results from the AI!

'''CharacterMoveInRange(GAMEOBJECT|FLOAT3:target, FLOAT:rangeMin, FLOAT:rangeMax, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within a certain range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveInWeaponRange(GAMEOBJECT|FLOAT3:target, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within weapon range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveInSkillRange(GAMEOBJECT|FLOAT3:target, SKILL:skill, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within skill range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveOutOfSight(FLOAT:angle)'''

Move out of screen

'''CharacterPlayAnimation(FIXEDSTRING:animation [, INT:exitOnFinish=1, INT:waitForCompletion=1])'''

Plays a certain animation ExitOnFinish means if the exit will kill itself after it was played (revert back to still)

'''CharacterStopAnimation(-)'''

Stops all animations.

'''CharacterPickUpItem(ITEM:item)'''

Moves close enough to the item if necessary and picks it up

'''CharacterUseItem(ITEM:item [, INTEGER:LongPath])'''

Moves close enough to the item if necessary and uses it

'''CharacterMoveItem(ITEM:item, INTEGER:ignoreWeight, INTEGER:ignoreAPCost [, INTEGER:ignoreDangerousSurfaces=1, INT:amount=-1, GAMEOBJECT|FLOAT3:destination])'''

Moves close enough to the item if necessary and moves it to the destination. Will try to find a destination if not supplied.

'''CharacterAddSkill(CHARACTER:character, SKILL:skill[, INT:ShowNotification=0])'''

Adds <skill> to <character>

'''CharacterRemoveSkill(CHARACTER:character, SKILL:skill)'''

Removes <skill> from <character>

'''CharacterUseSkill(SKILL:skill, GAMEOBJECT|FLOAT3:target [, GAMEOBJECT|FLOAT3:target2, ITEM:skillItem, INT:ignoreHasSkill=0])'''

Cast a skill

'''CharacterAppearAt(GAMEOBJECT|FLOAT3:target, INT:playspawn)'''

Appear at the target

'''CharacterAppearOutOfSightTo(GAMEOBJECT:target, FLOAT:angle, INT:playspawn)'''

Appears out of sight to the players from a certain angle while being able to reach target

'''CharacterAppearOnTrailOutOfSightTo(CHARACTER:target, FLOAT:angle, INT:playspawn)'''

Appears out of sight to the players, on its previous locations, from a certain angle while being able to reach target

'''CharacterDisappear(FLOAT:angle[, INTEGER:isRunning=0])'''

Move out of screen and go of stage, will run if <isRunning> is not 0

'''CharacterSetOffStage(-)'''

Set Off Stage

'''CharacterSetOnStage(-)'''

Set On Stage

'''CharacterLookAt(GAMEOBJECT|FLOAT3|SPLINE:target[, INT:snapToTarget=0, INT:angleTolerance=0])'''

Rotates the character to look at the target (Closest spline point in case of a spline).

'''CharacterLookFrom(GAMEOBJECT|SPLINE:target[, INT:snapToTarget=0])'''

Rotates to the character so it has the same rotation as the target (Closest spline point in case of a spline).

'''CharacterFollow(CHARACTER:target, FLOAT:durationInSeconds, INT:run)'''

Follow the target for a certain time

'''CharacterFollowOwnerOrLeader(FLOAT:durationInSeconds, INT:run)'''

Follow the leader or owner for a certain time

'''CharacterWander(FLOAT|TRIGGER:range, FLOAT:durationInSeconds [, INT:run, GAMEOBJECT:anchor])'''

Wander around for a certain time

'''CharacterSwitchWeaponType(WEAPON:type)'''

If necessary switch to the new weapon type

'''CharacterFleeFrom(RELATION:relation, FLOAT:range)'''

Run away from certain characters if necessary
'''
CharacterFleeFromSurface(SURFACE:surface)'''

Run away from a certain surface if necessary

'''CharacterFleeFromDangerousSurface(-)'''

Run away from a dangerous surfaces if necessary

'''CharacterAddSourcePoints(CHARACTER:character, INT:amount)'''

Adds x source points (x can be negative to substract)

'''CharacterDie(CHARACTER:character[, DEATH:type=DoT])'''

Kills the character

'''CharacterHeal(CHARACTER:character, FLOAT:percentage)'''

Heals the character

'''CharacterConsume(CHARACTER:character, POTION:potion)'''

Makes the character consume a potion. Doesn't cost any AP and will just execute the result of the potion.

'''CharacterDisableAllCrimes(CHARACTER:target)'''

Disables all generic behaviours for <target>.

'''CharacterEnableAllCrimes(CHARACTER:target)'''

Enables all generic behaviours for <target>.
'''
CharacterEnableCrime(CHARACTER:target, STRING:crime, ...)'''

Enables the specified generic behaviours for <target>.

'''CharacterDisableCrime(CHARACTER:target, STRING:crime, ...)'''

Disables the specified generic behaviours for <target>.

'''CharacterSetLongInvestigationDuration(CHARACTER:target)'''

Doubles the time it takes for the investigation to time out. Use this when the character needs to move a long path before investigating.

'''CharacterAiCalculate(-)'''

Calculate the AI of the character

'''CharacterAiStopCalculate(-)'''

Stop the calculation of the AI of the character

'''CharacterAiFinishMoveSkill(-)'''

Finish the current MoveSkill.
'''
CharacterAiAddInterestingItem(CHARACTER:character, ITEM:item)'''

Make it interesting for the AI to destroy that Item

'''CharacterAiRemoveInterestingItem(CHARACTER:character, ITEM:item)'''

Make it no longer interesting for the AI to destroy that Item

'''CharacterSetArchetype(CHARACTER:character, ARCHETYPE:archetype)'''

Sets the archetype of the character, used in AI calculations

'''CharacterSetStoryNPC(CHARACTER:character, INT:bool)'''

Makes the character storyNPC or not.
'''
CharacterAddActionPoints(CHARACTER:character, INT:amount)'''

Give character some action points

'''CharacterSetImmortal(CHARACTER:character, INT:bool)'''

Makes the character immortal or not. (Allow dying)

'''CharacterPlayEffect(CHARACTER:character, STRING:effect [,FIXEDSTRING:boneName])'''

Plays an effect on the character and it follows the character

'''CharacterPlayLoopEffect(OUT INT64:effectHandle, CHARACTER:character, STRING:effect [,FIXEDSTRING:boneName])'''

Plays a looping effect on the character and it follows the character

'''CharacterEvent(CHARACTER:character, STRING:eventName)'''

Throw a character event which you can catch in scripts and story

'''CharacterItemEvent(CHARACTER:character, ITEM:item, STRING:eventName)'''

Throw a character/item event which you can catch in scripts and story

'''CharacterCharacterEvent(CHARACTER:character1, CHARACTER:character2, STRING:eventName)'''

Throw a character/character event which you can catch in scripts and story

'''CharacterSetRelationIndivToIndiv(CHARACTER:source, CHARACTER:target, INT:relation)'''

Changes the relationship between 2 characters.
'''
CharacterForceUpdate(INT:forceUpdate)'''

Makes sure the attached character is always being update or not.
'''
CharacterSetEnemy(CHARACTER:character, CHARACTER:enemy)'''

Sets the current enemy of character

'''CharacterApplyStatus(CHARACTER:character, STATUS:statusId [, INT:turns=null, INT:force=0])'''

Applies the status to the character When turns is -1 it's a permanent status When turns is -2 it's a keep alive status (which means it will die if it's not applied again within 1 second)

'''CharacterRemoveStatus(CHARACTER:character, STATUS:statusId [, STATUS:reasonStatusID=null, INT:notify=1])'''

Removes the status from the character

'''CharacterDestroy(CHARACTER:character)'''

Destroys the character

'''CharacterSetCanSpotSneakers(CHARACTER:character, INT:enabled)'''

Enables/Disables the fact if the character can spot sneaking characters.

'''CharacterSetAttackOfOpportunity(CHARACTER:character, INT:enabled)'''

Enables/Disables the fact if the character can do attack of opportunities.

'''CharacterResurrect(CHARACTER:character [, INT:Percentage = 100])'''

Resurrects the character at [2]% health.

'''CharacterAddToInventory(CHARACTER:character, FIXEDSTRING:itemStatsObject[, INT:amount, INT:showInTrade=1])'''

Add the item to the character

'''CharacterRemoveFromInventory(CHARACTER:character, FIXEDSTRING:itemStatsObject[, INT:amount])'''

Remove the item from the character. If Amount is -1, then all are removed

'''CharacterDrinkPotion(FIXEDSTRING:statID)'''

Makes the character drink a potion from the inventory.

'''CharacterSetAnimationOverride(CHARACTER:character, FIXEDSTRING:animation)'''

Sets an animation override, only walk/run/die animations can override it.

'''CharacterUseActionPoints(CHARACTER:character, INT:amount [, OUT INT:succeeded])'''

Uses x action points

'''CharacterAddTreasureTable(CHARACTER:character, FIXEDSTRING:treasureTable)'''

Adds <treasureTable> to the treasure list of <character>

'''CharacterRemoveTreasureTable(CHARACTER:character, FIXEDSTRING:treasureTable)'''

Removes <treasureTable> from the treasure list of <character>

'''CharacterClearTreasureTables(CHARACTER:character)'''

Removes all treasure tables from <character>

'''CharacterSetTemporaryHostileRelation(CHARACTER:character, CHARACTER:otherCharacter)'''

Creates a temporary hostile relation between the 2 characters!

'''CharacterSetFightMode(CHARACTER:character, INT:fight [, INT:force=0])'''

Set the character in sheath/unsheated mode.

'''CharacterSetStats(CHARACTER:character, FIXEDSTRING:statsEntry [, INT:keepVitality=0, INT:keepAP=0, INT:keepLevel=0, OUT FLOAT:currentHP])'''

Applies <statsEntry> from character.xlsm to <character>, returns <currentHP>.

'''CharacterSetWalkSpeedOverride(CHARACTER:character, INTEGER:override [, FLOAT:walkSpeed])'''

Sets walk speed override of <character>, removes it if <override> is 0

'''CharacterSetRunSpeedOverride(CHARACTER:character, INTEGER:override [, FLOAT:runSpeed])'''

Sets run speed override of <character>, removes it if <override> is 0

'''CharacterSetHasDialog(CHARACTER:character, INTEGER:bool)'''

Enables/Disables the dialog of the character

'''CharacterInitPatrol(SPLINE:spline, INT:splineIndex, INT:reversed, INT:running)'''

Start patroling from the given index along the given spline with the given character.

'''CharacterStartPatrol(SPLINE:spline, INT:splineIndex, INT:reversed, INT:running)'''

Start patroling from the given index along the given spline with the given character.

'''CharacterStopPatrol(-)'''

Let the character stop patrolling whatever spline he's on!

'''CharacterInterruptPatrol(-)'''

Call when the patrol should interrupt so the guard stops moving to the next spline. If this is called when the character is deactivated, a caret will take his place.

'''CharacterSetAnimationSetOverride(CHARACTER:source, FIXEDSTRING:override)'''

Sets an animation set override for a character. Empty fixedstring clears the override.

'''CharacterSetFloating(CHARACTER:target, INTEGER:isFloating)'''

Sets <target> floating if <isFloating> is not 0

'''CharacterResetCooldowns(CHARACTER:target)'''

Resets the skill cooldowns for <target>

'''ItemEvent(ITEM:item, STRING:eventName)'''

Throw an item event which you can catch in scripts and story

'''ItemPlayAnimation(FIXEDSTRING:animation)'''

Plays an animation on the item

'''ItemPlayAnimationTo(FIXEDSTRING:animation, FLOAT:targetPercentage, [FLOAT:speed])'''

Plays an animation on the item to the target time (percentage of the total duration)

'''ItemPlayEffect(ITEM:item, STRING:effect [,FIXEDSTRING:boneName])'''

Plays an effect on the item and it follows the item

'''ItemPlayLoopEffect(OUT INT:effectHandle, ITEM:item, STRING:effect [,FIXEDSTRING:boneName])'''

Plays a looping effect on the item and it follows the item

'''ItemSetOnStage(ITEM:item, INTEGER:bool)'''

Sets an item on or offstage

'''ItemSetCanInteract(ITEM:item, INTEGER:bool)'''

Sets an item (not) interactible

'''ItemClose(ITEM:item)'''

Close an item

'''ItemOpen(ITEM:item)'''

Open an item

'''ItemDrop(ITEM:item)'''

Drop an item

'''ItemLock(ITEM:item, FIXEDSTRING:key)'''

Lock an item

'''ItemUnlock(ITEM:item)'''

Unlock an item

'''ItemApplyStatus(ITEM:item, STATUS:statusId [, INT:turns=null, INT:force=0])'''

Applies the status to the item When turns is -1 it's a permanent status When turns is -2 it's a keep alive status (which means it will die if it's not applied again within 1 second)

'''ItemRemoveStatus(ITEM:item, STATUS:statusId)'''

Removes the status from the item

'''ItemDie(ITEM:item)'''

Kills the item

'''ItemMoveTo(GAMEOBJECT|FLOAT3:target, FLOAT:velocity, FLOAT:acceleration, INTEGER:matchTargetRotation)'''

Moves the item to the target

'''ItemToInventory(ITEM:item, CHARACTER|ITEM:target [,INT:amount=-1])'''

Moves the item to the target's inventory

'''ItemLookAt(GAMEOBJECT:target, FLOAT:degreesPerSecond)'''

Rotates the item to look at the target

'''ItemDestroy(ITEM:item)'''

Destroys the item

'''ItemSetAmount(ITEM:item, INT:amount)'''

Change the amount of the item

'''IterateItemsInInventory(CHARACTER|ITEM:source, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each iten in source's inventory. If you pass a tag, it has to have that tag.

'''ItemAddCharges(ITEM:TargetItem, INT:charges)'''

Add/subtract charges from an item

'''ItemResetChargesToInitial(ITEM:TargetItem)'''

Resets charges from item to initial state

'''MakePeace(CHARACTER:Source, CHARACTER:Target[, INT:IgnoreVote = 1])'''

Make peace between users of the characters

'''MakeWar(CHARACTER:Source, CHARACTER:Target[, INT:IgnoreVote = 1])'''

Make war between users of the characters

'''FindSurface(OUT FLOAT3:result, GAMEOBJECT|FLOAT3:source, FLOAT:minRange, FLOAT:maxRange, SURFACE:type [,CHARACTER:alignSource, INT:minEnemiesInSurface, INT:maxAlliesInSurface, INT:minimumCellCount])'''

Finds the closest surface of a specific type.

'''FindValidPosition(INOUT FLOAT3:position, FLOAT:radius[, CHARACTER|ITEM:object=null])'''

Finds the closest valid position (where the object can stand.)

'''FindPosition(INOUT FLOAT3:position, CHARACTER:source, INT:canStand, INT:checkSight, FLOAT:minRadius, FLOAT:maxRadius, FLOAT:rangeCheck, CHARACTER:alignSource, INT:minAllies, INT:maxAllies, INT:minEnemies, INT:maxEnemies [,FIXEDSTRING:AiHintTag=null, INT:forceHint=0, FLOAT3:SourcePosition])'''

Finds the closest position from the source (within radius) where the conditions are matched.

'''Cast(OUT OBJECT variable, OBJECT value)'''

Casts the value to the variable.

'''StringConcatenate(STRING:stringA, STRING:stringB, OUT STRING:resultingString)'''

Appends stringB to stringA. Resulting string is stored in the third parameter.

== QUERIES ==

'''GetPosition(GAMEOBJECT:object,OUT FLOAT3:src)''' 

Get the current position of an object

'''GetForwardDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current forward direction of an object

'''GetRightDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current right direction of an object

'''GetUpDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current up direction of an object

'''GetDirection(GAMEOBJECT|FLOAT3:src,GAMEOBJECT|FLOAT3:target,OUT FLOAT3:direction[, OUT FLOAT:distance])''' 

Get the direction from src to target (optional: returns the distance between the objects as well)

'''GetRotation(GAMEOBJECT:object, OUT FLOAT3:vector)''' 

Get the rotation of an object

'''CharacterGetTargetSpline(INT: SplineIndex)''' 

Returns the spline index the character is currently walking towards, or -1 if he is not active on a spline.

'''IsEqual(OBJECT:variable, OBJECT:variable)''' 

Compares both objects and see if they are equal.

'''IsLessThen(INT|FLOAT:variable, INT|FLOAT:variable)''' 

Compares both objects and see if the first one is smaller.

'''IsGreaterThen(INT|FLOAT:variable, INT|FLOAT:variable)''' 

Compares both objects and see if the first one is bigger.

'''IsRandom(FLOAT:percentage)''' 

Each time this condition is checked, it will succeed with a chance of the percentage (between 0 and 1)

'''IsRound(INT:roundNumber)''' 

Checks if we are currently in combat in round x

'''IsInSurface(OBJECT|FLOAT3:target, SURFACE:type[, FLOAT:radius])''' 

Check if the character, item, trigger or position is currently within the specific surface.

'''IsInDangerousSurface(OBJECT|FLOAT3:target[, CHARACTER:character, FLOAT:radius])''' 

Check if <target> is currently in on a dangerous surface. Uses <character> for path influences if provided (is necessary with non-character targets)

'''IsInDialog(CHARACTER|ITEM:target[, INT:ignoreAutomatedDialogs=0])''' 

Check if the character or item is currently in a dialog, optionally ignoring automated dialogs

'''IsInAutomatedDialog(CHARACTER|ITEM:target)''' 

Check if the character or item is currently in an automated dialog

'''GetDistance(OUT FLOAT:distance, GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 

Returns the distance between 2 positions

'''GetDistance2D(OUT FLOAT:distance, GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 

Returns the 2D distance between 2 positions (ignores height)

'''GetInnerDistance(OUT FLOAT:distance, GAMEOBJECT:source, GAMEOBJECT:target)''' 

Returns the distance between 2 gameobjects (character, item, trigger, ...) Their bounds are already subtracted.

'''GetPosition(GAMEOBJECT:object, OUT FLOAT3:position)''' 

Returns the position of a gameobject (character, item, trigger, ...)

'''GetVar(OUT OBJECT:returnValue, CHARACTER|ITEM:target, FIXEDSTRING:varName)''' 

Gets a global variable from the target

'''GetClosestPlayer(OUT CHARACTER:player, GAMEOBJECT|FLOAT3:source)''' 

Gets the closest player near the source, default being being the object itself

'''GetPlayerCount(OUT INT:playerCount)''' 

Gets the number of players in the party

'''GetPlayerByIndex(OUT CHARACTER:returnCharacter, INT:playerIndex)''' 

Gets a player from the party by index

'''GetRandomCharacter(OUT CHARACTER:returnCharacter, [INT:canBeSelf=0, INT:canBePlayer=0])''' 

Gets a random character in the current level

'''ContainsSurface(GAMEOBJECT|FLOAT3:source, FLOAT:radius, SURFACE:type,)''' 

Checks if there is any surface of the type within a radius of the source

'''IsSurface(GAMEOBJECT|FLOAT3:source, FLOAT:radius, SURFACE:type)''' 

Checks if the whole radius around the source is the specified surface type

'''IsObjectOnObject(CHARACTER|ITEM:source,CHARACTER|ITEM:target)''' 

Checks if the source is standing on the target

'''GetX(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the X component of the vector

'''GetY(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the Y component of the vector

'''GetZ(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the Z component of the vector

'''CanSee(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target[, INT:addProjectileTargetGroundOffset=0])''' 

Check if the sight is blocked between 2 points.

'''IsVisible(CHARACTER|ITEM:object)''' 

Check if the object is set invisible or not with SetVisible.

'''GetTextDuration(CHARACTER|ITEM:object, FIXEDSRTING:key, OUT FLOAT:duration)''' 

Gets how long a text needs to be displayed

'''IsCasual(-)''' 

Returns if the current game mode is Casual

'''IsHardcore(-)''' 

Returns if the current game mode is Hardcore

'''IsTagged(GAMEOBJECT:object, FIXEDSTRING:tag)''' 

Check if the object is tagged.

'''TranslatedStringKeyExists(FIXEDSTRING:key)''' 

Check if the TranslatedString key exists.

'''IsInCombat(CHARACTER|ITEM:object)''' 

Returns true if the object is in combat.

'''IsInCombatWith(CHARACTER|ITEM:object, CHARACTER|ITEM:object)''' 

Returns true if the objects are in combat with each other.

'''IsFacing(GAMEOBJECT:source, GAMEOBJECT|FLOAT3:target, [INT:angle=90])''' 

Returns true if the object is facing the position within the given angle.

'''GameIsSaving(-)''' 

Returns true if the game is saving.

'''GameIsLoading(-)''' 

Returns true if the game is loading.

'''GetUserCount(OUT INT:userCount)''' 

Returns the user count.

'''GetCurrentCharacter(OUT CHARACTER:character, INT:user)''' 

Returns the character currently being controlled by the specified user.

'''GetCurrentLevel(OUT FIXEDSTRING:currentLevel)''' 

Returns the current levelname

'''GetAIBounds(CHARACTER|ITEM:source, OUT FLOAT:bounds)''' 

Returns AI bounds of <source> in <bounds>

'''HasGlobalFlag(FIXEDSTRING:flagName)''' 

Returns if the Global Flag is set

'''HasFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the Object

'''HasUserFlag(CHARACTER:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the user's characters

'''HasPartyFlag(CHARACTER:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the party's characters

'''DialogExists(STRING:dialogue)''' 

Returns true if the dialogue exists.

'''IsActive(CHARACTER|ITEM:Object)''' 

Returns if the character or item is currently active.

'''ListGetSize(LIST<OBJECT>:list, out INT:size)''' 

Returns the number of elements in <list>

'''ListGet(LIST<OBJECT>:list, INT:index, out OBJECT:entry)''' 

Returns <entry> at <index> of <list>

'''ListGetRandom(LIST<OBJECT>:list, out OBJECT:entry)''' 

Returns a random <entry> of <list>

'''IsBoss(CHARACTER|ITEM:Object)''' 

Returns true if the entity is tagged as a boss

'''IsProjectileSkill(SKILL:skill)''' 

Returns true if the skill is a ranged skill (uses a projectile)

'''IsValidSkillTarget(CHARACTER:source, OBJECT|FLOAT3:target, SKILLID:skill[, INTEGER:ignoreRangeCheck=0])''' 

Checks whether <target> is a valid target for <skill> at <source>

'''GetFaction(OUT FIXEDSTRING:faction, CHARACTER|ITEM:character)''' 

Returns the faction of the provided character or item

'''IsInActiveTurn(CHARACTER|ITEM:target)''' 

Returns true if it's the character's or item's turn in combat.

'''IsSkillActive(CHARACTER:character, SKILL:skillId)''' 

Returns true if <character> has <skillId> active (in memory).

'''HasSkillAi(SKILLID:skillId)''' 

Returns true if the skill is using the new Ai system

'''IsInArena(CHARACTER::character)''' 

Returns true if the character is in an arena fight

'''CrimeGetType(INTEGER:crimeId, OUT STRING:crimeType)''' 

Returns the type of the crime with this id.

'''CrimeGetCriminals(INTEGER:crimeId, OUT CHARACTER:criminal1, OUT CHARACTER:criminal2, OUT CHARACTER:criminal3, OUT CHARACTER:criminal4)''' 

Returns the criminals of that crime. They might all be null.

'''IsSourceSkill(SKILL:skill)''' 

Returns true if the skill is a source skill.

'''IsInGameMasterMode(-)''' 

Returns true if the game in game master mode.

'''CharacterGet(OUT CHARACTER:character, GAMEOBJECT|FLOAT3:src, FLOAT:range, COMPARE:howTo, COMPAREFUNC:compareFunc[, RELATION: relation, SURFACE:surface, STATUS:status, TALENT:talent, CHARACTER:inSightOf, FIXEDSTRING:tag])''' 

Get a character within a certain range conforming to the filled in restraints.

'''CharacterCount(OUT INT:count, GAMEOBJECT|FLOAT3:src, FLOAT:range, [RELATION: relation, SURFACE:surface, STATUS:status, TALENT:talent, CHARACTER:inSightOf])''' 

Counts the characters within a certain range conforming to the filled in restraints.

'''CharacterGetOwner(OUT CHARACTER:owner, CHARACTER:source)''' 

Get the character's owner

'''CharacterGetFollow(OUT CHARACTER:to follow, CHARACTER:source)''' 

Get the character to follow

'''CharacterGetEnemy(OUT CHARACTER:current enemy, CHARACTER:source)''' 

Get current enemy of character

'''CharacterCanCast(CHARACTER:source, SKILL:skillId, [ITEM:skillItem=null, INT:ignoreActionPoints=0])''' 

Check if the character source can cast the skill: will check cooldown, actionpoints

'''CharacterCanSitOnItem(CHARACTER:source, ITEM:item)''' 

Check if the character source can sit or lie on an item.

'''CharacterCanDrinkPotion(CHARACTER:source, FIXEDSTRING:potionID[, INT:ignoreActionPoints=0])''' 

Check if the character source can drink the potion: will check inv and actionpoints

'''CharacterCanUseItem(CHARACTER:source, ITEM:item[, INT:ignoreActionPoints=0])''' 

Check if the character source can use the item in the world

'''CharacterCanUseItemInInventory(CHARACTER:source, ITEM:item[, INT:ignoreActionPoints=0])''' 

Check if the character source can use the item in his inventory

'''CharacterCanSee(CHARACTER:watchingChar, CHARACTER|ITEM:target [, INT:forceUpdate=0])''' 

Check if character has target in his line of sight.

'''CharacterCanShoot(CHARACTER:source, GAMEOBJECT|FLOAT3:target)''' 

Check if the character can shoot the target.

'''CharacterIsPlayer(CHARACTER:character)''' 

Check if the character is a player

'''CharacterIsInParty(CHARACTER:character)''' 

Check if the character is in the party

'''CharacterIsEnemy(CHARACTER:source, CHARACTER:target)''' 

Check if target is enemy of source

'''CharacterIsAlly(CHARACTER:source, CHARACTER:target)''' 

Check if target is ally of source

'''CharacterIsNeutral(CHARACTER:source, CHARACTER:target)''' 

Check if target is neutral of source

'''CharacterIsDead(CHARACTER:character)''' 

Check if character is dead

'''CharacterIsMoving(CHARACTER:character)''' 

Check if character is moving (speed > 0)

'''CharacterIsSummon(CHARACTER:character)''' 

Check if character is a summon

'''CharacterIsPartyFollower(CHARACTER:character)''' 

Check if character is a party follower

'''CharacterIsStoryNPC(CHARACTER:character)''' 

Check if character is a story NPC

'''CharacterInWeaponRange(CHARACTER:character, CHARACTER:target)''' 

Check if target is in the current's weapon range

'''CharacterInTouchRange(CHARACTER:character, CHARACTER:targetChar)''' 

Check if target is in the character's touch range

'''CharacterHasStatus(CHARACTER:character, STATUS:statusId[, FIXEDSTRING:extraData])''' 

Check if character currently has the status. ExtraData can be filled in for some statuses: - Consume: statsid of the item - Shield: skillid of the shield

'''CharacterGetStatusSourceCharacter(CHARACTER:character, STATUS:statusId, OUT CHARACTER:source[, FIXEDSTRING:extraData])''' 

Get the source character of a status

'''CharacterGetStatusSourceItem(CHARACTER:character, STATUS:statusId, OUT ITEM:source[, FIXEDSTRING:extraData])''' 

Get the source item of a status

'''CharacterHasTalent(CHARACTER:character, TALENT:talent)''' 

Check if character currently has the talent

'''CharacterHasSkill(CHARACTER:character, SKILL:skillId)''' 

Check if character currently has the skill

'''CharacterHasWeaponType(CHARACTER:character, WEAPON:weaponTYPE [, INT:equipped])''' 

Check if character currently has a weapon of this type in his inventory or equipped

'''CharacterGetStat(OUT FLOAT:statValue, CHARACTER:character, CHARACTERSTAT:statType)''' 

Returns the current value of the stat (Vitality, ...)

'''CharacterGetSightRange(OUT FLOAT:range, CHARACTER:character)''' 

Returns the character's sight range

'''CharacterGetWeaponRange(OUT FLOAT:minRange, OUT FLOAT:maxRange, CHARACTER:character)''' 

Returns the character's current weapon range

'''CharacterGetTouchRange(OUT FLOAT:touchRange, CHARACTER:character)''' 

Returns the character's current touch range

'''CharacterGetSkillRange(OUT FLOAT:minRange, OUT FLOAT:maxRange,CHARACTER:character, SKILL:skillId)''' 

Returns the character's skill range

'''CharacterGetSkillImpactRange(OUT FLOAT:areaRange, CHARACTER:character, SKILL:skillId)''' 

Returns the character's skill range

'''CharacterIsInTrigger(CHARACTER:character, TRIGGER:trigger)''' 

Check if character is in given trigger

'''CharacterGetAbility(OUT INT:value, CHARACTER:character, ABILITY:ability)''' 

Returns the character's value of the specified ability

'''CharacterGetHostileCount(OUT INT:value, CHARACTER:character)''' 

Returns how many characters are targeting this character right now... You can iterate over them with IterateEnemiesOf.

'''CharacterCanFight(CHARACTER:character)''' 

Returns true if the character can fight.

'''CharacterGetTemplate(CHARACTER:character, OUT CHARACTERTEMPLATE:root)''' 

Returns the roottemplate of the character.

'''CharacterCanSpotSneakers(CHARACTER:character)''' 

Returns true if the character can spot sneaking characters

'''CharacterIsFloating(CHARACTER:character)''' 

Check if character is a floating character

'''CharacterInCreation(CHARACTER:character)''' 

Returns true if the character is in character creation

'''CharacterAvoidsTraps(CHARACTER:character)''' 

Returns true if the character avoids traps

'''CharacterCheckRelation(CHARACTER:character, RELATION:relation)''' 

Returns true if relation check succeeds

'''CharacterIsBetterOrEqualClass(CHARACTER:character, INT:currentScore, OUT INT:newScore, INT warriorScore, INT rogueScore, INT mageScore, INT clericScore, INT rangerScore)''' 

Returns true if score is higher or equal than the current score

'''CharacterHasBeenHitBy(CHARACTER:character, DAMAGE_TYPE:damageType)''' 

Returns true if the character was hit by this type.

'''CharacterHasCastedSpellLastTurn(CHARACTER:character)''' 

Returns true if the character has casted a spell in his last turn.

'''CharacterHasHadStatus(CHARACTER:character, STATUS:status)''' 

Returns true if the character has had a specific status this combat.

'''CharacterHasAnimationOverride(CHARACTER:character)''' 

Returns true if the character has an animation override.

'''CharacterCanUnlock(CHARACTER:character, ITEM:item)''' 

Returns true if the character can unlock the item (if the item is already unlocked it returns true!)

'''CharacterGetReservedUserID(OUT INT:user, CHARACTER:character)''' 

Returns the character's reserved User id.

'''CharacterGetRace(CHARACTER:character, OUT FIXEDSTRING:race)''' 

Returns the <character>'s race in <race>.

'''CharacterIsRace(CHARACTER:character, FIXEDSTRING:race)''' 

Returns true if <character>'s race is <race>.

'''CharacterCanMoveItem(CHARACTER:character, ITEM:item, FLOAT:minRadius, FLOAT:maxRadius [, OUT FLOAT3:destination])''' 

Returns true + <destination> if <character> can move <item> somewhere between <minRadius> and <maxRadius>.

'''CharacterGetDeathType(CHARACTER:character, OUT FIXEDSTRING:deathType)''' 

Returns death type of <character> in <deathType>.

'''CharacterGetStillAnimation(CHARACTER:object, OUT FIXEDSTRING:stillAnimation)''' 

Returns the still animation to play

'''CrimeTransferLeadership(INT: CrimeID[, FIXEDSTRING:Tag1,...])''' 

Try and transfer the leadership of this crime to someone else.

'''CrimeGetLeadInvestigator(OUT CHARACTER:lead, INT: CrimeID)''' 

Returns the lead investigator for the crime.

'''CharacterCanHitTargetWithRangedWeapon(CHARACTER:source, OBJECT|FLOAT3:target[, SKILL:skill = null])''' 

Returns true if <source> can hit <target> with currently equipped ranged weapon. Will use <skill> instead of equipped weapon if provided.

'''CharacterHasRangedWeapon(CHARACTER:character[, INT:checkInventory = 0])''' 

Returns true if <character> has has ranged weapon. Checks for non-wielded weapons if <checkInventory> is 1

'''CheckInteractionReach(CHARACTER:character, CHARACTER|ITEM: target)''' 

Returns true if <character> could interact with <target>. This is not checking ranges, but checking if there's too much of a height difference or too many obstacles in between.

'''CharacterGetSourcePoints(CHARACTER:character, OUT INT: amount)''' 

Returns the amount of sourcepoints of <character>.

'''CharacterAiIsCalculating(-)''' 

Returns if the character is still calculating the AI.

'''CharacterAiFetchMoveSkillCommand(OUT SKILL:skill, OUT ITEM:skillItem, OUT FLOAT3:target)''' 

Returns if the character has a Move Skill command to execute according to the AI.

'''CharacterAiFetchSkillCommand(OUT SKILL:skill, OUT ITEM:skillItem, OUT FLOAT3 endPosition, OUT FLOAT3:target, OUT CHARACTER:target, OUT ITEM:target, OUT FLOAT3:target2, OUT CHARACTER:target2, OUT ITEM:target)''' 

Returns if the character has a Skill command to execute according to the AI.

'''CharacterAiFetchConsumeCommand(OUT ITEM:item)''' 

Returns if the character has a Consume command to execute according to the AI.

'''CharacterAiFetchAttackCommand(OUT FLOAT3:endPosition, OUT FLOAT3:target, OUT CHARACTER:target, OUT ITEM:target)''' 

Returns if the character has a Attack command to execute according to the AI.

'''CharacterAiFetchFallbackCommand(OUT FLOAT3:targetPosition, OUT FLOAT3:lookAtPosition)''' 

Returns if the character has a Fallback command to execute according to the AI.

'''CharacterGetArchetype(CHARACTER:character, OUT ARCHETYPE:archetype)''' 

Returns the archetype of the character.

'''CharacterIsPolymorphedInto(CHARACTER:character, FIXEDSTRING:race)''' 

Returns true if <character> is polymorphed into <race>. Race can be a race (like HUMAN), but also a template (in case of a polymorph skill like Chicken Touch).

'''CharacterIsPolymorphInteractionDisabled(CHARACTER:character)''' 

Returns true if <character> has his interaction disabled because of a polymorph.

'''ItemGet(OUT ITEM:item, GAMEOBJECT|FLOAT3:src, FLOAT:range, COMPARE:howTo [, COMPAREFUNC:compareFunc, FIXEDSTRING:rootTemplate, FIXEDSTRING:tag])''' 

Get an item within a certain range conforming to the filled in restraints.

'''ItemGetFromInventory(OUT ITEM:item, CHARACTER|ITEM:object [, FIXEDSTRING:statsId, FIXEDSTRING:tag, INT:isEquiped])''' 

Returns the first item in the inventory conforming to the filled in restraints.

'''ItemIsInCharacterInventory(ITEM:item, CHARACTER:object)''' 

Returns if the item is in the inventory of the character

'''ItemIsInTrigger(ITEM:item, TRIGGER:trigger)''' 

Check if item is in given trigger

'''ItemGetStat(OUT FLOAT:statValue, ITEM:item, ITEMSTAT:statType)''' 

Returns the current value of the stat (Weight, ...)

'''ItemIsMoving(ITEM:item)''' 

Returns if the item is moving or not.

'''ItemIsFalling(ITEM:item)''' 

Returns if the item is falling or not. (after teleport)

'''ItemIsOpening(ITEM:item)''' 

Returns if the item is opening or not.

'''ItemIsClosing(ITEM:item)''' 

Returns if the item is closing or not.

'''ItemIsLocked(ITEM:item)''' 

Returns if the item is locked or not.

'''ItemIsMovable(ITEM:item)''' 

Returns if the item is movable or not.

'''ItemCanBeLockPicked(ITEM:item)''' 

Returns if the item is can be opened by lockpicking.

'''ItemIsOpen(ITEM:item)''' 

Returns if the item is open or not.

'''IsStoryItem(ITEM:item)''' 

Returns if the item is a story item.

'''ItemHasStatus(ITEM:item, STATUS:statusId)''' 

Returns if the item has the status.

'''ItemIsDestroyed(ITEM:item)''' 

Returns if the item is destroyed.

'''ItemGetTemplate(ITEM:item, OUT ITEMTEMPLATE:root)''' 

Returns the roottemplate of the item.

'''ItemGetSkillId(ITEM:item, OUT SKILL:root)''' 

Returns the skillid of the item if it has one.

'''ItemGetItemType(ITEM:item, OUT FIXEDSTRING:itemType)''' 

Returns the itemtype of the item: common, unique, rare, ...

'''ItemGetStatusSourceCharacter(ITEM:item, STATUS:statusId, OUT CHARACTER:source)''' 

Get the source character of a status

'''ItemGetStatusSourceItem(ITEM:item, STATUS:statusId, OUT ITEM:source)''' 

Get the source item of a status

'''ItemCanBeMoved(ITEM:item)''' 

Returns if the item can be moved.

'''GetStatusTurns(CHARACTER|ITEM:object, STATUS:statusId, OUT INT:turnsLeft)''' 

Returns true if the object has the given status, and returns the amount of turns still left

== EVENTS ==

'''OnCharacterEvent(CHARACTER:character, STRING:eventName)''' 
Thrown from scripts or story

'''OnCharacterItemEvent(CHARACTER:character, ITEM:item, STRING:eventName)''' 
Thrown from scripts or story

'''OnCharacterCharacterEvent(CHARACTER:character, CHARACTER:character, STRING:eventName)''' 
Thrown from scripts or story

'''OnItemEvent(ITEM:item, STRING:eventName)''' 
Thrown from scripts or story

'''OnItemDestroyed(ITEM:item)''' 
Thrown when an item is destroyed

'''OnItemDestroying(ITEM:item)''' 
Thrown when an item is being destroyed

'''OnItemOpened(ITEM:item)''' 
Thrown when an item is opened

'''OnItemClosed(ITEM:item)''' 
Thrown when an item is closed

'''OnItemDropped(ITEM:item, STRING:itemTemplate)''' 
Thrown when an item is dropped

'''OnGlobalFlagSet(FIXEDSTRING:eventName)''' 
Thrown when a global event is set

'''OnGlobalFlagCleared(FIXEDSTRING:eventName)''' 
Thrown when a global event is cleared

'''OnCharacterFlagSet(FIXEDSTRING:eventName, CHARACTER:character)''' 
Thrown when a dialog event is set on a character

'''OnCharacterFlagCleared(FIXEDSTRING:eventName, CHARACTER:character)''' 
Thrown when a dialog event is cleared on a character

'''OnItemFlagSet(FIXEDSTRING:eventName, ITEM:item)''' 
Thrown when a dialog event is set on an item

'''OItemFlagCleared(FIXEDSTRING:eventName, ITEM:item)''' 
Thrown when a dialog event is cleared on an item

'''OnTimer(FIXEDSTRING:timerName)''' 
Thrown when a timer has ended

'''OnInit(-)''' 
Thrown when the script is set

'''OnLoaded(INT:major, INT:minor, INT:revision, INT:build)''' 
Thrown when the script is loaded from the savegame

'''OnShutdown(-)''' 
Thrown when the character's script is removed

'''OnVariableCleared(FIXEDSTRING:varName)''' 
Thrown when this object's script variable is cleared from Osiris with ClearVarObject

'''OnCombatStarted(INT:combatID)''' 
Thrown when combat starts

'''OnCombatSwitched(CHARACTER:source, ITEM:source)''' 
Thrown when the character switch from one combat to another

'''OnLeftCombat(CHARACTER:source, ITEM:source)''' 
Thrown when the character or item left the combat

'''OnTurn(CHARACTER:source, ITEM:source)''' 
Thrown when the character's turn starts

'''OnTurnEnded(CHARACTER:source, ITEM:source)''' 
Thrown when the character's turn ended

'''OnCharacterVitalityChanged(CHARACTER:character, FLOAT:percentage)''' 
Thrown when the characters's vitality changed

'''OnItemVitalityChanged(ITEM:item, FLOAT:percentage)''' 
Thrown when the item's vitality changed

'''OnAttackOfOpportunity(CHARACTER:target)''' 
Thrown when the characters gets an attack of opportunity on an enemy

'''OnClearAttackOfOpportunity(-)''' 
Thrown when the characters attack of opportunity is cleared

'''OnDamage(DAMAGE:type, FLOAT:percentage, CHARACTER:source, ITEM:source)''' 
Thrown when the object receives damage

'''OnMiss(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character dodges something

'''OnCriticalHit(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character is critical hit

'''OnPreBlock(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown before the character blocks something (at the start of the attack animation)

'''OnBlock(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character blocks something

'''OnDie(CHARACTER:character, DAMAGE:type, CHARACTER:source, ITEM:source)''' 
Thrown when the character dies

'''OnCharacterStatusAttempt(CHARACTER:character, STATUS:status)''' 
Thrown when the character attempts to gain a status

'''OnCharacterStatusApplied(CHARACTER:character, STATUS:status)''' 
Thrown when the character gains a status

'''OnCharacterStatusRemoved(CHARACTER:character, STATUS:status)''' 
Thrown when the character loses a status

'''OnItemStatusAttempt(ITEM:item, STATUS:status)''' 
Thrown when the item attempts to gain a status

'''OnItemStatus(ITEM:item, STATUS:status)''' 
Thrown when the item gains a status

'''OnItemStatusRemoved(ITEM:item, STATUS:status)''' 
Thrown when the item loses a status

'''OnStatusCreateVisuals(STATUS:status)''' 
Thrown when the item should create the visuals for this status

'''OnStatusDestroyVisuals(STATUS:status)''' 
Thrown when the item should destroy the visuals for this status

'''OnSight(CHARACTER:character)''' 
Thrown when the character sees another character

'''OnLostSight(CHARACTER:character)''' 
Thrown when the character doesn't see another character anymore

'''OnUseItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character uses an item

'''OnPickupItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character picks up an item

'''OnCharacterPreMovedItem(CHARACTER:source, ITEM:item)''' 
Event thrown just before a character moves an item. No difference whether it is in the world or in their inventory

'''OnCharacterMovedItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character moved an item

'''OnItemEquipped(CHARACTER:source, ITEM:item)''' 
Thrown when a character equips an item

'''OnItemUnequipped(CHARACTER:source, ITEM:item)''' 
Thrown when a character unequips an item

'''OnIterateCharacter(CHARACTER:character, FIXEDSTRING:eventId)''' 
Thrown by iterators

'''OnIterateItem(ITEM:source, FIXEDSTRING:eventId)''' 
Thrown by iterators

'''OnIterateCount(FIXEDSTRING:eventId, INTEGER:Count)''' 
Thrown by iterators after all iterations to inform you of the count.

'''OnStoryOverride(-)''' 
Throw when story overrides what the character was doing: teleport, movement, on/offstage

'''OnTriggerEnter(CHARACTER:character, ITEM:item, FIXEDSTRING:eventId)''' 
Thrown by a character or item entering an EventTrigger

'''OnTriggerLeave(CHARACTER:character, ITEM:item, FIXEDSTRING:eventId)''' 
Thrown by a character or item leaving an EventTrigger

'''OnEnemyChanged(CHARACTER:character, CHARACTER:newEnemy)''' 
Thrown when the character's currentenemy changes

'''OnTalentUnlocked(CHARACTER:character, TALENT:newTalent)''' 
Thrown when the character unlocks a new talent

'''OnTalentLocked(CHARACTER:character, TALENT:removedTalent)''' 
Thrown when the there's a talent removed from a character

'''OnCharacterClassChanged(CHARACTER:character, FIXEDSTRING:class)''' 
Thrown when the character changes class in the character creation screen

'''OnCharacterCreationStarted(CHARACTER:character, TRIGGER:creationPoint)''' 
Thrown when the character creation has started, and gives where the character should walk to

'''OnCharacterCreationStopped(CHARACTER:character)''' 
Thrown when the character creation has stopped

'''OnFunction(FIXEDSTRING:functionName)''' 
Throws an event on itself with the functionName. This is to fake function calls

'''OnSkillCast(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when the character casts a skill

'''OnSkillCombatComment(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when the character needs to make a comment

'''OnCharacterUsedSkillOnMe(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when you are hit by a skill from a character

'''OnItemUnlocked(ITEM: item, CHARACTER:character, ITEM:key)''' 
Thrown when an item gets unlocked by a character.

'''OnAutomatedDialogEnded(STRING:dialogName, INT:instanceID)''' 
Thrown when a automated dialog is ended for this speaker

'''OnAutomatedDialogStarted(STRING:dialogName, INT:instanceID)''' 
Thrown when a automated dialog is started for this speaker

'''OnDialogStarted(STRING:dialogName, INT:instanceID)''' 
Thrown when a dialog is started for this speaker

'''OnDialogEnded(STRING:dialogName, INT:instanceID)''' 
Thrown when a dialog is ended for this speaker

'''OnCrimeSensibleAction(FIXEDSTRING:regionID, INT:crimeID, FIXEDSTRING:reactionName, STRING:primaryDialog, CHARACTER:criminal1, CHARACTER:criminal2, CHARACTER:criminal3, CHARACTER:criminal4, INT:IsPrimary)''' 
Thrown when a character needs to perform a sensible action against criminals

'''OnCrimeInterrogationRequest(FIXEDSTRING:regionID, INT:crimeID, CHARACTER:criminal1, CHARACTER:criminal2, CHARACTER:criminal3, CHARACTER:criminal4, STRING:interrogationDialog)''' 
Thrown when a character needs to perform an interrogation against criminals

'''OnCrimeInvestigate(FLOAT3:CrimePosition, INT:crimeID)''' 
One NPC investigates a crimescene

'''OnCrimeAlarmed(FLOAT3:CrimePosition, INT:crimeID)''' 
All NPCs in a crimearea start looking around.

'''OnCrimeReturnToNormal(-)''' 
Investigation or Alarm timed out.

'''OnCrimeAborted(-)''' 
The game interrupted the sensible action of this NPC.

'''OnSplineControlPointReached(INT:Index, INT:EndReached, STRING:EventString)''' 
Thrown when a character reached a spline node.

''''OnFinishCalculationAi(-)''' 
Thrown when the calculation of the AI is finished.

'''OnGrenadeLand(INT:hitObstacle, CHARACTER:caster)''' 
Thrown when the grenades lands

'''FetchCharacterApplyStatusData(CHARACTER:character, STATUS:status) RETURN(LIST<STATUS>:removeStatuses, STATUS:applyStatus, INT:turns)''' 
Fetch from script which statuses to remove and apply.

'''FetchItemApplyStatusData(ITEM:item, STATUS:status) RETURN(LIST<STATUS>:removeStatuses, STATUS:applyStatus, INT:turns)''' 
Fetch from script which statuses to remove and apply.

'''FetchItemSkillOnDamage(INT:damage, DAMAGE_TYPE:damageType) RETURN(INT:hasSkill, SKILL_ID:skillID, INT:casterLevel)''' 
Fetch from script what skill to execute on damage.

'''FetchSkillScore(SKILL_ID:skillId, CHARACTER:sourceCharacter, CHARACTER:targetCharacter1, ITEM:targetItem1, FLOAT3:targetPosition1, CHARACTER:targetCharacter2, ITEM:targetItem2, FLOAT3:targetPosition2) RETURN(FLOAT:score) 
Fetch from script the score of a skill with set source and target

'''OnActivate(-)''' 
Thrown when a character/item activates

'''OnDeactivate(-)''' 
Thrown when a character/item deactivates

'''OnCharacterUsedSourcePoint(CHARACTER:character)''' 
Thrown when a character uses a source point

'''OnSkillAdded(CHARACTER:character, SKILL_ID:skillId, INT:learned)''' 
Thrown when a character learns a skill

'''OnSkillActivated(CHARACTER:character, SKILL_ID:skillId)''' 
Thrown when a character activates (=adds to memory) a skill

'''OnSkillDeactivated(CHARACTER:character, SKILL_ID:skillId)''' 
Thrown when a character deactivates (=removes from memory) a skill

'''OnItemFlagShared(FIXEDSTRING:eventName, ITEM:item, INT:newValue)''' 
Thrown when a dialog event is shared with an item

'''OnCharacterFlagShared(FIXEDSTRING:eventName, CHARACTER:character, INT:newValue)''' 
Thrown when a dialog event is shared with a character

'''OnItemOffStageChanged(CHARACTER:character, INT:offstage)''' 
Thrown when a character is set on/off stage

'''OnCharacterOffStageChanged(ITEM:item, INT:offstage)''' 
Thrown when a item is set on/off stage

'''OnCharacterTeleported(CHARACTER:target, CHARACTER:cause, FLOAT3:oldPosition, FLOAT3:newPosition, SKILL_ID:skillId)''' 
Thrown when a character gets teleported with a teleport skill

'''OnCombatTick(-)''' 
Thrown when this object ticks in combat. Only thrown for objects that don't get a turn.

'''OnCombatRoundStarted(INT:combatID, INT:roundID) 
Thrown when a round in a combat starts

'''OnReadyInCombat(CHARACTER:character, ITEM:item, INT:combatID)''' 
Thrown when a character or item is ready in combat

'''OnRegionLeft(CHARACTER:character, ITEM:item, FIXEDSTRING:region)''' 
Thrown when a character or item leaves a region

'''OnRegionEntered(CHARACTER:character, ITEM:item, FIXEDSTRING:region)''' 
Thrown when a character or item enters a region

'''OnRuneInserted(CHARACTER:character, ITEM:item, ITEMTEMPLATE:runeItemTemplate, INT:slot)''' 
Thrown when a <character> inserts a rune with roottemplate <runeItemTemplate> from an <item> at a specified <slot>

'''OnRuneRemoved(CHARACTER:character, ITEM:item, ITEM:rune, INT:slot)''' 
Thrown when a <character> removes a <rune> from an <item> at a specified <slot>

'''OnCharacterStartAttackObject(CHARACTER:defenderCharacter, ITEM:defenderItem, CHARACTER:attackerOwner, CHARACTER:attacker)''' 
Thrown when a character attacks a character or item with default attack

'''OnCharacterStartAttackPosition(FLOAT3:position, CHARACTER:attackerOwner, CHARACTER:attacker)''' 
Thrown when a character attacks a position with default attack

== INTERRUPTS ==

'''OnMovementFailed(FLOAT3:targetPos)''' 
Thrown when the reaction is interrupted by a move action failing

'''OnException(-)''' 
Thrown when the reaction is interrupted by an exception

'''OnBetterReactionFound(FIXEDSTRING:reactionName)''' 
Thrown when the reaction is interrupted by another reaction

'''OnNoReactionFound(-)''' 
Thrown when the reaction is interrupted because no reaction is valid

'''OnScriptDisabled(-)''' 
Thrown when the reaction is interrupted because the scriptcontroller is disabled

'''OnManualInterrupt(FIXEDSTRING:reactionName)''' 
Thrown when the reaction is interrupted using the interrupt action

'''OnRegionSwap(FIXEDSTRING:oldLevel, FIXEDSTRING:newLevel)''' 
Thrown when the reaction is interrupted by a region swap

= Divinity: Original Sin 2 Definitive Edition =
The following was added/changed for the Definitive Edition.

== CALLS ==
'''ItemDrop(ITEM:item)''' 
Drops an item from it's owner's inventory. Only characters are treated as owners.

'''RemoveSurfaceLayerAt(GAMEOBJECT|FLOAT3:target, INT:layer, FLOAT:radius)''' 
Removes surface (ground or cloud) at object/position. (Layer 0 for surface, otherwise - cloud) (Radius for cleanup)

'''SurfaceCreateLink(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 
Makes surfaces at 2 locations/positions interact as if they were adjacent.

'''SurfaceRemoveLink(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 
Stops surfaces at 2 distinctive locations/positions from interacting.

== QUERIES ==
'''AttributeGetDifficultyLevelMappedValue(FIXEDSTRING:difficulty, INT:level, OUT INT:levelMappedValue)''' 
Returns a level-mapped value of a primary attribute. (Difficulty = "Easy", "Normal" or "Hard")

'''CharacterGetCreationClass(CHARACTER:character, OUT FIXEDSTRING: class)''' 
During character creation returns character class. Fails outside of character creation.

'''CharacterGetEquippedItem(CHARACTER:character, FIXEDSTRING:slot, OUT ITEM:seatingItem)''' 
Returns item equipped into slot. (Slot = "Helmet", "Breast", "Leggings", "Weapon", "Shield", "Ring", "Ring2", "Belt", "Boots", "Gloves", "Amulet" or "Wings")

(CHANGED) '''CharacterInCreation(CHARACTER:character, OUT INT:CharacterIndex)''' 
Checks if character is in character creation currently. (CharacterIndex: assigned index of the player character during character creation)

UI Colors Reference Sheet

2018-12-16T20:46:24Z

LaughingLeader: Added hex code / samples for all RGBA colors

Below, you can find the color sheet for all engine-registered colors. 
There are several tables. All but the last table contain engine entries, used throughout the game for UI consistency, gameplay denotations (red = enemy,...),... 
These values are in RGBA format. 

 
The last table contains all registered colors used for text purposes. This table contains dialog colors, colors for status afflictions,... 
All of the [[Stats_Editor|Stats Editor]]'s FormatColor field values come from this table as well. 
These are defined in HEX format. 

 
{| class="wikitable sortable"
|-
! Base !! Color Value (HEX) !! Color Example !! Color Value (RGBA)
|-
| Black || #000000 || '''sample''' || (0.0, 0.0, 0.0, 1.0)
|-
| Blue || #0078FF || '''sample''' || (0.0, 0.470588, 1.0, 1.0)
|-
| Green || #00F27D || '''sample''' || (0.0, 0.94902, 0.490196, 1.0)
|-
| Red || #FF0200 || '''sample''' || (1.0, 0.00784314, 0.0, 1.0)
|-
| White || #FFFFFF || '''sample''' || (1.0, 1.0, 1.0, 1.0)
|-
| Yellow || #FFFF00 || '''sample''' || (1.0, 1.0, 0.0, 1.0)
|}

{| class="wikitable sortable"
|-
! General !! Color Value (HEX) !! Color Example !! Color Value (RGBA)
|-
| ActiveCharacter || #FFFFFF || '''sample''' || (1.0, 1.0, 1.0, 1.0)
|-
| AoO || #FF0100 || '''sample''' || (1.0, 0.00784314, 0.0, 1.0)
|-
| AreaInteract || #FFD400 || '''sample''' || (1.0, 0.831373, 0.0, 1.0)
|-
| Attack || #FF0200 || '''sample''' || (1.0, 0.00784314, 0.0, 1.0)
|-
| BackstabRegion || #FFFFFF || '''sample''' || (1.0, 1.0, 1.0, 1.0)
|-
| DefaultRangeOutlineColor || #4BA0FF || '''sample''' || (0.294118, 0.627451, 1.0, 1.0)
|-
| DefaultTaskColor || #FFD400 || '''sample''' || (1.0, 0.831373, 0.0, 1.0)
|-
| FallbackOutline || #FFFFFF || '''sample''' || (1.0, 1.0, 1.0, 1.0)
|-
| InvalidAction || #FF0200 || '''sample''' || (1.0, 0.00784314, 0.0, 1.0)
|-
| MaximumSkillRange || #CCCCCC || '''sample''' || (0.8, 0.8, 0.8, 1.0)
|-
| MoveFootstep || #FFFFFF || '''sample''' || (1.0, 1.0, 1.0, 1.0)
|-
| MoveTargetCircle || #FFFFFF || '''sample''' || (1.0, 1.0, 1.0, 1.0)
|-
| MoveTargetCross || #FFFFFF || '''sample''' || (1.0, 1.0, 1.0, 1.0)
|-
| MutedEffect || #00FFFF || '''sample''' || (0.0, 1.0, 1.0, 1.0)
|-
| OutlineInterract || #FFD400 || '''sample''' || (1.0, 0.831373, 0.0, 1.0)
|-
| OutlineMoveItem || #FFFFFF || '''sample''' || (1.0, 1.0, 1.0, 1.0)
|-
| OutlineMoveItemDestination || #FFFF00 || '''sample''' || (1.0, 1.0, 0.0, 1.0)
|-
| PeaceOutline || #FFFFFF || '''sample''' || (1.0, 1.0, 1.0, 1.0)
|}

{| class="wikitable sortable"
|-
! Arena Team !! Color Value (HEX) !! Color Example !! Color Value (RGBA)
|-
| ArenaTeam1 || #318666 || '''sample''' || (0.192157, 0.52549, 0.4, 1.0)
|-
| ArenaTeam2 || #3C6983 || '''sample''' || (0.235294, 0.411765, 0.513726, 1.0)
|-
| ArenaTeam3 || #85662F || '''sample''' || (0.521569, 0.4, 0.184314, 1.0)
|-
| ArenaTeam4 || #87365C || '''sample''' || (0.529412, 0.211765, 0.360784, 1.0)
|}

{| class="wikitable sortable"
|-
! Skill School !! Color Value (HEX) !! Color Example !! Color Value (RGBA)
|-
| SchoolAir || #7478DC || '''Aerotheurge''' || (0.458824, 0.47451, 0.831373, 0.85098)
|-
| SchoolEarth || #AA895B || '''Geomancer''' || (0.666667, 0.537255, 0.356863, 0.85098)
|-
| SchoolFire || #C76537 || '''Pyrokinetic''' || (0.780392, 0.396078, 0.215686, 0.85098)
|-
| SchoolNecromancy || #9A5085 || '''Necromancer''' || (0.603922, 0.313726, 0.521569, 0.85098)
|-
| SchoolPolymorph || #FFB811 || '''Polymorph''' || (0.960784, 0.721569, 0.0705882, 0.85098)
|-
| SchoolRanger || #5A9646 || '''Huntsman''' || (0.352941, 0.588235, 0.27451, 0.85098)
|-
| SchoolRogue || #566C6C || '''Scoundrel''' || (0.337255, 0.423529, 0.423529, 0.85098)
|-
| SchoolSource || #6EB09D || '''Source''' || (0.431373, 0.690196, 0.615686, 0.85098)
|-
| SchoolSummoning || #9440B3 || '''Summoning''' || (0.580392, 0.25098, 0.701961, 0.85098)
|-
| SchoolWarrior || #A11919 || '''Warfare''' || (0.631373, 0.0980392, 0.0980392, 0.85098)
|-
| SchoolWater || #579CCA || '''Hydrosophist''' || (0.341176, 0.611765, 0.792157, 0.85098)
|}

{| class="wikitable sortable"
|-
! Alignments !! Color Value (HEX) !! Color Example !! Color Value (RGBA)
|-
| Party_Base || #00A2FD || '''sample''' || (0.0, 0.639, 0.992, 1.0)
|-
| Party_Light || #6CCBFF || '''sample''' || (0.424, 0.796, 1.0, 1.0)
|-
| Ally_Base || #11D77A || '''sample''' || (0.067, 0.847, 0.478, 1.0)
|-
| Ally_Light || #80FFC3 || '''sample''' || (0.502, 1.0, 0.765, 1.0)
|-
| Neutral_Base || #F3D347 || '''sample''' || (0.953, 0.827, 0.278, 1.0)
|-
| Neutral_Light || #FFEA8C || '''sample''' || (1.0, 0.918, 0.549, 1.0)
|-
| Enemy_Base || #D7001F || '''sample''' || (0.843, 0.0, 0.122, 1.0)
|-
| Enemy_Light || #FF001F || '''sample''' || (1.0, 0.302, 0.404, 1.0)
|-
| Item_Base || #F3D347 || '''sample''' || (0.953, 0.827, 0.278, 1.0)
|-
| Item_Light || #FFEA8C || '''sample''' || (1.0, 0.918, 0.549, 1.0)
|}

{| class="wikitable sortable"
|-
! Text !! Color Value (HEX) !! Color Example
|-
| White || #FFFFFF || '''sample'''
|-
| DarkGray || #454545 || '''sample'''
|-
| Gray || #A8A8A8 || '''sample'''
|-
| LightGray || #DBDBDB || '''sample'''
|-
| Red || #C80030 || '''sample'''
|-
| Blue || #188EDE || '''sample'''
|-
| DarkBlue || #004672 || '''sample'''
|-
| LightBlue || #CFECFF || '''sample'''
|-
| Green || #40B606 || '''sample'''
|-
| PoisonGreen || #00AA00 || '''sample'''
|-
| Yellow || #FCD203 || '''sample'''
|-
| Orange || #FF9600 || '''sample'''
|-
| Pink || #FFC3C3 || '''sample'''
|-
| Purple || #7F00FF || '''sample'''
|-
| Brown || #B97A57 || '''sample'''
|-
| Gold || #C7A758 || '''sample'''
|-
| Black || #000000 || '''sample'''
|-
| Normal || #FFFFFF || '''sample'''
|-
| Storyitem || #D040D0 || '''sample'''
|-
| Shadow || #797980 || '''sample'''
|-
| Poison || #65C900 || '''sample'''
|-
| Earth || #7F3D00 || '''sample'''
|-
| Air || #7D71D9 || '''sample'''
|-
| Water || #4197E2 || '''sample'''
|-
| Fire || #FE6E27 || '''sample'''
|-
| Source || #46B195 || '''sample'''
|-
| Decay || #B823CB || '''sample'''
|-
| Polymorph || #F7BA14 || '''sample'''
|-
| Ranger || #81AB00 || '''sample'''
|-
| Rogue || #639594 || '''sample'''
|-
| Summoner || #7F25D4 || '''sample'''
|-
| Void || #73F6FF || '''sample'''
|-
| Warrior || #DA2512 || '''sample'''
|-
| Special || #C9AA58 || '''sample'''
|-
| Healing || #97FBFF || '''sample'''
|-
| Charm || #FFB8B8 || '''sample'''
|-
| Reputation || #FFAB00 || '''sample'''
|-
| Karma || #7F00FF || '''sample'''
|-
| Stats_Off_Def || #411600 || '''sample'''
|-
| Stats_LvlUp || #007431 || '''sample'''
|-
| Stats_Greyed_Out || #403625 || '''sample'''
|-
| Stat_Boosted || #00547F || '''sample'''
|-
| Dialog_NoPlayer || #FFFFFF || '''sample'''
|-
| Dialog_Peer_Owns_Player || #9A6A46 || '''sample'''
|-
| Dialog_Peer_Not_Owns_Player || #745035 || '''sample'''
|-
| Dialog_Player_Is_Enemy || #AA3938 || '''sample'''
|-
| Dialog_Player_Not_Popular || #ED9D07 || '''sample'''
|-
| Dialog_Player_Neutral || #FCD203 || '''sample'''
|-
| Dialog_Player_Popular || #88A25B || '''sample'''
|-
| Dialog_Player_Super_Popular || #34789C || '''sample'''
|-
| Rps_Charm || #D66565 || '''sample'''
|-
| Rps_Intimidate || #D85B00 || '''sample'''
|-
| Rps_Reason || #E4CE93 || '''sample'''
|-
| Illegal_Action || #CD1F1F || '''sample'''
|-
| PlayerColor_Green || #318666 || '''sample'''
|-
| PlayerColor_Blue || #3C6983 || '''sample'''
|-
| PlayerColor_Yellow || #85662F || '''sample'''
|-
| PlayerColor_Red || #87365C || '''sample'''
|-
| Sticky || #F1D466 || '''sample'''
|-
| TutorialKey || #008858 || '''sample'''
|}

Talk:Scripting

2018-12-11T18:10:49Z

LaughingLeader: Added a section for typo/mistake (requests for corrections)

=== Mistakes/Typos ===

In the section "CHECK or IF", ACTIONS needs to be declared after the INTERRUPT, above Reset().

[[User:LaughingLeader|LaughingLeader]] ([[User talk:LaughingLeader|talk]]) 19:10, 11 December 2018 (CET)

=== Misc ===

Some very useful information here. I'm slightly confused about the purpose of SCRIPTFRAMES. It would be nice to see an example of one, including the Osiris code. Also an example of a LIST in action would be nice. I also think the example EVENT is not super helpful, since most people aren't going to know what the archetypes are.

I also find the Behavior example confusing. It looks like maybe there's a ! on the second condition (for dangerous surfaces), that shouldn't be there?

Under common mistakes there's CHECK or IF. Are there situations where you would use IF over CHECK in behavior?

Another common mistake I think could be checking things in the wrong order. Something like:

IsGreaterThen(_Vitality,.5)
CharacterGetStat(_Vitality,__Me,Vitality)

(I mean, that is a mistake, right?)

Will DebugText print the text exactly as you put it in? Like printing out the float value 0.47 exactly as "0.47"?

Going over types of variables (INT, FLOAT, FIXEDSTRING, STATUS, CHARACTERTEMPLATE, etc.) here or somewhere else would be useful too.

Character and Item Script Triggers, Calls, and Queries

2018-10-01T02:21:38Z

LaughingLeader: Added the optional notify parameter to CharacterRemoveStatus.

This is a list of almost every character and item script event trigger, call, and query. An event is what triggers the script, and always begin with ''On''. Queries provide information and are always inside an ''IF'' or ''CHECK.'' Calls are actions that are always after THEN.

CharScript/ItemScript Functions

= Divinity: Original Sin 2 Classic=
== CALLS ==

'''Set(OUT OBJECT:variable, OBJECT:value)'''

Set the value of a variable

'''SetVar(CHARACTER|ITEM:object, FIXEDSTRING:variableName, OBJECT:value)'''

Set the value of a global variable

'''Cast(OUT OBJECT variable, OBJECT value)'''

Casts the value to the variable

'''Print(OUT STRING:output, STRING:text)'''

Prints the text to the output with possible parameters: [1], [2], ...

'''Add(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT|FLOAT3:value)'''

Adds both values and stores it in the first variable

'''Subtract(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT|FLOAT3:value)'''

Subtracts both values and stores it in the first variable

'''Multiply(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT:value)'''

Multiplies both values and stores it in the first variable

'''Divide(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT:value)'''

Divides both values and stores it in the first variable

'''Abs(INOUT INT|FLOAT:variable)'''

Takes the absolute value of a variable

'''Clamp(INOUT INT|FLOAT:variable, INT|FLOAT:min, INT|FLOAT:max)'''

Clamps a variable between min and max

'''GetRandom(OUT OBJECT:variable, OBJECT:value, OBJECT:value, OBJECT:value)'''

Fills in the variable with random one of the values.

'''GetWeightedRandom(OUT OBJECT:variable, OBJECT:value, INT|FLOAT:weight, ...)'''

Gets a weighted random of the given values!

'''GetRandomBetween(OUT INT|FLOAT:variable, INT|FLOAT:min, INT|FLOAT:max)'''

Gets a random value between min and max (both included)

'''GetRandomPositionInTrigger(OUT FLOAT3:variable, TRIGGER:areaTrigger)'''

Get a random position in a trigger area

'''GetElement(OUT OBJECT:variable, INT:index, OBJECT:value, OBJECT:value, OBJECT:value)'''

Fills in the variable with the index one of the values (starting from 0)

'''SetPriority(FIXEDSTRING:reactionName, INT:priority)'''

Changes the priority of a reaction. Priority 0 and below are not executed!

'''DelayReaction(FIXEDSTRING:reactionName, FLOAT:timeInSeconds)'''

The reaction will not be chosen for the specified time

'''SetScriptFrame(CHARACTER:character, FIXEDSTRING:frame)'''

Sets the scriptframe on the character.

'''ClearScriptFrame(CHARACTER:character)'''

Clears the scriptframe on the character.

'''Goto(FIXEDSTRING:labelName)'''

Jumps to the label. Two label names are built-in: "Start" for the first instruction of the reaction, and "End" for the last one.

'''GotoIfEqual(OBJECT:variable, OBJECT:value, FIXEDSTRING:labelName)'''

Jumps to the label if the 2 objects are equal

'''GotoRand(FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName)'''

Jumps to a random label in the list

'''CreatePuddleAt(GAMEOBJECT|FLOAT3:target, SURFACE:type, INT:cellAmountMin, INT:cellAmountMax, INT:growAmountMin, INT:growAmountMax, )'''

Spawn a puddle at the target's position for a certain lifetime (in turns)

'''CreateSurfaceAt(GAMEOBJECT|FLOAT3:target, SURFACE:type, FLOAT:radius, INT:lifeTime[, GAMEOBJECT:owner])'''

Spawn a surface at the target's position for a certain lifetime (in turns)

'''CreateSurfaceInPolygon(GAMEOBJECT:owner, SURFACE:type, FLOAT:duration, FLOAT:growTimer, INT:growStep, GAMEOBJECT|FLOAT3:point1, GAMEOBJECT|FLOAT3:point2, GAMEOBJECT|FLOAT3:point3, ...)'''

Spawn a polygon surface at the target's position. Grows <growStep> every <growTimer>.

'''CreateSurfaceInAreaTrigger(GAMEOBJECT:owner, SURFACE:type, FLOAT:duration, FLOAT:growTimer, INT:growStep, TRIGGER:areaTrigger)'''

Spawn a surface within <areaTrigger>. Grows <growStep> every <growTimer>.

'''CreateConeSurfaceAt(GAMEOBJECT|FLOAT3:start, GAMEOBJECT|FLOAT3:target, SURFACE:type, FLOAT:radius, FLOAT:angle, FLOAT:duration)'''

Spawn a Cone surface at the target's position

'''PlayEffectAt(GAMEOBJECT|FLOAT3:target, STRING:effectName)'''

Plays an effect at the target's position

'''PlayLoopEffectAt(OUT INT64:effectHandle, GAMEOBJECT|FLOAT3:target, STRING:effectName)'''

Plays an effect at the target's position

'''ExplodeAt(GAMEOBJECT|FLOAT3:target, SKILL:projectileSkill, [INT:casterLevel=-1, CHARACTER|ITEM:cause])'''

Trigger an explosion of a projectile skill at the target's position. The cause will trigger NPC behavior as if the cause casted the projectile

'''DisplayText(CHARACTER|ITEM:target, FIXEDSTRING:text, FLOAT:timeInSeconds)'''

Displays text above the character/item for a certain amount of time. It will replace the current text, including dialogtext

'''DisplayCombatInfoText(CHARACTER|ITEM:target, FIXEDSTRING:text, FLOAT:timeInSeconds)'''

Displays text above the character/item for a certain amount of time. It will replace the current text, including dialogtext

'''StatusText(CHARACTER|ITEM:target, FIXEDSTRING:text)'''

Adds statustext above the character/item for a short amount of time. Will not replace texts or dialogtexts

'''DebugText(CHARACTER|ITEM:target, STRING:text)'''

Adds debugtext above the character/item for a short amount of time.

'''CombatLogText(CHARACTER|ITEM:target, FIXEDSTRING:text, INT:filterID, INT:broadcastID)'''

Adds combatlog text inside the combat log window. Color-/SizeFormatting should already be applied, if not color and size of the string will be NORMAL. filterID determines what filter shows/hides the text. broadcastID determines who will be able to see the message (0 hearingrange. 1 party. 2 all)

'''Log(STRING:text, ...)'''

Log's the the scriptlog. (for debugging purposes)

'''Output(STRING:text, ...)'''

Pass text with optional parameters to the output panel (e.g. Output("An int [1]", INT:10))

'''Assert(STRING:text, ...)'''

Pass text with optional parameters to display as an assert message (e.g. Assert("This number is wrong: [1]", INT:666))

'''Label(FIXEDSTRING:name)'''

Marks this line as a label where Goto actions can jump to

'''StartTimer(FIXEDSTRING:timerName, FLOAT:timeInSeconds, INT:repeatCount)'''

Start a timer which will throw the timer event. Set repeatcount < 0 for a permanent timer.

'''StopTimer(FIXEDSTRING:timerName)'''

Stop a timer which will throw the timer event

'''DialogStart(OUT INT:instanceId, STRING:dialog, CHARACTER|ITEM:target, CHARACTER|ITEM:target, CHARACTER|ITEM:target, CHARACTER|ITEM:target)'''

Start a dialog between the targets. You can specify fewer targets than the maximum number.

{{warning|Starting a dialog from behaviour script will always start it as an [[Dialog_editor#Automated|Automated Dialog]]. Interactive dialogs can only be started from [[Osiris]].}}

'''DialogRequestStop(CHARACTER|ITEM:speaker, STRING:dialog)'''

Stops a certain dialog on a certain speaker

'''Check(-)'''

Reevaluate the conditions in the CHECK section of this reaction

'''Reset(-)'''

Resets the current reaction. It will start from the beginning again

'''Interrupt(FIXEDSTRING:reactionName)'''

Interrupt the reaction.

'''GlobalSetEvent(FIXEDSTRING:eventName)'''

Sets a global event. Scripts and Story can catch it.

'''GlobalClearEvent(FIXEDSTRING:eventName)'''

Clears a global event. Scripts and Story can catch it.

'''StopLoopEffect(INT64:fxHandle)'''

Stops a looping effect

'''IterateItems(FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item. If you pass a tag, it has to have that tag.

'''IterateItemsNear(GAMEOBJECT:source, FLOAT:radius, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item in range. If you pass a tag, it has to have that tag.

'''IterateItemsOnObject(CHARACTER|ITEM:source, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item standing on the source. If you pass a tag, it has to have that tag.

'''IterateParty(FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, CHARACTER:partyMember, FIXEDSTRING:tag])'''

Launch iterate event for each member of all parties. If you pass a party member only members of that party will be considered. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharacters(FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersNear(GAMEOBJECT:source, FLOAT:radius, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character in range. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersOnObject(CHARACTER|ITEM:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''
Launch iterate event for each character standing on the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersInCombat(CHARACTER|ITEM:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character in combat with the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateHostilesFor(CHARACTER:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character who is targetting the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''SpawnCharacter(OUT CHARACTER:result, CHARACTERTEMPLATE:rootTemplate, GAMEOBJECT|FLOAT3:position, INT:playSpawn, [INT:isSummon=0, CHARACTER:summonOwner=null, INT:overrideLevel=-1])'''

Spawns a character

'''SpawnItem(ITEMTEMPLATE:rootTemplate,GAMEOBJECT|FLOAT3:position, OUT ITEM:result)'''

Spawns an item

'''ShootLocalProjectile(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,FLOAT3:direction,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Spawns a projectile at the source (with offset, can be null) shooting at the target

'''ShootLocalProjectileAt(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,GAMEOBJECT|FLOAT3:target,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Spawns a projectile at the source (with offset, can be null) shooting at the target

'''ShootWorldProjectile(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,FLOAT3:direction,[INT:casterLevel])'''

Spawns a projectile at worldPos shooting at the target. Source can be null.

'''ShootWorldProjectileAt(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,GAMEOBJECT|FLOAT3:target,[INT:casterLevel])'''

Spawns a projectile at worldPos shooting at the target. Source can be null.

'''ShootLocalCone(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,FLOAT3:direction,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Shoots a cone from source (with offset, can be null) in a direction

'''ShootLocalConeAt(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,GAMEOBJECT|FLOAT3:target,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Shoots a cone from source (with offset, can be null) at the target

'''ShootWorldCone(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,FLOAT3:direction,[INT:casterLevel])'''

Shoots a cone from worldPos in a direction. Source can be null.

'''ShootWorldConeAt(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,GAMEOBJECT|FLOAT3:target,[INT:casterLevel])'''

Shoots a cone from worldPos at the target. Source can be null.

'''SetVisible(CHARACTER|ITEM:object, INT:visible)'''

Sets a character or item visible or not.

'''RotateY(INOUT FLOAT3:vector, FLOAT:degrees)'''

Rotate the vector around the Y-axis for a certain angle (in degrees)

'''SetHealth(CHARACTER|ITEM:target, FLOAT:percent)'''

Set a characters or items health on the given percentage. (percentage between 0 and 1)

'''PlaySound(CHARACTER|ITEM:target, STRING:soundEvent)'''

Plays a sound event at the target

'''PlayMusicForEveryone(STRING:musicEvent)'''

Plays a music event on all the clients

'''PlayMusicOnCharacter(CHARACTER:target, STRING:musicEvent)'''

Plays a music event on a character for all peers (3D)

'''PlayMusicForPeer(CHARACTER:target, STRING:musicEvent)'''

Plays a music event on the peer of the character

'''PlayMusicForPeerWithInstrument(CHARACTER:target, CHARACTER:charInstrument, STRING:musicEvent)'''

Plays a music event on the peer of the character concated with _INSTRUMENT

'''SetX(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the X component of the FLOAT3

'''SetY(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the Y component of the FLOAT3

'''SetZ(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the Z component of the FLOAT3

'''SetAtmosphere(FIXEDSTRING:atmosphereTriggerUUID, FIXEDSTRING:atmosphere)'''

Changes the atmosphere of the trigger

'''ResetAtmosphere(FIXEDSTRING:atmosphereTriggerUUID)'''

Resets the atmosphere of the trigger

'''AddStatusInfluence(CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1], [INT:force=1])'''

Adds the status influence strength on the object.

'''RemoveStatusInfluence(CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1])'''

Removes the status influence strength on the object.

'''AddTemporaryStatusInfluence(CHARACTER|ITEM:source, CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1])'''

Adds a temporary status influence strength on the object.. It will be gone in a few seconds if it's not set again

'''CallFunction(FIXEDSTRING:functionName)'''

Calls a function with the ID

'''SetMaterial(CHARACTER|ITEM:object, FIXEDSTRING:materialUUID, INT:duration, INT:applyOnBody, INT:applyOnArmor, INT:applyOnWeapon[)'''

Changes the material of the object for a set time (in turns), -1 is infinite. applyNormalMap: Copy the original materials normal map

'''TeleportTo(CHARACTER|ITEM:object, GAMEOBJECT|FLOAT3:target, [INT:Force=0])'''

Teleport object to or near the target

'''Transform(CHARACTER|ITEM:object, CHARACTERTEMPLATE|ITEMTEMPLATE:root [, FIXEDSTRING:fx, INT:replaceScripts=1, OUT FLOAT:currentHP])'''

Transforms <object> using <root>, returns <currentHP>, plays <fx>.

'''SaveGame(FIXEDSTRING:saveGameName)'''

Save the savegame with name <saveGameName>

'''LoadGame(FIXEDSTRING:saveGameName)'''

Load the savegame with name <saveGameName>

'''LoadLevel(FIXEDSTRING:levelName)'''

Load the level with name <levelName>

'''KillCombat(CHARACTER:character)'''

Kill all the enemies in the combat which contains <character>

'''SetTag(CHARACTER|ITEM:object, FIXEDSTRING:tag)'''

Sets the Tag on the Object

'''ClearTag(CHARACTER|ITEM:object, FIXEDSTRING:tag)'''

Clears the Tag on the Object

'''SetGlobalFlag(FIXEDSTRING:flagname)'''

Sets the Global Flag

'''ClearGlobalFlag(FIXEDSTRING:flagname)'''

Clears the Global Flag

'''SetFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Sets the Flag on the Object

'''ClearFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the Object

'''SetUserFlag(CHARACTER:object, FIXEDSTRING:flagname)'''

Sets the Flag on the user's characters

'''ClearUserFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the user's characters

'''SetPartyFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Sets the Flag on the party's characters

'''ClearPartyFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the party's characters

'''StartVoiceBark(STRING:barkName, CHARACTER:character)'''

Start a voicebark on character

'''ConfrontationDone(INT: CrimeID, CHARACTER:lead, CHARACTER:criminal, ...)'''

Resolve the crime with id CrimeID for the specified criminals

'''CrimesceneInvestigationDone(CHARACTER:investigator)'''

Crimescene is considered investigated by this NPC, start looking for culprits

'''ListAdd(LIST<OBJECT>:list, OBJECT:entry)'''

Add <entry> at the back of <list>

'''ListRemove(LIST<OBJECT>:list, INT:index)'''

Remove the entry at <index> of <list>

'''ListSet(LIST<OBJECT>:list, INT:index, OBJECT:entry)'''

Set the entry at <index> of <list> to <entry>

'''ListClear(LIST<OBJECT>:list)'''

Remove all entries of <list>

'''EndTurn(CHARACTER|ITEM:Target)'''

Ends the object's current turn

'''SetCanFight(CHARACTER|ITEM:entity, INT:enabled[, INT:wholeGroup=0])'''

Enables/Disables the fact if the entity can fight. Optional for the whole group

'''SetCanJoinCombat(CHARACTER|ITEM:entity, INT:enabled[, INT:wholeGroup=0])'''

Enables/Disables the fact if the entity can join combats. Optional for the whole group

'''SetIsBoss(CHARACTER|ITEM:entity, INT:enabled)'''

Enables/Disables the fact if the entity is a boss.

'''GetAIHintTriggers(OUT LIST<TRIGGER>:triggers[, [LIST]FIXEDSTRING:tags, INT:needsAllTags = -1)'''

Returns all AIHintAreaTriggers in <triggers>. Uses contraints if set.

'''SetCombatTimeout(CHARACTER|ITEM:entity, FLOAT:timer)'''

Overwrites the entity's combat timeout check.

'''ResetCombatTimeout(CHARACTER|ITEM:entity)'''

Resets the entity's combat timeout check.

'''EnterCombat(CHARACTER|ITEM:source, CHARACTER|ITEM:target)'''

Enters combat with target

'''LeaveCombat(CHARACTER|ITEM:source)'''

Leaves the combat

'''SetFaction(CHARACTER|ITEM:target, FIXEDSTRING:faction)'''

Changes the faction of a character or item

'''SetInvulnerable(CHARACTER|ITEM:target, INT:bool)'''

Makes the character or item invulnerable or not. (Allow damage)

'''JumpToTurn(CHARACTER|ITEM:Target)'''

Jumps to targets turn (ends the current turn)

'''Sleep(FLOAT:timeInSeconds)'''

Sleeps for a certain amount of time

'''CharacterAttack(CHARACTER|ITEM|FLOAT3:target [,INT:alwaysHit])'''

Moves in weapon range and attacks the target

'''CharacterAttackWithoutMove(CHARACTER|ITEM|FLOAT3:target [,INT:alwaysHit])'''

Attacks the target without checking weaponranges and without moving

'''CharacterMoveTo(GAMEOBJECT|FLOAT3:target, [INT:running=0, INT:shouldArrive=0, INT:longPath=0, FLOAT:minDistance=1.5, FLOAT:maxDistance=minDistance+2.5])'''

Move to the target. Set shouldArrive to 1 if you want a guaranteed move. (teleports on fail)

'''CharacterAiMove(FLOAT3:target, CHARACTER:targetCharacter, ITEM:targetItem)'''

Moves to the target, calculated by the AI. Should only be used with results from the AI!

'''CharacterMoveInRange(GAMEOBJECT|FLOAT3:target, FLOAT:rangeMin, FLOAT:rangeMax, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within a certain range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveInWeaponRange(GAMEOBJECT|FLOAT3:target, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within weapon range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveInSkillRange(GAMEOBJECT|FLOAT3:target, SKILL:skill, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within skill range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveOutOfSight(FLOAT:angle)'''

Move out of screen

'''CharacterPlayAnimation(FIXEDSTRING:animation [, INT:exitOnFinish=1, INT:waitForCompletion=1])'''

Plays a certain animation ExitOnFinish means if the exit will kill itself after it was played (revert back to still)

'''CharacterStopAnimation(-)'''

Stops all animations.

'''CharacterPickUpItem(ITEM:item)'''

Moves close enough to the item if necessary and picks it up

'''CharacterUseItem(ITEM:item [, INTEGER:LongPath])'''

Moves close enough to the item if necessary and uses it

'''CharacterMoveItem(ITEM:item, INTEGER:ignoreWeight, INTEGER:ignoreAPCost [, INTEGER:ignoreDangerousSurfaces=1, INT:amount=-1, GAMEOBJECT|FLOAT3:destination])'''

Moves close enough to the item if necessary and moves it to the destination. Will try to find a destination if not supplied.

'''CharacterAddSkill(CHARACTER:character, SKILL:skill[, INT:ShowNotification=0])'''

Adds <skill> to <character>

'''CharacterRemoveSkill(CHARACTER:character, SKILL:skill)'''

Removes <skill> from <character>

'''CharacterUseSkill(SKILL:skill, GAMEOBJECT|FLOAT3:target [, GAMEOBJECT|FLOAT3:target2, ITEM:skillItem, INT:ignoreHasSkill=0])'''

Cast a skill

'''CharacterAppearAt(GAMEOBJECT|FLOAT3:target, INT:playspawn)'''

Appear at the target

'''CharacterAppearOutOfSightTo(GAMEOBJECT:target, FLOAT:angle, INT:playspawn)'''

Appears out of sight to the players from a certain angle while being able to reach target

'''CharacterAppearOnTrailOutOfSightTo(CHARACTER:target, FLOAT:angle, INT:playspawn)'''

Appears out of sight to the players, on its previous locations, from a certain angle while being able to reach target

'''CharacterDisappear(FLOAT:angle[, INTEGER:isRunning=0])'''

Move out of screen and go of stage, will run if <isRunning> is not 0

'''CharacterSetOffStage(-)'''

Set Off Stage

'''CharacterSetOnStage(-)'''

Set On Stage

'''CharacterLookAt(GAMEOBJECT|FLOAT3|SPLINE:target[, INT:snapToTarget=0, INT:angleTolerance=0])'''

Rotates the character to look at the target (Closest spline point in case of a spline).

'''CharacterLookFrom(GAMEOBJECT|SPLINE:target[, INT:snapToTarget=0])'''

Rotates to the character so it has the same rotation as the target (Closest spline point in case of a spline).

'''CharacterFollow(CHARACTER:target, FLOAT:durationInSeconds, INT:run)'''

Follow the target for a certain time

'''CharacterFollowOwnerOrLeader(FLOAT:durationInSeconds, INT:run)'''

Follow the leader or owner for a certain time

'''CharacterWander(FLOAT|TRIGGER:range, FLOAT:durationInSeconds [, INT:run, GAMEOBJECT:anchor])'''

Wander around for a certain time

'''CharacterSwitchWeaponType(WEAPON:type)'''

If necessary switch to the new weapon type

'''CharacterFleeFrom(RELATION:relation, FLOAT:range)'''

Run away from certain characters if necessary
'''
CharacterFleeFromSurface(SURFACE:surface)'''

Run away from a certain surface if necessary

'''CharacterFleeFromDangerousSurface(-)'''

Run away from a dangerous surfaces if necessary

'''CharacterAddSourcePoints(CHARACTER:character, INT:amount)'''

Adds x source points (x can be negative to substract)

'''CharacterDie(CHARACTER:character[, DEATH:type=DoT])'''

Kills the character

'''CharacterHeal(CHARACTER:character, FLOAT:percentage)'''

Heals the character

'''CharacterConsume(CHARACTER:character, POTION:potion)'''

Makes the character consume a potion. Doesn't cost any AP and will just execute the result of the potion.

'''CharacterDisableAllCrimes(CHARACTER:target)'''

Disables all generic behaviours for <target>.

'''CharacterEnableAllCrimes(CHARACTER:target)'''

Enables all generic behaviours for <target>.
'''
CharacterEnableCrime(CHARACTER:target, STRING:crime, ...)'''

Enables the specified generic behaviours for <target>.

'''CharacterDisableCrime(CHARACTER:target, STRING:crime, ...)'''

Disables the specified generic behaviours for <target>.

'''CharacterSetLongInvestigationDuration(CHARACTER:target)'''

Doubles the time it takes for the investigation to time out. Use this when the character needs to move a long path before investigating.

'''CharacterAiCalculate(-)'''

Calculate the AI of the character

'''CharacterAiStopCalculate(-)'''

Stop the calculation of the AI of the character

'''CharacterAiFinishMoveSkill(-)'''

Finish the current MoveSkill.
'''
CharacterAiAddInterestingItem(CHARACTER:character, ITEM:item)'''

Make it interesting for the AI to destroy that Item

'''CharacterAiRemoveInterestingItem(CHARACTER:character, ITEM:item)'''

Make it no longer interesting for the AI to destroy that Item

'''CharacterSetArchetype(CHARACTER:character, ARCHETYPE:archetype)'''

Sets the archetype of the character, used in AI calculations

'''CharacterSetStoryNPC(CHARACTER:character, INT:bool)'''

Makes the character storyNPC or not.
'''
CharacterAddActionPoints(CHARACTER:character, INT:amount)'''

Give character some action points

'''CharacterSetImmortal(CHARACTER:character, INT:bool)'''

Makes the character immortal or not. (Allow dying)

'''CharacterPlayEffect(CHARACTER:character, STRING:effect [,FIXEDSTRING:boneName])'''

Plays an effect on the character and it follows the character

'''CharacterPlayLoopEffect(OUT INT64:effectHandle, CHARACTER:character, STRING:effect [,FIXEDSTRING:boneName])'''

Plays a looping effect on the character and it follows the character

'''CharacterEvent(CHARACTER:character, STRING:eventName)'''

Throw a character event which you can catch in scripts and story

'''CharacterItemEvent(CHARACTER:character, ITEM:item, STRING:eventName)'''

Throw a character/item event which you can catch in scripts and story

'''CharacterCharacterEvent(CHARACTER:character1, CHARACTER:character2, STRING:eventName)'''

Throw a character/character event which you can catch in scripts and story

'''CharacterSetRelationIndivToIndiv(CHARACTER:source, CHARACTER:target, INT:relation)'''

Changes the relationship between 2 characters.
'''
CharacterForceUpdate(INT:forceUpdate)'''

Makes sure the attached character is always being update or not.
'''
CharacterSetEnemy(CHARACTER:character, CHARACTER:enemy)'''

Sets the current enemy of character

'''CharacterApplyStatus(CHARACTER:character, STATUS:statusId [, INT:turns=null, INT:force=0])'''

Applies the status to the character When turns is -1 it's a permanent status When turns is -2 it's a keep alive status (which means it will die if it's not applied again within 1 second)

'''CharacterRemoveStatus(CHARACTER:character, STATUS:statusId [, STATUS:reasonStatusID=null, INT:notify=1])'''

Removes the status from the character

'''CharacterDestroy(CHARACTER:character)'''

Destroys the character

'''CharacterSetCanSpotSneakers(CHARACTER:character, INT:enabled)'''

Enables/Disables the fact if the character can spot sneaking characters.

'''CharacterSetAttackOfOpportunity(CHARACTER:character, INT:enabled)'''

Enables/Disables the fact if the character can do attack of opportunities.

'''CharacterResurrect(CHARACTER:character [, INT:Percentage = 100])'''

Resurrects the character at [2]% health.

'''CharacterAddToInventory(CHARACTER:character, FIXEDSTRING:itemStatsObject[, INT:amount, INT:showInTrade=1])'''

Add the item to the character

'''CharacterRemoveFromInventory(CHARACTER:character, FIXEDSTRING:itemStatsObject[, INT:amount])'''

Remove the item from the character. If Amount is -1, then all are removed

'''CharacterDrinkPotion(FIXEDSTRING:statID)'''

Makes the character drink a potion from the inventory.

'''CharacterSetAnimationOverride(CHARACTER:character, FIXEDSTRING:animation)'''

Sets an animation override, only walk/run/die animations can override it.

'''CharacterUseActionPoints(CHARACTER:character, INT:amount [, OUT INT:succeeded])'''

Uses x action points

'''CharacterAddTreasureTable(CHARACTER:character, FIXEDSTRING:treasureTable)'''

Adds <treasureTable> to the treasure list of <character>

'''CharacterRemoveTreasureTable(CHARACTER:character, FIXEDSTRING:treasureTable)'''

Removes <treasureTable> from the treasure list of <character>

'''CharacterClearTreasureTables(CHARACTER:character)'''

Removes all treasure tables from <character>

'''CharacterSetTemporaryHostileRelation(CHARACTER:character, CHARACTER:otherCharacter)'''

Creates a temporary hostile relation between the 2 characters!

'''CharacterSetFightMode(CHARACTER:character, INT:fight [, INT:force=0])'''

Set the character in sheath/unsheated mode.

'''CharacterSetStats(CHARACTER:character, FIXEDSTRING:statsEntry [, INT:keepVitality=0, INT:keepAP=0, INT:keepLevel=0, OUT FLOAT:currentHP])'''

Applies <statsEntry> from character.xlsm to <character>, returns <currentHP>.

'''CharacterSetWalkSpeedOverride(CHARACTER:character, INTEGER:override [, FLOAT:walkSpeed])'''

Sets walk speed override of <character>, removes it if <override> is 0

'''CharacterSetRunSpeedOverride(CHARACTER:character, INTEGER:override [, FLOAT:runSpeed])'''

Sets run speed override of <character>, removes it if <override> is 0

'''CharacterSetHasDialog(CHARACTER:character, INTEGER:bool)'''

Enables/Disables the dialog of the character

'''CharacterInitPatrol(SPLINE:spline, INT:splineIndex, INT:reversed, INT:running)'''

Start patroling from the given index along the given spline with the given character.

'''CharacterStartPatrol(SPLINE:spline, INT:splineIndex, INT:reversed, INT:running)'''

Start patroling from the given index along the given spline with the given character.

'''CharacterStopPatrol(-)'''

Let the character stop patrolling whatever spline he's on!

'''CharacterInterruptPatrol(-)'''

Call when the patrol should interrupt so the guard stops moving to the next spline. If this is called when the character is deactivated, a caret will take his place.

'''CharacterSetAnimationSetOverride(CHARACTER:source, FIXEDSTRING:override)'''

Sets an animation set override for a character. Empty fixedstring clears the override.

'''CharacterSetFloating(CHARACTER:target, INTEGER:isFloating)'''

Sets <target> floating if <isFloating> is not 0

'''CharacterResetCooldowns(CHARACTER:target)'''

Resets the skill cooldowns for <target>

'''ItemEvent(ITEM:item, STRING:eventName)'''

Throw an item event which you can catch in scripts and story

'''ItemPlayAnimation(FIXEDSTRING:animation)'''

Plays an animation on the item

'''ItemPlayAnimationTo(FIXEDSTRING:animation, FLOAT:targetPercentage, [FLOAT:speed])'''

Plays an animation on the item to the target time (percentage of the total duration)

'''ItemPlayEffect(ITEM:item, STRING:effect [,FIXEDSTRING:boneName])'''

Plays an effect on the item and it follows the item

'''ItemPlayLoopEffect(OUT INT:effectHandle, ITEM:item, STRING:effect [,FIXEDSTRING:boneName])'''

Plays a looping effect on the item and it follows the item

'''ItemSetOnStage(ITEM:item, INTEGER:bool)'''

Sets an item on or offstage

'''ItemSetCanInteract(ITEM:item, INTEGER:bool)'''

Sets an item (not) interactible

'''ItemClose(ITEM:item)'''

Close an item

'''ItemOpen(ITEM:item)'''

Open an item

'''ItemDrop(ITEM:item)'''

Drop an item

'''ItemLock(ITEM:item, FIXEDSTRING:key)'''

Lock an item

'''ItemUnlock(ITEM:item)'''

Unlock an item

'''ItemApplyStatus(ITEM:item, STATUS:statusId [, INT:turns=null, INT:force=0])'''

Applies the status to the item When turns is -1 it's a permanent status When turns is -2 it's a keep alive status (which means it will die if it's not applied again within 1 second)

'''ItemRemoveStatus(ITEM:item, STATUS:statusId)'''

Removes the status from the item

'''ItemDie(ITEM:item)'''

Kills the item

'''ItemMoveTo(GAMEOBJECT|FLOAT3:target, FLOAT:velocity, FLOAT:acceleration, INTEGER:matchTargetRotation)'''

Moves the item to the target

'''ItemToInventory(ITEM:item, CHARACTER|ITEM:target [,INT:amount=-1])'''

Moves the item to the target's inventory

'''ItemLookAt(GAMEOBJECT:target, FLOAT:degreesPerSecond)'''

Rotates the item to look at the target

'''ItemDestroy(ITEM:item)'''

Destroys the item

'''ItemSetAmount(ITEM:item, INT:amount)'''

Change the amount of the item

'''IterateItemsInInventory(CHARACTER|ITEM:source, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each iten in source's inventory. If you pass a tag, it has to have that tag.

'''ItemAddCharges(ITEM:TargetItem, INT:charges)'''

Add/subtract charges from an item

'''ItemResetChargesToInitial(ITEM:TargetItem)'''

Resets charges from item to initial state

'''MakePeace(CHARACTER:Source, CHARACTER:Target[, INT:IgnoreVote = 1])'''

Make peace between users of the characters

'''MakeWar(CHARACTER:Source, CHARACTER:Target[, INT:IgnoreVote = 1])'''

Make war between users of the characters

'''FindSurface(OUT FLOAT3:result, GAMEOBJECT|FLOAT3:source, FLOAT:minRange, FLOAT:maxRange, SURFACE:type [,CHARACTER:alignSource, INT:minEnemiesInSurface, INT:maxAlliesInSurface, INT:minimumCellCount])'''

Finds the closest surface of a specific type.

'''FindValidPosition(INOUT FLOAT3:position, FLOAT:radius[, CHARACTER|ITEM:object=null])'''

Finds the closest valid position (where the object can stand.)

'''FindPosition(INOUT FLOAT3:position, CHARACTER:source, INT:canStand, INT:checkSight, FLOAT:minRadius, FLOAT:maxRadius, FLOAT:rangeCheck, CHARACTER:alignSource, INT:minAllies, INT:maxAllies, INT:minEnemies, INT:maxEnemies [,FIXEDSTRING:AiHintTag=null, INT:forceHint=0, FLOAT3:SourcePosition])'''

Finds the closest position from the source (within radius) where the conditions are matched.

'''Cast(OUT OBJECT variable, OBJECT value)'''

Casts the value to the variable.

'''StringConcatenate(STRING:stringA, STRING:stringB, OUT STRING:resultingString)'''

Appends stringB to stringA. Resulting string is stored in the third parameter.

== QUERIES ==

'''GetPosition(GAMEOBJECT:object,OUT FLOAT3:src)''' 

Get the current position of an object

'''GetForwardDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current forward direction of an object

'''GetRightDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current right direction of an object

'''GetUpDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current up direction of an object

'''GetDirection(GAMEOBJECT|FLOAT3:src,GAMEOBJECT|FLOAT3:target,OUT FLOAT3:direction[, OUT FLOAT:distance])''' 

Get the direction from src to target (optional: returns the distance between the objects as well)

'''GetRotation(GAMEOBJECT:object, OUT FLOAT3:vector)''' 

Get the rotation of an object

'''CharacterGetTargetSpline(INT: SplineIndex)''' 

Returns the spline index the character is currently walking towards, or -1 if he is not active on a spline.

'''IsEqual(OBJECT:variable, OBJECT:variable)''' 

Compares both objects and see if they are equal.

'''IsLessThen(INT|FLOAT:variable, INT|FLOAT:variable)''' 

Compares both objects and see if the first one is smaller.

'''IsGreaterThen(INT|FLOAT:variable, INT|FLOAT:variable)''' 

Compares both objects and see if the first one is bigger.

'''IsRandom(FLOAT:percentage)''' 

Each time this condition is checked, it will succeed with a chance of the percentage (between 0 and 1)

'''IsRound(INT:roundNumber)''' 

Checks if we are currently in combat in round x

'''IsInSurface(OBJECT|FLOAT3:target, SURFACE:type[, FLOAT:radius])''' 

Check if the character, item, trigger or position is currently within the specific surface.

'''IsInDangerousSurface(OBJECT|FLOAT3:target[, CHARACTER:character, FLOAT:radius])''' 

Check if <target> is currently in on a dangerous surface. Uses <character> for path influences if provided (is necessary with non-character targets)

'''IsInDialog(CHARACTER|ITEM:target[, INT:ignoreAutomatedDialogs=0])''' 

Check if the character or item is currently in a dialog, optionally ignoring automated dialogs

'''IsInAutomatedDialog(CHARACTER|ITEM:target)''' 

Check if the character or item is currently in an automated dialog

'''GetDistance(OUT FLOAT:distance, GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 

Returns the distance between 2 positions

'''GetDistance2D(OUT FLOAT:distance, GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 

Returns the 2D distance between 2 positions (ignores height)

'''GetInnerDistance(OUT FLOAT:distance, GAMEOBJECT:source, GAMEOBJECT:target)''' 

Returns the distance between 2 gameobjects (character, item, trigger, ...) Their bounds are already subtracted.

'''GetPosition(GAMEOBJECT:object, OUT FLOAT3:position)''' 

Returns the position of a gameobject (character, item, trigger, ...)

'''GetVar(OUT OBJECT:returnValue, CHARACTER|ITEM:target, FIXEDSTRING:varName)''' 

Gets a global variable from the target

'''GetClosestPlayer(OUT CHARACTER:player, GAMEOBJECT|FLOAT3:source)''' 

Gets the closest player near the source, default being being the object itself

'''GetPlayerCount(OUT INT:playerCount)''' 

Gets the number of players in the party

'''GetPlayerByIndex(OUT CHARACTER:returnCharacter, INT:playerIndex)''' 

Gets a player from the party by index

'''GetRandomCharacter(OUT CHARACTER:returnCharacter, [INT:canBeSelf=0, INT:canBePlayer=0])''' 

Gets a random character in the current level

'''ContainsSurface(GAMEOBJECT|FLOAT3:source, FLOAT:radius, SURFACE:type,)''' 

Checks if there is any surface of the type within a radius of the source

'''IsSurface(GAMEOBJECT|FLOAT3:source, FLOAT:radius, SURFACE:type)''' 

Checks if the whole radius around the source is the specified surface type

'''IsObjectOnObject(CHARACTER|ITEM:source,CHARACTER|ITEM:target)''' 

Checks if the source is standing on the target

'''GetX(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the X component of the vector

'''GetY(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the Y component of the vector

'''GetZ(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the Z component of the vector

'''CanSee(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target[, INT:addProjectileTargetGroundOffset=0])''' 

Check if the sight is blocked between 2 points.

'''IsVisible(CHARACTER|ITEM:object)''' 

Check if the object is set invisible or not with SetVisible.

'''GetTextDuration(CHARACTER|ITEM:object, FIXEDSRTING:key, OUT FLOAT:duration)''' 

Gets how long a text needs to be displayed

'''IsCasual(-)''' 

Returns if the current game mode is Casual

'''IsHardcore(-)''' 

Returns if the current game mode is Hardcore

'''IsTagged(GAMEOBJECT:object, FIXEDSTRING:tag)''' 

Check if the object is tagged.

'''TranslatedStringKeyExists(FIXEDSTRING:key)''' 

Check if the TranslatedString key exists.

'''IsInCombat(CHARACTER|ITEM:object)''' 

Returns true if the object is in combat.

'''IsInCombatWith(CHARACTER|ITEM:object, CHARACTER|ITEM:object)''' 

Returns true if the objects are in combat with each other.

'''IsFacing(GAMEOBJECT:source, GAMEOBJECT|FLOAT3:target, [INT:angle=90])''' 

Returns true if the object is facing the position within the given angle.

'''GameIsSaving(-)''' 

Returns true if the game is saving.

'''GameIsLoading(-)''' 

Returns true if the game is loading.

'''GetUserCount(OUT INT:userCount)''' 

Returns the user count.

'''GetCurrentCharacter(OUT CHARACTER:character, INT:user)''' 

Returns the character currently being controlled by the specified user.

'''GetCurrentLevel(OUT FIXEDSTRING:currentLevel)''' 

Returns the current levelname

'''GetAIBounds(CHARACTER|ITEM:source, OUT FLOAT:bounds)''' 

Returns AI bounds of <source> in <bounds>

'''HasGlobalFlag(FIXEDSTRING:flagName)''' 

Returns if the Global Flag is set

'''HasFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the Object

'''HasUserFlag(CHARACTER:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the user's characters

'''HasPartyFlag(CHARACTER:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the party's characters

'''DialogExists(STRING:dialogue)''' 

Returns true if the dialogue exists.

'''IsActive(CHARACTER|ITEM:Object)''' 

Returns if the character or item is currently active.

'''ListGetSize(LIST<OBJECT>:list, out INT:size)''' 

Returns the number of elements in <list>

'''ListGet(LIST<OBJECT>:list, INT:index, out OBJECT:entry)''' 

Returns <entry> at <index> of <list>

'''ListGetRandom(LIST<OBJECT>:list, out OBJECT:entry)''' 

Returns a random <entry> of <list>

'''IsBoss(CHARACTER|ITEM:Object)''' 

Returns true if the entity is tagged as a boss

'''IsProjectileSkill(SKILL:skill)''' 

Returns true if the skill is a ranged skill (uses a projectile)

'''IsValidSkillTarget(CHARACTER:source, OBJECT|FLOAT3:target, SKILLID:skill[, INTEGER:ignoreRangeCheck=0])''' 

Checks whether <target> is a valid target for <skill> at <source>

'''GetFaction(OUT FIXEDSTRING:faction, CHARACTER|ITEM:character)''' 

Returns the faction of the provided character or item

'''IsInActiveTurn(CHARACTER|ITEM:target)''' 

Returns true if it's the character's or item's turn in combat.

'''IsSkillActive(CHARACTER:character, SKILL:skillId)''' 

Returns true if <character> has <skillId> active (in memory).

'''HasSkillAi(SKILLID:skillId)''' 

Returns true if the skill is using the new Ai system

'''IsInArena(CHARACTER::character)''' 

Returns true if the character is in an arena fight

'''CrimeGetType(INTEGER:crimeId, OUT STRING:crimeType)''' 

Returns the type of the crime with this id.

'''CrimeGetCriminals(INTEGER:crimeId, OUT CHARACTER:criminal1, OUT CHARACTER:criminal2, OUT CHARACTER:criminal3, OUT CHARACTER:criminal4)''' 

Returns the criminals of that crime. They might all be null.

'''IsSourceSkill(SKILL:skill)''' 

Returns true if the skill is a source skill.

'''IsInGameMasterMode(-)''' 

Returns true if the game in game master mode.

'''CharacterGet(OUT CHARACTER:character, GAMEOBJECT|FLOAT3:src, FLOAT:range, COMPARE:howTo, COMPAREFUNC:compareFunc[, RELATION: relation, SURFACE:surface, STATUS:status, TALENT:talent, CHARACTER:inSightOf, FIXEDSTRING:tag])''' 

Get a character within a certain range conforming to the filled in restraints.

'''CharacterCount(OUT INT:count, GAMEOBJECT|FLOAT3:src, FLOAT:range, [RELATION: relation, SURFACE:surface, STATUS:status, TALENT:talent, CHARACTER:inSightOf])''' 

Counts the characters within a certain range conforming to the filled in restraints.

'''CharacterGetOwner(OUT CHARACTER:owner, CHARACTER:source)''' 

Get the character's owner

'''CharacterGetFollow(OUT CHARACTER:to follow, CHARACTER:source)''' 

Get the character to follow

'''CharacterGetEnemy(OUT CHARACTER:current enemy, CHARACTER:source)''' 

Get current enemy of character

'''CharacterCanCast(CHARACTER:source, SKILL:skillId, [ITEM:skillItem=null, INT:ignoreActionPoints=0])''' 

Check if the character source can cast the skill: will check cooldown, actionpoints

'''CharacterCanSitOnItem(CHARACTER:source, ITEM:item)''' 

Check if the character source can sit or lie on an item.

'''CharacterCanDrinkPotion(CHARACTER:source, FIXEDSTRING:potionID[, INT:ignoreActionPoints=0])''' 

Check if the character source can drink the potion: will check inv and actionpoints

'''CharacterCanUseItem(CHARACTER:source, ITEM:item[, INT:ignoreActionPoints=0])''' 

Check if the character source can use the item in the world

'''CharacterCanUseItemInInventory(CHARACTER:source, ITEM:item[, INT:ignoreActionPoints=0])''' 

Check if the character source can use the item in his inventory

'''CharacterCanSee(CHARACTER:watchingChar, CHARACTER|ITEM:target [, INT:forceUpdate=0])''' 

Check if character has target in his line of sight.

'''CharacterCanShoot(CHARACTER:source, GAMEOBJECT|FLOAT3:target)''' 

Check if the character can shoot the target.

'''CharacterIsPlayer(CHARACTER:character)''' 

Check if the character is a player

'''CharacterIsInParty(CHARACTER:character)''' 

Check if the character is in the party

'''CharacterIsEnemy(CHARACTER:source, CHARACTER:target)''' 

Check if target is enemy of source

'''CharacterIsAlly(CHARACTER:source, CHARACTER:target)''' 

Check if target is ally of source

'''CharacterIsNeutral(CHARACTER:source, CHARACTER:target)''' 

Check if target is neutral of source

'''CharacterIsDead(CHARACTER:character)''' 

Check if character is dead

'''CharacterIsMoving(CHARACTER:character)''' 

Check if character is moving (speed > 0)

'''CharacterIsSummon(CHARACTER:character)''' 

Check if character is a summon

'''CharacterIsPartyFollower(CHARACTER:character)''' 

Check if character is a party follower

'''CharacterIsStoryNPC(CHARACTER:character)''' 

Check if character is a story NPC

'''CharacterInWeaponRange(CHARACTER:character, CHARACTER:target)''' 

Check if target is in the current's weapon range

'''CharacterInTouchRange(CHARACTER:character, CHARACTER:targetChar)''' 

Check if target is in the character's touch range

'''CharacterHasStatus(CHARACTER:character, STATUS:statusId[, FIXEDSTRING:extraData])''' 

Check if character currently has the status. ExtraData can be filled in for some statuses: - Consume: statsid of the item - Shield: skillid of the shield

'''CharacterGetStatusSourceCharacter(CHARACTER:character, STATUS:statusId, OUT CHARACTER:source[, FIXEDSTRING:extraData])''' 

Get the source character of a status

'''CharacterGetStatusSourceItem(CHARACTER:character, STATUS:statusId, OUT ITEM:source[, FIXEDSTRING:extraData])''' 

Get the source item of a status

'''CharacterHasTalent(CHARACTER:character, TALENT:talent)''' 

Check if character currently has the talent

'''CharacterHasSkill(CHARACTER:character, SKILL:skillId)''' 

Check if character currently has the skill

'''CharacterHasWeaponType(CHARACTER:character, WEAPON:weaponTYPE [, INT:equipped])''' 

Check if character currently has a weapon of this type in his inventory or equipped

'''CharacterGetStat(OUT FLOAT:statValue, CHARACTER:character, CHARACTERSTAT:statType)''' 

Returns the current value of the stat (Vitality, ...)

'''CharacterGetSightRange(OUT FLOAT:range, CHARACTER:character)''' 

Returns the character's sight range

'''CharacterGetWeaponRange(OUT FLOAT:minRange, OUT FLOAT:maxRange, CHARACTER:character)''' 

Returns the character's current weapon range

'''CharacterGetTouchRange(OUT FLOAT:touchRange, CHARACTER:character)''' 

Returns the character's current touch range

'''CharacterGetSkillRange(OUT FLOAT:minRange, OUT FLOAT:maxRange,CHARACTER:character, SKILL:skillId)''' 

Returns the character's skill range

'''CharacterGetSkillImpactRange(OUT FLOAT:areaRange, CHARACTER:character, SKILL:skillId)''' 

Returns the character's skill range

'''CharacterIsInTrigger(CHARACTER:character, TRIGGER:trigger)''' 

Check if character is in given trigger

'''CharacterGetAbility(OUT INT:value, CHARACTER:character, ABILITY:ability)''' 

Returns the character's value of the specified ability

'''CharacterGetHostileCount(OUT INT:value, CHARACTER:character)''' 

Returns how many characters are targeting this character right now... You can iterate over them with IterateEnemiesOf.

'''CharacterCanFight(CHARACTER:character)''' 

Returns true if the character can fight.

'''CharacterGetTemplate(CHARACTER:character, OUT CHARACTERTEMPLATE:root)''' 

Returns the roottemplate of the character.

'''CharacterCanSpotSneakers(CHARACTER:character)''' 

Returns true if the character can spot sneaking characters

'''CharacterIsFloating(CHARACTER:character)''' 

Check if character is a floating character

'''CharacterInCreation(CHARACTER:character)''' 

Returns true if the character is in character creation

'''CharacterAvoidsTraps(CHARACTER:character)''' 

Returns true if the character avoids traps

'''CharacterCheckRelation(CHARACTER:character, RELATION:relation)''' 

Returns true if relation check succeeds

'''CharacterIsBetterOrEqualClass(CHARACTER:character, INT:currentScore, OUT INT:newScore, INT warriorScore, INT rogueScore, INT mageScore, INT clericScore, INT rangerScore)''' 

Returns true if score is higher or equal than the current score

'''CharacterHasBeenHitBy(CHARACTER:character, DAMAGE_TYPE:damageType)''' 

Returns true if the character was hit by this type.

'''CharacterHasCastedSpellLastTurn(CHARACTER:character)''' 

Returns true if the character has casted a spell in his last turn.

'''CharacterHasHadStatus(CHARACTER:character, STATUS:status)''' 

Returns true if the character has had a specific status this combat.

'''CharacterHasAnimationOverride(CHARACTER:character)''' 

Returns true if the character has an animation override.

'''CharacterCanUnlock(CHARACTER:character, ITEM:item)''' 

Returns true if the character can unlock the item (if the item is already unlocked it returns true!)

'''CharacterGetReservedUserID(OUT INT:user, CHARACTER:character)''' 

Returns the character's reserved User id.

'''CharacterGetRace(CHARACTER:character, OUT FIXEDSTRING:race)''' 

Returns the <character>'s race in <race>.

'''CharacterIsRace(CHARACTER:character, FIXEDSTRING:race)''' 

Returns true if <character>'s race is <race>.

'''CharacterCanMoveItem(CHARACTER:character, ITEM:item, FLOAT:minRadius, FLOAT:maxRadius [, OUT FLOAT3:destination])''' 

Returns true + <destination> if <character> can move <item> somewhere between <minRadius> and <maxRadius>.

'''CharacterGetDeathType(CHARACTER:character, OUT FIXEDSTRING:deathType)''' 

Returns death type of <character> in <deathType>.

'''CharacterGetStillAnimation(CHARACTER:object, OUT FIXEDSTRING:stillAnimation)''' 

Returns the still animation to play

'''CrimeTransferLeadership(INT: CrimeID[, FIXEDSTRING:Tag1,...])''' 

Try and transfer the leadership of this crime to someone else.

'''CrimeGetLeadInvestigator(OUT CHARACTER:lead, INT: CrimeID)''' 

Returns the lead investigator for the crime.

'''CharacterCanHitTargetWithRangedWeapon(CHARACTER:source, OBJECT|FLOAT3:target[, SKILL:skill = null])''' 

Returns true if <source> can hit <target> with currently equipped ranged weapon. Will use <skill> instead of equipped weapon if provided.

'''CharacterHasRangedWeapon(CHARACTER:character[, INT:checkInventory = 0])''' 

Returns true if <character> has has ranged weapon. Checks for non-wielded weapons if <checkInventory> is 1

'''CheckInteractionReach(CHARACTER:character, CHARACTER|ITEM: target)''' 

Returns true if <character> could interact with <target>. This is not checking ranges, but checking if there's too much of a height difference or too many obstacles in between.

'''CharacterGetSourcePoints(CHARACTER:character, OUT INT: amount)''' 

Returns the amount of sourcepoints of <character>.

'''CharacterAiIsCalculating(-)''' 

Returns if the character is still calculating the AI.

'''CharacterAiFetchMoveSkillCommand(OUT SKILL:skill, OUT ITEM:skillItem, OUT FLOAT3:target)''' 

Returns if the character has a Move Skill command to execute according to the AI.

'''CharacterAiFetchSkillCommand(OUT SKILL:skill, OUT ITEM:skillItem, OUT FLOAT3 endPosition, OUT FLOAT3:target, OUT CHARACTER:target, OUT ITEM:target, OUT FLOAT3:target2, OUT CHARACTER:target2, OUT ITEM:target)''' 

Returns if the character has a Skill command to execute according to the AI.

'''CharacterAiFetchConsumeCommand(OUT ITEM:item)''' 

Returns if the character has a Consume command to execute according to the AI.

'''CharacterAiFetchAttackCommand(OUT FLOAT3:endPosition, OUT FLOAT3:target, OUT CHARACTER:target, OUT ITEM:target)''' 

Returns if the character has a Attack command to execute according to the AI.

'''CharacterAiFetchFallbackCommand(OUT FLOAT3:targetPosition, OUT FLOAT3:lookAtPosition)''' 

Returns if the character has a Fallback command to execute according to the AI.

'''CharacterGetArchetype(CHARACTER:character, OUT ARCHETYPE:archetype)''' 

Returns the archetype of the character.

'''CharacterIsPolymorphedInto(CHARACTER:character, FIXEDSTRING:race)''' 

Returns true if <character> is polymorphed into <race>. Race can be a race (like HUMAN), but also a template (in case of a polymorph skill like Chicken Touch).

'''CharacterIsPolymorphInteractionDisabled(CHARACTER:character)''' 

Returns true if <character> has his interaction disabled because of a polymorph.

'''ItemGet(OUT ITEM:item, GAMEOBJECT|FLOAT3:src, FLOAT:range, COMPARE:howTo [, COMPAREFUNC:compareFunc, FIXEDSTRING:rootTemplate, FIXEDSTRING:tag])''' 

Get an item within a certain range conforming to the filled in restraints.

'''ItemGetFromInventory(OUT ITEM:item, CHARACTER|ITEM:object [, FIXEDSTRING:statsId, FIXEDSTRING:tag, INT:isEquiped])''' 

Returns the first item in the inventory conforming to the filled in restraints.

'''ItemIsInCharacterInventory(ITEM:item, CHARACTER:object)''' 

Returns if the item is in the inventory of the character

'''ItemIsInTrigger(ITEM:item, TRIGGER:trigger)''' 

Check if item is in given trigger

'''ItemGetStat(OUT FLOAT:statValue, ITEM:item, ITEMSTAT:statType)''' 

Returns the current value of the stat (Weight, ...)

'''ItemIsMoving(ITEM:item)''' 

Returns if the item is moving or not.

'''ItemIsFalling(ITEM:item)''' 

Returns if the item is falling or not. (after teleport)

'''ItemIsOpening(ITEM:item)''' 

Returns if the item is opening or not.

'''ItemIsClosing(ITEM:item)''' 

Returns if the item is closing or not.

'''ItemIsLocked(ITEM:item)''' 

Returns if the item is locked or not.

'''ItemIsMovable(ITEM:item)''' 

Returns if the item is movable or not.

'''ItemCanBeLockPicked(ITEM:item)''' 

Returns if the item is can be opened by lockpicking.

'''ItemIsOpen(ITEM:item)''' 

Returns if the item is open or not.

'''IsStoryItem(ITEM:item)''' 

Returns if the item is a story item.

'''ItemHasStatus(ITEM:item, STATUS:statusId)''' 

Returns if the item has the status.

'''ItemIsDestroyed(ITEM:item)''' 

Returns if the item is destroyed.

'''ItemGetTemplate(ITEM:item, OUT ITEMTEMPLATE:root)''' 

Returns the roottemplate of the item.

'''ItemGetSkillId(ITEM:item, OUT SKILL:root)''' 

Returns the skillid of the item if it has one.

'''ItemGetItemType(ITEM:item, OUT FIXEDSTRING:itemType)''' 

Returns the itemtype of the item: common, unique, rare, ...

'''ItemGetStatusSourceCharacter(ITEM:item, STATUS:statusId, OUT CHARACTER:source)''' 

Get the source character of a status

'''ItemGetStatusSourceItem(ITEM:item, STATUS:statusId, OUT ITEM:source)''' 

Get the source item of a status

'''ItemCanBeMoved(ITEM:item)''' 

Returns if the item can be moved.

'''GetStatusTurns(CHARACTER|ITEM:object, STATUS:statusId, OUT INT:turnsLeft)''' 

Returns true if the object has the given status, and returns the amount of turns still left

== EVENTS ==

'''OnCharacterEvent(CHARACTER:character, STRING:eventName)''' 
Thrown from scripts or story

'''OnCharacterItemEvent(CHARACTER:character, ITEM:item, STRING:eventName)''' 
Thrown from scripts or story

'''OnCharacterCharacterEvent(CHARACTER:character, CHARACTER:character, STRING:eventName)''' 
Thrown from scripts or story

'''OnItemEvent(ITEM:item, STRING:eventName)''' 
Thrown from scripts or story

'''OnItemDestroyed(ITEM:item)''' 
Thrown when an item is destroyed

'''OnItemDestroying(ITEM:item)''' 
Thrown when an item is being destroyed

'''OnItemOpened(ITEM:item)''' 
Thrown when an item is opened

'''OnItemClosed(ITEM:item)''' 
Thrown when an item is closed

'''OnItemDropped(ITEM:item, STRING:itemTemplate)''' 
Thrown when an item is dropped

'''OnGlobalFlagSet(FIXEDSTRING:eventName)''' 
Thrown when a global event is set

'''OnGlobalFlagCleared(FIXEDSTRING:eventName)''' 
Thrown when a global event is cleared

'''OnCharacterFlagSet(FIXEDSTRING:eventName, CHARACTER:character)''' 
Thrown when a dialog event is set on a character

'''OnCharacterFlagCleared(FIXEDSTRING:eventName, CHARACTER:character)''' 
Thrown when a dialog event is cleared on a character

'''OnItemFlagSet(FIXEDSTRING:eventName, ITEM:item)''' 
Thrown when a dialog event is set on an item

'''OItemFlagCleared(FIXEDSTRING:eventName, ITEM:item)''' 
Thrown when a dialog event is cleared on an item

'''OnTimer(FIXEDSTRING:timerName)''' 
Thrown when a timer has ended

'''OnInit(-)''' 
Thrown when the script is set

'''OnLoaded(INT:major, INT:minor, INT:revision, INT:build)''' 
Thrown when the script is loaded from the savegame

'''OnShutdown(-)''' 
Thrown when the character's script is removed

'''OnVariableCleared(FIXEDSTRING:varName)''' 
Thrown when this object's script variable is cleared from Osiris with ClearVarObject

'''OnCombatStarted(INT:combatID)''' 
Thrown when combat starts

'''OnCombatSwitched(CHARACTER:source, ITEM:source)''' 
Thrown when the character switch from one combat to another

'''OnLeftCombat(CHARACTER:source, ITEM:source)''' 
Thrown when the character or item left the combat

'''OnTurn(CHARACTER:source, ITEM:source)''' 
Thrown when the character's turn starts

'''OnTurnEnded(CHARACTER:source, ITEM:source)''' 
Thrown when the character's turn ended

'''OnCharacterVitalityChanged(CHARACTER:character, FLOAT:percentage)''' 
Thrown when the characters's vitality changed

'''OnItemVitalityChanged(ITEM:item, FLOAT:percentage)''' 
Thrown when the item's vitality changed

'''OnAttackOfOpportunity(CHARACTER:target)''' 
Thrown when the characters gets an attack of opportunity on an enemy

'''OnClearAttackOfOpportunity(-)''' 
Thrown when the characters attack of opportunity is cleared

'''OnDamage(DAMAGE:type, FLOAT:percentage, CHARACTER:source, ITEM:source)''' 
Thrown when the object receives damage

'''OnMiss(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character dodges something

'''OnCriticalHit(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character is critical hit

'''OnPreBlock(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown before the character blocks something (at the start of the attack animation)

'''OnBlock(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character blocks something

'''OnDie(CHARACTER:character, DAMAGE:type, CHARACTER:source, ITEM:source)''' 
Thrown when the character dies

'''OnCharacterStatusAttempt(CHARACTER:character, STATUS:status)''' 
Thrown when the character attempts to gain a status

'''OnCharacterStatusApplied(CHARACTER:character, STATUS:status)''' 
Thrown when the character gains a status

'''OnCharacterStatusRemoved(CHARACTER:character, STATUS:status)''' 
Thrown when the character loses a status

'''OnItemStatusAttempt(ITEM:item, STATUS:status)''' 
Thrown when the item attempts to gain a status

'''OnItemStatus(ITEM:item, STATUS:status)''' 
Thrown when the item gains a status

'''OnItemStatusRemoved(ITEM:item, STATUS:status)''' 
Thrown when the item loses a status

'''OnStatusCreateVisuals(STATUS:status)''' 
Thrown when the item should create the visuals for this status

'''OnStatusDestroyVisuals(STATUS:status)''' 
Thrown when the item should destroy the visuals for this status

'''OnSight(CHARACTER:character)''' 
Thrown when the character sees another character

'''OnLostSight(CHARACTER:character)''' 
Thrown when the character doesn't see another character anymore

'''OnUseItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character uses an item

'''OnPickupItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character picks up an item

'''OnCharacterPreMovedItem(CHARACTER:source, ITEM:item)''' 
Event thrown just before a character moves an item. No difference whether it is in the world or in their inventory

'''OnCharacterMovedItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character moved an item

'''OnItemEquipped(CHARACTER:source, ITEM:item)''' 
Thrown when a character equips an item

'''OnItemUnequipped(CHARACTER:source, ITEM:item)''' 
Thrown when a character unequips an item

'''OnIterateCharacter(CHARACTER:character, FIXEDSTRING:eventId)''' 
Thrown by iterators

'''OnIterateItem(ITEM:source, FIXEDSTRING:eventId)''' 
Thrown by iterators

'''OnIterateCount(FIXEDSTRING:eventId, INTEGER:Count)''' 
Thrown by iterators after all iterations to inform you of the count.

'''OnStoryOverride(-)''' 
Throw when story overrides what the character was doing: teleport, movement, on/offstage

'''OnTriggerEnter(CHARACTER:character, ITEM:item, FIXEDSTRING:eventId)''' 
Thrown by a character or item entering an EventTrigger

'''OnTriggerLeave(CHARACTER:character, ITEM:item, FIXEDSTRING:eventId)''' 
Thrown by a character or item leaving an EventTrigger

'''OnEnemyChanged(CHARACTER:character, CHARACTER:newEnemy)''' 
Thrown when the character's currentenemy changes

'''OnTalentUnlocked(CHARACTER:character, TALENT:newTalent)''' 
Thrown when the character unlocks a new talent

'''OnTalentLocked(CHARACTER:character, TALENT:removedTalent)''' 
Thrown when the there's a talent removed from a character

'''OnCharacterClassChanged(CHARACTER:character, FIXEDSTRING:class)''' 
Thrown when the character changes class in the character creation screen

'''OnCharacterCreationStarted(CHARACTER:character, TRIGGER:creationPoint)''' 
Thrown when the character creation has started, and gives where the character should walk to

'''OnCharacterCreationStopped(CHARACTER:character)''' 
Thrown when the character creation has stopped

'''OnFunction(FIXEDSTRING:functionName)''' 
Throws an event on itself with the functionName. This is to fake function calls

'''OnSkillCast(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when the character casts a skill

'''OnSkillCombatComment(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when the character needs to make a comment

'''OnCharacterUsedSkillOnMe(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when you are hit by a skill from a character

'''OnItemUnlocked(ITEM: item, CHARACTER:character, ITEM:key)''' 
Thrown when an item gets unlocked by a character.

'''OnAutomatedDialogEnded(STRING:dialogName, INT:instanceID)''' 
Thrown when a automated dialog is ended for this speaker

'''OnAutomatedDialogStarted(STRING:dialogName, INT:instanceID)''' 
Thrown when a automated dialog is started for this speaker

'''OnDialogStarted(STRING:dialogName, INT:instanceID)''' 
Thrown when a dialog is started for this speaker

'''OnDialogEnded(STRING:dialogName, INT:instanceID)''' 
Thrown when a dialog is ended for this speaker

'''OnCrimeSensibleAction(FIXEDSTRING:regionID, INT:crimeID, FIXEDSTRING:reactionName, STRING:primaryDialog, CHARACTER:criminal1, CHARACTER:criminal2, CHARACTER:criminal3, CHARACTER:criminal4, INT:IsPrimary)''' 
Thrown when a character needs to perform a sensible action against criminals

'''OnCrimeInterrogationRequest(FIXEDSTRING:regionID, INT:crimeID, CHARACTER:criminal1, CHARACTER:criminal2, CHARACTER:criminal3, CHARACTER:criminal4, STRING:interrogationDialog)''' 
Thrown when a character needs to perform an interrogation against criminals

'''OnCrimeInvestigate(FLOAT3:CrimePosition, INT:crimeID)''' 
One NPC investigates a crimescene

'''OnCrimeAlarmed(FLOAT3:CrimePosition, INT:crimeID)''' 
All NPCs in a crimearea start looking around.

'''OnCrimeReturnToNormal(-)''' 
Investigation or Alarm timed out.

'''OnCrimeAborted(-)''' 
The game interrupted the sensible action of this NPC.

'''OnSplineControlPointReached(INT:Index, INT:EndReached, STRING:EventString)''' 
Thrown when a character reached a spline node.

''''OnFinishCalculationAi(-)''' 
Thrown when the calculation of the AI is finished.

'''OnGrenadeLand(INT:hitObstacle, CHARACTER:caster)''' 
Thrown when the grenades lands

'''FetchCharacterApplyStatusData(CHARACTER:character, STATUS:status) RETURN(LIST<STATUS>:removeStatuses, STATUS:applyStatus, INT:turns)''' 
Fetch from script which statuses to remove and apply.

'''FetchItemApplyStatusData(ITEM:item, STATUS:status) RETURN(LIST<STATUS>:removeStatuses, STATUS:applyStatus, INT:turns)''' 
Fetch from script which statuses to remove and apply.

'''FetchItemSkillOnDamage(INT:damage, DAMAGE_TYPE:damageType) RETURN(INT:hasSkill, SKILL_ID:skillID, INT:casterLevel)''' 
Fetch from script what skill to execute on damage.

'''FetchSkillScore(SKILL_ID:skillId, CHARACTER:sourceCharacter, CHARACTER:targetCharacter1, ITEM:targetItem1, FLOAT3:targetPosition1, CHARACTER:targetCharacter2, ITEM:targetItem2, FLOAT3:targetPosition2) RETURN(FLOAT:score) 
Fetch from script the score of a skill with set source and target

'''OnActivate(-)''' 
Thrown when a character/item activates

'''OnDeactivate(-)''' 
Thrown when a character/item deactivates

'''OnCharacterUsedSourcePoint(CHARACTER:character)''' 
Thrown when a character uses a source point

'''OnSkillAdded(CHARACTER:character, SKILL_ID:skillId, INT:learned)''' 
Thrown when a character learns a skill

'''OnSkillActivated(CHARACTER:character, SKILL_ID:skillId)''' 
Thrown when a character activates (=adds to memory) a skill

'''OnSkillDeactivated(CHARACTER:character, SKILL_ID:skillId)''' 
Thrown when a character deactivates (=removes from memory) a skill

'''OnItemFlagShared(FIXEDSTRING:eventName, ITEM:item, INT:newValue)''' 
Thrown when a dialog event is shared with an item

'''OnCharacterFlagShared(FIXEDSTRING:eventName, CHARACTER:character, INT:newValue)''' 
Thrown when a dialog event is shared with a character

'''OnItemOffStageChanged(CHARACTER:character, INT:offstage)''' 
Thrown when a character is set on/off stage

'''OnCharacterOffStageChanged(ITEM:item, INT:offstage)''' 
Thrown when a item is set on/off stage

'''OnCharacterTeleported(CHARACTER:target, CHARACTER:cause, FLOAT3:oldPosition, FLOAT3:newPosition, SKILL_ID:skillId)''' 
Thrown when a character gets teleported with a teleport skill

'''OnCombatTick(-)''' 
Thrown when this object ticks in combat. Only thrown for objects that don't get a turn.

'''OnCombatRoundStarted(INT:combatID, INT:roundID) 
Thrown when a round in a combat starts

'''OnReadyInCombat(CHARACTER:character, ITEM:item, INT:combatID)''' 
Thrown when a character or item is ready in combat

'''OnRegionLeft(CHARACTER:character, ITEM:item, FIXEDSTRING:region)''' 
Thrown when a character or item leaves a region

'''OnRegionEntered(CHARACTER:character, ITEM:item, FIXEDSTRING:region)''' 
Thrown when a character or item enters a region

'''OnRuneInserted(CHARACTER:character, ITEM:item, ITEMTEMPLATE:runeItemTemplate, INT:slot)''' 
Thrown when a <character> inserts a rune with roottemplate <runeItemTemplate> from an <item> at a specified <slot>

'''OnRuneRemoved(CHARACTER:character, ITEM:item, ITEM:rune, INT:slot)''' 
Thrown when a <character> removes a <rune> from an <item> at a specified <slot>

'''OnCharacterStartAttackObject(CHARACTER:defenderCharacter, ITEM:defenderItem, CHARACTER:attackerOwner, CHARACTER:attacker)''' 
Thrown when a character attacks a character or item with default attack

'''OnCharacterStartAttackPosition(FLOAT3:position, CHARACTER:attackerOwner, CHARACTER:attacker)''' 
Thrown when a character attacks a position with default attack

== INTERRUPTS ==

'''OnMovementFailed(FLOAT3:targetPos)''' 
Thrown when the reaction is interrupted by a move action failing

'''OnException(-)''' 
Thrown when the reaction is interrupted by an exception

'''OnBetterReactionFound(FIXEDSTRING:reactionName)''' 
Thrown when the reaction is interrupted by another reaction

'''OnNoReactionFound(-)''' 
Thrown when the reaction is interrupted because no reaction is valid

'''OnScriptDisabled(-)''' 
Thrown when the reaction is interrupted because the scriptcontroller is disabled

'''OnManualInterrupt(FIXEDSTRING:reactionName)''' 
Thrown when the reaction is interrupted using the interrupt action

'''OnRegionSwap(FIXEDSTRING:oldLevel, FIXEDSTRING:newLevel)''' 
Thrown when the reaction is interrupted by a region swap

= Divinity: Original Sin 2 Definitive Edition =
The following was added/changed for the Definitive Edition.

== CALLS ==
'''ItemDrop(ITEM:item)''' 
Drops an item from it's owner's inventory. Only characters are treated as owners.

'''RemoveSurfaceLayerAt(GAMEOBJECT|FLOAT3:target, INT:layer, FLOAT:radius)''' 
Removes surface (ground or cloud) at object/position. (Layer 0 for surface, otherwise - cloud) (Radius for cleanup)

'''SurfaceCreateLink(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 
Makes surfaces at 2 locations/positions interact as if they were adjacent.

'''SurfaceRemoveLink(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 
Stops surfaces at 2 distinctive locations/positions from interacting.

== QUERIES ==
'''AttributeGetDifficultyLevelMappedValue(FIXEDSTRING:difficulty, INT:level, OUT INT:levelMappedValue)''' 
Returns a level-mapped value of a primary attribute. (Difficulty = "Easy", "Normal" or "Hard")

'''CharacterGetCreationClass(CHARACTER:character, OUT FIXEDSTRING: class)''' 
During character creation returns character class. Fails outside of character creation.

'''CharacterGetEquippedItem(CHARACTER:character, FIXEDSTRING:slot, OUT ITEM:seatingItem)''' 
Returns item equipped into slot. (Slot = "Helmet", "Breast", "Leggings", "Weapon", "Shield", "Ring", "Ring2", "Belt", "Boots", "Gloves", "Amulet" or "Wings")

(CHANGED) '''CharacterInCreation(CHARACTER:character, OUT INT:CharacterIndex)''' 
Checks if character is in character creation currently. (CharacterIndex: assigned index of the player character during character creation)

Character and Item Script Triggers, Calls, and Queries

2018-09-30T20:10:39Z

LaughingLeader: Added GetStatusTurns

This is a list of almost every character and item script event trigger, call, and query. An event is what triggers the script, and always begin with ''On''. Queries provide information and are always inside an ''IF'' or ''CHECK.'' Calls are actions that are always after THEN.

CharScript/ItemScript Functions

= Divinity: Original Sin 2 Classic=
== CALLS ==

'''Set(OUT OBJECT:variable, OBJECT:value)'''

Set the value of a variable

'''SetVar(CHARACTER|ITEM:object, FIXEDSTRING:variableName, OBJECT:value)'''

Set the value of a global variable

'''Cast(OUT OBJECT variable, OBJECT value)'''

Casts the value to the variable

'''Print(OUT STRING:output, STRING:text)'''

Prints the text to the output with possible parameters: [1], [2], ...

'''Add(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT|FLOAT3:value)'''

Adds both values and stores it in the first variable

'''Subtract(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT|FLOAT3:value)'''

Subtracts both values and stores it in the first variable

'''Multiply(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT:value)'''

Multiplies both values and stores it in the first variable

'''Divide(INOUT INT|FLOAT|FLOAT3:variable, INT|FLOAT:value)'''

Divides both values and stores it in the first variable

'''Abs(INOUT INT|FLOAT:variable)'''

Takes the absolute value of a variable

'''Clamp(INOUT INT|FLOAT:variable, INT|FLOAT:min, INT|FLOAT:max)'''

Clamps a variable between min and max

'''GetRandom(OUT OBJECT:variable, OBJECT:value, OBJECT:value, OBJECT:value)'''

Fills in the variable with random one of the values.

'''GetWeightedRandom(OUT OBJECT:variable, OBJECT:value, INT|FLOAT:weight, ...)'''

Gets a weighted random of the given values!

'''GetRandomBetween(OUT INT|FLOAT:variable, INT|FLOAT:min, INT|FLOAT:max)'''

Gets a random value between min and max (both included)

'''GetRandomPositionInTrigger(OUT FLOAT3:variable, TRIGGER:areaTrigger)'''

Get a random position in a trigger area

'''GetElement(OUT OBJECT:variable, INT:index, OBJECT:value, OBJECT:value, OBJECT:value)'''

Fills in the variable with the index one of the values (starting from 0)

'''SetPriority(FIXEDSTRING:reactionName, INT:priority)'''

Changes the priority of a reaction. Priority 0 and below are not executed!

'''DelayReaction(FIXEDSTRING:reactionName, FLOAT:timeInSeconds)'''

The reaction will not be chosen for the specified time

'''SetScriptFrame(CHARACTER:character, FIXEDSTRING:frame)'''

Sets the scriptframe on the character.

'''ClearScriptFrame(CHARACTER:character)'''

Clears the scriptframe on the character.

'''Goto(FIXEDSTRING:labelName)'''

Jumps to the label. Two label names are built-in: "Start" for the first instruction of the reaction, and "End" for the last one.

'''GotoIfEqual(OBJECT:variable, OBJECT:value, FIXEDSTRING:labelName)'''

Jumps to the label if the 2 objects are equal

'''GotoRand(FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName, FIXEDSTRING:labelName)'''

Jumps to a random label in the list

'''CreatePuddleAt(GAMEOBJECT|FLOAT3:target, SURFACE:type, INT:cellAmountMin, INT:cellAmountMax, INT:growAmountMin, INT:growAmountMax, )'''

Spawn a puddle at the target's position for a certain lifetime (in turns)

'''CreateSurfaceAt(GAMEOBJECT|FLOAT3:target, SURFACE:type, FLOAT:radius, INT:lifeTime[, GAMEOBJECT:owner])'''

Spawn a surface at the target's position for a certain lifetime (in turns)

'''CreateSurfaceInPolygon(GAMEOBJECT:owner, SURFACE:type, FLOAT:duration, FLOAT:growTimer, INT:growStep, GAMEOBJECT|FLOAT3:point1, GAMEOBJECT|FLOAT3:point2, GAMEOBJECT|FLOAT3:point3, ...)'''

Spawn a polygon surface at the target's position. Grows <growStep> every <growTimer>.

'''CreateSurfaceInAreaTrigger(GAMEOBJECT:owner, SURFACE:type, FLOAT:duration, FLOAT:growTimer, INT:growStep, TRIGGER:areaTrigger)'''

Spawn a surface within <areaTrigger>. Grows <growStep> every <growTimer>.

'''CreateConeSurfaceAt(GAMEOBJECT|FLOAT3:start, GAMEOBJECT|FLOAT3:target, SURFACE:type, FLOAT:radius, FLOAT:angle, FLOAT:duration)'''

Spawn a Cone surface at the target's position

'''PlayEffectAt(GAMEOBJECT|FLOAT3:target, STRING:effectName)'''

Plays an effect at the target's position

'''PlayLoopEffectAt(OUT INT64:effectHandle, GAMEOBJECT|FLOAT3:target, STRING:effectName)'''

Plays an effect at the target's position

'''ExplodeAt(GAMEOBJECT|FLOAT3:target, SKILL:projectileSkill, [INT:casterLevel=-1, CHARACTER|ITEM:cause])'''

Trigger an explosion of a projectile skill at the target's position. The cause will trigger NPC behavior as if the cause casted the projectile

'''DisplayText(CHARACTER|ITEM:target, FIXEDSTRING:text, FLOAT:timeInSeconds)'''

Displays text above the character/item for a certain amount of time. It will replace the current text, including dialogtext

'''DisplayCombatInfoText(CHARACTER|ITEM:target, FIXEDSTRING:text, FLOAT:timeInSeconds)'''

Displays text above the character/item for a certain amount of time. It will replace the current text, including dialogtext

'''StatusText(CHARACTER|ITEM:target, FIXEDSTRING:text)'''

Adds statustext above the character/item for a short amount of time. Will not replace texts or dialogtexts

'''DebugText(CHARACTER|ITEM:target, STRING:text)'''

Adds debugtext above the character/item for a short amount of time.

'''CombatLogText(CHARACTER|ITEM:target, FIXEDSTRING:text, INT:filterID, INT:broadcastID)'''

Adds combatlog text inside the combat log window. Color-/SizeFormatting should already be applied, if not color and size of the string will be NORMAL. filterID determines what filter shows/hides the text. broadcastID determines who will be able to see the message (0 hearingrange. 1 party. 2 all)

'''Log(STRING:text, ...)'''

Log's the the scriptlog. (for debugging purposes)

'''Output(STRING:text, ...)'''

Pass text with optional parameters to the output panel (e.g. Output("An int [1]", INT:10))

'''Assert(STRING:text, ...)'''

Pass text with optional parameters to display as an assert message (e.g. Assert("This number is wrong: [1]", INT:666))

'''Label(FIXEDSTRING:name)'''

Marks this line as a label where Goto actions can jump to

'''StartTimer(FIXEDSTRING:timerName, FLOAT:timeInSeconds, INT:repeatCount)'''

Start a timer which will throw the timer event. Set repeatcount < 0 for a permanent timer.

'''StopTimer(FIXEDSTRING:timerName)'''

Stop a timer which will throw the timer event

'''DialogStart(OUT INT:instanceId, STRING:dialog, CHARACTER|ITEM:target, CHARACTER|ITEM:target, CHARACTER|ITEM:target, CHARACTER|ITEM:target)'''

Start a dialog between the targets. You can specify fewer targets than the maximum number.

{{warning|Starting a dialog from behaviour script will always start it as an [[Dialog_editor#Automated|Automated Dialog]]. Interactive dialogs can only be started from [[Osiris]].}}

'''DialogRequestStop(CHARACTER|ITEM:speaker, STRING:dialog)'''

Stops a certain dialog on a certain speaker

'''Check(-)'''

Reevaluate the conditions in the CHECK section of this reaction

'''Reset(-)'''

Resets the current reaction. It will start from the beginning again

'''Interrupt(FIXEDSTRING:reactionName)'''

Interrupt the reaction.

'''GlobalSetEvent(FIXEDSTRING:eventName)'''

Sets a global event. Scripts and Story can catch it.

'''GlobalClearEvent(FIXEDSTRING:eventName)'''

Clears a global event. Scripts and Story can catch it.

'''StopLoopEffect(INT64:fxHandle)'''

Stops a looping effect

'''IterateItems(FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item. If you pass a tag, it has to have that tag.

'''IterateItemsNear(GAMEOBJECT:source, FLOAT:radius, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item in range. If you pass a tag, it has to have that tag.

'''IterateItemsOnObject(CHARACTER|ITEM:source, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each item standing on the source. If you pass a tag, it has to have that tag.

'''IterateParty(FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, CHARACTER:partyMember, FIXEDSTRING:tag])'''

Launch iterate event for each member of all parties. If you pass a party member only members of that party will be considered. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharacters(FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersNear(GAMEOBJECT:source, FLOAT:radius, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character in range. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersOnObject(CHARACTER|ITEM:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''
Launch iterate event for each character standing on the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateCharactersInCombat(CHARACTER|ITEM:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character in combat with the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''IterateHostilesFor(CHARACTER:source, FIXEDSTRING:eventname, [COMPARE:howTo, COMPAREFUNC:compareFunc, FIXEDSTRING:tag])'''

Launch iterate event for each character who is targetting the source. If you pass compare parameters, it will iterate over them in the requested order. If you pass a tag, it has to have that tag.

'''SpawnCharacter(OUT CHARACTER:result, CHARACTERTEMPLATE:rootTemplate, GAMEOBJECT|FLOAT3:position, INT:playSpawn, [INT:isSummon=0, CHARACTER:summonOwner=null, INT:overrideLevel=-1])'''

Spawns a character

'''SpawnItem(ITEMTEMPLATE:rootTemplate,GAMEOBJECT|FLOAT3:position, OUT ITEM:result)'''

Spawns an item

'''ShootLocalProjectile(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,FLOAT3:direction,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Spawns a projectile at the source (with offset, can be null) shooting at the target

'''ShootLocalProjectileAt(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,GAMEOBJECT|FLOAT3:target,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Spawns a projectile at the source (with offset, can be null) shooting at the target

'''ShootWorldProjectile(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,FLOAT3:direction,[INT:casterLevel])'''

Spawns a projectile at worldPos shooting at the target. Source can be null.

'''ShootWorldProjectileAt(SKILL:projectileSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,GAMEOBJECT|FLOAT3:target,[INT:casterLevel])'''

Spawns a projectile at worldPos shooting at the target. Source can be null.

'''ShootLocalCone(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,FLOAT3:direction,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Shoots a cone from source (with offset, can be null) in a direction

'''ShootLocalConeAt(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:localOffset,GAMEOBJECT|FLOAT3:target,[INT:casterLevel, CHARACTER|ITEM:caster])'''

Shoots a cone from source (with offset, can be null) at the target

'''ShootWorldCone(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,FLOAT3:direction,[INT:casterLevel])'''

Shoots a cone from worldPos in a direction. Source can be null.

'''ShootWorldConeAt(SKILL:coneSkill,CHARACTER|ITEM:source,FLOAT3:worldPos,GAMEOBJECT|FLOAT3:target,[INT:casterLevel])'''

Shoots a cone from worldPos at the target. Source can be null.

'''SetVisible(CHARACTER|ITEM:object, INT:visible)'''

Sets a character or item visible or not.

'''RotateY(INOUT FLOAT3:vector, FLOAT:degrees)'''

Rotate the vector around the Y-axis for a certain angle (in degrees)

'''SetHealth(CHARACTER|ITEM:target, FLOAT:percent)'''

Set a characters or items health on the given percentage. (percentage between 0 and 1)

'''PlaySound(CHARACTER|ITEM:target, STRING:soundEvent)'''

Plays a sound event at the target

'''PlayMusicForEveryone(STRING:musicEvent)'''

Plays a music event on all the clients

'''PlayMusicOnCharacter(CHARACTER:target, STRING:musicEvent)'''

Plays a music event on a character for all peers (3D)

'''PlayMusicForPeer(CHARACTER:target, STRING:musicEvent)'''

Plays a music event on the peer of the character

'''PlayMusicForPeerWithInstrument(CHARACTER:target, CHARACTER:charInstrument, STRING:musicEvent)'''

Plays a music event on the peer of the character concated with _INSTRUMENT

'''SetX(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the X component of the FLOAT3

'''SetY(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the Y component of the FLOAT3

'''SetZ(INOUT FLOAT3:vector, FLOAT|INT:value)'''

Sets the Z component of the FLOAT3

'''SetAtmosphere(FIXEDSTRING:atmosphereTriggerUUID, FIXEDSTRING:atmosphere)'''

Changes the atmosphere of the trigger

'''ResetAtmosphere(FIXEDSTRING:atmosphereTriggerUUID)'''

Resets the atmosphere of the trigger

'''AddStatusInfluence(CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1], [INT:force=1])'''

Adds the status influence strength on the object.

'''RemoveStatusInfluence(CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1])'''

Removes the status influence strength on the object.

'''AddTemporaryStatusInfluence(CHARACTER|ITEM:source, CHARACTER|ITEM:object, STATUS:statusId, FLOAT:strength, [FIXEDSTRING:extraData=""], [INT:isWeather=1])'''

Adds a temporary status influence strength on the object.. It will be gone in a few seconds if it's not set again

'''CallFunction(FIXEDSTRING:functionName)'''

Calls a function with the ID

'''SetMaterial(CHARACTER|ITEM:object, FIXEDSTRING:materialUUID, INT:duration, INT:applyOnBody, INT:applyOnArmor, INT:applyOnWeapon[)'''

Changes the material of the object for a set time (in turns), -1 is infinite. applyNormalMap: Copy the original materials normal map

'''TeleportTo(CHARACTER|ITEM:object, GAMEOBJECT|FLOAT3:target, [INT:Force=0])'''

Teleport object to or near the target

'''Transform(CHARACTER|ITEM:object, CHARACTERTEMPLATE|ITEMTEMPLATE:root [, FIXEDSTRING:fx, INT:replaceScripts=1, OUT FLOAT:currentHP])'''

Transforms <object> using <root>, returns <currentHP>, plays <fx>.

'''SaveGame(FIXEDSTRING:saveGameName)'''

Save the savegame with name <saveGameName>

'''LoadGame(FIXEDSTRING:saveGameName)'''

Load the savegame with name <saveGameName>

'''LoadLevel(FIXEDSTRING:levelName)'''

Load the level with name <levelName>

'''KillCombat(CHARACTER:character)'''

Kill all the enemies in the combat which contains <character>

'''SetTag(CHARACTER|ITEM:object, FIXEDSTRING:tag)'''

Sets the Tag on the Object

'''ClearTag(CHARACTER|ITEM:object, FIXEDSTRING:tag)'''

Clears the Tag on the Object

'''SetGlobalFlag(FIXEDSTRING:flagname)'''

Sets the Global Flag

'''ClearGlobalFlag(FIXEDSTRING:flagname)'''

Clears the Global Flag

'''SetFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Sets the Flag on the Object

'''ClearFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the Object

'''SetUserFlag(CHARACTER:object, FIXEDSTRING:flagname)'''

Sets the Flag on the user's characters

'''ClearUserFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the user's characters

'''SetPartyFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Sets the Flag on the party's characters

'''ClearPartyFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagname)'''

Clears the Flag on the party's characters

'''StartVoiceBark(STRING:barkName, CHARACTER:character)'''

Start a voicebark on character

'''ConfrontationDone(INT: CrimeID, CHARACTER:lead, CHARACTER:criminal, ...)'''

Resolve the crime with id CrimeID for the specified criminals

'''CrimesceneInvestigationDone(CHARACTER:investigator)'''

Crimescene is considered investigated by this NPC, start looking for culprits

'''ListAdd(LIST<OBJECT>:list, OBJECT:entry)'''

Add <entry> at the back of <list>

'''ListRemove(LIST<OBJECT>:list, INT:index)'''

Remove the entry at <index> of <list>

'''ListSet(LIST<OBJECT>:list, INT:index, OBJECT:entry)'''

Set the entry at <index> of <list> to <entry>

'''ListClear(LIST<OBJECT>:list)'''

Remove all entries of <list>

'''EndTurn(CHARACTER|ITEM:Target)'''

Ends the object's current turn

'''SetCanFight(CHARACTER|ITEM:entity, INT:enabled[, INT:wholeGroup=0])'''

Enables/Disables the fact if the entity can fight. Optional for the whole group

'''SetCanJoinCombat(CHARACTER|ITEM:entity, INT:enabled[, INT:wholeGroup=0])'''

Enables/Disables the fact if the entity can join combats. Optional for the whole group

'''SetIsBoss(CHARACTER|ITEM:entity, INT:enabled)'''

Enables/Disables the fact if the entity is a boss.

'''GetAIHintTriggers(OUT LIST<TRIGGER>:triggers[, [LIST]FIXEDSTRING:tags, INT:needsAllTags = -1)'''

Returns all AIHintAreaTriggers in <triggers>. Uses contraints if set.

'''SetCombatTimeout(CHARACTER|ITEM:entity, FLOAT:timer)'''

Overwrites the entity's combat timeout check.

'''ResetCombatTimeout(CHARACTER|ITEM:entity)'''

Resets the entity's combat timeout check.

'''EnterCombat(CHARACTER|ITEM:source, CHARACTER|ITEM:target)'''

Enters combat with target

'''LeaveCombat(CHARACTER|ITEM:source)'''

Leaves the combat

'''SetFaction(CHARACTER|ITEM:target, FIXEDSTRING:faction)'''

Changes the faction of a character or item

'''SetInvulnerable(CHARACTER|ITEM:target, INT:bool)'''

Makes the character or item invulnerable or not. (Allow damage)

'''JumpToTurn(CHARACTER|ITEM:Target)'''

Jumps to targets turn (ends the current turn)

'''Sleep(FLOAT:timeInSeconds)'''

Sleeps for a certain amount of time

'''CharacterAttack(CHARACTER|ITEM|FLOAT3:target [,INT:alwaysHit])'''

Moves in weapon range and attacks the target

'''CharacterAttackWithoutMove(CHARACTER|ITEM|FLOAT3:target [,INT:alwaysHit])'''

Attacks the target without checking weaponranges and without moving

'''CharacterMoveTo(GAMEOBJECT|FLOAT3:target, [INT:running=0, INT:shouldArrive=0, INT:longPath=0, FLOAT:minDistance=1.5, FLOAT:maxDistance=minDistance+2.5])'''

Move to the target. Set shouldArrive to 1 if you want a guaranteed move. (teleports on fail)

'''CharacterAiMove(FLOAT3:target, CHARACTER:targetCharacter, ITEM:targetItem)'''

Moves to the target, calculated by the AI. Should only be used with results from the AI!

'''CharacterMoveInRange(GAMEOBJECT|FLOAT3:target, FLOAT:rangeMin, FLOAT:rangeMax, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within a certain range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveInWeaponRange(GAMEOBJECT|FLOAT3:target, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within weapon range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveInSkillRange(GAMEOBJECT|FLOAT3:target, SKILL:skill, INT:running, [LIST<TRIGGER>:hintTriggers=null, INT:mustBeInTrigger=0])'''

Move within skill range of target. Optionally pass hinttriggers in which the result is preferred/necessary.

'''CharacterMoveOutOfSight(FLOAT:angle)'''

Move out of screen

'''CharacterPlayAnimation(FIXEDSTRING:animation [, INT:exitOnFinish=1, INT:waitForCompletion=1])'''

Plays a certain animation ExitOnFinish means if the exit will kill itself after it was played (revert back to still)

'''CharacterStopAnimation(-)'''

Stops all animations.

'''CharacterPickUpItem(ITEM:item)'''

Moves close enough to the item if necessary and picks it up

'''CharacterUseItem(ITEM:item [, INTEGER:LongPath])'''

Moves close enough to the item if necessary and uses it

'''CharacterMoveItem(ITEM:item, INTEGER:ignoreWeight, INTEGER:ignoreAPCost [, INTEGER:ignoreDangerousSurfaces=1, INT:amount=-1, GAMEOBJECT|FLOAT3:destination])'''

Moves close enough to the item if necessary and moves it to the destination. Will try to find a destination if not supplied.

'''CharacterAddSkill(CHARACTER:character, SKILL:skill[, INT:ShowNotification=0])'''

Adds <skill> to <character>

'''CharacterRemoveSkill(CHARACTER:character, SKILL:skill)'''

Removes <skill> from <character>

'''CharacterUseSkill(SKILL:skill, GAMEOBJECT|FLOAT3:target [, GAMEOBJECT|FLOAT3:target2, ITEM:skillItem, INT:ignoreHasSkill=0])'''

Cast a skill

'''CharacterAppearAt(GAMEOBJECT|FLOAT3:target, INT:playspawn)'''

Appear at the target

'''CharacterAppearOutOfSightTo(GAMEOBJECT:target, FLOAT:angle, INT:playspawn)'''

Appears out of sight to the players from a certain angle while being able to reach target

'''CharacterAppearOnTrailOutOfSightTo(CHARACTER:target, FLOAT:angle, INT:playspawn)'''

Appears out of sight to the players, on its previous locations, from a certain angle while being able to reach target

'''CharacterDisappear(FLOAT:angle[, INTEGER:isRunning=0])'''

Move out of screen and go of stage, will run if <isRunning> is not 0

'''CharacterSetOffStage(-)'''

Set Off Stage

'''CharacterSetOnStage(-)'''

Set On Stage

'''CharacterLookAt(GAMEOBJECT|FLOAT3|SPLINE:target[, INT:snapToTarget=0, INT:angleTolerance=0])'''

Rotates the character to look at the target (Closest spline point in case of a spline).

'''CharacterLookFrom(GAMEOBJECT|SPLINE:target[, INT:snapToTarget=0])'''

Rotates to the character so it has the same rotation as the target (Closest spline point in case of a spline).

'''CharacterFollow(CHARACTER:target, FLOAT:durationInSeconds, INT:run)'''

Follow the target for a certain time

'''CharacterFollowOwnerOrLeader(FLOAT:durationInSeconds, INT:run)'''

Follow the leader or owner for a certain time

'''CharacterWander(FLOAT|TRIGGER:range, FLOAT:durationInSeconds [, INT:run, GAMEOBJECT:anchor])'''

Wander around for a certain time

'''CharacterSwitchWeaponType(WEAPON:type)'''

If necessary switch to the new weapon type

'''CharacterFleeFrom(RELATION:relation, FLOAT:range)'''

Run away from certain characters if necessary
'''
CharacterFleeFromSurface(SURFACE:surface)'''

Run away from a certain surface if necessary

'''CharacterFleeFromDangerousSurface(-)'''

Run away from a dangerous surfaces if necessary

'''CharacterAddSourcePoints(CHARACTER:character, INT:amount)'''

Adds x source points (x can be negative to substract)

'''CharacterDie(CHARACTER:character[, DEATH:type=DoT])'''

Kills the character

'''CharacterHeal(CHARACTER:character, FLOAT:percentage)'''

Heals the character

'''CharacterConsume(CHARACTER:character, POTION:potion)'''

Makes the character consume a potion. Doesn't cost any AP and will just execute the result of the potion.

'''CharacterDisableAllCrimes(CHARACTER:target)'''

Disables all generic behaviours for <target>.

'''CharacterEnableAllCrimes(CHARACTER:target)'''

Enables all generic behaviours for <target>.
'''
CharacterEnableCrime(CHARACTER:target, STRING:crime, ...)'''

Enables the specified generic behaviours for <target>.

'''CharacterDisableCrime(CHARACTER:target, STRING:crime, ...)'''

Disables the specified generic behaviours for <target>.

'''CharacterSetLongInvestigationDuration(CHARACTER:target)'''

Doubles the time it takes for the investigation to time out. Use this when the character needs to move a long path before investigating.

'''CharacterAiCalculate(-)'''

Calculate the AI of the character

'''CharacterAiStopCalculate(-)'''

Stop the calculation of the AI of the character

'''CharacterAiFinishMoveSkill(-)'''

Finish the current MoveSkill.
'''
CharacterAiAddInterestingItem(CHARACTER:character, ITEM:item)'''

Make it interesting for the AI to destroy that Item

'''CharacterAiRemoveInterestingItem(CHARACTER:character, ITEM:item)'''

Make it no longer interesting for the AI to destroy that Item

'''CharacterSetArchetype(CHARACTER:character, ARCHETYPE:archetype)'''

Sets the archetype of the character, used in AI calculations

'''CharacterSetStoryNPC(CHARACTER:character, INT:bool)'''

Makes the character storyNPC or not.
'''
CharacterAddActionPoints(CHARACTER:character, INT:amount)'''

Give character some action points

'''CharacterSetImmortal(CHARACTER:character, INT:bool)'''

Makes the character immortal or not. (Allow dying)

'''CharacterPlayEffect(CHARACTER:character, STRING:effect [,FIXEDSTRING:boneName])'''

Plays an effect on the character and it follows the character

'''CharacterPlayLoopEffect(OUT INT64:effectHandle, CHARACTER:character, STRING:effect [,FIXEDSTRING:boneName])'''

Plays a looping effect on the character and it follows the character

'''CharacterEvent(CHARACTER:character, STRING:eventName)'''

Throw a character event which you can catch in scripts and story

'''CharacterItemEvent(CHARACTER:character, ITEM:item, STRING:eventName)'''

Throw a character/item event which you can catch in scripts and story

'''CharacterCharacterEvent(CHARACTER:character1, CHARACTER:character2, STRING:eventName)'''

Throw a character/character event which you can catch in scripts and story

'''CharacterSetRelationIndivToIndiv(CHARACTER:source, CHARACTER:target, INT:relation)'''

Changes the relationship between 2 characters.
'''
CharacterForceUpdate(INT:forceUpdate)'''

Makes sure the attached character is always being update or not.
'''
CharacterSetEnemy(CHARACTER:character, CHARACTER:enemy)'''

Sets the current enemy of character

'''CharacterApplyStatus(CHARACTER:character, STATUS:statusId [, INT:turns=null, INT:force=0])'''

Applies the status to the character When turns is -1 it's a permanent status When turns is -2 it's a keep alive status (which means it will die if it's not applied again within 1 second)

'''CharacterRemoveStatus(CHARACTER:character, STATUS:statusId [, STATUS:reasonStatusID=null])'''

Removes the status from the character

'''CharacterDestroy(CHARACTER:character)'''

Destroys the character

'''CharacterSetCanSpotSneakers(CHARACTER:character, INT:enabled)'''

Enables/Disables the fact if the character can spot sneaking characters.

'''CharacterSetAttackOfOpportunity(CHARACTER:character, INT:enabled)'''

Enables/Disables the fact if the character can do attack of opportunities.

'''CharacterResurrect(CHARACTER:character [, INT:Percentage = 100])'''

Resurrects the character at [2]% health.

'''CharacterAddToInventory(CHARACTER:character, FIXEDSTRING:itemStatsObject[, INT:amount, INT:showInTrade=1])'''

Add the item to the character

'''CharacterRemoveFromInventory(CHARACTER:character, FIXEDSTRING:itemStatsObject[, INT:amount])'''

Remove the item from the character. If Amount is -1, then all are removed

'''CharacterDrinkPotion(FIXEDSTRING:statID)'''

Makes the character drink a potion from the inventory.

'''CharacterSetAnimationOverride(CHARACTER:character, FIXEDSTRING:animation)'''

Sets an animation override, only walk/run/die animations can override it.

'''CharacterUseActionPoints(CHARACTER:character, INT:amount [, OUT INT:succeeded])'''

Uses x action points

'''CharacterAddTreasureTable(CHARACTER:character, FIXEDSTRING:treasureTable)'''

Adds <treasureTable> to the treasure list of <character>

'''CharacterRemoveTreasureTable(CHARACTER:character, FIXEDSTRING:treasureTable)'''

Removes <treasureTable> from the treasure list of <character>

'''CharacterClearTreasureTables(CHARACTER:character)'''

Removes all treasure tables from <character>

'''CharacterSetTemporaryHostileRelation(CHARACTER:character, CHARACTER:otherCharacter)'''

Creates a temporary hostile relation between the 2 characters!

'''CharacterSetFightMode(CHARACTER:character, INT:fight [, INT:force=0])'''

Set the character in sheath/unsheated mode.

'''CharacterSetStats(CHARACTER:character, FIXEDSTRING:statsEntry [, INT:keepVitality=0, INT:keepAP=0, INT:keepLevel=0, OUT FLOAT:currentHP])'''

Applies <statsEntry> from character.xlsm to <character>, returns <currentHP>.

'''CharacterSetWalkSpeedOverride(CHARACTER:character, INTEGER:override [, FLOAT:walkSpeed])'''

Sets walk speed override of <character>, removes it if <override> is 0

'''CharacterSetRunSpeedOverride(CHARACTER:character, INTEGER:override [, FLOAT:runSpeed])'''

Sets run speed override of <character>, removes it if <override> is 0

'''CharacterSetHasDialog(CHARACTER:character, INTEGER:bool)'''

Enables/Disables the dialog of the character

'''CharacterInitPatrol(SPLINE:spline, INT:splineIndex, INT:reversed, INT:running)'''

Start patroling from the given index along the given spline with the given character.

'''CharacterStartPatrol(SPLINE:spline, INT:splineIndex, INT:reversed, INT:running)'''

Start patroling from the given index along the given spline with the given character.

'''CharacterStopPatrol(-)'''

Let the character stop patrolling whatever spline he's on!

'''CharacterInterruptPatrol(-)'''

Call when the patrol should interrupt so the guard stops moving to the next spline. If this is called when the character is deactivated, a caret will take his place.

'''CharacterSetAnimationSetOverride(CHARACTER:source, FIXEDSTRING:override)'''

Sets an animation set override for a character. Empty fixedstring clears the override.

'''CharacterSetFloating(CHARACTER:target, INTEGER:isFloating)'''

Sets <target> floating if <isFloating> is not 0

'''CharacterResetCooldowns(CHARACTER:target)'''

Resets the skill cooldowns for <target>

'''ItemEvent(ITEM:item, STRING:eventName)'''

Throw an item event which you can catch in scripts and story

'''ItemPlayAnimation(FIXEDSTRING:animation)'''

Plays an animation on the item

'''ItemPlayAnimationTo(FIXEDSTRING:animation, FLOAT:targetPercentage, [FLOAT:speed])'''

Plays an animation on the item to the target time (percentage of the total duration)

'''ItemPlayEffect(ITEM:item, STRING:effect [,FIXEDSTRING:boneName])'''

Plays an effect on the item and it follows the item

'''ItemPlayLoopEffect(OUT INT:effectHandle, ITEM:item, STRING:effect [,FIXEDSTRING:boneName])'''

Plays a looping effect on the item and it follows the item

'''ItemSetOnStage(ITEM:item, INTEGER:bool)'''

Sets an item on or offstage

'''ItemSetCanInteract(ITEM:item, INTEGER:bool)'''

Sets an item (not) interactible

'''ItemClose(ITEM:item)'''

Close an item

'''ItemOpen(ITEM:item)'''

Open an item

'''ItemDrop(ITEM:item)'''

Drop an item

'''ItemLock(ITEM:item, FIXEDSTRING:key)'''

Lock an item

'''ItemUnlock(ITEM:item)'''

Unlock an item

'''ItemApplyStatus(ITEM:item, STATUS:statusId [, INT:turns=null, INT:force=0])'''

Applies the status to the item When turns is -1 it's a permanent status When turns is -2 it's a keep alive status (which means it will die if it's not applied again within 1 second)

'''ItemRemoveStatus(ITEM:item, STATUS:statusId)'''

Removes the status from the item

'''ItemDie(ITEM:item)'''

Kills the item

'''ItemMoveTo(GAMEOBJECT|FLOAT3:target, FLOAT:velocity, FLOAT:acceleration, INTEGER:matchTargetRotation)'''

Moves the item to the target

'''ItemToInventory(ITEM:item, CHARACTER|ITEM:target [,INT:amount=-1])'''

Moves the item to the target's inventory

'''ItemLookAt(GAMEOBJECT:target, FLOAT:degreesPerSecond)'''

Rotates the item to look at the target

'''ItemDestroy(ITEM:item)'''

Destroys the item

'''ItemSetAmount(ITEM:item, INT:amount)'''

Change the amount of the item

'''IterateItemsInInventory(CHARACTER|ITEM:source, FIXEDSTRING:eventname[, FIXEDSTRING:tag])'''

Launch iterate event for each iten in source's inventory. If you pass a tag, it has to have that tag.

'''ItemAddCharges(ITEM:TargetItem, INT:charges)'''

Add/subtract charges from an item

'''ItemResetChargesToInitial(ITEM:TargetItem)'''

Resets charges from item to initial state

'''MakePeace(CHARACTER:Source, CHARACTER:Target[, INT:IgnoreVote = 1])'''

Make peace between users of the characters

'''MakeWar(CHARACTER:Source, CHARACTER:Target[, INT:IgnoreVote = 1])'''

Make war between users of the characters

'''FindSurface(OUT FLOAT3:result, GAMEOBJECT|FLOAT3:source, FLOAT:minRange, FLOAT:maxRange, SURFACE:type [,CHARACTER:alignSource, INT:minEnemiesInSurface, INT:maxAlliesInSurface, INT:minimumCellCount])'''

Finds the closest surface of a specific type.

'''FindValidPosition(INOUT FLOAT3:position, FLOAT:radius[, CHARACTER|ITEM:object=null])'''

Finds the closest valid position (where the object can stand.)

'''FindPosition(INOUT FLOAT3:position, CHARACTER:source, INT:canStand, INT:checkSight, FLOAT:minRadius, FLOAT:maxRadius, FLOAT:rangeCheck, CHARACTER:alignSource, INT:minAllies, INT:maxAllies, INT:minEnemies, INT:maxEnemies [,FIXEDSTRING:AiHintTag=null, INT:forceHint=0, FLOAT3:SourcePosition])'''

Finds the closest position from the source (within radius) where the conditions are matched.

'''Cast(OUT OBJECT variable, OBJECT value)'''

Casts the value to the variable.

'''StringConcatenate(STRING:stringA, STRING:stringB, OUT STRING:resultingString)'''

Appends stringB to stringA. Resulting string is stored in the third parameter.

== QUERIES ==

'''GetPosition(GAMEOBJECT:object,OUT FLOAT3:src)''' 

Get the current position of an object

'''GetForwardDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current forward direction of an object

'''GetRightDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current right direction of an object

'''GetUpDirection(GAMEOBJECT:object,OUT FLOAT3:direction)''' 

Get the current up direction of an object

'''GetDirection(GAMEOBJECT|FLOAT3:src,GAMEOBJECT|FLOAT3:target,OUT FLOAT3:direction[, OUT FLOAT:distance])''' 

Get the direction from src to target (optional: returns the distance between the objects as well)

'''GetRotation(GAMEOBJECT:object, OUT FLOAT3:vector)''' 

Get the rotation of an object

'''CharacterGetTargetSpline(INT: SplineIndex)''' 

Returns the spline index the character is currently walking towards, or -1 if he is not active on a spline.

'''IsEqual(OBJECT:variable, OBJECT:variable)''' 

Compares both objects and see if they are equal.

'''IsLessThen(INT|FLOAT:variable, INT|FLOAT:variable)''' 

Compares both objects and see if the first one is smaller.

'''IsGreaterThen(INT|FLOAT:variable, INT|FLOAT:variable)''' 

Compares both objects and see if the first one is bigger.

'''IsRandom(FLOAT:percentage)''' 

Each time this condition is checked, it will succeed with a chance of the percentage (between 0 and 1)

'''IsRound(INT:roundNumber)''' 

Checks if we are currently in combat in round x

'''IsInSurface(OBJECT|FLOAT3:target, SURFACE:type[, FLOAT:radius])''' 

Check if the character, item, trigger or position is currently within the specific surface.

'''IsInDangerousSurface(OBJECT|FLOAT3:target[, CHARACTER:character, FLOAT:radius])''' 

Check if <target> is currently in on a dangerous surface. Uses <character> for path influences if provided (is necessary with non-character targets)

'''IsInDialog(CHARACTER|ITEM:target[, INT:ignoreAutomatedDialogs=0])''' 

Check if the character or item is currently in a dialog, optionally ignoring automated dialogs

'''IsInAutomatedDialog(CHARACTER|ITEM:target)''' 

Check if the character or item is currently in an automated dialog

'''GetDistance(OUT FLOAT:distance, GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 

Returns the distance between 2 positions

'''GetDistance2D(OUT FLOAT:distance, GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 

Returns the 2D distance between 2 positions (ignores height)

'''GetInnerDistance(OUT FLOAT:distance, GAMEOBJECT:source, GAMEOBJECT:target)''' 

Returns the distance between 2 gameobjects (character, item, trigger, ...) Their bounds are already subtracted.

'''GetPosition(GAMEOBJECT:object, OUT FLOAT3:position)''' 

Returns the position of a gameobject (character, item, trigger, ...)

'''GetVar(OUT OBJECT:returnValue, CHARACTER|ITEM:target, FIXEDSTRING:varName)''' 

Gets a global variable from the target

'''GetClosestPlayer(OUT CHARACTER:player, GAMEOBJECT|FLOAT3:source)''' 

Gets the closest player near the source, default being being the object itself

'''GetPlayerCount(OUT INT:playerCount)''' 

Gets the number of players in the party

'''GetPlayerByIndex(OUT CHARACTER:returnCharacter, INT:playerIndex)''' 

Gets a player from the party by index

'''GetRandomCharacter(OUT CHARACTER:returnCharacter, [INT:canBeSelf=0, INT:canBePlayer=0])''' 

Gets a random character in the current level

'''ContainsSurface(GAMEOBJECT|FLOAT3:source, FLOAT:radius, SURFACE:type,)''' 

Checks if there is any surface of the type within a radius of the source

'''IsSurface(GAMEOBJECT|FLOAT3:source, FLOAT:radius, SURFACE:type)''' 

Checks if the whole radius around the source is the specified surface type

'''IsObjectOnObject(CHARACTER|ITEM:source,CHARACTER|ITEM:target)''' 

Checks if the source is standing on the target

'''GetX(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the X component of the vector

'''GetY(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the Y component of the vector

'''GetZ(FLOAT3:vector, OUT FLOAT:value)''' 

Returns the Z component of the vector

'''CanSee(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target[, INT:addProjectileTargetGroundOffset=0])''' 

Check if the sight is blocked between 2 points.

'''IsVisible(CHARACTER|ITEM:object)''' 

Check if the object is set invisible or not with SetVisible.

'''GetTextDuration(CHARACTER|ITEM:object, FIXEDSRTING:key, OUT FLOAT:duration)''' 

Gets how long a text needs to be displayed

'''IsCasual(-)''' 

Returns if the current game mode is Casual

'''IsHardcore(-)''' 

Returns if the current game mode is Hardcore

'''IsTagged(GAMEOBJECT:object, FIXEDSTRING:tag)''' 

Check if the object is tagged.

'''TranslatedStringKeyExists(FIXEDSTRING:key)''' 

Check if the TranslatedString key exists.

'''IsInCombat(CHARACTER|ITEM:object)''' 

Returns true if the object is in combat.

'''IsInCombatWith(CHARACTER|ITEM:object, CHARACTER|ITEM:object)''' 

Returns true if the objects are in combat with each other.

'''IsFacing(GAMEOBJECT:source, GAMEOBJECT|FLOAT3:target, [INT:angle=90])''' 

Returns true if the object is facing the position within the given angle.

'''GameIsSaving(-)''' 

Returns true if the game is saving.

'''GameIsLoading(-)''' 

Returns true if the game is loading.

'''GetUserCount(OUT INT:userCount)''' 

Returns the user count.

'''GetCurrentCharacter(OUT CHARACTER:character, INT:user)''' 

Returns the character currently being controlled by the specified user.

'''GetCurrentLevel(OUT FIXEDSTRING:currentLevel)''' 

Returns the current levelname

'''GetAIBounds(CHARACTER|ITEM:source, OUT FLOAT:bounds)''' 

Returns AI bounds of <source> in <bounds>

'''HasGlobalFlag(FIXEDSTRING:flagName)''' 

Returns if the Global Flag is set

'''HasFlag(CHARACTER|ITEM:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the Object

'''HasUserFlag(CHARACTER:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the user's characters

'''HasPartyFlag(CHARACTER:object, FIXEDSTRING:flagName)''' 

Returns if the Flag is set on the party's characters

'''DialogExists(STRING:dialogue)''' 

Returns true if the dialogue exists.

'''IsActive(CHARACTER|ITEM:Object)''' 

Returns if the character or item is currently active.

'''ListGetSize(LIST<OBJECT>:list, out INT:size)''' 

Returns the number of elements in <list>

'''ListGet(LIST<OBJECT>:list, INT:index, out OBJECT:entry)''' 

Returns <entry> at <index> of <list>

'''ListGetRandom(LIST<OBJECT>:list, out OBJECT:entry)''' 

Returns a random <entry> of <list>

'''IsBoss(CHARACTER|ITEM:Object)''' 

Returns true if the entity is tagged as a boss

'''IsProjectileSkill(SKILL:skill)''' 

Returns true if the skill is a ranged skill (uses a projectile)

'''IsValidSkillTarget(CHARACTER:source, OBJECT|FLOAT3:target, SKILLID:skill[, INTEGER:ignoreRangeCheck=0])''' 

Checks whether <target> is a valid target for <skill> at <source>

'''GetFaction(OUT FIXEDSTRING:faction, CHARACTER|ITEM:character)''' 

Returns the faction of the provided character or item

'''IsInActiveTurn(CHARACTER|ITEM:target)''' 

Returns true if it's the character's or item's turn in combat.

'''IsSkillActive(CHARACTER:character, SKILL:skillId)''' 

Returns true if <character> has <skillId> active (in memory).

'''HasSkillAi(SKILLID:skillId)''' 

Returns true if the skill is using the new Ai system

'''IsInArena(CHARACTER::character)''' 

Returns true if the character is in an arena fight

'''CrimeGetType(INTEGER:crimeId, OUT STRING:crimeType)''' 

Returns the type of the crime with this id.

'''CrimeGetCriminals(INTEGER:crimeId, OUT CHARACTER:criminal1, OUT CHARACTER:criminal2, OUT CHARACTER:criminal3, OUT CHARACTER:criminal4)''' 

Returns the criminals of that crime. They might all be null.

'''IsSourceSkill(SKILL:skill)''' 

Returns true if the skill is a source skill.

'''IsInGameMasterMode(-)''' 

Returns true if the game in game master mode.

'''CharacterGet(OUT CHARACTER:character, GAMEOBJECT|FLOAT3:src, FLOAT:range, COMPARE:howTo, COMPAREFUNC:compareFunc[, RELATION: relation, SURFACE:surface, STATUS:status, TALENT:talent, CHARACTER:inSightOf, FIXEDSTRING:tag])''' 

Get a character within a certain range conforming to the filled in restraints.

'''CharacterCount(OUT INT:count, GAMEOBJECT|FLOAT3:src, FLOAT:range, [RELATION: relation, SURFACE:surface, STATUS:status, TALENT:talent, CHARACTER:inSightOf])''' 

Counts the characters within a certain range conforming to the filled in restraints.

'''CharacterGetOwner(OUT CHARACTER:owner, CHARACTER:source)''' 

Get the character's owner

'''CharacterGetFollow(OUT CHARACTER:to follow, CHARACTER:source)''' 

Get the character to follow

'''CharacterGetEnemy(OUT CHARACTER:current enemy, CHARACTER:source)''' 

Get current enemy of character

'''CharacterCanCast(CHARACTER:source, SKILL:skillId, [ITEM:skillItem=null, INT:ignoreActionPoints=0])''' 

Check if the character source can cast the skill: will check cooldown, actionpoints

'''CharacterCanSitOnItem(CHARACTER:source, ITEM:item)''' 

Check if the character source can sit or lie on an item.

'''CharacterCanDrinkPotion(CHARACTER:source, FIXEDSTRING:potionID[, INT:ignoreActionPoints=0])''' 

Check if the character source can drink the potion: will check inv and actionpoints

'''CharacterCanUseItem(CHARACTER:source, ITEM:item[, INT:ignoreActionPoints=0])''' 

Check if the character source can use the item in the world

'''CharacterCanUseItemInInventory(CHARACTER:source, ITEM:item[, INT:ignoreActionPoints=0])''' 

Check if the character source can use the item in his inventory

'''CharacterCanSee(CHARACTER:watchingChar, CHARACTER|ITEM:target [, INT:forceUpdate=0])''' 

Check if character has target in his line of sight.

'''CharacterCanShoot(CHARACTER:source, GAMEOBJECT|FLOAT3:target)''' 

Check if the character can shoot the target.

'''CharacterIsPlayer(CHARACTER:character)''' 

Check if the character is a player

'''CharacterIsInParty(CHARACTER:character)''' 

Check if the character is in the party

'''CharacterIsEnemy(CHARACTER:source, CHARACTER:target)''' 

Check if target is enemy of source

'''CharacterIsAlly(CHARACTER:source, CHARACTER:target)''' 

Check if target is ally of source

'''CharacterIsNeutral(CHARACTER:source, CHARACTER:target)''' 

Check if target is neutral of source

'''CharacterIsDead(CHARACTER:character)''' 

Check if character is dead

'''CharacterIsMoving(CHARACTER:character)''' 

Check if character is moving (speed > 0)

'''CharacterIsSummon(CHARACTER:character)''' 

Check if character is a summon

'''CharacterIsPartyFollower(CHARACTER:character)''' 

Check if character is a party follower

'''CharacterIsStoryNPC(CHARACTER:character)''' 

Check if character is a story NPC

'''CharacterInWeaponRange(CHARACTER:character, CHARACTER:target)''' 

Check if target is in the current's weapon range

'''CharacterInTouchRange(CHARACTER:character, CHARACTER:targetChar)''' 

Check if target is in the character's touch range

'''CharacterHasStatus(CHARACTER:character, STATUS:statusId[, FIXEDSTRING:extraData])''' 

Check if character currently has the status. ExtraData can be filled in for some statuses: - Consume: statsid of the item - Shield: skillid of the shield

'''CharacterGetStatusSourceCharacter(CHARACTER:character, STATUS:statusId, OUT CHARACTER:source[, FIXEDSTRING:extraData])''' 

Get the source character of a status

'''CharacterGetStatusSourceItem(CHARACTER:character, STATUS:statusId, OUT ITEM:source[, FIXEDSTRING:extraData])''' 

Get the source item of a status

'''CharacterHasTalent(CHARACTER:character, TALENT:talent)''' 

Check if character currently has the talent

'''CharacterHasSkill(CHARACTER:character, SKILL:skillId)''' 

Check if character currently has the skill

'''CharacterHasWeaponType(CHARACTER:character, WEAPON:weaponTYPE [, INT:equipped])''' 

Check if character currently has a weapon of this type in his inventory or equipped

'''CharacterGetStat(OUT FLOAT:statValue, CHARACTER:character, CHARACTERSTAT:statType)''' 

Returns the current value of the stat (Vitality, ...)

'''CharacterGetSightRange(OUT FLOAT:range, CHARACTER:character)''' 

Returns the character's sight range

'''CharacterGetWeaponRange(OUT FLOAT:minRange, OUT FLOAT:maxRange, CHARACTER:character)''' 

Returns the character's current weapon range

'''CharacterGetTouchRange(OUT FLOAT:touchRange, CHARACTER:character)''' 

Returns the character's current touch range

'''CharacterGetSkillRange(OUT FLOAT:minRange, OUT FLOAT:maxRange,CHARACTER:character, SKILL:skillId)''' 

Returns the character's skill range

'''CharacterGetSkillImpactRange(OUT FLOAT:areaRange, CHARACTER:character, SKILL:skillId)''' 

Returns the character's skill range

'''CharacterIsInTrigger(CHARACTER:character, TRIGGER:trigger)''' 

Check if character is in given trigger

'''CharacterGetAbility(OUT INT:value, CHARACTER:character, ABILITY:ability)''' 

Returns the character's value of the specified ability

'''CharacterGetHostileCount(OUT INT:value, CHARACTER:character)''' 

Returns how many characters are targeting this character right now... You can iterate over them with IterateEnemiesOf.

'''CharacterCanFight(CHARACTER:character)''' 

Returns true if the character can fight.

'''CharacterGetTemplate(CHARACTER:character, OUT CHARACTERTEMPLATE:root)''' 

Returns the roottemplate of the character.

'''CharacterCanSpotSneakers(CHARACTER:character)''' 

Returns true if the character can spot sneaking characters

'''CharacterIsFloating(CHARACTER:character)''' 

Check if character is a floating character

'''CharacterInCreation(CHARACTER:character)''' 

Returns true if the character is in character creation

'''CharacterAvoidsTraps(CHARACTER:character)''' 

Returns true if the character avoids traps

'''CharacterCheckRelation(CHARACTER:character, RELATION:relation)''' 

Returns true if relation check succeeds

'''CharacterIsBetterOrEqualClass(CHARACTER:character, INT:currentScore, OUT INT:newScore, INT warriorScore, INT rogueScore, INT mageScore, INT clericScore, INT rangerScore)''' 

Returns true if score is higher or equal than the current score

'''CharacterHasBeenHitBy(CHARACTER:character, DAMAGE_TYPE:damageType)''' 

Returns true if the character was hit by this type.

'''CharacterHasCastedSpellLastTurn(CHARACTER:character)''' 

Returns true if the character has casted a spell in his last turn.

'''CharacterHasHadStatus(CHARACTER:character, STATUS:status)''' 

Returns true if the character has had a specific status this combat.

'''CharacterHasAnimationOverride(CHARACTER:character)''' 

Returns true if the character has an animation override.

'''CharacterCanUnlock(CHARACTER:character, ITEM:item)''' 

Returns true if the character can unlock the item (if the item is already unlocked it returns true!)

'''CharacterGetReservedUserID(OUT INT:user, CHARACTER:character)''' 

Returns the character's reserved User id.

'''CharacterGetRace(CHARACTER:character, OUT FIXEDSTRING:race)''' 

Returns the <character>'s race in <race>.

'''CharacterIsRace(CHARACTER:character, FIXEDSTRING:race)''' 

Returns true if <character>'s race is <race>.

'''CharacterCanMoveItem(CHARACTER:character, ITEM:item, FLOAT:minRadius, FLOAT:maxRadius [, OUT FLOAT3:destination])''' 

Returns true + <destination> if <character> can move <item> somewhere between <minRadius> and <maxRadius>.

'''CharacterGetDeathType(CHARACTER:character, OUT FIXEDSTRING:deathType)''' 

Returns death type of <character> in <deathType>.

'''CharacterGetStillAnimation(CHARACTER:object, OUT FIXEDSTRING:stillAnimation)''' 

Returns the still animation to play

'''CrimeTransferLeadership(INT: CrimeID[, FIXEDSTRING:Tag1,...])''' 

Try and transfer the leadership of this crime to someone else.

'''CrimeGetLeadInvestigator(OUT CHARACTER:lead, INT: CrimeID)''' 

Returns the lead investigator for the crime.

'''CharacterCanHitTargetWithRangedWeapon(CHARACTER:source, OBJECT|FLOAT3:target[, SKILL:skill = null])''' 

Returns true if <source> can hit <target> with currently equipped ranged weapon. Will use <skill> instead of equipped weapon if provided.

'''CharacterHasRangedWeapon(CHARACTER:character[, INT:checkInventory = 0])''' 

Returns true if <character> has has ranged weapon. Checks for non-wielded weapons if <checkInventory> is 1

'''CheckInteractionReach(CHARACTER:character, CHARACTER|ITEM: target)''' 

Returns true if <character> could interact with <target>. This is not checking ranges, but checking if there's too much of a height difference or too many obstacles in between.

'''CharacterGetSourcePoints(CHARACTER:character, OUT INT: amount)''' 

Returns the amount of sourcepoints of <character>.

'''CharacterAiIsCalculating(-)''' 

Returns if the character is still calculating the AI.

'''CharacterAiFetchMoveSkillCommand(OUT SKILL:skill, OUT ITEM:skillItem, OUT FLOAT3:target)''' 

Returns if the character has a Move Skill command to execute according to the AI.

'''CharacterAiFetchSkillCommand(OUT SKILL:skill, OUT ITEM:skillItem, OUT FLOAT3 endPosition, OUT FLOAT3:target, OUT CHARACTER:target, OUT ITEM:target, OUT FLOAT3:target2, OUT CHARACTER:target2, OUT ITEM:target)''' 

Returns if the character has a Skill command to execute according to the AI.

'''CharacterAiFetchConsumeCommand(OUT ITEM:item)''' 

Returns if the character has a Consume command to execute according to the AI.

'''CharacterAiFetchAttackCommand(OUT FLOAT3:endPosition, OUT FLOAT3:target, OUT CHARACTER:target, OUT ITEM:target)''' 

Returns if the character has a Attack command to execute according to the AI.

'''CharacterAiFetchFallbackCommand(OUT FLOAT3:targetPosition, OUT FLOAT3:lookAtPosition)''' 

Returns if the character has a Fallback command to execute according to the AI.

'''CharacterGetArchetype(CHARACTER:character, OUT ARCHETYPE:archetype)''' 

Returns the archetype of the character.

'''CharacterIsPolymorphedInto(CHARACTER:character, FIXEDSTRING:race)''' 

Returns true if <character> is polymorphed into <race>. Race can be a race (like HUMAN), but also a template (in case of a polymorph skill like Chicken Touch).

'''CharacterIsPolymorphInteractionDisabled(CHARACTER:character)''' 

Returns true if <character> has his interaction disabled because of a polymorph.

'''ItemGet(OUT ITEM:item, GAMEOBJECT|FLOAT3:src, FLOAT:range, COMPARE:howTo [, COMPAREFUNC:compareFunc, FIXEDSTRING:rootTemplate, FIXEDSTRING:tag])''' 

Get an item within a certain range conforming to the filled in restraints.

'''ItemGetFromInventory(OUT ITEM:item, CHARACTER|ITEM:object [, FIXEDSTRING:statsId, FIXEDSTRING:tag, INT:isEquiped])''' 

Returns the first item in the inventory conforming to the filled in restraints.

'''ItemIsInCharacterInventory(ITEM:item, CHARACTER:object)''' 

Returns if the item is in the inventory of the character

'''ItemIsInTrigger(ITEM:item, TRIGGER:trigger)''' 

Check if item is in given trigger

'''ItemGetStat(OUT FLOAT:statValue, ITEM:item, ITEMSTAT:statType)''' 

Returns the current value of the stat (Weight, ...)

'''ItemIsMoving(ITEM:item)''' 

Returns if the item is moving or not.

'''ItemIsFalling(ITEM:item)''' 

Returns if the item is falling or not. (after teleport)

'''ItemIsOpening(ITEM:item)''' 

Returns if the item is opening or not.

'''ItemIsClosing(ITEM:item)''' 

Returns if the item is closing or not.

'''ItemIsLocked(ITEM:item)''' 

Returns if the item is locked or not.

'''ItemIsMovable(ITEM:item)''' 

Returns if the item is movable or not.

'''ItemCanBeLockPicked(ITEM:item)''' 

Returns if the item is can be opened by lockpicking.

'''ItemIsOpen(ITEM:item)''' 

Returns if the item is open or not.

'''IsStoryItem(ITEM:item)''' 

Returns if the item is a story item.

'''ItemHasStatus(ITEM:item, STATUS:statusId)''' 

Returns if the item has the status.

'''ItemIsDestroyed(ITEM:item)''' 

Returns if the item is destroyed.

'''ItemGetTemplate(ITEM:item, OUT ITEMTEMPLATE:root)''' 

Returns the roottemplate of the item.

'''ItemGetSkillId(ITEM:item, OUT SKILL:root)''' 

Returns the skillid of the item if it has one.

'''ItemGetItemType(ITEM:item, OUT FIXEDSTRING:itemType)''' 

Returns the itemtype of the item: common, unique, rare, ...

'''ItemGetStatusSourceCharacter(ITEM:item, STATUS:statusId, OUT CHARACTER:source)''' 

Get the source character of a status

'''ItemGetStatusSourceItem(ITEM:item, STATUS:statusId, OUT ITEM:source)''' 

Get the source item of a status

'''ItemCanBeMoved(ITEM:item)''' 

Returns if the item can be moved.

'''GetStatusTurns(CHARACTER|ITEM:object, STATUS:statusId, OUT INT:turnsLeft)''' 

Returns true if the object has the given status, and returns the amount of turns still left

== EVENTS ==

'''OnCharacterEvent(CHARACTER:character, STRING:eventName)''' 
Thrown from scripts or story

'''OnCharacterItemEvent(CHARACTER:character, ITEM:item, STRING:eventName)''' 
Thrown from scripts or story

'''OnCharacterCharacterEvent(CHARACTER:character, CHARACTER:character, STRING:eventName)''' 
Thrown from scripts or story

'''OnItemEvent(ITEM:item, STRING:eventName)''' 
Thrown from scripts or story

'''OnItemDestroyed(ITEM:item)''' 
Thrown when an item is destroyed

'''OnItemDestroying(ITEM:item)''' 
Thrown when an item is being destroyed

'''OnItemOpened(ITEM:item)''' 
Thrown when an item is opened

'''OnItemClosed(ITEM:item)''' 
Thrown when an item is closed

'''OnItemDropped(ITEM:item, STRING:itemTemplate)''' 
Thrown when an item is dropped

'''OnGlobalFlagSet(FIXEDSTRING:eventName)''' 
Thrown when a global event is set

'''OnGlobalFlagCleared(FIXEDSTRING:eventName)''' 
Thrown when a global event is cleared

'''OnCharacterFlagSet(FIXEDSTRING:eventName, CHARACTER:character)''' 
Thrown when a dialog event is set on a character

'''OnCharacterFlagCleared(FIXEDSTRING:eventName, CHARACTER:character)''' 
Thrown when a dialog event is cleared on a character

'''OnItemFlagSet(FIXEDSTRING:eventName, ITEM:item)''' 
Thrown when a dialog event is set on an item

'''OItemFlagCleared(FIXEDSTRING:eventName, ITEM:item)''' 
Thrown when a dialog event is cleared on an item

'''OnTimer(FIXEDSTRING:timerName)''' 
Thrown when a timer has ended

'''OnInit(-)''' 
Thrown when the script is set

'''OnLoaded(INT:major, INT:minor, INT:revision, INT:build)''' 
Thrown when the script is loaded from the savegame

'''OnShutdown(-)''' 
Thrown when the character's script is removed

'''OnVariableCleared(FIXEDSTRING:varName)''' 
Thrown when this object's script variable is cleared from Osiris with ClearVarObject

'''OnCombatStarted(INT:combatID)''' 
Thrown when combat starts

'''OnCombatSwitched(CHARACTER:source, ITEM:source)''' 
Thrown when the character switch from one combat to another

'''OnLeftCombat(CHARACTER:source, ITEM:source)''' 
Thrown when the character or item left the combat

'''OnTurn(CHARACTER:source, ITEM:source)''' 
Thrown when the character's turn starts

'''OnTurnEnded(CHARACTER:source, ITEM:source)''' 
Thrown when the character's turn ended

'''OnCharacterVitalityChanged(CHARACTER:character, FLOAT:percentage)''' 
Thrown when the characters's vitality changed

'''OnItemVitalityChanged(ITEM:item, FLOAT:percentage)''' 
Thrown when the item's vitality changed

'''OnAttackOfOpportunity(CHARACTER:target)''' 
Thrown when the characters gets an attack of opportunity on an enemy

'''OnClearAttackOfOpportunity(-)''' 
Thrown when the characters attack of opportunity is cleared

'''OnDamage(DAMAGE:type, FLOAT:percentage, CHARACTER:source, ITEM:source)''' 
Thrown when the object receives damage

'''OnMiss(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character dodges something

'''OnCriticalHit(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character is critical hit

'''OnPreBlock(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown before the character blocks something (at the start of the attack animation)

'''OnBlock(CHARACTER:source, ITEM:source, CHARACTER:target, ITEM:target)''' 
Thrown when the character blocks something

'''OnDie(CHARACTER:character, DAMAGE:type, CHARACTER:source, ITEM:source)''' 
Thrown when the character dies

'''OnCharacterStatusAttempt(CHARACTER:character, STATUS:status)''' 
Thrown when the character attempts to gain a status

'''OnCharacterStatusApplied(CHARACTER:character, STATUS:status)''' 
Thrown when the character gains a status

'''OnCharacterStatusRemoved(CHARACTER:character, STATUS:status)''' 
Thrown when the character loses a status

'''OnItemStatusAttempt(ITEM:item, STATUS:status)''' 
Thrown when the item attempts to gain a status

'''OnItemStatus(ITEM:item, STATUS:status)''' 
Thrown when the item gains a status

'''OnItemStatusRemoved(ITEM:item, STATUS:status)''' 
Thrown when the item loses a status

'''OnStatusCreateVisuals(STATUS:status)''' 
Thrown when the item should create the visuals for this status

'''OnStatusDestroyVisuals(STATUS:status)''' 
Thrown when the item should destroy the visuals for this status

'''OnSight(CHARACTER:character)''' 
Thrown when the character sees another character

'''OnLostSight(CHARACTER:character)''' 
Thrown when the character doesn't see another character anymore

'''OnUseItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character uses an item

'''OnPickupItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character picks up an item

'''OnCharacterPreMovedItem(CHARACTER:source, ITEM:item)''' 
Event thrown just before a character moves an item. No difference whether it is in the world or in their inventory

'''OnCharacterMovedItem(CHARACTER:source, ITEM:item)''' 
Thrown when a character moved an item

'''OnItemEquipped(CHARACTER:source, ITEM:item)''' 
Thrown when a character equips an item

'''OnItemUnequipped(CHARACTER:source, ITEM:item)''' 
Thrown when a character unequips an item

'''OnIterateCharacter(CHARACTER:character, FIXEDSTRING:eventId)''' 
Thrown by iterators

'''OnIterateItem(ITEM:source, FIXEDSTRING:eventId)''' 
Thrown by iterators

'''OnIterateCount(FIXEDSTRING:eventId, INTEGER:Count)''' 
Thrown by iterators after all iterations to inform you of the count.

'''OnStoryOverride(-)''' 
Throw when story overrides what the character was doing: teleport, movement, on/offstage

'''OnTriggerEnter(CHARACTER:character, ITEM:item, FIXEDSTRING:eventId)''' 
Thrown by a character or item entering an EventTrigger

'''OnTriggerLeave(CHARACTER:character, ITEM:item, FIXEDSTRING:eventId)''' 
Thrown by a character or item leaving an EventTrigger

'''OnEnemyChanged(CHARACTER:character, CHARACTER:newEnemy)''' 
Thrown when the character's currentenemy changes

'''OnTalentUnlocked(CHARACTER:character, TALENT:newTalent)''' 
Thrown when the character unlocks a new talent

'''OnTalentLocked(CHARACTER:character, TALENT:removedTalent)''' 
Thrown when the there's a talent removed from a character

'''OnCharacterClassChanged(CHARACTER:character, FIXEDSTRING:class)''' 
Thrown when the character changes class in the character creation screen

'''OnCharacterCreationStarted(CHARACTER:character, TRIGGER:creationPoint)''' 
Thrown when the character creation has started, and gives where the character should walk to

'''OnCharacterCreationStopped(CHARACTER:character)''' 
Thrown when the character creation has stopped

'''OnFunction(FIXEDSTRING:functionName)''' 
Throws an event on itself with the functionName. This is to fake function calls

'''OnSkillCast(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when the character casts a skill

'''OnSkillCombatComment(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when the character needs to make a comment

'''OnCharacterUsedSkillOnMe(CHARACTER:character, SKILL_ID:skillID)''' 
Thrown when you are hit by a skill from a character

'''OnItemUnlocked(ITEM: item, CHARACTER:character, ITEM:key)''' 
Thrown when an item gets unlocked by a character.

'''OnAutomatedDialogEnded(STRING:dialogName, INT:instanceID)''' 
Thrown when a automated dialog is ended for this speaker

'''OnAutomatedDialogStarted(STRING:dialogName, INT:instanceID)''' 
Thrown when a automated dialog is started for this speaker

'''OnDialogStarted(STRING:dialogName, INT:instanceID)''' 
Thrown when a dialog is started for this speaker

'''OnDialogEnded(STRING:dialogName, INT:instanceID)''' 
Thrown when a dialog is ended for this speaker

'''OnCrimeSensibleAction(FIXEDSTRING:regionID, INT:crimeID, FIXEDSTRING:reactionName, STRING:primaryDialog, CHARACTER:criminal1, CHARACTER:criminal2, CHARACTER:criminal3, CHARACTER:criminal4, INT:IsPrimary)''' 
Thrown when a character needs to perform a sensible action against criminals

'''OnCrimeInterrogationRequest(FIXEDSTRING:regionID, INT:crimeID, CHARACTER:criminal1, CHARACTER:criminal2, CHARACTER:criminal3, CHARACTER:criminal4, STRING:interrogationDialog)''' 
Thrown when a character needs to perform an interrogation against criminals

'''OnCrimeInvestigate(FLOAT3:CrimePosition, INT:crimeID)''' 
One NPC investigates a crimescene

'''OnCrimeAlarmed(FLOAT3:CrimePosition, INT:crimeID)''' 
All NPCs in a crimearea start looking around.

'''OnCrimeReturnToNormal(-)''' 
Investigation or Alarm timed out.

'''OnCrimeAborted(-)''' 
The game interrupted the sensible action of this NPC.

'''OnSplineControlPointReached(INT:Index, INT:EndReached, STRING:EventString)''' 
Thrown when a character reached a spline node.

''''OnFinishCalculationAi(-)''' 
Thrown when the calculation of the AI is finished.

'''OnGrenadeLand(INT:hitObstacle, CHARACTER:caster)''' 
Thrown when the grenades lands

'''FetchCharacterApplyStatusData(CHARACTER:character, STATUS:status) RETURN(LIST<STATUS>:removeStatuses, STATUS:applyStatus, INT:turns)''' 
Fetch from script which statuses to remove and apply.

'''FetchItemApplyStatusData(ITEM:item, STATUS:status) RETURN(LIST<STATUS>:removeStatuses, STATUS:applyStatus, INT:turns)''' 
Fetch from script which statuses to remove and apply.

'''FetchItemSkillOnDamage(INT:damage, DAMAGE_TYPE:damageType) RETURN(INT:hasSkill, SKILL_ID:skillID, INT:casterLevel)''' 
Fetch from script what skill to execute on damage.

'''FetchSkillScore(SKILL_ID:skillId, CHARACTER:sourceCharacter, CHARACTER:targetCharacter1, ITEM:targetItem1, FLOAT3:targetPosition1, CHARACTER:targetCharacter2, ITEM:targetItem2, FLOAT3:targetPosition2) RETURN(FLOAT:score) 
Fetch from script the score of a skill with set source and target

'''OnActivate(-)''' 
Thrown when a character/item activates

'''OnDeactivate(-)''' 
Thrown when a character/item deactivates

'''OnCharacterUsedSourcePoint(CHARACTER:character)''' 
Thrown when a character uses a source point

'''OnSkillAdded(CHARACTER:character, SKILL_ID:skillId, INT:learned)''' 
Thrown when a character learns a skill

'''OnSkillActivated(CHARACTER:character, SKILL_ID:skillId)''' 
Thrown when a character activates (=adds to memory) a skill

'''OnSkillDeactivated(CHARACTER:character, SKILL_ID:skillId)''' 
Thrown when a character deactivates (=removes from memory) a skill

'''OnItemFlagShared(FIXEDSTRING:eventName, ITEM:item, INT:newValue)''' 
Thrown when a dialog event is shared with an item

'''OnCharacterFlagShared(FIXEDSTRING:eventName, CHARACTER:character, INT:newValue)''' 
Thrown when a dialog event is shared with a character

'''OnItemOffStageChanged(CHARACTER:character, INT:offstage)''' 
Thrown when a character is set on/off stage

'''OnCharacterOffStageChanged(ITEM:item, INT:offstage)''' 
Thrown when a item is set on/off stage

'''OnCharacterTeleported(CHARACTER:target, CHARACTER:cause, FLOAT3:oldPosition, FLOAT3:newPosition, SKILL_ID:skillId)''' 
Thrown when a character gets teleported with a teleport skill

'''OnCombatTick(-)''' 
Thrown when this object ticks in combat. Only thrown for objects that don't get a turn.

'''OnCombatRoundStarted(INT:combatID, INT:roundID) 
Thrown when a round in a combat starts

'''OnReadyInCombat(CHARACTER:character, ITEM:item, INT:combatID)''' 
Thrown when a character or item is ready in combat

'''OnRegionLeft(CHARACTER:character, ITEM:item, FIXEDSTRING:region)''' 
Thrown when a character or item leaves a region

'''OnRegionEntered(CHARACTER:character, ITEM:item, FIXEDSTRING:region)''' 
Thrown when a character or item enters a region

'''OnRuneInserted(CHARACTER:character, ITEM:item, ITEMTEMPLATE:runeItemTemplate, INT:slot)''' 
Thrown when a <character> inserts a rune with roottemplate <runeItemTemplate> from an <item> at a specified <slot>

'''OnRuneRemoved(CHARACTER:character, ITEM:item, ITEM:rune, INT:slot)''' 
Thrown when a <character> removes a <rune> from an <item> at a specified <slot>

'''OnCharacterStartAttackObject(CHARACTER:defenderCharacter, ITEM:defenderItem, CHARACTER:attackerOwner, CHARACTER:attacker)''' 
Thrown when a character attacks a character or item with default attack

'''OnCharacterStartAttackPosition(FLOAT3:position, CHARACTER:attackerOwner, CHARACTER:attacker)''' 
Thrown when a character attacks a position with default attack

== INTERRUPTS ==

'''OnMovementFailed(FLOAT3:targetPos)''' 
Thrown when the reaction is interrupted by a move action failing

'''OnException(-)''' 
Thrown when the reaction is interrupted by an exception

'''OnBetterReactionFound(FIXEDSTRING:reactionName)''' 
Thrown when the reaction is interrupted by another reaction

'''OnNoReactionFound(-)''' 
Thrown when the reaction is interrupted because no reaction is valid

'''OnScriptDisabled(-)''' 
Thrown when the reaction is interrupted because the scriptcontroller is disabled

'''OnManualInterrupt(FIXEDSTRING:reactionName)''' 
Thrown when the reaction is interrupted using the interrupt action

'''OnRegionSwap(FIXEDSTRING:oldLevel, FIXEDSTRING:newLevel)''' 
Thrown when the reaction is interrupted by a region swap

= Divinity: Original Sin 2 Definitive Edition =
The following was added/changed for the Definitive Edition.

== CALLS ==
'''ItemDrop(ITEM:item)''' 
Drops an item from it's owner's inventory. Only characters are treated as owners.

'''RemoveSurfaceLayerAt(GAMEOBJECT|FLOAT3:target, INT:layer, FLOAT:radius)''' 
Removes surface (ground or cloud) at object/position. (Layer 0 for surface, otherwise - cloud) (Radius for cleanup)

'''SurfaceCreateLink(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 
Makes surfaces at 2 locations/positions interact as if they were adjacent.

'''SurfaceRemoveLink(GAMEOBJECT|FLOAT3:source, GAMEOBJECT|FLOAT3:target)''' 
Stops surfaces at 2 distinctive locations/positions from interacting.

== QUERIES ==
'''AttributeGetDifficultyLevelMappedValue(FIXEDSTRING:difficulty, INT:level, OUT INT:levelMappedValue)''' 
Returns a level-mapped value of a primary attribute. (Difficulty = "Easy", "Normal" or "Hard")

'''CharacterGetCreationClass(CHARACTER:character, OUT FIXEDSTRING: class)''' 
During character creation returns character class. Fails outside of character creation.

'''CharacterGetEquippedItem(CHARACTER:character, FIXEDSTRING:slot, OUT ITEM:seatingItem)''' 
Returns item equipped into slot. (Slot = "Helmet", "Breast", "Leggings", "Weapon", "Shield", "Ring", "Ring2", "Belt", "Boots", "Gloves", "Amulet" or "Wings")

(CHANGED) '''CharacterInCreation(CHARACTER:character, OUT INT:CharacterIndex)''' 
Checks if character is in character creation currently. (CharacterIndex: assigned index of the player character during character creation)

Your First Story Script

2018-09-16T05:24:12Z

LaughingLeader: SkillCast DE update.

Note: this tutorial assumes you have already [[Project browser|created a mod project]], and have a [[Osiris Overview|general idea on Osiris syntax]]. For the purposes of this tutorial, we will be using a basic "Addon" project that targets "Story".

== Required Reading ==
The following is required reading, as it covers the Story Editor, and Osiris syntax and concepts:
* [[Story_editor|Story Editor]]
* [[Osiris Overview]]

== Recommended Reading ==
* [[Osiris_Tips_and_Examples|Osiris Tips and Examples]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]

=== API Docs ===
* [[:Category:Osiris_APIs|Osiris APIs]]
* [[:Category:Osiris_Calls|Osiris Calls]]

== Overview ==
While some basic concepts are covered here, Osiris syntax and defintitions should be referred to in [[Osiris Overview]], as the goal of this tutorial is to guide you in creating a foundation for your code to run, via a parent script and child script.

=== Starting Tips ===
Before we get started, some basic tips to keep in mind:

==== Generate Definitions ====
When opening the story editor in a new project, always generate definitions (File -> Generate Definitions) and exit/re-open the story editor. This will generate the files necessary for auto-complete and syntax highlighting.

==== Prefixing ====
Prefix your goals (a.k.a. your script files), databases, queries, and procs in a way that will make then unique and least likely to conflict with other mods. For example, if our mod is called "Better Cupcakes", and our username is "SuperChef", we could prefix our mod entries with SCBC, or SC_BetterCupcakes, or some combination of the two.

''This concept also applies for entries in the stats editor, as multiple entries with the same name will conflict.''

== Implementing a Basic Story Script ==
=== Getting Started ===
----
# Open the [[Story editor]] by clicking the icon that looks like a book ([[File:StoryEditor_Icon.png|24px]]) under the "Editors" section, at the top-right of the Divinity Engine 2 editor.
# Inside the story editor, Click "File -> Generate Definitions and Build" on the top left.
#* This is an important step in generating the appropriate files. Any time you create new definitions (databases, PROCs, or queries), you need to generate definitions.
#* Building is as equally important, as your changes won't compile until you build.
#* Reloading the story is necessary to see your changes in-game. You can either do this from the story editor ("File -> Reload Story"), or from the main editor with "File -> Reload Level and Story".
# Close the story editor and open it again to essentially reload the syntax highlighting and auto-complete features.

=== Creating a Parent Goal ===
----
For organizational purposes, creating a parent story goal is recommended. For the sake of this tutorial, we'll be parenting our parent goal to __Start, which is a goal provided by Shared.

# Inside the story editor, at the goal list on the left, right click "__Start" and select "Add New Sub Item...".
[[File:FirstStoryScript_ParentingToStart.png|thumb|Right click the goal and click "Add New Sub Item..."]]
# Name this script something unique to your mod in a prefix format (Username_ModName), such as "SuperChef_BetterCupcakes". This has the best chance of not potentially conflicting with any other mod.
# After clicking OK, your script will automatically open. Hit CTRL+S to automatically save this script. Scripts with unsaved changes display and asterisk (*) next to their name.

==== Tip: Story Script Naming ====
----
Goals in the story are ran in alphabetical order. This is important to keep in mind if you use a particular story goal as a sort of "top-level" script that has methods and databases your other goals reference to.

With proper naming, you can control the order your scripts are run. For example, naming your top-level goal "WT_FS__Main", and your second goal "WT_FS_Skills" ensures "WT_FS__Main" will always run before "WT_FS_Skills".
[[File:FirstStoryScript_ScriptOrder.png|thumb|WT_FS__Main will always run before WT_FS_Skills.]]

=== Completing the Parent Goal ===
----
Parent goals need to "complete" before their sub-goals will run. This is done by calling "GoalCompleted;" within the parent script. We have a few options for how to go about this:

==== Parenting to a DOS2 Goal ====
----
Instead of handling the completion events yourself, simply parenting your parent goal to some specific goals provided by Larian is an easy way to ensure your goal runs at the right time.

;Parenting to __Start (No Origins Dependency)
:If your mod doesn't depend on Origins (see: [[Project_settings_window#The_Dependencies_Tab|Dependencies]], parenting your parent goal to __Start will ensure that it runs when the game is ready.

;Parenting to Start (Origins Dependency)
:Start (not to be confused with __Start) is a top-level goal in Origins that completes when character creation is ready, or if a mode other than "Campaign" is started. Parenting to this goal requires your mod to have Origins as a dependency.

;Manual Completion
:Rather than relying on an existing parent goal, it's possible to make a top-level goal that completes on its own. See more on that here: [[Your_First_Story_Script#Manually_Completing_Parent_Goals|Manually Completing Parent Goals]].

==== Parenting Example ====
----
Inside of the INIT section of our new goal, enter the following:
<pre>
DB_WikiTutorial_ModStarted(1);
</pre>

Next, inside the KB section of your goal, enter the following:
<pre>
IF
DB_WikiTutorial_ModStarted(1)
THEN
DebugBreak("[WT_FS] WikiTutorial_FirstStory has initialized.");
GoalCompleted;
</pre>

The goal should look like so:
[[File:FirstStoryScript_ParentGoal.png|thumb]]

# Save, then select "File -> Build and Reload".
# Minimize the story editor.
# Inside the message log, you should see the message we added with DebugBreak.
[[File:FirstStoryScript_ParentGoalComplete.png|thumb|The debug message appears in the message log once the game is started.]]

The way this example works is, as soon as __Start calls GoalCompleted; (which occurs when the event GameEventSet("GAMEEVENT_GameStarted") fires), our goal then sets a database value, which then triggers our own code for GoalCompleted.

Additionally, if this mod is added to an existing save, where __Start was already completed, our parent goal will complete as well, due to the way the parent-child goal relationship works (if a parent is already complete when a new child is added, that child will run).

=== Adding a Sub-Goal ===
----
With the parent goal completing properly, parented sub-goals will now run.

==== Creating a Sub-Goal ====
----
Let's create a basic script that will display some text when a skill is cast.

# Double click on your parent goal to have it selected.
#* Currently, there's a bug where not having your parent goal open may cause a sub-item created to not properly parent under the right goal. If this happens, simply click and drag the new goal to your parent goal, and it should move underneath it.
# Click "Add New Sub Item...", then name it something appropriate, like "WikiTutorial_FirstStory_Skills".
# Save the new script (CTRL+S).

==== Creating a Rule ====
----
In the KB section of our new script, add the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

IF
SkillCast(_Character, "Shout_InspireStart", _, _)
AND
DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Good job!");
CharacterResetCooldowns(_Character);
</pre>

This rule will run when the player casts "Encourage", displaying some text, and resetting their cooldowns. The Encourage skill is added automatically to the player if they lack it.

# Save, then "Generate Definitions and Build".
# In the main editor, select "File -> Reload Level and story".
# Hit the "Switch Game/Editor" button to get in-game. [[File:FirstStoryScript_GameEditorButton.png|thumb|Click this button to switch between game and editor mode.]]
# In whatever level you're working in, your provided dummy character should spawn and be given the Encourage skill.
# Cast the skill to test that your script is working properly.
[[File:FirstStoryScript_SkillCast_Result.png|thumb|Our script in action.]]

===== Notes =====
----
'''HTML Font Formatting'''
* HTML font formatting can be used in DisplayText, CharacterStatusText, and in various text entries (skill descriptions, status names/descriptions, book text, and more).

'''SkillCast '''
* This event runs when the skill's animation reaches the CastTextEvent value specified by the skill stats (which is "cast" in most cases).
* The textkey "cast" is a common textkey used in skill cast animations.
* To view the textkeys present in an animation, open it within the [[Content_browser|Resource Manager]].
* Example: Open the resource manager and search for the "Humans_Hero_Female_ABC_Skill_Cast_Aoe_Air_01_Cast" animation under the Shared folder. Double click on the resource to open the animation preview to see the different textkeys. [[File:FirstStoryScript_SkillCast_Textkey.png|thumb|The cast textkey.]]

'''DB_IsPlayer'''
* This is a base game database that is populated with all the current player characters when the game is started.
* By passing in the _Character value from the event parameters to DB_IsPlayer, we're matching the character against the database of player characters, to have the following code only run if the caster is a player-controlled character.
* Using DB_IsPlayer as an event makes the subsequent code run when a character is added to the DB_IsPlayer database.

== Taking the Script Further ==
Now that we have a basic script heirarchy working, let's take the script further.

=== Randomization ===
----
We can add randomization to the displayed text in our previous script to make the result more interesting.

We'll do this by creating a custom procedure.

;Procedure Tips:
: Procedures are declared with a "PROC" at the top of the block, and follow the same flow as a rule.
: Parameters for a procedure can be customized. You must declare their type.
: Procedures are called within the "call" section of a rule or a custom query.

Add this to the INIT section:
<pre>
//DB_WikiTutorial_FirstStory_RandomText(_Ran, _Text, _FontColor, _FontSize)
DB_WikiTutorial_FirstStory_Skills_RandomText(0, "Woo!", "00CED1", "23");
DB_WikiTutorial_FirstStory_Skills_RandomText(1, "Good job!", "00FF00", "30");
DB_WikiTutorial_FirstStory_Skills_RandomText(2, "I did it!", "DEB887", "20");
DB_WikiTutorial_FirstStory_Skills_RandomText(3, "I'm da best!", "A52A2A", "26");
</pre>

Change the code in the KB section to the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

PROC
WikiTutorial_FirstStory_Skills_DisplayRandomMessage((CHARACTERGUID)_Character)
AND
Random(4, _Ran)
AND
DB_WikiTutorial_FirstStory_Skills_RandomText(_Ran, _Text, _FontColor, _FontSize)
AND
StringConcatenate("", _Str4)
AND
StringConcatenate(_Str4, _Text, _Str5)
AND
StringConcatenate(_Str5, "", _Message)
AND
IntegertoString(_Ran, _RanStr)
AND
StringConcatenate("[WT_FS] Rolled a ", _RanStr, _DebugMessage)
THEN
DisplayText(_Character, _Message);
DebugBreak(_DebugMessage);

IF
SkillCast(_Character, "Shout_InspireStart", _, _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload".
# Switch back to the main editor and hit the play button to get in-game.
# Cast the Encourage skill a few times in game mode to ensure the script is working properly. You should see the different messages, font colors, and font sizes.

===== Notes =====
----
'''Procedures'''
* WikiTutorial_FirstStory_Skills_DisplayRandomMessage is a custom subroutine call, called a PROC. By splitting our message logic off into a separate procedure, this ensures the calls for this rule are ran regardless of the result of our message logic (so CharacterResetCooldowns will always run if a player casts this skill). This also allows us to use this procedure elsewhere, and possible extend it further.

'''Databases'''
* We create our "RandomText" settings in the INIT section by using a database we create, called "DB_WikiTutorial_FirstStory_Skills_RandomText". Databases are a powerful tool for making your scripting logic extensible.

'''[[Osiris/API/Random|Random]]'''
* [[Osiris/API/Random|Random]] returns a random integer value between 0 and (_Modulo - 1). Since our DB_WikiTutorial_FirstStory_Skills_RandomText has 4 entries, we want our random number to be between 0 and 3, so we use 4 as our _Modulo.

=== Using Queries ===
----
Mastering queries is essential for creating complex conditions for your rules. "OR" logic is done within Osiris with multiple rules, subscribing to the same events, that look for different conditions through the use of queries.

Let's add to our skills script. Add this to the KB section, so your SkillCast rules look like this:

<pre>
IF
SkillCast(_Character, "Shout_InspireStart", _, _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);

IF
SkillCast(_Character, "Shout_InspireStart", _, _)
AND
NOT DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Win... Please! Ahhhh!");
ApplyStatus(_Character, "FEAR", 1.0, 1);
</pre>

By simpling adding a NOT before our database check, our second rule will now run on any character (who's not a player) that casts Encourage, and apply fear. You can test this by loading an inherited level that contains some human enemies, or adding human enemies yourself to your test level.

=== Creating a Custom Query ===
----
Taking this idea further, we'll create a custom query.

Custom queries are defined with the keyword "QRY" at the top of a block, and follow the same flow as a rule.

Add the following code to your KB section:

<pre>
QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "HUMAN", 1)
THEN
DB_NOOP(1);

QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "DWARF", 1)
THEN
DB_NOOP(1);
</pre>

By adding two query blocks with the same name, we're effectively adding an "OR" condition. This query will evaluate as true if the character is tagged as either a human or a dwarf.

"DB_NOOP(1);" is a dummy database fact. Since rules must have a call, DB_NOOP is used to have a rule succeed without using any actual calls.

==== Implementing the Custom Query ====
----

Below our query code, in the KB section, add the following:
<pre>
IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Perception_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Perception_Potion");

IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
NOT WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Constitution_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Constitution_Potion");

IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload". Since we added a query and another database, we must generate the definitions again.
# Go in-game and test out the changes by casting Encourage on an human or dwarf (it will work on yourself as well).

===== Notes =====
----
'''NOT'''
* By adding two rules for the same event, and checking for the opposite of our query, we're effectively adding an OR condition to this event.

'''CharacterConsume/CharacterUnconsume'''
* Since CharacterConsume returns a value, it's a query instead of a call. We store the out value from the query (_Handle) in a database to later unconsume the potion effect when ENCOURAGED ends.

'''Removing Database Entries'''
* When unconsuming the potion handle, notice we also remove that entry from the database by calling "NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);" as a call. Using NOT before a database entry (in the call section) removes that entry.
* By using DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion) in the query section, the _Handle and _Potion value is returned with all entries that match the value we pass in (_Character), effectively unconsuming every potion handle we added for that character to the database.

=== Using a Query as a Subroutine ===
----
While queries can be used as conditions, they can also be used to call specific procedures/calls before the main rule reaches that section of the flow.

Let's try a simple example that runs when we unconsume a potion. Change our status removed event code to this:

<pre>
IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_ZombieCheck(_Character)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "UNDEAD", 1)
AND
CharacterGetDisplayName(_Character, _, _Name)
AND
StringConcatenate("[WT_FS] ", _Name, _Str1)
AND
StringConcatenate(_Str1, " is a zombie! Ahh! Burn it!", _Message)
THEN
ApplyStatus(_Character, "BURNING", 1.0);
DebugBreak(_Message);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
THEN
DB_NOOP(1);
</pre>

Which this, our query will apply burning if the character is tagged as UNDEAD. Note how we added a second QRY rule that always evaluates as true - this is to keep the rest of our rule in the CharacterStatusRemoved event running, undead or not.

Practically speaking, using queries as subroutines is ideal when:
* You need specific calls/procedures to run before iterating through a database. Calling your query before retrieving variables from a database ensures that those calls will only run once.
* You need to debug a rule to ensure it reaches a certain section of the conditions. If you're not sure if a specific condition is passing, adding a query with a DebugBreak message right before/after it is a good way to debug that situation.

== Bonus Tips ==

* In the story editor, select "File -> Open Story Header" for a list of all available events, queries, and calls. Heavily reference this file when you find yourself unsure if a specifc method exists, as not all methods appear in the auto-complete.

* If you use databases to store global mod settings, and your mod users have played with that mod, changing that information post-mod install will not automatically remove that data from existing saves - you need to handle this update internally within your mod.
** More on implementing an update system here: [[Osiris_Tips#Updating_Databases|Manual Mod Updates]].

* By using custom procedures and queries, you can reduce your rule redundancy and extend desired calls/conditions to multiple rules.

* To make your life with Osiris easier, wrap your rule blocks in regions with the following:
<pre>
//REGION MY_REGION_NAME

//END_REGION
</pre>
* In the story editor, right click inside your script sections (INIT, KB, or EXIT) and "Expand All" or "Collapse All" to expand/collapse all regions, respectively.

* Procedures can be called from the EXIT and INIT section of scripts.

* Use the INIT section of your scripts as a way to store commented references to your databases. As an example from our previous script, placing this inside your INIT section is a good way to remember such a database exists (since we don't initialize it in the INIT section):
<pre>
//DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
</pre>
Then, when you wish to use this database, you have a quick way to copy/paste that code into other sections of your script.

=== Manually Completing Parent Goals ===
----
Instead of parenting your parent goal to one of the Start goals, it's possible to handle goal completion yourself, using a few different events:

The following events are recommended to use for completing your parent goals:
; [[Osiris/API/GameStarted|GameStarted]]
: Thrown when a level has been loaded and is ready at both the server and client side. This will ensure all the base game scripts have already initialized.
; [[Osiris/API/RegionStarted|RegionStarted]]
: Thrown when the level has been loaded and is ready at the server side, but not yet at the client side.
Both of these events can be used with specific level names, as a way to make your goal only complete once that level is loaded (as a way to create level-specific logic).
;[[Osiris/API/GameEventSet|GameEventSet("GAMEEVENT_GameStarted")]]
: The first story event that gets thrown after the game engine has been initialised when starting a new game. This particular event will only fire the first time a new game is started, so additional rules are needed for cases where your mod is added to an existing save.
;[[Osiris/API/Osiris/API/SavegameLoaded|Osiris/API/SavegameLoaded]]
: Fires when a save is being loaded on an existing save. This can be used to complete your goal on existing saves that just added your mod.

==== Example Goal Completion ====
----
The following is an example of handling initial goal completion yourself:

INIT:
<pre>
MyMod_Internal_CompleteIfStarted();
</pre>

KB:
<pre>
PROC
MyMod_Internal_Start()
THEN
DebugBreak("[MyMod] Parent goal complete.");
GoalCompleted;

IF
GameEventSet("GAMEEVENT_GameStarted")
THEN
MyMod_Internal_Start();

PROC
MyMod_Internal_CompleteIfStarted()
AND
DB_StoryStarted(_)
THEN
DebugBreak("[MyMod:CompleteIfStarted] Story was already started.");
MyMod_Internal_Start();

// For saves where this goal is active, but wasn't completed
IF
SavegameLoaded(_,_,_,_)
AND
DB_StoryStarted(_)
THEN
DebugBreak("[MyMod:SavegameLoaded] Mod added to an existing save.");
MyMod_Internal_Start();
</pre>

[[Category:Osiris]]

Talk:Item Progression

2018-09-14T22:15:46Z

LaughingLeader: Added a request.

=== Open Request: Reformatting the stat examples to the stats editor format (a.k.a. tables) ===
If anyone is interested in reworking the stat examples into a table format, to be more in line with the other wiki pages (such as the Treasure Tables page), that would be greatly appreciated. Personally I prefer to work with the generated text files directly, but I know that many people start off (and stick) with the stats editor, so I don't mind in the slightest if someone would like to take a crack at reformatting things. Thanks.

[[User:LaughingLeader|LaughingLeader]] ([[User talk:LaughingLeader|talk]]) 00:15, 15 September 2018 (CEST)

Your First Story Script

2018-08-08T04:25:12Z

LaughingLeader: Reorganized reading links, starting tips, added some information to clarify the purpose of the tutorial, and simplified parent goal completion section.

Note: this tutorial assumes you have already [[Project browser|created a mod project]], and have a [[Osiris Overview|general idea on Osiris syntax]]. For the purposes of this tutorial, we will be using a basic "Addon" project that targets "Story".

== Required Reading ==
The following is required reading, as it covers the Story Editor, and Osiris syntax and concepts:
* [[Story_editor|Story Editor]]
* [[Osiris Overview]]

== Recommended Reading ==
* [[Osiris_Tips_and_Examples|Osiris Tips and Examples]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]

=== API Docs ===
* [[:Category:Osiris_APIs|Osiris APIs]]
* [[:Category:Osiris_Calls|Osiris Calls]]

== Overview ==
While some basic concepts are covered here, Osiris syntax and defintitions should be referred to in [[Osiris Overview]], as the goal of this tutorial is to guide you in creating a foundation for your code to run, via a parent script and child script.

=== Starting Tips ===
Before we get started, some basic tips to keep in mind:

==== Generate Definitions ====
When opening the story editor in a new project, always generate definitions (File -> Generate Definitions) and exit/re-open the story editor. This will generate the files necessary for auto-complete and syntax highlighting.

==== Prefixing ====
Prefix your goals (a.k.a. your script files), databases, queries, and procs in a way that will make then unique and least likely to conflict with other mods. For example, if our mod is called "Better Cupcakes", and our username is "SuperChef", we could prefix our mod entries with SCBC, or SC_BetterCupcakes, or some combination of the two.

''This concept also applies for entries in the stats editor, as multiple entries with the same name will conflict.''

== Implementing a Basic Story Script ==
=== Getting Started ===
----
# Open the [[Story editor]] by clicking the icon that looks like a book ([[File:StoryEditor_Icon.png|24px]]) under the "Editors" section, at the top-right of the Divinity Engine 2 editor.
# Inside the story editor, Click "File -> Generate Definitions and Build" on the top left.
#* This is an important step in generating the appropriate files. Any time you create new definitions (databases, PROCs, or queries), you need to generate definitions.
#* Building is as equally important, as your changes won't compile until you build.
#* Reloading the story is necessary to see your changes in-game. You can either do this from the story editor ("File -> Reload Story"), or from the main editor with "File -> Reload Level and Story".
# Close the story editor and open it again to essentially reload the syntax highlighting and auto-complete features.

=== Creating a Parent Goal ===
----
For organizational purposes, creating a parent story goal is recommended. For the sake of this tutorial, we'll be parenting our parent goal to __Start, which is a goal provided by Shared.

# Inside the story editor, at the goal list on the left, right click "__Start" and select "Add New Sub Item...".
[[File:FirstStoryScript_ParentingToStart.png|thumb|Right click the goal and click "Add New Sub Item..."]]
# Name this script something unique to your mod in a prefix format (Username_ModName), such as "SuperChef_BetterCupcakes". This has the best chance of not potentially conflicting with any other mod.
# After clicking OK, your script will automatically open. Hit CTRL+S to automatically save this script. Scripts with unsaved changes display and asterisk (*) next to their name.

==== Tip: Story Script Naming ====
----
Goals in the story are ran in alphabetical order. This is important to keep in mind if you use a particular story goal as a sort of "top-level" script that has methods and databases your other goals reference to.

With proper naming, you can control the order your scripts are run. For example, naming your top-level goal "WT_FS__Main", and your second goal "WT_FS_Skills" ensures "WT_FS__Main" will always run before "WT_FS_Skills".
[[File:FirstStoryScript_ScriptOrder.png|thumb|WT_FS__Main will always run before WT_FS_Skills.]]

=== Completing the Parent Goal ===
----
Parent goals need to "complete" before their sub-goals will run. This is done by calling "GoalCompleted;" within the parent script. We have a few options for how to go about this:

==== Parenting to a DOS2 Goal ====
----
Instead of handling the completion events yourself, simply parenting your parent goal to some specific goals provided by Larian is an easy way to ensure your goal runs at the right time.

;Parenting to __Start (No Origins Dependency)
:If your mod doesn't depend on Origins (see: [[Project_settings_window#The_Dependencies_Tab|Dependencies]], parenting your parent goal to __Start will ensure that it runs when the game is ready.

;Parenting to Start (Origins Dependency)
:Start (not to be confused with __Start) is a top-level goal in Origins that completes when character creation is ready, or if a mode other than "Campaign" is started. Parenting to this goal requires your mod to have Origins as a dependency.

;Manual Completion
:Rather than relying on an existing parent goal, it's possible to make a top-level goal that completes on its own. See more on that here: [[Your_First_Story_Script#Manually_Completing_Parent_Goals|Manually Completing Parent Goals]].

==== Parenting Example ====
----
Inside of the INIT section of our new goal, enter the following:
<pre>
DB_WikiTutorial_ModStarted(1);
</pre>

Next, inside the KB section of your goal, enter the following:
<pre>
IF
DB_WikiTutorial_ModStarted(1)
THEN
DebugBreak("[WT_FS] WikiTutorial_FirstStory has initialized.");
GoalCompleted;
</pre>

The goal should look like so:
[[File:FirstStoryScript_ParentGoal.png|thumb]]

# Save, then select "File -> Build and Reload".
# Minimize the story editor.
# Inside the message log, you should see the message we added with DebugBreak.
[[File:FirstStoryScript_ParentGoalComplete.png|thumb|The debug message appears in the message log once the game is started.]]

The way this example works is, as soon as __Start calls GoalCompleted; (which occurs when the event GameEventSet("GAMEEVENT_GameStarted") fires), our goal then sets a database value, which then triggers our own code for GoalCompleted.

Additionally, if this mod is added to an existing save, where __Start was already completed, our parent goal will complete as well, due to the way the parent-child goal relationship works (if a parent is already complete when a new child is added, that child will run).

=== Adding a Sub-Goal ===
----
With the parent goal completing properly, parented sub-goals will now run.

==== Creating a Sub-Goal ====
----
Let's create a basic script that will display some text when a skill is cast.

# Double click on your parent goal to have it selected.
#* Currently, there's a bug where not having your parent goal open may cause a sub-item created to not properly parent under the right goal. If this happens, simply click and drag the new goal to your parent goal, and it should move underneath it.
# Click "Add New Sub Item...", then name it something appropriate, like "WikiTutorial_FirstStory_Skills".
# Save the new script (CTRL+S).

==== Creating a Rule ====
----
In the KB section of our new script, add the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Good job!");
CharacterResetCooldowns(_Character);
</pre>

This rule will run when the player casts "Encourage", displaying some text, and resetting their cooldowns. The Encourage skill is added automatically to the player if they lack it.

# Save, then "Generate Definitions and Build".
# In the main editor, select "File -> Reload Level and story".
# Hit the "Switch Game/Editor" button to get in-game. [[File:FirstStoryScript_GameEditorButton.png|thumb|Click this button to switch between game and editor mode.]]
# In whatever level you're working in, your provided dummy character should spawn and be given the Encourage skill.
# Cast the skill to test that your script is working properly.
[[File:FirstStoryScript_SkillCast_Result.png|thumb|Our script in action.]]

===== Notes =====
----
'''HTML Font Formatting'''
* HTML font formatting can be used in DisplayText, CharacterStatusText, and in various text entries (skill descriptions, status names/descriptions, book text, and more).

'''SkillCast '''
* This event runs when the skill's animation reaches the CastTextEvent value specified by the skill stats (which is "cast" in most cases).
* The textkey "cast" is a common textkey used in skill cast animations.
* To view the textkeys present in an animation, open it within the [[Content_browser|Resource Manager]].
* Example: Open the resource manager and search for the "Humans_Hero_Female_ABC_Skill_Cast_Aoe_Air_01_Cast" animation under the Shared folder. Double click on the resource to open the animation preview to see the different textkeys. [[File:FirstStoryScript_SkillCast_Textkey.png|thumb|The cast textkey.]]

'''DB_IsPlayer'''
* This is a base game database that is populated with all the current player characters when the game is started.
* By passing in the _Character value from the event parameters to DB_IsPlayer, we're matching the character against the database of player characters, to have the following code only run if the caster is a player-controlled character.
* Using DB_IsPlayer as an event makes the subsequent code run when a character is added to the DB_IsPlayer database.

== Taking the Script Further ==
Now that we have a basic script heirarchy working, let's take the script further.

=== Randomization ===
----
We can add randomization to the displayed text in our previous script to make the result more interesting.

We'll do this by creating a custom procedure.

;Procedure Tips:
: Procedures are declared with a "PROC" at the top of the block, and follow the same flow as a rule.
: Parameters for a procedure can be customized. You must declare their type.
: Procedures are called within the "call" section of a rule or a custom query.

Add this to the INIT section:
<pre>
//DB_WikiTutorial_FirstStory_RandomText(_Ran, _Text, _FontColor, _FontSize)
DB_WikiTutorial_FirstStory_Skills_RandomText(0, "Woo!", "00CED1", "23");
DB_WikiTutorial_FirstStory_Skills_RandomText(1, "Good job!", "00FF00", "30");
DB_WikiTutorial_FirstStory_Skills_RandomText(2, "I did it!", "DEB887", "20");
DB_WikiTutorial_FirstStory_Skills_RandomText(3, "I'm da best!", "A52A2A", "26");
</pre>

Change the code in the KB section to the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

PROC
WikiTutorial_FirstStory_Skills_DisplayRandomMessage((CHARACTERGUID)_Character)
AND
Random(4, _Ran)
AND
DB_WikiTutorial_FirstStory_Skills_RandomText(_Ran, _Text, _FontColor, _FontSize)
AND
StringConcatenate("", _Str4)
AND
StringConcatenate(_Str4, _Text, _Str5)
AND
StringConcatenate(_Str5, "", _Message)
AND
IntegertoString(_Ran, _RanStr)
AND
StringConcatenate("[WT_FS] Rolled a ", _RanStr, _DebugMessage)
THEN
DisplayText(_Character, _Message);
DebugBreak(_DebugMessage);

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload".
# Switch back to the main editor and hit the play button to get in-game.
# Cast the Encourage skill a few times in game mode to ensure the script is working properly. You should see the different messages, font colors, and font sizes.

===== Notes =====
----
'''Procedures'''
* WikiTutorial_FirstStory_Skills_DisplayRandomMessage is a custom subroutine call, called a PROC. By splitting our message logic off into a separate procedure, this ensures the calls for this rule are ran regardless of the result of our message logic (so CharacterResetCooldowns will always run if a player casts this skill). This also allows us to use this procedure elsewhere, and possible extend it further.

'''Databases'''
* We create our "RandomText" settings in the INIT section by using a database we create, called "DB_WikiTutorial_FirstStory_Skills_RandomText". Databases are a powerful tool for making your scripting logic extensible.

'''[[Osiris/API/Random|Random]]'''
* [[Osiris/API/Random|Random]] returns a random integer value between 0 and (_Modulo - 1). Since our DB_WikiTutorial_FirstStory_Skills_RandomText has 4 entries, we want our random number to be between 0 and 3, so we use 4 as our _Modulo.

=== Using Queries ===
----
Mastering queries is essential for creating complex conditions for your rules. "OR" logic is done within Osiris with multiple rules, subscribing to the same events, that look for different conditions through the use of queries.

Let's add to our skills script. Add this to the KB section, so your SkillCast rules look like this:

<pre>
IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
NOT DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Win... Please! Ahhhh!");
ApplyStatus(_Character, "FEAR", 1.0, 1);
</pre>

By simpling adding a NOT before our database check, our second rule will now run on any character (who's not a player) that casts Encourage, and apply fear. You can test this by loading an inherited level that contains some human enemies, or adding human enemies yourself to your test level.

=== Creating a Custom Query ===
----
Taking this idea further, we'll create a custom query.

Custom queries are defined with the keyword "QRY" at the top of a block, and follow the same flow as a rule.

Add the following code to your KB section:

<pre>
QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "HUMAN", 1)
THEN
DB_NOOP(1);

QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "DWARF", 1)
THEN
DB_NOOP(1);
</pre>

By adding two query blocks with the same name, we're effectively adding an "OR" condition. This query will evaluate as true if the character is tagged as either a human or a dwarf.

"DB_NOOP(1);" is a dummy database fact. Since rules must have a call, DB_NOOP is used to have a rule succeed without using any actual calls.

==== Implementing the Custom Query ====
----

Below our query code, in the KB section, add the following:
<pre>
IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Perception_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Perception_Potion");

IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
NOT WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Constitution_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Constitution_Potion");

IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload". Since we added a query and another database, we must generate the definitions again.
# Go in-game and test out the changes by casting Encourage on an human or dwarf (it will work on yourself as well).

===== Notes =====
----
'''NOT'''
* By adding two rules for the same event, and checking for the opposite of our query, we're effectively adding an OR condition to this event.

'''CharacterConsume/CharacterUnconsume'''
* Since CharacterConsume returns a value, it's a query instead of a call. We store the out value from the query (_Handle) in a database to later unconsume the potion effect when ENCOURAGED ends.

'''Removing Database Entries'''
* When unconsuming the potion handle, notice we also remove that entry from the database by calling "NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);" as a call. Using NOT before a database entry (in the call section) removes that entry.
* By using DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion) in the query section, the _Handle and _Potion value is returned with all entries that match the value we pass in (_Character), effectively unconsuming every potion handle we added for that character to the database.

=== Using a Query as a Subroutine ===
----
While queries can be used as conditions, they can also be used to call specific procedures/calls before the main rule reaches that section of the flow.

Let's try a simple example that runs when we unconsume a potion. Change our status removed event code to this:

<pre>
IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_ZombieCheck(_Character)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "UNDEAD", 1)
AND
CharacterGetDisplayName(_Character, _, _Name)
AND
StringConcatenate("[WT_FS] ", _Name, _Str1)
AND
StringConcatenate(_Str1, " is a zombie! Ahh! Burn it!", _Message)
THEN
ApplyStatus(_Character, "BURNING", 1.0);
DebugBreak(_Message);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
THEN
DB_NOOP(1);
</pre>

Which this, our query will apply burning if the character is tagged as UNDEAD. Note how we added a second QRY rule that always evaluates as true - this is to keep the rest of our rule in the CharacterStatusRemoved event running, undead or not.

Practically speaking, using queries as subroutines is ideal when:
* You need specific calls/procedures to run before iterating through a database. Calling your query before retrieving variables from a database ensures that those calls will only run once.
* You need to debug a rule to ensure it reaches a certain section of the conditions. If you're not sure if a specific condition is passing, adding a query with a DebugBreak message right before/after it is a good way to debug that situation.

== Bonus Tips ==

* In the story editor, select "File -> Open Story Header" for a list of all available events, queries, and calls. Heavily reference this file when you find yourself unsure if a specifc method exists, as not all methods appear in the auto-complete.

* If you use databases to store global mod settings, and your mod users have played with that mod, changing that information post-mod install will not automatically remove that data from existing saves - you need to handle this update internally within your mod.
** More on implementing an update system here: [[Osiris_Tips#Updating_Databases|Manual Mod Updates]].

* By using custom procedures and queries, you can reduce your rule redundancy and extend desired calls/conditions to multiple rules.

* To make your life with Osiris easier, wrap your rule blocks in regions with the following:
<pre>
//REGION MY_REGION_NAME

//END_REGION
</pre>
* In the story editor, right click inside your script sections (INIT, KB, or EXIT) and "Expand All" or "Collapse All" to expand/collapse all regions, respectively.

* Procedures can be called from the EXIT and INIT section of scripts.

* Use the INIT section of your scripts as a way to store commented references to your databases. As an example from our previous script, placing this inside your INIT section is a good way to remember such a database exists (since we don't initialize it in the INIT section):
<pre>
//DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
</pre>
Then, when you wish to use this database, you have a quick way to copy/paste that code into other sections of your script.

=== Manually Completing Parent Goals ===
----
Instead of parenting your parent goal to one of the Start goals, it's possible to handle goal completion yourself, using a few different events:

The following events are recommended to use for completing your parent goals:
; [[Osiris/API/GameStarted|GameStarted]]
: Thrown when a level has been loaded and is ready at both the server and client side. This will ensure all the base game scripts have already initialized.
; [[Osiris/API/RegionStarted|RegionStarted]]
: Thrown when the level has been loaded and is ready at the server side, but not yet at the client side.
Both of these events can be used with specific level names, as a way to make your goal only complete once that level is loaded (as a way to create level-specific logic).
;[[Osiris/API/GameEventSet|GameEventSet("GAMEEVENT_GameStarted")]]
: The first story event that gets thrown after the game engine has been initialised when starting a new game. This particular event will only fire the first time a new game is started, so additional rules are needed for cases where your mod is added to an existing save.
;[[Osiris/API/Osiris/API/SavegameLoaded|Osiris/API/SavegameLoaded]]
: Fires when a save is being loaded on an existing save. This can be used to complete your goal on existing saves that just added your mod.

==== Example Goal Completion ====
----
The following is an example of handling initial goal completion yourself:

INIT:
<pre>
MyMod_Internal_CompleteIfStarted();
</pre>

KB:
<pre>
PROC
MyMod_Internal_Start()
THEN
DebugBreak("[MyMod] Parent goal complete.");
GoalCompleted;

IF
GameEventSet("GAMEEVENT_GameStarted")
THEN
MyMod_Internal_Start();

PROC
MyMod_Internal_CompleteIfStarted()
AND
DB_StoryStarted(_)
THEN
DebugBreak("[MyMod:CompleteIfStarted] Story was already started.");
MyMod_Internal_Start();

// For saves where this goal is active, but wasn't completed
IF
SavegameLoaded(_,_,_,_)
AND
DB_StoryStarted(_)
THEN
DebugBreak("[MyMod:SavegameLoaded] Mod added to an existing save.");
MyMod_Internal_Start();
</pre>

[[Category:Osiris]]

File:FirstStoryScript ParentingToStart.png

2018-08-08T00:45:31Z

LaughingLeader:

File:FirstStoryScript ParentGoalComplete.png

2018-08-08T00:40:15Z

LaughingLeader: LaughingLeader uploaded a new version of File:FirstStoryScript ParentGoalComplete.png

File:FirstStoryScript ParentGoal.png

2018-08-08T00:39:46Z

LaughingLeader:

Item Progression

2018-07-23T03:36:56Z

LaughingLeader:

== Description ==
An important part of the treasure system, Item Progression is the link between item stats and root templates, and is necessary to customize the level range, rarity, and names of items generated by stats, or by treasure tables.

== ItemProgressionVisuals ==

ItemProgressionVisuals links an itemgroup with a levelgroup (the level range and rarity), a root group (the root template used), and a namegroup (the names to use).

=== Properties ===
{| class="wikitable"
! style="text-align:left;"| Property
! style="text-align:left;"| Parameters
! style="text-align:left;"| Description
|-
|[[Item_Progression#itemgroup|itemgroup]]||Name||The name of the itemgroup, defined as a property on an item stat.
|-
|[[Item_Progression#LevelGroup|levelgroup]]||MinLevel,MaxLevel,[[Rarity]]||The level range and rarity to link the subsequent rootgroup and namegroup to.
|-
|[[Item_Progression#RootGroup|rootgroup]]||RootTemplate,[[ItemColor]]||The RootTemplate is the GUIDSTRING of the root template to use. ItemColor is defined in its own stats file, and changes the color of items with materials that support MSK.
|-
|[[Item_Progression#NameGroup|namegroup]]||NameGroup,[[Item_Progression#Cool_Names|AffixType]],[[Item_Progression#Icon_Override|Icon]]||The namegroup to use, whether to use the "cool" version, and an icon to use in place of the root template's icon.
|}

=== ItemGroup ===

ItemGroup is a property set in equipment stats, and is used to group progression settings in ItemProgressionVisuals.

To define an itemgroup, simply define the property on an equipment stat (weapon, armor, or shield):

<pre>
new entry "_Clubs"
type "Weapon"
data "ItemGroup" "Maces_1H"
data "ModifierType" "Item"
data "Act" "1"
data "Requirements" "Strength 12"
</pre>

_Clubs is used as a base stat inherited by other club weapons. Here it defines "Maces_1H" as the itemgroup. If we wanted to inherit from _Clubs, but create a new itemgroup, we simply have to override the ItemGroup property:

<pre>
new entry "WPN_Common_Mace_1H_A"
type "Weapon"
using "_Clubs"
data "ItemGroup" "WPN_Common_Mace_1H_A"
data "Act part" "1"
data "Value" "2"
data "Weight" "1000"
data "ComboCategory" "Club,Hammer"
</pre>

In our new stat, "WPN_Common_Mace_1H_A", we inherit from _Clubs, but override the ItemGroup with our own, thus placing progression for our new item within its own group.

=== LevelGroup ===

The levelgroup sets the level range and [[Rarity]] that the following rootgroups and namegroups will apply to.

Examples:

<pre>
add levelgroup 9,16,"Uncommon"
add rootgroup "648d501c-2d8e-4464-acfb-6e6f061305f6","MageUncommon"
add namegroup "MageRobe9","",""
</pre>

This item will generate at levels 9-16 at the "Uncommon" rarity.

<pre>
add levelgroup 17,0,"Common"
add rootgroup "94aaefe8-4843-4624-b1a0-92d63be2e5b8","LizardsCommon"
add namegroup "Claymore","",""
</pre>

This item will spawn at level 17 and above, at the "Common" rarity.

<pre>
new itemgroup "Wings"

add levelgroup 0,0,"All"
add rootgroup "a71d1908-7499-42c2-8c6b-a2173be582dc",""
add namegroup "Wings","",""
</pre>

This item is generated at any level, and any rarity. ''Fun fact: These are the wings created by the Wings Polymorph skill.''

=== RootGroup ===

The rootgroup is simply the GUIDSTRING of the root template to link the itemgroup with. The second property is an optional ItemColor to use. You can get the GUIDSTRING of a root template by right clicking it in the [[Root template panel]], and selecting "Copy GUID to clipboard".

Example:

<pre>
add levelgroup 4,4,"Common"
add rootgroup "16600f2c-3817-42e7-be9d-5804f8ac77c8","HumansCommon"
add namegroup "Twohander 2","",""
</pre>

=== NameGroup ===

The namegroup is a set of names to use with the item, defined in ItemProgressionNames. The first parameter is the name of the namegroup, while the second and third parameters are optional, and usually blank (""). The second parameter activates the "namecool" version of a name (via "Cool"), and the third parameter specifies the icon to use, which overrides the icon on the root template.

Example:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""
</pre>

This entry uses the namegroup named "Elven Sword".

<pre>
add levelgroup 9,16,"Rare"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","Cool","Item_WPN_Dwarves_Sword_1H_C"
</pre>

While this entry also uses the namegroup named "Elven Sword", it uses the "namecool" entry thanks to "Cool", and uses the "Item_WPN_Dwarves_Sword_1H_C" icon instead of the one set by the root template.

== ItemProgressionNames ==

ItemProgressionNames defines a set of names and (optional) descriptions to use for items defined in ItemProgressionVisuals.

=== Properties ===
{| class="wikitable"
! style="text-align:left;"| Property
! style="text-align:left;"| Parameters
! style="text-align:left;"| Description
|-
|namegroup||Name||The name of the namegroup. Used in ItemProgressionVisuals.
|-
|name||ItemName,Description||The item name and (optional) description to use.
|-
|namecool||ItemName,Description||An optional, additional entry to use if "Cool" is specified in ItemProgressionVisuals.
|}

Example:

Say we have an entry in ItemProgressionVisuals:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""
</pre>

We then define the namegroup "Elven Sword" within ItemProgressionNames:

<pre>
new namegroup "Elven Sword"
add name "Elven Sword",""
add namecool "Elegant Sword",""
</pre>

"name" is the name to use normally, followed by the name to use. The second parameter an optional description. If left blank, the description on the root template is used.

"namecool" is the name to use when "Cool" is specified in ItemProgressionVisuals, typically for higher rarity versions of an item.

''Note: If the root template specifies a name (Display Name, or Display Name (Unknown)), that value will override the name provided by the namegroup.''

== Cool Names ==

Say we have the following entries:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""

add levelgroup 9,16,"Epic"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","Cool",""
</pre>

If the item spawns at level 9-16 with the "Epic" rarity, the resulting item will use the name "Elegant Sword" instead of "Elven Sword". Otherwise, the normal name is used.

=== Icon Override ===

The third parameter for the ItemProgressionVisuals namegroup entry is an icon override, allowing us to change the icon used for the weapon that matches the progression parameters.

Example:
<pre>
new itemgroup "ARM_UNIQUE_WikiMod_BrilliantRing"

add levelgroup 0,0,"Common"
add rootgroup "f6fd6b73-191d-4ba1-b844-cec875608fe3",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","",""

add levelgroup 0,0,"Rare"
add rootgroup "c21de6ee-136b-45f7-b083-565d3f458726",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","Cool","Item_LOOT_Ring_B_Silver_Turquoise"
</pre>

Now when a rare version of our ring spawns, it will use the icon "Item_LOOT_Ring_B_Silver_Turquoise", located in the Icons_DOS2_Items texture atlas.

== Unique Items ==

For cases where we want an item to be unique, and spawn regardless of level, an ItemProgression entry is still needed.

Say we have a unique ring, defined in Armor:

<pre>
new entry "ARM_UNIQUE_WikiMod_BrilliantRing"
type "Armor"
using "_Rings"
data "ItemGroup" "ARM_UNIQUE_WikiMod_BrilliantRing"
data "Unique" "1"
</pre>

We then define a new entry in ItemProgressionVisuals:

<pre>
new itemgroup "ARM_UNIQUE_WikiMod_BrilliantRing"

add levelgroup 0,0,"All"
add rootgroup "24c3d50a-c377-4c09-b3e8-274f8447494b",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","",""
</pre>

And finally, an entry in ItemProgressionNames:

<pre>
new namegroup "ARM_UNIQUE_WikiMod_BrilliantRing"
add name "Brilliant Ring of Amun-Ra","This ring shines with a brilliant light. The metal is warm to the touch, and seems impervious to scuffing."
</pre>

By making our levelgroup 0,0 with the "All" rarity, this makes our ring spawn at any level, and any rarity. Naturally, rarity is left out of the equation, since our ring is unique.

== Common Mistakes ==

* '''Trying to generate an item with a level range or rarity that isn't defined.'''

Say we have a weapon:

<pre>
new entry "WPN_Wikimod_Crossbow_Plus"
type "Weapon"
using "_Crossbows"
data "ItemGroup" "WPN_Wikimod_Crossbow_Plus"
data "ComboCategory" "Crossbow"
data "ObjectCategory" "Wikimod_Crossbows"
data "MinAmount" "1"
data "MaxAmount" "1"
data "Priority" "1"
data "MinLevel" "1"
</pre>

A single ItemProgressionVisuals entry:
<pre>
new itemgroup "WPN_Wikimod_Crossbow_Plus"

add levelgroup 1,9,"Epic"
add rootgroup "b8da3005-cc77-4150-b9f3-23e1d3cc92e9","DwarvesCommon"
add namegroup "Dwarven Crossbow","",""
</pre>

And a TreasureTable:
<pre>
new treasuretable "ST_Wikimod_Crossbows"
new subtable "1,1"
object category "Wikimod_Crossbows",1,1,0,0,0,0,0,0
</pre>

Our table is attempting to generate our item at "Common" rarity, yet we only have an entry for the "Epic" rarity. Furthermore, attempting to generate this item at a level higher than 9 will fail.

The solution is to add new entries for each level range and rarity we want to support (This is why the ItemProgressionVisuals in Shared contains so many entries).

* '''Using a root template with a "defined" name, and expecting a namegroup to work.'''

If a root template has a display name set, it will take priority over the namegroup. This includes "Display Name (Unknown)".

Talk:Skill creation

2018-07-22T23:24:52Z

LaughingLeader: /* UseCharacterStats */

== Incorrect Info ==
Surface creation actually works like this: CreateSurface,Radius,Duration,Type,Chance,Hole [[User:Lofgren|Lofgren]] ([[User talk:Lofgren|talk]]) 08:58, 25 June 2018 (CEST)

== Hidden Parameters ==

Some of the functions, at least in the skill properties section, have hidden parameters that are unused in the base game. Here is what I've discovered so far: 
Douse,Radius,Chance? 
Freeze,Chance,Duration,?,Radius 
Contaminate,Chance,Duration 
[[User:Lofgren|Lofgren]] ([[User talk:Lofgren|talk]]) 09:00, 25 June 2018 (CEST)

== UseCharacterStats ==

Would it be possible to add a little blurb on the 'UseCharacterStats' property? It appears to make a skill able to miss if a Requirement is also added.

For instance, with this skill:
<pre>
new entry "Target_Wikimod_TestSkill_A"
type "SkillData"
using "Target_MosquitoSwarm"
data "Ability" "Rogue"
data "DisplayName" "Mosquito Swarm (Character Stats)"
data "Requirement" "MeleeWeapon"
data "UseCharacterStats" "Yes"
</pre>
Adding UseCharacterStats and MeleeWeapon as a requirement makes this skill potentially miss, depending on the caster's accuracy.

Furthermore, UseWeaponDamage appears to also make the skill able to miss if set to true, so adding that information could be helpful for those wanting to make missable skills.

[[User:LaughingLeader|LaughingLeader]] ([[User talk:LaughingLeader|talk]]) 09:00, 22 July 2018 (CEST)

Talk:Skill creation

2018-07-22T23:24:07Z

LaughingLeader: /* UseCharacterStats */

== Incorrect Info ==
Surface creation actually works like this: CreateSurface,Radius,Duration,Type,Chance,Hole [[User:Lofgren|Lofgren]] ([[User talk:Lofgren|talk]]) 08:58, 25 June 2018 (CEST)

== Hidden Parameters ==

Some of the functions, at least in the skill properties section, have hidden parameters that are unused in the base game. Here is what I've discovered so far: 
Douse,Radius,Chance? 
Freeze,Chance,Duration,?,Radius 
Contaminate,Chance,Duration 
[[User:Lofgren|Lofgren]] ([[User talk:Lofgren|talk]]) 09:00, 25 June 2018 (CEST)

== UseCharacterStats ==

Would it be possible to add a little blurb on the 'UseCharacterStats' property? It appears to make a skill able to miss if a Requirement is also added.

For instance, with this skill:
<pre>
new entry "Target_Wikimod_TestSkill_A"
type "SkillData"
using "Target_MosquitoSwarm"
data "Ability" "Rogue"
data "DisplayName" "Mosquito Swarm (Character Stats)"
data "Requirement" "MeleeWeapon"
data "UseCharacterStats" "Yes"
</pre>
Adding UseCharacterStats and MeleeWeapon as a requirement makes this skill potentially miss, depending on the caster's accuracy.

Furthermore, UseWeaponDamage appears to also make the skill able to miss if set to true, adding that information could be helpful for those wanting to make missable skills.

[[User:LaughingLeader|LaughingLeader]] ([[User talk:LaughingLeader|talk]]) 09:00, 22 July 2018 (CEST)

Talk:Skill creation

2018-07-22T23:23:21Z

LaughingLeader: /* UseCharacterStats */ new section

== Incorrect Info ==
Surface creation actually works like this: CreateSurface,Radius,Duration,Type,Chance,Hole [[User:Lofgren|Lofgren]] ([[User talk:Lofgren|talk]]) 08:58, 25 June 2018 (CEST)

== Hidden Parameters ==

Some of the functions, at least in the skill properties section, have hidden parameters that are unused in the base game. Here is what I've discovered so far: 
Douse,Radius,Chance? 
Freeze,Chance,Duration,?,Radius 
Contaminate,Chance,Duration 
[[User:Lofgren|Lofgren]] ([[User talk:Lofgren|talk]]) 09:00, 25 June 2018 (CEST)

== UseCharacterStats ==

Would it be possible to add a little blurb on the 'UseCharacterStats' property? It appears to make a skill able to miss if a Requirement is also added.

For instance, with this skill:
<pre>
new entry "Target_Wikimod_TestSkill_A"
type "SkillData"
using "Target_MosquitoSwarm"
data "Ability" "Rogue"
data "DisplayName" "Mosquito Swarm (Character Stats)"
data "Requirement" "MeleeWeapon"
data "UseCharacterStats" "Yes"
</pre>
Adding UseCharacterStats and MeleeWeapon as a requirement makes this skill potentially miss, depending on the caster's accuracy.

Furthermore, UseWeaponDamage appears to also make the skill able to miss if set to true, adding that information could be helpful for those wanting to make missable skills.

Item Progression

2018-07-22T22:07:42Z

LaughingLeader:

== Description ==
An important part of the treasure system, Item Progression is the link between item stats and root templates, and is necessary to customize the level range, rarity, and names of items generated by stats, or by treasure tables.

== ItemProgressionVisuals ==

ItemProgressionVisuals links an itemgroup with a levelgroup (the level range and rarity), a root group (the root template used), and a namegroup (the names to use).

=== Properties ===
{| class="wikitable"
! style="text-align:left;"| Property
! style="text-align:left;"| Parameters
! style="text-align:left;"| Description
|-
|[[Item_Progression#itemgroup|itemgroup]]||ItemGroup||The itemgroup, defined via item stats. Consider this the "header" that subsequent entries are included under, until a new itemgroup is used.
|-
|[[Item_Progression#LevelGroup|levelgroup]]||MinLevel,MaxLevel,[[Rarity]]||The level range and rarity to link the subsequent rootgroup and namegroup to.
|-
|[[Item_Progression#RootGroup|rootgroup]]||RootTemplate,[[ItemColor]]||The RootTemplate is the GUIDSTRING of the root template to use. ItemColor is defined in its own stats file, and changes the color of items with materials that support MSK.
|-
|[[Item_Progression#NameGroup|namegroup]]||NameGroup,[[Item_Progression#Cool_Names|AffixType]],[[Item_Progression#Icon_Override|Icon]]||The namegroup to use, whether to use the "cool" version, and an icon to use in place of the root template's icon.
|}

=== ItemGroup ===

ItemGroup is defined in equipment stats, and is used to define which group of stats the subsequent levelgroup, rootgroup, and namegroup use.

Examples:

A base stat inherited by other weapons:

<pre>
new entry "_Clubs"
type "Weapon"
data "ItemGroup" "Maces_1H"
data "ModifierType" "Item"
data "Act" "1"
data "Requirements" "Strength 12"
data "IsTwoHanded" "No"
data "AttackAPCost" "2"
data "Damage Type" "Physical"
data "Damage" "0"
data "Damage Range" "5"
data "DamageFromBase" "67"
data "CriticalDamage" "150"
data "CriticalChance" "0"
data "WeaponRange" "120"
data "Durability" "20"
data "DurabilityDegradeSpeed" "6"
data "Value" "40"
data "Weight" "3500"
data "Movement" "0"
data "WeaponType" "Club"
data "Slot" "Weapon"
data "InventoryTab" "Equipment"
data "Charges" "0"
data "MaxCharges" "0"
data "ItemColor" "DefaultGray"
data "RuneSlots" "0"
data "RuneSlots_V1" "0"
</pre>

Overriding the inherited ItemGroup with a new one:
<pre>
new entry "WPN_Common_Mace_1H_A"
type "Weapon"
using "_Clubs"
data "ItemGroup" "WPN_Common_Mace_1H_A"
data "Act part" "1"
data "Value" "2"
data "Weight" "1000"
data "ComboCategory" "Club,Hammer"
</pre>

=== LevelGroup ===

The levelgroup sets the level range and [[Rarity]] that the following rootgroups and namegroups will apply to.

Examples:

<pre>
add levelgroup 9,16,"Uncommon"
add rootgroup "648d501c-2d8e-4464-acfb-6e6f061305f6","MageUncommon"
add namegroup "MageRobe9","",""
</pre>

This item will generate at levels 9-16 at the "Uncommon" rarity.

<pre>
add levelgroup 17,0,"Common"
add rootgroup "94aaefe8-4843-4624-b1a0-92d63be2e5b8","LizardsCommon"
add namegroup "Claymore","",""
</pre>

This item will spawn at level 17 and above, at the "Common" rarity.

<pre>
new itemgroup "Wings"

add levelgroup 0,0,"All"
add rootgroup "a71d1908-7499-42c2-8c6b-a2173be582dc",""
add namegroup "Wings","",""
</pre>

This item is generated at any level, and any rarity. ''Fun fact: These are the wings created by the Wings Polymorph skill.''

=== RootGroup ===

The rootgroup is simply the GUIDSTRING of the root template to link the itemgroup with. The second property is an optional ItemColor to use. You can get the GUIDSTRING of a root template by right clicking it in the [[Root template panel]], and selecting "Copy GUID to clipboard".

Example:

<pre>
add levelgroup 4,4,"Common"
add rootgroup "16600f2c-3817-42e7-be9d-5804f8ac77c8","HumansCommon"
add namegroup "Twohander 2","",""
</pre>

=== NameGroup ===

The namegroup is a set of names to use with the item, defined in ItemProgressionNames. The first parameter is the name of the namegroup, while the second and third parameters are optional, and usually blank (""). The second parameter activates the "namecool" version of a name (via "Cool"), and the third parameter specifies the icon to use, which overrides the icon on the root template.

Example:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""
</pre>

This entry uses the namegroup named "Elven Sword".

<pre>
add levelgroup 9,16,"Rare"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","Cool","Item_WPN_Dwarves_Sword_1H_C"
</pre>

While this entry also uses the namegroup named "Elven Sword", it uses the "namecool" entry thanks to "Cool", and uses the "Item_WPN_Dwarves_Sword_1H_C" icon instead of the one set by the root template.

== ItemProgressionNames ==

ItemProgressionNames defines a set of names and (optional) descriptions to use for items defined in ItemProgressionVisuals.

=== Properties ===
{| class="wikitable"
! style="text-align:left;"| Property
! style="text-align:left;"| Parameters
! style="text-align:left;"| Description
|-
|namegroup||Name||The name of the namegroup. Used in ItemProgressionVisuals.
|-
|name||ItemName,Description||The item name and (optional) description to use.
|-
|namecool||ItemName,Description||An optional, additional entry to use if "Cool" is specified in ItemProgressionVisuals.
|}

Example:

Say we have an entry in ItemProgressionVisuals:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""
</pre>

We then define the namegroup "Elven Sword" within ItemProgressionNames:

<pre>
new namegroup "Elven Sword"
add name "Elven Sword",""
add namecool "Elegant Sword",""
</pre>

"name" is the name to use normally, followed by the name to use. The second parameter an optional description. If left blank, the description on the root template is used.

"namecool" is the name to use when "Cool" is specified in ItemProgressionVisuals, typically for higher rarity versions of an item.

''Note: If the root template specifies a name (Display Name, or Display Name (Unknown)), that value will override the name provided by the namegroup.''

== Cool Names ==

Say we have the following entries:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""

add levelgroup 9,16,"Epic"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","Cool",""
</pre>

If the item spawns at level 9-16 with the "Epic" rarity, the resulting item will use the name "Elegant Sword" instead of "Elven Sword". Otherwise, the normal name is used.

=== Icon Override ===

The third parameter for the ItemProgressionVisuals namegroup entry is an icon override, allowing us to change the icon used for the weapon that matches the progression parameters.

Example:
<pre>
new itemgroup "ARM_UNIQUE_WikiMod_BrilliantRing"

add levelgroup 0,0,"Common"
add rootgroup "f6fd6b73-191d-4ba1-b844-cec875608fe3",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","",""

add levelgroup 0,0,"Rare"
add rootgroup "c21de6ee-136b-45f7-b083-565d3f458726",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","Cool","Item_LOOT_Ring_B_Silver_Turquoise"
</pre>

Now when a rare version of our ring spawns, it will use the icon "Item_LOOT_Ring_B_Silver_Turquoise", located in the Icons_DOS2_Items texture atlas.

== Unique Items ==

For cases where we want an item to be unique, and spawn regardless of level, an ItemProgression entry is still needed.

Say we have a unique ring, defined in Armor:

<pre>
new entry "ARM_UNIQUE_WikiMod_BrilliantRing"
type "Armor"
using "_Rings"
data "ItemGroup" "ARM_UNIQUE_WikiMod_BrilliantRing"
data "Unique" "1"
</pre>

We then define a new entry in ItemProgressionVisuals:

<pre>
new itemgroup "ARM_UNIQUE_WikiMod_BrilliantRing"

add levelgroup 0,0,"All"
add rootgroup "24c3d50a-c377-4c09-b3e8-274f8447494b",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","",""
</pre>

And finally, an entry in ItemProgressionNames:

<pre>
new namegroup "ARM_UNIQUE_WikiMod_BrilliantRing"
add name "Brilliant Ring of Amun-Ra","This ring shines with a brilliant light. The metal is warm to the touch, and seems impervious to scuffing."
</pre>

By making our levelgroup 0,0 with the "All" rarity, this makes our ring spawn at any level, and any rarity. Naturally, rarity is left out of the equation, since our ring is unique.

== Common Mistakes ==

* '''Trying to generate an item with a level range or rarity that isn't defined.'''

Say we have a weapon:

<pre>
new entry "WPN_Wikimod_Crossbow_Plus"
type "Weapon"
using "_Crossbows"
data "ItemGroup" "WPN_Wikimod_Crossbow_Plus"
data "ComboCategory" "Crossbow"
data "ObjectCategory" "Wikimod_Crossbows"
data "MinAmount" "1"
data "MaxAmount" "1"
data "Priority" "1"
data "MinLevel" "1"
</pre>

A single ItemProgressionVisuals entry:
<pre>
new itemgroup "WPN_Wikimod_Crossbow_Plus"

add levelgroup 1,9,"Epic"
add rootgroup "b8da3005-cc77-4150-b9f3-23e1d3cc92e9","DwarvesCommon"
add namegroup "Dwarven Crossbow","",""
</pre>

And a TreasureTable:
<pre>
new treasuretable "ST_Wikimod_Crossbows"
new subtable "1,1"
object category "Wikimod_Crossbows",1,1,0,0,0,0,0,0
</pre>

Our table is attempting to generate our item at "Common" rarity, yet we only have an entry for the "Epic" rarity. Furthermore, attempting to generate this item at a level higher than 9 will fail.

The solution is to add new entries for each level range and rarity we want to support (This is why the ItemProgressionVisuals in Shared contains so many entries).

* '''Using a root template with a "defined" name, and expecting a namegroup to work.'''

If a root template has a display name set, it will take priority over the namegroup. This includes "Display Name (Unknown)".

Item Progression

2018-07-22T22:02:55Z

LaughingLeader:

== Description ==
An important part of the treasure system, Item Progression is the link between item stats and root templates, and is necessary to customize the level range, rarity, and names of items generated by stat, or by treasure tables.

== ItemProgressionVisuals ==

ItemProgressionVisuals links an itemgroup with a levelgroup (the level range and rarity), a root group (the root template used), and a namegroup (the names to use).

=== Properties ===
{| class="wikitable"
! style="text-align:left;"| Property
! style="text-align:left;"| Parameters
! style="text-align:left;"| Description
|-
|[[Item_Progression#itemgroup|itemgroup]]||ItemGroup||The itemgroup, defined via item stats. Consider this the "header" that subsequent entries are included under, until a new itemgroup is used.
|-
|[[Item_Progression#LevelGroup|levelgroup]]||MinLevel,MaxLevel,[[Rarity]]||The level range and rarity to link the subsequent rootgroup and namegroup to.
|-
|[[Item_Progression#RootGroup|rootgroup]]||RootTemplate,[[ItemColor]]||The RootTemplate is the GUIDSTRING of the root template to use. ItemColor is defined in its own stats file, and changes the color of items with materials that support MSK.
|-
|[[Item_Progression#NameGroup|namegroup]]||NameGroup,[[Item_Progression#Cool_Names|AffixType]],[[Item_Progression#Icon_Override|Icon]]||The namegroup to use, whether to use the "cool" version, and an icon to use in place of the root template's icon.
|}

=== ItemGroup ===

ItemGroup is defined in equipment stats, and is used to define which group of stats the subsequent levelgroup, rootgroup, and namegroup use.

Examples:

A base stat inherited by other weapons:

<pre>
new entry "_Clubs"
type "Weapon"
data "ItemGroup" "Maces_1H"
data "ModifierType" "Item"
data "Act" "1"
data "Requirements" "Strength 12"
data "IsTwoHanded" "No"
data "AttackAPCost" "2"
data "Damage Type" "Physical"
data "Damage" "0"
data "Damage Range" "5"
data "DamageFromBase" "67"
data "CriticalDamage" "150"
data "CriticalChance" "0"
data "WeaponRange" "120"
data "Durability" "20"
data "DurabilityDegradeSpeed" "6"
data "Value" "40"
data "Weight" "3500"
data "Movement" "0"
data "WeaponType" "Club"
data "Slot" "Weapon"
data "InventoryTab" "Equipment"
data "Charges" "0"
data "MaxCharges" "0"
data "ItemColor" "DefaultGray"
data "RuneSlots" "0"
data "RuneSlots_V1" "0"
</pre>

Overriding the inherited ItemGroup with a new one:
<pre>
new entry "WPN_Common_Mace_1H_A"
type "Weapon"
using "_Clubs"
data "ItemGroup" "WPN_Common_Mace_1H_A"
data "Act part" "1"
data "Value" "2"
data "Weight" "1000"
data "ComboCategory" "Club,Hammer"
</pre>

=== LevelGroup ===

The levelgroup sets the level range and [[Rarity]] that the following rootgroups and namegroups will apply to.

Examples:

<pre>
add levelgroup 9,16,"Uncommon"
add rootgroup "648d501c-2d8e-4464-acfb-6e6f061305f6","MageUncommon"
add namegroup "MageRobe9","",""
</pre>

This item will generate at levels 9-16 at the "Uncommon" rarity.

<pre>
add levelgroup 17,0,"Common"
add rootgroup "94aaefe8-4843-4624-b1a0-92d63be2e5b8","LizardsCommon"
add namegroup "Claymore","",""
</pre>

This item will spawn at level 17 and above, at the "Common" rarity.

<pre>
new itemgroup "Wings"

add levelgroup 0,0,"All"
add rootgroup "a71d1908-7499-42c2-8c6b-a2173be582dc",""
add namegroup "Wings","",""
</pre>

This item is generated at any level, and any rarity. ''Fun fact: These are the wings created by the Wings Polymorph skill.''

=== RootGroup ===

The rootgroup is simply the GUIDSTRING of the root template to link the itemgroup with. The second property is an optional ItemColor to use. You can get the GUIDSTRING of a root template by right clicking it in the [[Root template panel]], and selecting "Copy GUID to clipboard".

Example:

<pre>
add levelgroup 4,4,"Common"
add rootgroup "16600f2c-3817-42e7-be9d-5804f8ac77c8","HumansCommon"
add namegroup "Twohander 2","",""
</pre>

=== NameGroup ===

The namegroup is a set of names to use with the item, defined in ItemProgressionNames. The first parameter is the name of the namegroup, while the second and third parameters are optional, and usually blank (""). The second parameter activates the "namecool" version of a name (via "Cool"), and the third parameter specifies the icon to use, which overrides the icon on the root template.

Example:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""
</pre>

This entry uses the namegroup named "Elven Sword".

<pre>
add levelgroup 9,16,"Rare"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","Cool","Item_WPN_Dwarves_Sword_1H_C"
</pre>

While this entry also uses the namegroup named "Elven Sword", it uses the "namecool" entry thanks to "Cool", and uses the "Item_WPN_Dwarves_Sword_1H_C" icon instead of the one set by the root template.

== ItemProgressionNames ==

ItemProgressionNames defines a set of names and (optional) descriptions to use for items defined in ItemProgressionVisuals.

=== Properties ===
{| class="wikitable"
! style="text-align:left;"| Property
! style="text-align:left;"| Parameters
! style="text-align:left;"| Description
|-
|namegroup||Name||The name of the namegroup. Used in ItemProgressionVisuals.
|-
|name||ItemName,Description||The item name and (optional) description to use.
|-
|namecool||ItemName,Description||An optional, additional entry to use if "Cool" is specified in ItemProgressionVisuals.
|}

Example:

Say we have an entry in ItemProgressionVisuals:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""
</pre>

We then define the namegroup "Elven Sword" within ItemProgressionNames:

<pre>
new namegroup "Elven Sword"
add name "Elven Sword",""
add namecool "Elegant Sword",""
</pre>

"name" is the name to use normally, followed by the name to use. The second parameter an optional description. If left blank, the description on the root template is used.

"namecool" is the name to use when "Cool" is specified in ItemProgressionVisuals, typically for higher rarity versions of an item.

''Note: If the root template specifies a name (Display Name, or Display Name (Unknown)), that value will override the name provided by the namegroup.''

== Cool Names ==

Say we have the following entries:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""

add levelgroup 9,16,"Epic"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","Cool",""
</pre>

If the item spawns at level 9-16 with the "Epic" rarity, the resulting item will use the name "Elegant Sword" instead of "Elven Sword". Otherwise, the normal name is used.

=== Icon Override ===

The third parameter for the ItemProgressionVisuals namegroup entry is an icon override, allowing us to change the icon used for the weapon that matches the progression parameters.

Example:
<pre>
new itemgroup "ARM_UNIQUE_WikiMod_BrilliantRing"

add levelgroup 0,0,"Common"
add rootgroup "f6fd6b73-191d-4ba1-b844-cec875608fe3",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","",""

add levelgroup 0,0,"Rare"
add rootgroup "c21de6ee-136b-45f7-b083-565d3f458726",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","Cool","Item_LOOT_Ring_B_Silver_Turquoise"
</pre>

Now when a rare version of our ring spawns, it will use the icon "Item_LOOT_Ring_B_Silver_Turquoise", located in the Icons_DOS2_Items texture atlas.

== Unique Items ==

For cases where we want an item to be unique, and spawn regardless of level, an ItemProgression entry is still needed.

Say we have a unique ring, defined in Armor:

<pre>
new entry "ARM_UNIQUE_WikiMod_BrilliantRing"
type "Armor"
using "_Rings"
data "ItemGroup" "ARM_UNIQUE_WikiMod_BrilliantRing"
data "Unique" "1"
</pre>

We then define a new entry in ItemProgressionVisuals:

<pre>
new itemgroup "ARM_UNIQUE_WikiMod_BrilliantRing"

add levelgroup 0,0,"All"
add rootgroup "24c3d50a-c377-4c09-b3e8-274f8447494b",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","",""
</pre>

And finally, an entry in ItemProgressionNames:

<pre>
new namegroup "ARM_UNIQUE_WikiMod_BrilliantRing"
add name "Brilliant Ring of Amun-Ra","This ring shines with a brilliant light. The metal is warm to the touch, and seems impervious to scuffing."
</pre>

By making our levelgroup 0,0 with the "All" rarity, this makes our ring spawn at any level, and any rarity. Naturally, rarity is left out of the equation, since our ring is unique.

== Common Mistakes ==

* '''Trying to generate an item with a level range or rarity that isn't defined.'''

Say we have a weapon:

<pre>
new entry "WPN_Wikimod_Crossbow_Plus"
type "Weapon"
using "_Crossbows"
data "ItemGroup" "WPN_Wikimod_Crossbow_Plus"
data "ComboCategory" "Crossbow"
data "ObjectCategory" "Wikimod_Crossbows"
data "MinAmount" "1"
data "MaxAmount" "1"
data "Priority" "1"
data "MinLevel" "1"
</pre>

A single ItemProgressionVisuals entry:
<pre>
new itemgroup "WPN_Wikimod_Crossbow_Plus"

add levelgroup 1,9,"Epic"
add rootgroup "b8da3005-cc77-4150-b9f3-23e1d3cc92e9","DwarvesCommon"
add namegroup "Dwarven Crossbow","",""
</pre>

And a TreasureTable:
<pre>
new treasuretable "ST_Wikimod_Crossbows"
new subtable "1,1"
object category "Wikimod_Crossbows",1,1,0,0,0,0,0,0
</pre>

Our table is attempting to generate our item at "Common" rarity, yet we only have an entry for the "Epic" rarity. Furthermore, attempting to generate this item at a level higher than 9 will fail.

The solution is to add new entries for each level range and rarity we want to support (This is why the ItemProgressionVisuals in Shared contains so many entries).

* '''Using a root template with a "defined" name, and expecting a namegroup to work.'''

If a root template has a display name set, it will take priority over the namegroup. This includes "Display Name (Unknown)".

Community page submission

2018-07-22T21:50:52Z

LaughingLeader: Added the new Item Progression guide to the list.

Welcome to the community page submission section. 
First and foremost: thanks to all of you from everyone at Larian Studios! 
Without your love and feedback, we wouldn't be where we are today.

 
 
That being said, let's do our best to keep this wiki just as lovely as you guys: 
# To add your page to the main wiki pages, please add it to the list below.
# Once our moderators get a chance, they'll review the submissions and move approved pages to the appropriate location on the [[Community editor guides | Editor Guides]] and/or [[Community tutorials | Community Tutorials]] section.
# We'll leave the page link a couple of days on here with an approval stamp and a link to its new location, to give the editor a chance to find out where his/her page went.
# We love you all very much, but we do not tolerate any misbehavior. Please refrain from using foul language, messing with other people's pages,...
# This wiki follows the general open format. Anyone is allowed to edit a page. View an edit to your page as interest in your content, not as criticism.
# But do try to avoid editing someone else's pages before it has been approved and moved to the main sections, unless of course you have the permission to do so from the original editor.
# As always, stay awesome [[File: heart.png | 32px]]
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Example Submission|Example submission]]</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Reflection_Dialogues|Creating new Reflection Dialogues]] [[File:LarianLogo_Icon.png|32px]] AWAITING APPROVAL ([[Community tutorials|Community Tutorials]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Item_Progression|Item Progression]] [[File:LarianLogo_Icon.png|32px]] AWAITING APPROVAL ([[Community editor guides|Editor Guides]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[How to create a basic adventure with quests, dialog and scripts|How to create a basic adventure with quests, dialog and scripts]] [[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community tutorials|Community Tutorials]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Party Management via Dialog|Party Management via Dialog]] [[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community tutorials|Community Tutorials]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Subregion UI Notifications|Subregion UI Notifications]] [[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community tutorials|Community Tutorials]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[How to make an NPC sit|How to make an NPC sit]] [[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community tutorials|Community Tutorials]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Creating a book with TEXT inside|Creating a book with TEXT inside]] [[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community tutorials|Community Tutorials]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Pak Extractor Guide|Pak Extractor Guide]] [[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community editor guides|Editor Guides]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Tutorial - Implementing a Basic Quest|Tutorial - Implementing a Basic Quest]] [[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community tutorials|Community Tutorials]]) ([[Community:_Getting_Started|Editor Guides]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[NPC Patrols|NPC Patrols]] [[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community tutorials|Community Tutorials]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Basic Character Creation]] [[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community tutorials|Community Tutorials]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Character and Item Script Triggers, Calls, and Queries]] [[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community:_Script_editor|Editor Guides]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Scripting in New Talents, Attributes, and Combat Abilities]] [[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community tutorials|Community Tutorials]])([[Community:_Story_editor|Editor Guides]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Creating/Modifying Weapon Elements and Scaling]] [[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community tutorials|Community Tutorials]])([[Community:_Stats_editor|Editor Guides]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Adding New Icons]] [[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community tutorials|Community Tutorials]])([[Community:_Texture_atlas_editor|Editor Guides]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Your First Story Script]] [[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community tutorials|Community Tutorials]])([[Community:_Story_editor|Editor Guides]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Crime_System|Crime System]][[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community tutorials|Community Tutorials]])</big>
 

[[File:LarianLogo_Icon.png|32px]] <big>[[Experience_For_Exploration_Quests_And_Killing|Experience For Exploration Quests And Killing]][[File:LarianLogo_Icon.png|32px]] APPROVED ([[Community tutorials|Community Tutorials]])</big>

File:ItemProgression NameMistake01.png

2018-07-22T21:36:48Z

LaughingLeader: An example of setting a name on a root template, which overrides the namegroup item name set in ItemProgressionVisuals.

An example of setting a name on a root template, which overrides the namegroup item name set in ItemProgressionVisuals.

Item Progression

2018-07-22T21:32:47Z

LaughingLeader:

== Description ==
An important part of the treasure system, Item Progression is the link between item stats and root templates, and is necessary to customize the level range, rarity, and names of items generated by stat, or by treasure tables.

== ItemProgressionVisuals ==

ItemProgressionVisuals links an itemgroup with a levelgroup (the level range and rarity), a root group (the root template used), and a namegroup (the names to use).

=== Properties ===
{| class="wikitable"
! style="text-align:left;"| Property
! style="text-align:left;"| Parameters
! style="text-align:left;"| Description
|-
|[[Item_Progression#itemgroup|itemgroup]]||ItemGroup||The itemgroup, defined via item stats. Consider this the "header" that subsequent entries are included under, until a new itemgroup is used.
|-
|[[Item_Progression#LevelGroup|levelgroup]]||MinLevel,MaxLevel,[[Rarity]]||The level range and rarity to link the subsequent rootgroup and namegroup to.
|-
|[[Item_Progression#RootGroup|rootgroup]]||RootTemplate,[[ItemColor]]||The RootTemplate is the GUIDSTRING of the root template to use. ItemColor is defined in its own stats file, and changes the color of items with materials that support MSK.
|-
|[[Item_Progression#NameGroup|namegroup]]||NameGroup,[[Item_Progression#Cool_Names|AffixType]],[[Item_Progression#Icon_Override|Icon]]||The namegroup to use, whether to use the "cool" version, and an icon to use in place of the root template's icon.
|}

=== ItemGroup ===

ItemGroup is defined in equipment stats, and is used to define which group of stats the subsequent levelgroup, rootgroup, and namegroup use.

Examples:

A base stat inherited by other weapons:

<pre>
new entry "_Clubs"
type "Weapon"
data "ItemGroup" "Maces_1H"
data "ModifierType" "Item"
data "Act" "1"
data "Requirements" "Strength 12"
data "IsTwoHanded" "No"
data "AttackAPCost" "2"
data "Damage Type" "Physical"
data "Damage" "0"
data "Damage Range" "5"
data "DamageFromBase" "67"
data "CriticalDamage" "150"
data "CriticalChance" "0"
data "WeaponRange" "120"
data "Durability" "20"
data "DurabilityDegradeSpeed" "6"
data "Value" "40"
data "Weight" "3500"
data "Movement" "0"
data "WeaponType" "Club"
data "Slot" "Weapon"
data "InventoryTab" "Equipment"
data "Charges" "0"
data "MaxCharges" "0"
data "ItemColor" "DefaultGray"
data "RuneSlots" "0"
data "RuneSlots_V1" "0"
</pre>

Overriding the inherited ItemGroup with a new one:
<pre>
new entry "WPN_Common_Mace_1H_A"
type "Weapon"
using "_Clubs"
data "ItemGroup" "WPN_Common_Mace_1H_A"
data "Act part" "1"
data "Value" "2"
data "Weight" "1000"
data "ComboCategory" "Club,Hammer"
</pre>

=== LevelGroup ===

The levelgroup sets the level range and [[Rarity]] that the following rootgroups and namegroups will apply to.

Examples:

<pre>
add levelgroup 9,16,"Uncommon"
add rootgroup "648d501c-2d8e-4464-acfb-6e6f061305f6","MageUncommon"
add namegroup "MageRobe9","",""
</pre>

This item will generate at levels 9-16 at the "Uncommon" rarity.

<pre>
add levelgroup 17,0,"Common"
add rootgroup "94aaefe8-4843-4624-b1a0-92d63be2e5b8","LizardsCommon"
add namegroup "Claymore","",""
</pre>

This item will spawn at level 17 and above, at the "Common" rarity.

<pre>
new itemgroup "Wings"

add levelgroup 0,0,"All"
add rootgroup "a71d1908-7499-42c2-8c6b-a2173be582dc",""
add namegroup "Wings","",""
</pre>

This item is generated at any level, and any rarity. ''Fun fact: These are the wings created by the Wings Polymorph skill.''

=== RootGroup ===

The rootgroup is simply the GUIDSTRING of the root template to link the itemgroup with. The second property is an optional ItemColor to use. You can get the GUIDSTRING of a root template by right clicking it in the [[Root template panel]], and selecting "Copy GUID to clipboard".

Example:

<pre>
add levelgroup 4,4,"Common"
add rootgroup "16600f2c-3817-42e7-be9d-5804f8ac77c8","HumansCommon"
add namegroup "Twohander 2","",""
</pre>

=== NameGroup ===

The namegroup is a set of names to use with the item, defined in ItemProgressionNames. The first parameter is the name of the namegroup, while the second and third parameters are optional, and usually blank (""). The second parameter activates the "namecool" version of a name (via "Cool"), and the third parameter specifies the icon to use, which overrides the icon on the root template.

Example:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""
</pre>

This entry uses the namegroup named "Elven Sword".

<pre>
add levelgroup 9,16,"Rare"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","Cool","Item_WPN_Dwarves_Sword_1H_C"
</pre>

While this entry also uses the namegroup named "Elven Sword", it uses the "namecool" entry thanks to "Cool", and uses the "Item_WPN_Dwarves_Sword_1H_C" icon instead of the one set by the root template.

== ItemProgressionNames ==

ItemProgressionNames defines a set of names and (optional) descriptions to use for items defined in ItemProgressionVisuals.

=== Properties ===
{| class="wikitable"
! style="text-align:left;"| Property
! style="text-align:left;"| Parameters
! style="text-align:left;"| Description
|-
|namegroup||Name||The name of the namegroup. Used in ItemProgressionVisuals.
|-
|name||ItemName,Description||The item name and (optional) description to use.
|-
|namecool||ItemName,Description||An optional, additional entry to use if "Cool" is specified in ItemProgressionVisuals.
|}

Example:

Say we have an entry in ItemProgressionVisuals:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""
</pre>

We then define the namegroup "Elven Sword" within ItemProgressionNames:

<pre>
new namegroup "Elven Sword"
add name "Elven Sword",""
add namecool "Elegant Sword",""
</pre>

"name" is the name to use normally, followed by the name to use. The second parameter an optional description. If left blank, the description on the root template is used.

"namecool" is the name to use when "Cool" is specified in ItemProgressionVisuals, typically for higher rarity versions of an item.

''Note: If the root template specifies a name (Display Name, or Display Name (Unknown)), that value will override the name provided by the namegroup.''

== Cool Names ==

Say we have the following entries:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""

add levelgroup 9,16,"Epic"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","Cool",""
</pre>

If the item spawns at level 9-16 with the "Epic" rarity, the resulting item will use the name "Elegant Sword" instead of "Elven Sword". Otherwise, the normal name is used.

=== Icon Override ===

The third parameter for the ItemProgressionVisuals namegroup entry is an icon override, allowing us to change the icon used for the weapon that matches the progression parameters.

Example:
<pre>
new itemgroup "ARM_UNIQUE_WikiMod_BrilliantRing"

add levelgroup 0,0,"Common"
add rootgroup "f6fd6b73-191d-4ba1-b844-cec875608fe3",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","",""

add levelgroup 0,0,"Rare"
add rootgroup "c21de6ee-136b-45f7-b083-565d3f458726",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","Cool","Item_LOOT_Ring_B_Silver_Turquoise"
</pre>

Now when a rare version of our ring spawns, it will use the icon "Item_LOOT_Ring_B_Silver_Turquoise", located in the Icons_DOS2_Items texture atlas.

== Unique Items ==

For cases where we want an item to be unique, and spawn regardless of level, an ItemProgression entry is still needed.

Say we have a unique ring, defined in Armor:

<pre>
new entry "ARM_UNIQUE_WikiMod_BrilliantRing"
type "Armor"
using "_Rings"
data "ItemGroup" "ARM_UNIQUE_WikiMod_BrilliantRing"
data "Unique" "1"
</pre>

We then define a new entry in ItemProgressionVisuals:

<pre>
new itemgroup "ARM_UNIQUE_WikiMod_BrilliantRing"

add levelgroup 0,0,"All"
add rootgroup "24c3d50a-c377-4c09-b3e8-274f8447494b",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","",""
</pre>

And finally, an entry in ItemProgressionNames:

<pre>
new namegroup "ARM_UNIQUE_WikiMod_BrilliantRing"
add name "Brilliant Ring of Amun-Ra","This ring shines with a brilliant light. The metal is warm to the touch, and seems impervious to scuffing."
</pre>

By making our levelgroup 0,0 with the "All" rarity, this makes our ring spawn at any level, and any rarity. Naturally, rarity is left out of the equation, since our ring is unique.

== Common Mistakes ==

* '''Generating the Item with a level range or rarity that isn't defined.'''

Say we have an ItemProgressionVisuals entry:

<pre>
new itemgroup "WPN_Wikimod_Crossbow_Plus"

add levelgroup 1,9,"Common"
add rootgroup "b8da3005-cc77-4150-b9f3-23e1d3cc92e9","DwarvesCommon"
add namegroup "Dwarven Crossbow","",""
</pre>

Attempting to generate this item at a higher level than 9, or a rarity other than "Common" will fail. The solution is to add new entries for each level range and rarity we want to support, and is why Shared's ItemProgressionVisuals contains so many entries.

* '''Using a root template with a "defined" name, and expecting a namegroup to work.'''

If a root template has a display name set, it will take priority over the namegroup. This includes "Display Name (Unknown)".

Item Progression

2018-07-22T21:31:55Z

LaughingLeader: Initial ItemProgression draft.

== Description ==
An important part of the treasure system, Item Progression is the link between item stats and root templates, and is necessary to customize the level range, rarity, and names of items generated by stat, or by treasure tables.

== ItemProgressionVisuals ==

ItemProgressionVisuals links an itemgroup with a levelgroup (the level range and rarity), a root group (the root template used), and a namegroup (the names to use).

=== Properties ===
{| class="wikitable"
! style="text-align:left;"| Property
! style="text-align:left;"| Parameters
! style="text-align:left;"| Description
|-
|[[Item_Progression#itemgroup|itemgroup]]||ItemGroup||The itemgroup, defined via item stats. Consider this the "header" that subsequent entries are included under, until a new itemgroup is used.
|-
|[[Item_Progression#levelgroup|levelgroup]]||MinLevel,MaxLevel,[[Rarity]]||The level range and rarity to link the subsequent rootgroup and namegroup to.
|-
|[[Item_Progression#rootgroup|rootgroup]]||RootTemplate,[[ItemColor]]||The RootTemplate is the GUIDSTRING of the root template to use. ItemColor is defined in its own stats file, and changes the color of items with materials that support MSK.
|-
|[[Item_Progression#namegroup|namegroup]]||NameGroup,[[Item_Progression#Cool_Names|AffixType]],[[Item_Progression#Icon_Override|Icon]]||The namegroup to use, whether to use the "cool" version, and an icon to use in place of the root template's icon.
|}

=== ItemGroup ===

ItemGroup is defined in equipment stats, and is used to define which group of stats the subsequent levelgroup, rootgroup, and namegroup use.

Examples:

A base stat inherited by other weapons:

<pre>
new entry "_Clubs"
type "Weapon"
data "ItemGroup" "Maces_1H"
data "ModifierType" "Item"
data "Act" "1"
data "Requirements" "Strength 12"
data "IsTwoHanded" "No"
data "AttackAPCost" "2"
data "Damage Type" "Physical"
data "Damage" "0"
data "Damage Range" "5"
data "DamageFromBase" "67"
data "CriticalDamage" "150"
data "CriticalChance" "0"
data "WeaponRange" "120"
data "Durability" "20"
data "DurabilityDegradeSpeed" "6"
data "Value" "40"
data "Weight" "3500"
data "Movement" "0"
data "WeaponType" "Club"
data "Slot" "Weapon"
data "InventoryTab" "Equipment"
data "Charges" "0"
data "MaxCharges" "0"
data "ItemColor" "DefaultGray"
data "RuneSlots" "0"
data "RuneSlots_V1" "0"
</pre>

Overriding the inherited ItemGroup with a new one:
<pre>
new entry "WPN_Common_Mace_1H_A"
type "Weapon"
using "_Clubs"
data "ItemGroup" "WPN_Common_Mace_1H_A"
data "Act part" "1"
data "Value" "2"
data "Weight" "1000"
data "ComboCategory" "Club,Hammer"
</pre>

=== LevelGroup ===

The levelgroup sets the level range and [[Rarity]] that the following rootgroups and namegroups will apply to.

Examples:

<pre>
add levelgroup 9,16,"Uncommon"
add rootgroup "648d501c-2d8e-4464-acfb-6e6f061305f6","MageUncommon"
add namegroup "MageRobe9","",""
</pre>

This item will generate at levels 9-16 at the "Uncommon" rarity.

<pre>
add levelgroup 17,0,"Common"
add rootgroup "94aaefe8-4843-4624-b1a0-92d63be2e5b8","LizardsCommon"
add namegroup "Claymore","",""
</pre>

This item will spawn at level 17 and above, at the "Common" rarity.

<pre>
new itemgroup "Wings"

add levelgroup 0,0,"All"
add rootgroup "a71d1908-7499-42c2-8c6b-a2173be582dc",""
add namegroup "Wings","",""
</pre>

This item is generated at any level, and any rarity. ''Fun fact: These are the wings created by the Wings Polymorph skill.''

=== RootGroup ===

The rootgroup is simply the GUIDSTRING of the root template to link the itemgroup with. The second property is an optional ItemColor to use. You can get the GUIDSTRING of a root template by right clicking it in the [[Root template panel]], and selecting "Copy GUID to clipboard".

Example:

<pre>
add levelgroup 4,4,"Common"
add rootgroup "16600f2c-3817-42e7-be9d-5804f8ac77c8","HumansCommon"
add namegroup "Twohander 2","",""
</pre>

=== NameGroup ===

The namegroup is a set of names to use with the item, defined in ItemProgressionNames. The first parameter is the name of the namegroup, while the second and third parameters are optional, and usually blank (""). The second parameter activates the "namecool" version of a name (via "Cool"), and the third parameter specifies the icon to use, which overrides the icon on the root template.

Example:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""
</pre>

This entry uses the namegroup named "Elven Sword".

<pre>
add levelgroup 9,16,"Rare"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","Cool","Item_WPN_Dwarves_Sword_1H_C"
</pre>

While this entry also uses the namegroup named "Elven Sword", it uses the "namecool" entry thanks to "Cool", and uses the "Item_WPN_Dwarves_Sword_1H_C" icon instead of the one set by the root template.

== ItemProgressionNames ==

ItemProgressionNames defines a set of names and (optional) descriptions to use for items defined in ItemProgressionVisuals.

=== Properties ===
{| class="wikitable"
! style="text-align:left;"| Property
! style="text-align:left;"| Parameters
! style="text-align:left;"| Description
|-
|namegroup||Name||The name of the namegroup. Used in ItemProgressionVisuals.
|-
|name||ItemName,Description||The item name and (optional) description to use.
|-
|namecool||ItemName,Description||An optional, additional entry to use if "Cool" is specified in ItemProgressionVisuals.
|}

Example:

Say we have an entry in ItemProgressionVisuals:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""
</pre>

We then define the namegroup "Elven Sword" within ItemProgressionNames:

<pre>
new namegroup "Elven Sword"
add name "Elven Sword",""
add namecool "Elegant Sword",""
</pre>

"name" is the name to use normally, followed by the name to use. The second parameter an optional description. If left blank, the description on the root template is used.

"namecool" is the name to use when "Cool" is specified in ItemProgressionVisuals, typically for higher rarity versions of an item.

''Note: If the root template specifies a name (Display Name, or Display Name (Unknown)), that value will override the name provided by the namegroup.''

== Cool Names ==

Say we have the following entries:

<pre>
add levelgroup 9,16,"Common"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","",""

add levelgroup 9,16,"Epic"
add rootgroup "30102727-1802-4aad-b464-02b9816c07db","ElvesCommon"
add namegroup "Elven Sword","Cool",""
</pre>

If the item spawns at level 9-16 with the "Epic" rarity, the resulting item will use the name "Elegant Sword" instead of "Elven Sword". Otherwise, the normal name is used.

=== Icon Override ===

The third parameter for the ItemProgressionVisuals namegroup entry is an icon override, allowing us to change the icon used for the weapon that matches the progression parameters.

Example:
<pre>
new itemgroup "ARM_UNIQUE_WikiMod_BrilliantRing"

add levelgroup 0,0,"Common"
add rootgroup "f6fd6b73-191d-4ba1-b844-cec875608fe3",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","",""

add levelgroup 0,0,"Rare"
add rootgroup "c21de6ee-136b-45f7-b083-565d3f458726",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","Cool","Item_LOOT_Ring_B_Silver_Turquoise"
</pre>

Now when a rare version of our ring spawns, it will use the icon "Item_LOOT_Ring_B_Silver_Turquoise", located in the Icons_DOS2_Items texture atlas.

== Unique Items ==

For cases where we want an item to be unique, and spawn regardless of level, an ItemProgression entry is still needed.

Say we have a unique ring, defined in Armor:

<pre>
new entry "ARM_UNIQUE_WikiMod_BrilliantRing"
type "Armor"
using "_Rings"
data "ItemGroup" "ARM_UNIQUE_WikiMod_BrilliantRing"
data "Unique" "1"
</pre>

We then define a new entry in ItemProgressionVisuals:

<pre>
new itemgroup "ARM_UNIQUE_WikiMod_BrilliantRing"

add levelgroup 0,0,"All"
add rootgroup "24c3d50a-c377-4c09-b3e8-274f8447494b",""
add namegroup "ARM_UNIQUE_WikiMod_BrilliantRing","",""
</pre>

And finally, an entry in ItemProgressionNames:

<pre>
new namegroup "ARM_UNIQUE_WikiMod_BrilliantRing"
add name "Brilliant Ring of Amun-Ra","This ring shines with a brilliant light. The metal is warm to the touch, and seems impervious to scuffing."
</pre>

By making our levelgroup 0,0 with the "All" rarity, this makes our ring spawn at any level, and any rarity. Naturally, rarity is left out of the equation, since our ring is unique.

== Common Mistakes ==

* '''Generating the Item with a level range or rarity that isn't defined.'''

Say we have an ItemProgressionVisuals entry:

<pre>
new itemgroup "WPN_Wikimod_Crossbow_Plus"

add levelgroup 1,9,"Common"
add rootgroup "b8da3005-cc77-4150-b9f3-23e1d3cc92e9","DwarvesCommon"
add namegroup "Dwarven Crossbow","",""
</pre>

Attempting to generate this item at a higher level than 9, or a rarity other than "Common" will fail. The solution is to add new entries for each level range and rarity we want to support, and is why Shared's ItemProgressionVisuals contains so many entries.

* '''Using a root template with a "defined" name, and expecting a namegroup to work.'''

If a root template has a display name set, it will take priority over the namegroup. This includes "Display Name (Unknown)".

Rarity

2018-07-22T20:23:52Z

LaughingLeader: Created page with "Rarities are used in Treasure Tables, Item Progression, and Item Types. # Common # Uncommon # Rare # Epic # Legendary # Divine # Unique"

Rarities are used in [[Treasure Tables]], [[Item Progression]], and [[Item Types]].

# Common
# Uncommon
# Rare
# Epic
# Legendary
# Divine
# Unique

Osiris/Shared/DB GLO Attribute Check AgainstLevel

2018-07-06T19:23:05Z

LaughingLeader: Replaced "Medium" with "Normal", as per the description in "Attribute_Check_1_Difficulty" (Medium also spits out an error when used).

===== Full Definition(s) =====
* '''DB_GLO Attribute_Check_AgainstLevel'''(''(STRING)'''''_Dialog''',''(INTEGER)'''''_Index''',''(STRING)'''''_Attribute''',''(STRING)'''''_Difficulty''',''(INTEGER)'''''_Source''',''(INTEGER)'''''_Level''')
* '''DB_GLO Attribute_Check_AgainstSpeaker'''(''(STRING)'''''_Dialog''',''(INTEGER)'''''_Index''',''(STRING)'''''_Attribute''',''(STRING)'''''_Difficulty''',''(INTEGER)'''''_Source''',''(INTEGER)'''''_Target''')
===== Description =====
When the dialog '''_Dialog''' gets started, story will set the dialog variables needed for the '''Attribute Check ''<n>''''' script flag to function, with '''''<n>''''' equal to '''_Index'''. This script flag, when checked in the dialog, will then check whether the attribute '''_Attribute''' of speaker '''_Source''' is high enough. The required minimum value is set so that it is easy/hard to pass for a character of level '''_Level''' resp. the same level as '''_Target''' depending on the specified '''_Difficulty'''.

'''_Index''' can be 1, 2 or 3 to define up to three different attribute checks in a single dialog.

'''_Difficulty''' can be one of the following values: '''Always''', '''Easy''', '''Normal''', '''Hard''', '''Impossible'''.
===== Notes =====
* The valid values for '''_Attribute''' are the same as the ones for [[Osiris/API/CharacterGetAttribute|CharacterGetAttribute]].
===== See Also =====
* [[Osiris/API/CharacterGetAttribute|CharacterGetAttribute]]

[[Category:Osiris Shared Mod Helpers|Attribute Check AgainstLevel]]

Osiris/API/Follow

2018-05-15T23:11:42Z

LaughingLeader: Removed the _Running parameter since it doesn't exist within the call.

===== Full Definition(s) =====
* call '''CharacterFollowCharacter'''(''(CHARACTERGUID)'''''_Character''', ''(CHARACTERGUID'')'''''_ToCharacter''')

===== Description =====
Makes '''_Character''' start following '''_ToCharacter'''.

===== Notes =====
* Preferably use [[Osiris/Shared/ProcCharacterFollowCharacter|ProcCharacterFollowCharacter]] from the Shared mod. This will ensure that '''_Character''''s following behaviour gets suspended when it enters combat, and resumed afterwards.
* Use [[Osiris/API/CharacterStopFollow|CharacterStopFollow]] to stop the following behaviour (or [[Osiris/Shared/ProcCharacterStopFollow|ProcCharacterStopFollow]] if you used [[Osiris/Shared/ProcCharacterFollowCharacter|ProcCharacterFollowCharacter]]).
* Make sure to stop following a previous character before starting to follow a new one. [[Osiris/Shared/ProcCharacterFollowCharacter|ProcCharacterFollowCharacter]] will automatically take care of this.
* Note that this call does ''not'' turn '''_Character''' in a so-called "party follower" or minion, which is done via [[Osiris/API/CharacterAddToPlayerCharacter|CharacterAddToPlayerCharacter]]. The difference between "regular followers" (as created by this routine) and party followers/minions is that regular followers simply follow any other character around (you can have one NPC follow another one, if you want), while party followers/minions always follow a player-controlled character and can be partially controlled by the [[Osiris/API/CharacterGetReservedUserID|user]] that controls this player character.

===== See Also =====
* [[Osiris/API/CharacterAddToPlayerCharacter|CharacterAddToPlayerCharacter]]
* [[Osiris/API/CharacterStopFollow|CharacterStopFollow]]
* Helper [[Osiris/Shared/ProcCharacterFollowCharacter|ProcCharacterFollowCharacter]]
* Helper [[Osiris/Shared/ProcCharacterStopFollow|ProcCharacterStopFollow]]

[[Category:Osiris Calls|CharacterFollowCharacter]]

Osiris/Shared/PROC Follow

2018-05-15T23:08:01Z

LaughingLeader: Fixed formatting, removed the _Running parameter since it doesn't currently exist in _PROC. Removed the Return Value section since it's a call.

===== Full Definition(s) =====
* PROC '''ProcCharacterFollowCharacter'''(''(CHARACTERGUID)'''''_Char''',''(CHARACTERGUID)'''''_Target''')
===== Description =====
Same as the Osiris call [[Osiris/API/CharacterFollowCharacter|CharacterFollowCharacter]], except that it also first automatically cancels '''_Char''' from following if it was already following someone else. Additionally, it stops the following behaviour when '''_Char''' gets involved in combat and resumes it afterwards.

===== Notes =====
* Stop following through [[Osiris/Shared/ProcCharacterStopFollow|ProcCharacterStopFollow]].

===== See Also =====
* [[Osiris/API/CharacterFollowCharacter|CharacterFollowCharacter]]
* Helper [[Osiris/Shared/ProcCharacterStopFollow|ProcCharacterStopFollow]]

[[Category:Osiris Shared Mod Helpers|CharacterFollowCharacter]]

Osiris Tips and Examples

2018-04-17T19:30:21Z

LaughingLeader: /* Databases Queries for Conditions */

The following is a collection of practical examples and tips that will aid in your journey to learn how to power your mod through story script usage.

== Rule Flow ==
Story scripts run on "rules". Every frame, Osiris will evaluate the rules for every running story goal.

The flow of every rule is:
<pre>
IF
Event
AND
Query
THEN
Call();
</pre>

Queries between the event and the call section of a rule are optional. You can simply go from event to call if you desire:
<pre>
IF
Event
THEN
Call();
</pre>

Queries are both gatekeepers to the call section, and a way to retrieve information.

== Databases ==
Databases can be used to store specific data (such as characters entering a trigger), or as a way to story settings used in your rules.

=== Database Use Within Rules ===
----
Databases may be used in all three rule sections:
;IF
:Databases used in the event section will run when a new entry is added. It will never run when an entry is removed.
;AND
:Databases used in the query section can be used to evaluate if an entry exists, does not exist, or as a way to run subsequent lines on the whole database, or entries that match a particular value.
;THEN
:In the call section, new entries are added to databases, or existing entries are removed (i.e. NOT DB_MyDatabase(_VariableA, _VariableB).

=== Database Events ===
----
When used as an event, it becomes possible to create rules that run when an entry is added to a database.

Say we have a database we use to start a timer, called "DB_ExampleMod_Timers". Additionally, when the timer finishes, we'll add the timer name to a database as a sort of "On Complete" event.

<pre>
IF
DB_ExampleMod_Timers(_TimerName, _Time)
THEN
TimerLaunch(_TimerName, _Time);

IF
TimerFinished(_TimerName)
AND
DB_ExampleMod_Timers(_TimerName, _Time)
THEN
NOT DB_ExampleMod_Timers(_TimerName, _Time);
DB_ExampleMod_TimerFinished(_TimerName);
</pre>

Next we'll trigger the events by pulling a lever, with an additional rule for the "DB_ExampleMod_TimerFinished" database, with our specific timer name in mind:

<pre>
IF
CharacterUsedItem(_Player, ITEMGUID_Lever_RunTimer_4289a1de-0d4b-43b0-9c38-0d796dff1d43)
THEN
DB_ExampleMod_Timers("ExampleMod_LeverTimer", 1000);

IF
DB_ExampleMod_TimerFinished("ExampleMod_LeverTimer")
THEN
DebugBreak("ExampleMod_LeverTimer finished!");
NOT DB_ExampleMod_TimerFinished("ExampleMod_LeverTimer");
</pre>

Since database events only fire when an entry is ''added'', not removed, removing the entry right in the database rule works as expected.

=== Database Queries ===
----
Used as a query, databases are powerful ways to retrieve data, or create complex conditions.
==== Databases Queries for Conditions ====
Passing values into Databases is an easy way to create dynamic conditions:
<pre>
IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You're been bad this year! Coal for you!");
ItemTemplateAddTo("QUEST_Coal_df215b50-e18f-4527-a2ac-e7eec6cba576", _Target, 1);

IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
NOT DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You've been good this year! Have a present!");
ItemTemplateAddTo("QUEST_Present_29f926ff-bfb3-4c0f-b4a4-e356d6b88cf0", _Target, 1);
</pre>
This example assumes that characters were already added to a database, and uses it to determine which item to give to a target, when Santa casts his skill.

==== Databases Queries for Data Retrieval ====
Now we'll use a database to iterate through a number of targets dynamically.
<pre>
IF
SkillCast(_Santa, "Shout_SpreadCheer", _)
AND
DB_Santa_NiceList(_Target)
THEN
ApplyStatus(_Target, "HOLIDAY_CHEER", -1.0);
PlayEffect(_Target, "RS3_FX_Santa_HolidayExplosion_01");
</pre>
Since the value of _Target is not specified in the database query, it acts as an out variable, calling subsequent lines on each entry added to DB_Santa_NiceList.

=== Database Gotchas ===
----
While databases are a powerful way to create complex scripting logic, there are a few crucial concepts to keep in mind:
* Unless you take steps to clear it out, database data persists in existing saves, even if you no longer support a particular database in a later version of your mod.
* Consider keeping the number of database columns at a manageable size. Databases can be cross-referenced with other databases if needed.
* Inherited types from GUIDSTRING (CHARACTERGUID, ITEMGUID, TRIGGERGUID) need to be declared once in a database, to properly set the type.

=== System Methods ===
----
A few system methods, hidden from auto-complete, exist to enhance database use:

;call [[Osiris/API/SysClear|SysClear]]((STRING)_Predicate, (INTEGER)_Arity)
* Predicate is the name of the database ("DB_MyDatabase"), while arity are the number of columns (DB_MyDatabase("Apples", 10) would be 2 arity).
* SysClear provides an ideal way of clearing older saves of old databases from previous version of your mod, or paving the way for a full reset of a database.
;query [[Osiris/API/SysCount|SysCount]]([in](STRING)_Predicate,[in](INTEGER)_Arity,[out](INTEGER)_Count)
* SysCount is a way to count the entries in a database. This is especially useful when creating conditions in reference to a database that is added to dynamically through gameplay (i.e. the number of players inside a trigger, the number of characters who had a particular status applied, and so on).

=== Cross-Database Referencing ===
----
Using a consistent entry across multiple databases allows you to utilize various databases to dynamically enhance your mod.

==== Adventure Mod Example ====
----

First, we'll create a few databases to store some settings.

INIT:
<pre>
//DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
DB_MyAdventureMod_Triggers("MyLevel_FrontDoor", (TRIGGERGUID)TRIGGERGUID_S_MyLevel_DoorEntry_b5ab6a49-b015-4908-8f49-7b152d6c5d30);
DB_MyAdventureMod_Triggers("MyLevel_HallwayAmbush", TRIGGERGUID_S_MyLevel_Ambush1_1d089d37-fc5e-4cc6-807e-51d0535dc0cc);
DB_MyAdventureMod_Triggers("MyLevel_GolemBoss", TRIGGERGUID_S_MyLevel_Boss1_0a009ed0-61f5-4670-9d26-1417ebf02922);

//DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_FrontDoor", "12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_HallwayAmbush","12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_GolemBoss","2052f790-d2d7-4cf7-95f0-4de478e98d28");

//DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonLeader_584db8ce-8dcf-4906-bc6f-e51eb057de08");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonMage1_61bf204e-ba2e-412f-ac86-e132a3930105");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonRanger1_f7bd3244-e1e7-4079-ac95-fef6145a236e");
</pre>

By using multiple databases together, we now only need to worry about the TRIGGERGUID in one database, while the others rely on the string name. This is easier to deal with in the long run.

Next, we'll look for when a player enters one of these triggers, and store when it first activates.

KB:
<pre>
IF
CharacterEnteredTrigger((CHARACTERGUID)_Character, (TRIGGERGUID)_TriggerID)
AND
DB_IsPlayer(_Character)
AND
DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
AND
NOT DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
THEN
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID);
</pre>

We'll then look for when a trigger is added to the "TriggerActivated" database, and create rules for changing the atmosphere and spawning enemies.

KB:
<pre>
IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
THEN
TriggerSetAtmosphere(_TriggerID, _Atmosphere);

IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
AND
GetRandomPositionInTrigger(_TriggerID, _X, _Y, _Z)
AND
CharacterCreateAtPosition(_X, _Y, _Z, _CharacterTemplate, 1, _Enemy)
THEN
DB_MyAdventureMod_SpawnedEnemies(_TriggerName, _Enemy);
</pre>

We now have a good basis for changing atmosphere, spawning enemies, and tracking which enemies were spawned. This could easily be extended to support sounds, dialogs that need to start, and more.

=== Updating Databases ===
----
When you use databases as a way to store settings, this information will persist on existing saves unless you purposefully remove it.

As an example, say you have a script like this:

'''MyMod_ExampleScript.txt'''

INIT:
<pre>
//DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_A_7e24b009-f2bc-47c0-a635-b776407833aa", 1);
</pre>

KB:
<pre>
IF
SkillCast(_Character, _Skill, _)
AND
DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
THEN
ItemTemplateAddTo(_ItemTemplate, _Character, (INTEGER)_Count, 1);
</pre>
Later, after releasing your mod, you decide that you want "Target_MyMod_DiamondTransmutation" to spawn a different diamond item template. To properly do this, in a way that won't spawn the previous template for an existing save, you need to delete the previous entry from the database.

==== Database Update Example ====
----
One way to implement internal mod "updates" for your databases is by storing a "mod version" in a database, and checking against this version when a save is loaded.

In a top-level goal (one that will run before all others), enter the following:

'''MyMod__MainScript.txt'''
INIT:
<pre>
//The current mod version.
DB_MyMod_Version("1.1.1");
</pre>

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
DebugBreak("[MyMod] Mod update detected. Updating databases.");

IF
SavegameLoaded(_,_,_,_)
AND
NOT DB_MyMod_Version("1.1.1")
THEN
MyMod_Update_UpdateDatabases();
SysClear("DB_MyMod_Version", 1); // Clear existing mod versions.
DB_MyMod_Version("1.1.1");
</pre>

"MyMod_Update_UpdateDatabases()" is a custom PROC we've created to handle updating databases. In the individual goals that we want to update databases for, creating new rules with the same PROC name will run our PROC when the top-level goal's PROC is triggered:

'''MyMod_ExampleScript.txt'''

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
SysClear("DB_MyMod_Skill_ItemCreation", 3);
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_B_Black_VW_94933c36-393e-4077-abec-95e04341fc92", 1);
</pre>

Now when the main script triggers the update, our second script will also run its own update, clearing out the previous database data and adding our new settings.

=== Updating Mods: Beyond Databases ===
----
Beyond changing databases, updating your mod can be a more extensive ordeal, as there's a variety of factors to keep in mind. More on that here: [[Modding:_Versioning|Modding: Versioning]].

== Further Information ==
More in-depth information on Osiris can be read on the following pages:
* [[Osiris Overview]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]
* [[Your First Story Script]]
* [[:Category:Osiris_APIs|Osiris APIs]]
* [[:Category:Osiris_Calls|Osiris Calls]]

[[Category:Osiris]]

Osiris Tips and Examples

2018-03-10T06:44:35Z

LaughingLeader: Added a short example for database events.

The following is a collection of practical examples and tips that will aid in your journey to learn how to power your mod through story script usage.

== Rule Flow ==
Story scripts run on "rules". Every frame, Osiris will evaluate the rules for every running story goal.

The flow of every rule is:
<pre>
IF
Event
AND
Query
THEN
Call();
</pre>

Queries between the event and the call section of a rule are optional. You can simply go from event to call if you desire:
<pre>
IF
Event
THEN
Call();
</pre>

Queries are both gatekeepers to the call section, and a way to retrieve information.

== Databases ==
Databases can be used to store specific data (such as characters entering a trigger), or as a way to story settings used in your rules.

=== Database Use Within Rules ===
----
Databases may be used in all three rule sections:
;IF
:Databases used in the event section will run when a new entry is added. It will never run when an entry is removed.
;AND
:Databases used in the query section can be used to evaluate if an entry exists, does not exist, or as a way to run subsequent lines on the whole database, or entries that match a particular value.
;THEN
:In the call section, new entries are added to databases, or existing entries are removed (i.e. NOT DB_MyDatabase(_VariableA, _VariableB).

=== Database Events ===
----
When used as an event, it becomes possible to create rules that run when an entry is added to a database.

Say we have a database we use to start a timer, called "DB_ExampleMod_Timers". Additionally, when the timer finishes, we'll add the timer name to a database as a sort of "On Complete" event.

<pre>
IF
DB_ExampleMod_Timers(_TimerName, _Time)
THEN
TimerLaunch(_TimerName, _Time);

IF
TimerFinished(_TimerName)
AND
DB_ExampleMod_Timers(_TimerName, _Time)
THEN
NOT DB_ExampleMod_Timers(_TimerName, _Time);
DB_ExampleMod_TimerFinished(_TimerName);
</pre>

Next we'll trigger the events by pulling a lever, with an additional rule for the "DB_ExampleMod_TimerFinished" database, with our specific timer name in mind:

<pre>
IF
CharacterUsedItem(_Player, ITEMGUID_Lever_RunTimer_4289a1de-0d4b-43b0-9c38-0d796dff1d43)
THEN
DB_ExampleMod_Timers("ExampleMod_LeverTimer", 1000);

IF
DB_ExampleMod_TimerFinished("ExampleMod_LeverTimer")
THEN
DebugBreak("ExampleMod_LeverTimer finished!");
NOT DB_ExampleMod_TimerFinished("ExampleMod_LeverTimer");
</pre>

Since database events only fire when an entry is ''added'', not removed, removing the entry right in the database rule works as expected.

=== Database Queries ===
----
Used as a query, databases are powerful ways to retrieve data, or create complex conditions.
==== Databases Queries for Conditions ====
Passing values into Databases is an easy way to create dynamic conditions:
<pre>
IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You're been a bad guy this year! Coal for you!");
ItemTemplateAddTo("QUEST_Coal_df215b50-e18f-4527-a2ac-e7eec6cba576", _Target, 1);

IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
NOT DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You've been good this year! Have a present!");
ItemTemplateAddTo("QUEST_Present_29f926ff-bfb3-4c0f-b4a4-e356d6b88cf0", _Target, 1);
</pre>
This example assumes that characters were already added to a database, and uses it to determine which item to give to a target, when Santa casts his skill.

==== Databases Queries for Data Retrieval ====
Now we'll use a database to iterate through a number of targets dynamically.
<pre>
IF
SkillCast(_Santa, "Shout_SpreadCheer", _)
AND
DB_Santa_NiceList(_Target)
THEN
ApplyStatus(_Target, "HOLIDAY_CHEER", -1.0);
PlayEffect(_Target, "RS3_FX_Santa_HolidayExplosion_01");
</pre>
Since the value of _Target is not specified in the database query, it acts as an out variable, calling subsequent lines on each entry added to DB_Santa_NiceList.

=== Database Gotchas ===
----
While databases are a powerful way to create complex scripting logic, there are a few crucial concepts to keep in mind:
* Unless you take steps to clear it out, database data persists in existing saves, even if you no longer support a particular database in a later version of your mod.
* Consider keeping the number of database columns at a manageable size. Databases can be cross-referenced with other databases if needed.
* Inherited types from GUIDSTRING (CHARACTERGUID, ITEMGUID, TRIGGERGUID) need to be declared once in a database, to properly set the type.

=== System Methods ===
----
A few system methods, hidden from auto-complete, exist to enhance database use:

;call [[Osiris/API/SysClear|SysClear]]((STRING)_Predicate, (INTEGER)_Arity)
* Predicate is the name of the database ("DB_MyDatabase"), while arity are the number of columns (DB_MyDatabase("Apples", 10) would be 2 arity).
* SysClear provides an ideal way of clearing older saves of old databases from previous version of your mod, or paving the way for a full reset of a database.
;query [[Osiris/API/SysCount|SysCount]]([in](STRING)_Predicate,[in](INTEGER)_Arity,[out](INTEGER)_Count)
* SysCount is a way to count the entries in a database. This is especially useful when creating conditions in reference to a database that is added to dynamically through gameplay (i.e. the number of players inside a trigger, the number of characters who had a particular status applied, and so on).

=== Cross-Database Referencing ===
----
Using a consistent entry across multiple databases allows you to utilize various databases to dynamically enhance your mod.

==== Adventure Mod Example ====
----

First, we'll create a few databases to store some settings.

INIT:
<pre>
//DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
DB_MyAdventureMod_Triggers("MyLevel_FrontDoor", (TRIGGERGUID)TRIGGERGUID_S_MyLevel_DoorEntry_b5ab6a49-b015-4908-8f49-7b152d6c5d30);
DB_MyAdventureMod_Triggers("MyLevel_HallwayAmbush", TRIGGERGUID_S_MyLevel_Ambush1_1d089d37-fc5e-4cc6-807e-51d0535dc0cc);
DB_MyAdventureMod_Triggers("MyLevel_GolemBoss", TRIGGERGUID_S_MyLevel_Boss1_0a009ed0-61f5-4670-9d26-1417ebf02922);

//DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_FrontDoor", "12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_HallwayAmbush","12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_GolemBoss","2052f790-d2d7-4cf7-95f0-4de478e98d28");

//DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonLeader_584db8ce-8dcf-4906-bc6f-e51eb057de08");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonMage1_61bf204e-ba2e-412f-ac86-e132a3930105");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonRanger1_f7bd3244-e1e7-4079-ac95-fef6145a236e");
</pre>

By using multiple databases together, we now only need to worry about the TRIGGERGUID in one database, while the others rely on the string name. This is easier to deal with in the long run.

Next, we'll look for when a player enters one of these triggers, and store when it first activates.

KB:
<pre>
IF
CharacterEnteredTrigger((CHARACTERGUID)_Character, (TRIGGERGUID)_TriggerID)
AND
DB_IsPlayer(_Character)
AND
DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
AND
NOT DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
THEN
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID);
</pre>

We'll then look for when a trigger is added to the "TriggerActivated" database, and create rules for changing the atmosphere and spawning enemies.

KB:
<pre>
IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
THEN
TriggerSetAtmosphere(_TriggerID, _Atmosphere);

IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
AND
GetRandomPositionInTrigger(_TriggerID, _X, _Y, _Z)
AND
CharacterCreateAtPosition(_X, _Y, _Z, _CharacterTemplate, 1, _Enemy)
THEN
DB_MyAdventureMod_SpawnedEnemies(_TriggerName, _Enemy);
</pre>

We now have a good basis for changing atmosphere, spawning enemies, and tracking which enemies were spawned. This could easily be extended to support sounds, dialogs that need to start, and more.

=== Updating Databases ===
----
When you use databases as a way to store settings, this information will persist on existing saves unless you purposefully remove it.

As an example, say you have a script like this:

'''MyMod_ExampleScript.txt'''

INIT:
<pre>
//DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_A_7e24b009-f2bc-47c0-a635-b776407833aa", 1);
</pre>

KB:
<pre>
IF
SkillCast(_Character, _Skill, _)
AND
DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
THEN
ItemTemplateAddTo(_ItemTemplate, _Character, (INTEGER)_Count, 1);
</pre>
Later, after releasing your mod, you decide that you want "Target_MyMod_DiamondTransmutation" to spawn a different diamond item template. To properly do this, in a way that won't spawn the previous template for an existing save, you need to delete the previous entry from the database.

==== Database Update Example ====
----
One way to implement internal mod "updates" for your databases is by storing a "mod version" in a database, and checking against this version when a save is loaded.

In a top-level goal (one that will run before all others), enter the following:

'''MyMod__MainScript.txt'''
INIT:
<pre>
//The current mod version.
DB_MyMod_Version("1.1.1");
</pre>

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
DebugBreak("[MyMod] Mod update detected. Updating databases.");

IF
SavegameLoaded(_,_,_,_)
AND
NOT DB_MyMod_Version("1.1.1")
THEN
MyMod_Update_UpdateDatabases();
SysClear("DB_MyMod_Version", 1); // Clear existing mod versions.
DB_MyMod_Version("1.1.1");
</pre>

"MyMod_Update_UpdateDatabases()" is a custom PROC we've created to handle updating databases. In the individual goals that we want to update databases for, creating new rules with the same PROC name will run our PROC when the top-level goal's PROC is triggered:

'''MyMod_ExampleScript.txt'''

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
SysClear("DB_MyMod_Skill_ItemCreation", 3);
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_B_Black_VW_94933c36-393e-4077-abec-95e04341fc92", 1);
</pre>

Now when the main script triggers the update, our second script will also run its own update, clearing out the previous database data and adding our new settings.

=== Updating Mods: Beyond Databases ===
----
Beyond changing databases, updating your mod can be a more extensive ordeal, as there's a variety of factors to keep in mind. More on that here: [[Modding:_Versioning|Modding: Versioning]].

== Further Information ==
More in-depth information on Osiris can be read on the following pages:
* [[Osiris Overview]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]
* [[Your First Story Script]]
* [[:Category:Osiris_APIs|Osiris APIs]]
* [[:Category:Osiris_Calls|Osiris Calls]]

[[Category:Osiris]]

Adding New Icons

2018-03-08T01:53:21Z

LaughingLeader: /* Preparing Your Icon Images */

Adding new icons requires a bit of preparation, but once the initial setup is complete, adding additional icons is quick and easy.

== Preparing Your Icon Images ==
# Save your individual icons in a size and format supported by the Texture Atlas Editor.
## Support sizes are 16x16, 32x32, 64x64, 128x128, 256x256.
## Supported formats are .png, .tga, and .dds.
# Place your images in a directory you'll have easy access to later.
# In the Resource Manager, create a package to add your texture atlas/icons to later (click the Add Package button, next to the Add and Remove Folder buttons, in the upper-left of the Resource Editor and name it however you like).
[[File:IconGuide_ResourceManager_01.png|thumb|Using the resource manager.]]

== Preparing the Texture Atlas file: ==
# Open the Texture Atlas Editor.
# Click File -> New.
# Select ''"Public/MyModName_GUID/GUI"'' as the location for your .lsx file (create the GUI folder if it doesn't exist).
# Create a name for your texture file (something like ModName_Icons.dds), and select an ideal location inside your mod's Assets folder (i.e. ''"Data/Public/MyModName_GUID/Assets/Textures"'').
# Select the size of the individual icons (for skills: 64x64) and the size of the image.
# Select the package you created previously, then click Save.
# The Texture Atlas Editor should create a blank texture (.dds) file at the path specified previously.

== Adding Atlas Entries: ==
# Go to Edit -> Add Entries, or simply click the 'Add Entries' button (next to the Remove Entries X button) in the upper-left of the Texture Atlas Editor.
# Navigate to where you placed your individual icon images (anywhere on your computer).
# Select your icon and add it (repeat as needed). All of the new icon entries should be automatically added to your texture file.
# Save.
[[File:IconGuide_AddingEntries_01.png|thumb|Multiple atlas entries may be added at once.]]
== Notes: ==
* This same process can be used to add custom portraits (recommended size: 80px wide by 100px tall).
* The icon names you use are the entry names in your texture atlas sheet. Within the texture atlas editor, you can right click on an entry and select "Copy name to clipboard" to make the process easier.
* Skills and statuses are assigned icons in the stats editor (there's a column specifically for the icon name). Root templates can also be assigned an icon.

== Optional: ==
Texture files can be manually packed and created. Possible software for doing that is:
* [https://www.codeandweb.com/texturepacker TexturePacker] for packaging the icons. Example settings: [https://i.imgur.com/64aGPPr.png TexturePacker Settings]
* [https://github.com/castano/nvidia-texture-tools/releases nvidia-texture-tools] to convert the packed texture to DDS format. This is a command-line tool.
* For Photoshop users, Nvidia has a plugin to work with the DDS format: [https://developer.nvidia.com/nvidia-texture-tools-adobe-photoshop NVIDIA Texture Tools for Adobe Photoshop]

Adding New Icons

2018-03-08T01:51:40Z

LaughingLeader: /* Preparing Your Icon Images */

Adding new icons requires a bit of preparation, but once the initial setup is complete, adding additional icons is quick and easy.

== Preparing Your Icon Images ==
1. Save your individual icons in a size and format supported by the Texture Atlas Editor.
:* Support sizes are 16x16, 32x32, 64x64, 128x128, 256x256.
:* Supported formats are .png, .tga, and .dds.
2. Place your images in a directory you'll have easy access to later.
3. In the Resource Manager, create a package to add your texture atlas/icons to later (click the Add Package button, next to the Add and Remove Folder buttons, in the upper-left of the Resource Editor and name it however you like).
[[File:IconGuide_ResourceManager_01.png|thumb|Using the resource manager.]]

== Preparing the Texture Atlas file: ==
# Open the Texture Atlas Editor.
# Click File -> New.
# Select ''"Public/MyModName_GUID/GUI"'' as the location for your .lsx file (create the GUI folder if it doesn't exist).
# Create a name for your texture file (something like ModName_Icons.dds), and select an ideal location inside your mod's Assets folder (i.e. ''"Data/Public/MyModName_GUID/Assets/Textures"'').
# Select the size of the individual icons (for skills: 64x64) and the size of the image.
# Select the package you created previously, then click Save.
# The Texture Atlas Editor should create a blank texture (.dds) file at the path specified previously.

== Adding Atlas Entries: ==
# Go to Edit -> Add Entries, or simply click the 'Add Entries' button (next to the Remove Entries X button) in the upper-left of the Texture Atlas Editor.
# Navigate to where you placed your individual icon images (anywhere on your computer).
# Select your icon and add it (repeat as needed). All of the new icon entries should be automatically added to your texture file.
# Save.
[[File:IconGuide_AddingEntries_01.png|thumb|Multiple atlas entries may be added at once.]]
== Notes: ==
* This same process can be used to add custom portraits (recommended size: 80px wide by 100px tall).
* The icon names you use are the entry names in your texture atlas sheet. Within the texture atlas editor, you can right click on an entry and select "Copy name to clipboard" to make the process easier.
* Skills and statuses are assigned icons in the stats editor (there's a column specifically for the icon name). Root templates can also be assigned an icon.

== Optional: ==
Texture files can be manually packed and created. Possible software for doing that is:
* [https://www.codeandweb.com/texturepacker TexturePacker] for packaging the icons. Example settings: [https://i.imgur.com/64aGPPr.png TexturePacker Settings]
* [https://github.com/castano/nvidia-texture-tools/releases nvidia-texture-tools] to convert the packed texture to DDS format. This is a command-line tool.
* For Photoshop users, Nvidia has a plugin to work with the DDS format: [https://developer.nvidia.com/nvidia-texture-tools-adobe-photoshop NVIDIA Texture Tools for Adobe Photoshop]

Adding New Icons

2018-03-08T01:49:03Z

LaughingLeader: /* Preparing the Texture Atlas file: */

Adding new icons requires a bit of preparation, but once the initial setup is complete, adding additional icons is quick and easy.

== Preparing Your Icon Images ==
# Save your individual icons in a size and format supported by the Texture Atlas Editor.
::* Support sizes are 16x16, 32x32, 64x64, 128x128, 256x256.
::* Supported formats are .png, .tga, and .dds.
# Place your images in a directory you'll have easy access to later.
# In the Resource Manager, create a package to add your texture atlas/icons to later (click the Add Package button, next to the Add and Remove Folder buttons, in the upper-left of the Resource Editor and name it however you like).
[[File:IconGuide_ResourceManager_01.png|thumb|Using the resource manager.]]

== Preparing the Texture Atlas file: ==
# Open the Texture Atlas Editor.
# Click File -> New.
# Select ''"Public/MyModName_GUID/GUI"'' as the location for your .lsx file (create the GUI folder if it doesn't exist).
# Create a name for your texture file (something like ModName_Icons.dds), and select an ideal location inside your mod's Assets folder (i.e. ''"Data/Public/MyModName_GUID/Assets/Textures"'').
# Select the size of the individual icons (for skills: 64x64) and the size of the image.
# Select the package you created previously, then click Save.
# The Texture Atlas Editor should create a blank texture (.dds) file at the path specified previously.

== Adding Atlas Entries: ==
# Go to Edit -> Add Entries, or simply click the 'Add Entries' button (next to the Remove Entries X button) in the upper-left of the Texture Atlas Editor.
# Navigate to where you placed your individual icon images (anywhere on your computer).
# Select your icon and add it (repeat as needed). All of the new icon entries should be automatically added to your texture file.
# Save.
[[File:IconGuide_AddingEntries_01.png|thumb|Multiple atlas entries may be added at once.]]
== Notes: ==
* This same process can be used to add custom portraits (recommended size: 80px wide by 100px tall).
* The icon names you use are the entry names in your texture atlas sheet. Within the texture atlas editor, you can right click on an entry and select "Copy name to clipboard" to make the process easier.
* Skills and statuses are assigned icons in the stats editor (there's a column specifically for the icon name). Root templates can also be assigned an icon.

== Optional: ==
Texture files can be manually packed and created. Possible software for doing that is:
* [https://www.codeandweb.com/texturepacker TexturePacker] for packaging the icons. Example settings: [https://i.imgur.com/64aGPPr.png TexturePacker Settings]
* [https://github.com/castano/nvidia-texture-tools/releases nvidia-texture-tools] to convert the packed texture to DDS format. This is a command-line tool.
* For Photoshop users, Nvidia has a plugin to work with the DDS format: [https://developer.nvidia.com/nvidia-texture-tools-adobe-photoshop NVIDIA Texture Tools for Adobe Photoshop]

Your First Story Script

2018-02-24T18:18:18Z

LaughingLeader: /* Recommended Reading */ Added a link to the story editor wiki page.

Note: this tutorial assumes you have already created a mod project. More on that here: [[Project browser]]. For the purposes of this tutorial, we will be using a basic Addon project that inherits from Story and targets Story.

== Overview ==
Story scripts are a way to implement global logic with your mod, in a way that is compatible with other mods. Before we get started, some basic tips to keep in mind:

=== Starting Tips ===
----
* When opening the story editor in a new project, always generate definitions (File -> Generate Definitions) and exit/re-open the story editor. This will generate the files necessary for auto-complete and syntax highlighting.

* Prefix your goals (a.k.a. your script files), databases, queries, and procs in a way that will make then unique and least likely to conflict with other mods. For example, if our mod is called "Better Cupcakes", and our username is "SuperChef", we'd prefix our mod entries with SCBC, or SC_BetterCupcakes, or some combination of the two.
** This idea should also be used for entries in the stats editor, as multiple entries with the same name will conflict.

== Recommended Reading ==
* [[Story_editor|Story Editor]]
* [[Osiris Overview]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]
* [[Osiris_Tips_and_Examples|Osiris Tips and Examples]]
* [[:Category:Osiris_APIs|Osiris APIs]]
* [[:Category:Osiris_Calls|Osiris Calls]]

== Implementing a Basic Story Script ==
=== Getting Started ===
----
# Open the [[Story editor]] by clicking the icon that looks like a book ([[File:StoryEditor_Icon.png|24px]]) under the "Editors" section, at the top-right of the Divinity Engine 2 editor.
# Inside the story editor, Click "File -> Generate Definitions and Build" on the top left.
#* This is an important step in generating the appropriate files. Any time you create new definitions (databases, PROCs, or queries), you need to generate definitions.
#* Building is as equally important, as your changes won't compile until you build.
#* Reloading the story is necessary to see your changes in-game. You can either do this from the story editor ("File -> Reload Story"), or from the main editor with "File -> Reload Level and Story".
# Close the story editor and open it again to essentially reload the syntax highlighting and auto-complete features.

=== Creating a Parent Goal ===
----
For organizational purposes, creating a parent story goal is recommended.
# Inside the story editor, at the goal list on the left, right click and select "Add New Item".
[[File:FirstStoryScript_AddNewItem.png|thumb]]
# Name this script something unique to your mod in a prefix format (Username_ModName), such as "SuperChef_BetterCupcakes". This has the best chance of not potentially conflicting with any other mod.
# After clicking OK, your script will automatically open. Hit CTRL+S to automatically save this script. Scripts with unsaved changes display and asterisk (*) next to their name.

==== Tip: Story Script Naming ====
----
Goals in the story are ran in alphabetical order. This is important to keep in mind if you use a particular story goal as a sort of "top-level" script that has methods and databases your other goals reference to.

With proper naming, you can control the order your scripts are run. For example, naming your top-level goal "WT_FS__Main", and your second goal "WT_FS_Skills" ensures "WT_FS__Main" will always run before "WT_FS_Skills".
[[File:FirstStoryScript_ScriptOrder.png|thumb|WT_FS__Main will always run before WT_FS_Skills.]]

=== Completing the Parent Goal ===
----
Parent goals need to "complete" before their sub-goals will run. This is done by calling "GoalCompleted;" within the parent script. We have a few options for how to go about this:

==== Completion Events ====
----
The following events are recommended to use for completing your parent goals:
; [[Osiris/API/GameStarted|GameStarted]]
: Thrown when a level has been loaded and is ready at both the server and client side. This will ensure all the base game scripts have already initialized.
; [[Osiris/API/RegionStarted|RegionStarted]]
: Thrown when the level has been loaded and is ready at the server side, but not yet at the client side.

Both of these events can be used with specific level names, as a way to make your goal only complete once that level is loaded (as a way to create level-specific logic).

==== Example Goal Completion ====
----
Inside the KB section of your goal, enter the following:
<pre>
IF
GameStarted(_Level, _EditorMode)
AND
StringConcatenate("[WT_FS] WikiTutorial_FirstStory has initialized. Level[", _Level, _Str1)
AND
StringConcatenate(_Str1, "] EditorMode(", _Str2)
AND
IntegertoString(_EditorMode, _ModeStr)
AND
StringConcatenate(_Str2, _ModeStr, _Str3)
AND
StringConcatenate(_Str3, ")", _Message)
THEN
DebugBreak(_Message);
GoalCompleted;
</pre>
# Save, then select "File -> Generate Definitions, Build and Reload".
# Minimize the story editor, then clear the message log by clicking "Clear".
# Load a level in the main editor. Inside the message log, you should see the message we added with DebugBreak.
[[File:FirstStoryScript_ParentGoalComplete.png|thumb|The debug message appears in the message log once the game is started.]]

===== Standard Goal Completion =====
----
For a regular approach, without any debug messages or string combining, use this:
<pre>
IF
GameStarted(_,_)
THEN
GoalCompleted;
</pre>
In this code block, the variables for _Level and _EditorMode are underscores, which means we're ignoring their values.

=== Adding a Sub-Goal ===
----
With the parent goal completing properly, sub-goals that are parented to the previous goal will now run.

==== Creating a Sub-Goal ====
----
Let's create a basic script that will display some text when a skill is cast.

# Double click on your parent goal to have it selected.
#* Currently, there's a bug where not having your parent goal open may cause a sub-item created to not properly parent under the right goal. If this happens, simply click and drag the new goal to your parent goal, and it should move underneath it.
# Click "Add New Sub Item...", then name it something appropriate, like "WikiTutorial_FirstStory_Skills".
# Save the new script (CTRL+S).

==== Creating a Rule ====
----
In the KB section of our new script, add the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Good job!");
CharacterResetCooldowns(_Character);
</pre>

This rule will run when the player casts "Encourage", displaying some text, and resetting their cooldowns. The Encourage skill is added automatically to the player if they lack it.

# Save, then "Generate Definitions and Build".
# In the main editor, select "File -> Reload Level and story".
# Hit the "Switch Game/Editor" button to get in-game. [[File:FirstStoryScript_GameEditorButton.png|thumb|Click this button to switch between game and editor mode.]]
# In whatever level you're working in, your provided dummy character should spawn and be given the Encourage skill.
# Cast the skill to test that your script is working properly.
[[File:FirstStoryScript_SkillCast_Result.png|thumb|Our script in action.]]

===== Notes =====
----
'''HTML Font Formatting'''
* HTML font formatting can be used in DisplayText, CharacterStatusText, and in various text entries (skill descriptions, status names/descriptions, book text, and more).

'''SkillCast '''
* This event runs when the skill's animation reaches the CastTextEvent value specified by the skill stats (which is "cast" in most cases).
* The textkey "cast" is a common textkey used in skill cast animations.
* To view the textkeys present in an animation, open it within the [[Content_browser|Resource Manager]].
* Example: Open the resource manager and search for the "Humans_Hero_Female_ABC_Skill_Cast_Aoe_Air_01_Cast" animation under the Shared folder. Double click on the resource to open the animation preview to see the different textkeys. [[File:FirstStoryScript_SkillCast_Textkey.png|thumb|The cast textkey.]]

'''DB_IsPlayer'''
* This is a base game database that is populated with all the current player characters when the game is started.
* By passing in the _Character value from the event parameters to DB_IsPlayer, we're matching the character against the database of player characters, to have the following code only run if the caster is a player-controlled character.
* Using DB_IsPlayer as an event makes the subsequent code run when a character is added to the DB_IsPlayer database.

== Taking the Script Further ==
Now that we have a basic script heirarchy working, let's take the script further.

=== Randomization ===
----
We can add randomization to the displayed text in our previous script to make the result more interesting.

We'll do this by creating a custom procedure.

;Procedure Tips:
: Procedures are declared with a "PROC" at the top of the block, and follow the same flow as a rule.
: Parameters for a procedure can be customized. You must declare their type.
: Procedures are called within the "call" section of a rule or a custom query.

Add this to the INIT section:
<pre>
//DB_WikiTutorial_FirstStory_RandomText(_Ran, _Text, _FontColor, _FontSize)
DB_WikiTutorial_FirstStory_Skills_RandomText(0, "Woo!", "00CED1", "23");
DB_WikiTutorial_FirstStory_Skills_RandomText(1, "Good job!", "00FF00", "30");
DB_WikiTutorial_FirstStory_Skills_RandomText(2, "I did it!", "DEB887", "20");
DB_WikiTutorial_FirstStory_Skills_RandomText(3, "I'm da best!", "A52A2A", "26");
</pre>

Change the code in the KB section to the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

PROC
WikiTutorial_FirstStory_Skills_DisplayRandomMessage((CHARACTERGUID)_Character)
AND
Random(4, _Ran)
AND
DB_WikiTutorial_FirstStory_Skills_RandomText(_Ran, _Text, _FontColor, _FontSize)
AND
StringConcatenate("", _Str4)
AND
StringConcatenate(_Str4, _Text, _Str5)
AND
StringConcatenate(_Str5, "", _Message)
AND
IntegertoString(_Ran, _RanStr)
AND
StringConcatenate("[WT_FS] Rolled a ", _RanStr, _DebugMessage)
THEN
DisplayText(_Character, _Message);
DebugBreak(_DebugMessage);

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload".
# Switch back to the main editor and hit the play button to get in-game.
# Cast the Encourage skill a few times in game mode to ensure the script is working properly. You should see the different messages, font colors, and font sizes.

===== Notes =====
----
'''Procedures'''
* WikiTutorial_FirstStory_Skills_DisplayRandomMessage is a custom subroutine call, called a PROC. By splitting our message logic off into a separate procedure, this ensures the calls for this rule are ran regardless of the result of our message logic (so CharacterResetCooldowns will always run if a player casts this skill). This also allows us to use this procedure elsewhere, and possible extend it further.

'''Databases'''
* We create our "RandomText" settings in the INIT section by using a database we create, called "DB_WikiTutorial_FirstStory_Skills_RandomText". Databases are a powerful tool for making your scripting logic extensible.

'''[[Osiris/API/Random|Random]]'''
* [[Osiris/API/Random|Random]] returns a random integer value between 0 and (_Modulo - 1). Since our DB_WikiTutorial_FirstStory_Skills_RandomText has 4 entries, we want our random number to be between 0 and 3, so we use 4 as our _Modulo.

=== Using Queries ===
----
Mastering queries is essential for creating complex conditions for your rules. "OR" logic is done within Osiris with multiple rules, subscribing to the same events, that look for different conditions through the use of queries.

Let's add to our skills script. Add this to the KB section, so your SkillCast rules look like this:

<pre>
IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
NOT DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Win... Please! Ahhhh!");
ApplyStatus(_Character, "FEAR", 1.0, 1);
</pre>

By simpling adding a NOT before our database check, our second rule will now run on any character (who's not a player) that casts Encourage, and apply fear. You can test this by loading an inherited level that contains some human enemies, or adding human enemies yourself to your test level.

=== Creating a Custom Query ===
----
Taking this idea further, we'll create a custom query.

Custom queries are defined with the keyword "QRY" at the top of a block, and follow the same flow as a rule.

Add the following code to your KB section:

<pre>
QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "HUMAN", 1)
THEN
DB_NOOP(1);

QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "DWARF", 1)
THEN
DB_NOOP(1);
</pre>

By adding two query blocks with the same name, we're effectively adding an "OR" condition. This query will evaluate as true if the character is tagged as either a human or a dwarf.

"DB_NOOP(1);" is a dummy database fact. Since rules must have a call, DB_NOOP is used to have a rule succeed without using any actual calls.

==== Implementing the Custom Query ====
----

Below our query code, in the KB section, add the following:
<pre>
IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Perception_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Perception_Potion");

IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
NOT WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Constitution_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Constitution_Potion");

IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload". Since we added a query and another database, we must generate the definitions again.
# Go in-game and test out the changes by casting Encourage on an human or dwarf (it will work on yourself as well).

===== Notes =====
----
'''NOT'''
* By adding two rules for the same event, and checking for the opposite of our query, we're effectively adding an OR condition to this event.

'''CharacterConsume/CharacterUnconsume'''
* Since CharacterConsume returns a value, it's a query instead of a call. We store the out value from the query (_Handle) in a database to later unconsume the potion effect when ENCOURAGED ends.

'''Removing Database Entries'''
* When unconsuming the potion handle, notice we also remove that entry from the database by calling "NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);" as a call. Using NOT before a database entry (in the call section) removes that entry.
* By using DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion) in the query section, the _Handle and _Potion value is returned with all entries that match the value we pass in (_Character), effectively unconsuming every potion handle we added for that character to the database.

=== Using a Query as a Subroutine ===
----
While queries can be used as conditions, they can also be used to call specific procedures/calls before the main rule reaches that section of the flow.

Let's try a simple example that runs when we unconsume a potion. Change our status removed event code to this:

<pre>
IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_ZombieCheck(_Character)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "UNDEAD", 1)
AND
CharacterGetDisplayName(_Character, _, _Name)
AND
StringConcatenate("[WT_FS] ", _Name, _Str1)
AND
StringConcatenate(_Str1, " is a zombie! Ahh! Burn it!", _Message)
THEN
ApplyStatus(_Character, "BURNING", 1.0);
DebugBreak(_Message);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
THEN
DB_NOOP(1);
</pre>

Which this, our query will apply burning if the character is tagged as UNDEAD. Note how we added a second QRY rule that always evaluates as true - this is to keep the rest of our rule in the CharacterStatusRemoved event running, undead or not.

Practically speaking, using queries as subroutines is ideal when:
* You need specific calls/procedures to run before iterating through a database. Calling your query before retrieving variables from a database ensures that those calls will only run once.
* You need to debug a rule to ensure it reaches a certain section of the conditions. If you're not sure if a specific condition is passing, adding a query with a DebugBreak message right before/after it is a good way to debug that situation.

== Bonus Tips ==

* In the story editor, select "File -> Open Story Header" for a list of all available events, queries, and calls. Heavily reference this file when you find yourself unsure if a specifc method exists, as not all methods appear in the auto-complete.

* If you use databases to store global mod settings, and your mod users have played with that mod, changing that information post-mod install will not automatically remove that data from existing saves - you need to handle this update internally within your mod.
** More on implementing an update system here: [[Osiris_Tips#Updating_Databases|Manual Mod Updates]].

* By using custom procedures and queries, you can reduce your rule redundancy and extend desired calls/conditions to multiple rules.

* To make your life with Osiris easier, wrap your rule blocks in regions with the following:
<pre>
//REGION MY_REGION_NAME

//END_REGION
</pre>
* In the story editor, right click inside your script sections (INIT, KB, or EXIT) and "Expand All" or "Collapse All" to expand/collapse all regions, respectively.

* Procedures can be called from the EXIT and INIT section of scripts.

* Use the INIT section of your scripts as a way to store commented references to your databases. As an example from our previous script, placing this inside your INIT section is a good way to remember such a database exists (since we don't initialize it in the INIT section):
<pre>
//DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
</pre>
Then, when you wish to use this database, you have a quick way to copy/paste that code into other sections of your script.

[[Category:Osiris]]

Your First Story Script

2018-02-05T17:43:11Z

LaughingLeader: /* Notes */

Note: this tutorial assumes you have already created a mod project. More on that here: [[Project browser]]. For the purposes of this tutorial, we will be using a basic Addon project that inherits from Story and targets Story.

== Overview ==
Story scripts are a way to implement global logic with your mod, in a way that is compatible with other mods. Before we get started, some basic tips to keep in mind:

=== Starting Tips ===
----
* When opening the story editor in a new project, always generate definitions (File -> Generate Definitions) and exit/re-open the story editor. This will generate the files necessary for auto-complete and syntax highlighting.

* Prefix your goals (a.k.a. your script files), databases, queries, and procs in a way that will make then unique and least likely to conflict with other mods. For example, if our mod is called "Better Cupcakes", and our username is "SuperChef", we'd prefix our mod entries with SCBC, or SC_BetterCupcakes, or some combination of the two.
** This idea should also be used for entries in the stats editor, as multiple entries with the same name will conflict.

== Recommended Reading ==
* [[Osiris Overview]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]
* [[Osiris_Tips_and_Examples|Osiris Tips and Examples]]
* [[:Category:Osiris_APIs|Osiris APIs]]
* [[:Category:Osiris_Calls|Osiris Calls]]

== Implementing a Basic Story Script ==
=== Getting Started ===
----
# Open the [[Story editor]] by clicking the icon that looks like a book ([[File:StoryEditor_Icon.png|24px]]) under the "Editors" section, at the top-right of the Divinity Engine 2 editor.
# Inside the story editor, Click "File -> Generate Definitions and Build" on the top left.
#* This is an important step in generating the appropriate files. Any time you create new definitions (databases, PROCs, or queries), you need to generate definitions.
#* Building is as equally important, as your changes won't compile until you build.
#* Reloading the story is necessary to see your changes in-game. You can either do this from the story editor ("File -> Reload Story"), or from the main editor with "File -> Reload Level and Story".
# Close the story editor and open it again to essentially reload the syntax highlighting and auto-complete features.

=== Creating a Parent Goal ===
----
For organizational purposes, creating a parent story goal is recommended.
# Inside the story editor, at the goal list on the left, right click and select "Add New Item".
[[File:FirstStoryScript_AddNewItem.png|thumb]]
# Name this script something unique to your mod in a prefix format (Username_ModName), such as "SuperChef_BetterCupcakes". This has the best chance of not potentially conflicting with any other mod.
# After clicking OK, your script will automatically open. Hit CTRL+S to automatically save this script. Scripts with unsaved changes display and asterisk (*) next to their name.

==== Tip: Story Script Naming ====
----
Goals in the story are ran in alphabetical order. This is important to keep in mind if you use a particular story goal as a sort of "top-level" script that has methods and databases your other goals reference to.

With proper naming, you can control the order your scripts are run. For example, naming your top-level goal "WT_FS__Main", and your second goal "WT_FS_Skills" ensures "WT_FS__Main" will always run before "WT_FS_Skills".
[[File:FirstStoryScript_ScriptOrder.png|thumb|WT_FS__Main will always run before WT_FS_Skills.]]

=== Completing the Parent Goal ===
----
Parent goals need to "complete" before their sub-goals will run. This is done by calling "GoalCompleted;" within the parent script. We have a few options for how to go about this:

==== Completion Events ====
----
The following events are recommended to use for completing your parent goals:
; [[Osiris/API/GameStarted|GameStarted]]
: Thrown when a level has been loaded and is ready at both the server and client side. This will ensure all the base game scripts have already initialized.
; [[Osiris/API/RegionStarted|RegionStarted]]
: Thrown when the level has been loaded and is ready at the server side, but not yet at the client side.

Both of these events can be used with specific level names, as a way to make your goal only complete once that level is loaded (as a way to create level-specific logic).

==== Example Goal Completion ====
----
Inside the KB section of your goal, enter the following:
<pre>
IF
GameStarted(_Level, _EditorMode)
AND
StringConcatenate("[WT_FS] WikiTutorial_FirstStory has initialized. Level[", _Level, _Str1)
AND
StringConcatenate(_Str1, "] EditorMode(", _Str2)
AND
IntegertoString(_EditorMode, _ModeStr)
AND
StringConcatenate(_Str2, _ModeStr, _Str3)
AND
StringConcatenate(_Str3, ")", _Message)
THEN
DebugBreak(_Message);
GoalCompleted;
</pre>
# Save, then select "File -> Generate Definitions, Build and Reload".
# Minimize the story editor, then clear the message log by clicking "Clear".
# Load a level in the main editor. Inside the message log, you should see the message we added with DebugBreak.
[[File:FirstStoryScript_ParentGoalComplete.png|thumb|The debug message appears in the message log once the game is started.]]

===== Standard Goal Completion =====
----
For a regular approach, without any debug messages or string combining, use this:
<pre>
IF
GameStarted(_,_)
THEN
GoalCompleted;
</pre>
In this code block, the variables for _Level and _EditorMode are underscores, which means we're ignoring their values.

=== Adding a Sub-Goal ===
----
With the parent goal completing properly, sub-goals that are parented to the previous goal will now run.

==== Creating a Sub-Goal ====
----
Let's create a basic script that will display some text when a skill is cast.

# Double click on your parent goal to have it selected.
#* Currently, there's a bug where not having your parent goal open may cause a sub-item created to not properly parent under the right goal. If this happens, simply click and drag the new goal to your parent goal, and it should move underneath it.
# Click "Add New Sub Item...", then name it something appropriate, like "WikiTutorial_FirstStory_Skills".
# Save the new script (CTRL+S).

==== Creating a Rule ====
----
In the KB section of our new script, add the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Good job!");
CharacterResetCooldowns(_Character);
</pre>

This rule will run when the player casts "Encourage", displaying some text, and resetting their cooldowns. The Encourage skill is added automatically to the player if they lack it.

# Save, then "Generate Definitions and Build".
# In the main editor, select "File -> Reload Level and story".
# Hit the "Switch Game/Editor" button to get in-game. [[File:FirstStoryScript_GameEditorButton.png|thumb|Click this button to switch between game and editor mode.]]
# In whatever level you're working in, your provided dummy character should spawn and be given the Encourage skill.
# Cast the skill to test that your script is working properly.
[[File:FirstStoryScript_SkillCast_Result.png|thumb|Our script in action.]]

===== Notes =====
----
'''HTML Font Formatting'''
* HTML font formatting can be used in DisplayText, CharacterStatusText, and in various text entries (skill descriptions, status names/descriptions, book text, and more).

'''SkillCast '''
* This event runs when the skill's animation reaches the CastTextEvent value specified by the skill stats (which is "cast" in most cases).
* The textkey "cast" is a common textkey used in skill cast animations.
* To view the textkeys present in an animation, open it within the [[Content_browser|Resource Manager]].
* Example: Open the resource manager and search for the "Humans_Hero_Female_ABC_Skill_Cast_Aoe_Air_01_Cast" animation under the Shared folder. Double click on the resource to open the animation preview to see the different textkeys. [[File:FirstStoryScript_SkillCast_Textkey.png|thumb|The cast textkey.]]

'''DB_IsPlayer'''
* This is a base game database that is populated with all the current player characters when the game is started.
* By passing in the _Character value from the event parameters to DB_IsPlayer, we're matching the character against the database of player characters, to have the following code only run if the caster is a player-controlled character.
* Using DB_IsPlayer as an event makes the subsequent code run when a character is added to the DB_IsPlayer database.

== Taking the Script Further ==
Now that we have a basic script heirarchy working, let's take the script further.

=== Randomization ===
----
We can add randomization to the displayed text in our previous script to make the result more interesting.

We'll do this by creating a custom procedure.

;Procedure Tips:
: Procedures are declared with a "PROC" at the top of the block, and follow the same flow as a rule.
: Parameters for a procedure can be customized. You must declare their type.
: Procedures are called within the "call" section of a rule or a custom query.

Add this to the INIT section:
<pre>
//DB_WikiTutorial_FirstStory_RandomText(_Ran, _Text, _FontColor, _FontSize)
DB_WikiTutorial_FirstStory_Skills_RandomText(0, "Woo!", "00CED1", "23");
DB_WikiTutorial_FirstStory_Skills_RandomText(1, "Good job!", "00FF00", "30");
DB_WikiTutorial_FirstStory_Skills_RandomText(2, "I did it!", "DEB887", "20");
DB_WikiTutorial_FirstStory_Skills_RandomText(3, "I'm da best!", "A52A2A", "26");
</pre>

Change the code in the KB section to the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

PROC
WikiTutorial_FirstStory_Skills_DisplayRandomMessage((CHARACTERGUID)_Character)
AND
Random(4, _Ran)
AND
DB_WikiTutorial_FirstStory_Skills_RandomText(_Ran, _Text, _FontColor, _FontSize)
AND
StringConcatenate("", _Str4)
AND
StringConcatenate(_Str4, _Text, _Str5)
AND
StringConcatenate(_Str5, "", _Message)
AND
IntegertoString(_Ran, _RanStr)
AND
StringConcatenate("[WT_FS] Rolled a ", _RanStr, _DebugMessage)
THEN
DisplayText(_Character, _Message);
DebugBreak(_DebugMessage);

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload".
# Switch back to the main editor and hit the play button to get in-game.
# Cast the Encourage skill a few times in game mode to ensure the script is working properly. You should see the different messages, font colors, and font sizes.

===== Notes =====
----
'''Procedures'''
* WikiTutorial_FirstStory_Skills_DisplayRandomMessage is a custom subroutine call, called a PROC. By splitting our message logic off into a separate procedure, this ensures the calls for this rule are ran regardless of the result of our message logic (so CharacterResetCooldowns will always run if a player casts this skill). This also allows us to use this procedure elsewhere, and possible extend it further.

'''Databases'''
* We create our "RandomText" settings in the INIT section by using a database we create, called "DB_WikiTutorial_FirstStory_Skills_RandomText". Databases are a powerful tool for making your scripting logic extensible.

'''[[Osiris/API/Random|Random]]'''
* [[Osiris/API/Random|Random]] returns a random integer value between 0 and (_Modulo - 1). Since our DB_WikiTutorial_FirstStory_Skills_RandomText has 4 entries, we want our random number to be between 0 and 3, so we use 4 as our _Modulo.

=== Using Queries ===
----
Mastering queries is essential for creating complex conditions for your rules. "OR" logic is done within Osiris with multiple rules, subscribing to the same events, that look for different conditions through the use of queries.

Let's add to our skills script. Add this to the KB section, so your SkillCast rules look like this:

<pre>
IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
NOT DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Win... Please! Ahhhh!");
ApplyStatus(_Character, "FEAR", 1.0, 1);
</pre>

By simpling adding a NOT before our database check, our second rule will now run on any character (who's not a player) that casts Encourage, and apply fear. You can test this by loading an inherited level that contains some human enemies, or adding human enemies yourself to your test level.

=== Creating a Custom Query ===
----
Taking this idea further, we'll create a custom query.

Custom queries are defined with the keyword "QRY" at the top of a block, and follow the same flow as a rule.

Add the following code to your KB section:

<pre>
QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "HUMAN", 1)
THEN
DB_NOOP(1);

QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "DWARF", 1)
THEN
DB_NOOP(1);
</pre>

By adding two query blocks with the same name, we're effectively adding an "OR" condition. This query will evaluate as true if the character is tagged as either a human or a dwarf.

"DB_NOOP(1);" is a dummy database fact. Since rules must have a call, DB_NOOP is used to have a rule succeed without using any actual calls.

==== Implementing the Custom Query ====
----

Below our query code, in the KB section, add the following:
<pre>
IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Perception_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Perception_Potion");

IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
NOT WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Constitution_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Constitution_Potion");

IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload". Since we added a query and another database, we must generate the definitions again.
# Go in-game and test out the changes by casting Encourage on an human or dwarf (it will work on yourself as well).

===== Notes =====
----
'''NOT'''
* By adding two rules for the same event, and checking for the opposite of our query, we're effectively adding an OR condition to this event.

'''CharacterConsume/CharacterUnconsume'''
* Since CharacterConsume returns a value, it's a query instead of a call. We store the out value from the query (_Handle) in a database to later unconsume the potion effect when ENCOURAGED ends.

'''Removing Database Entries'''
* When unconsuming the potion handle, notice we also remove that entry from the database by calling "NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);" as a call. Using NOT before a database entry (in the call section) removes that entry.
* By using DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion) in the query section, the _Handle and _Potion value is returned with all entries that match the value we pass in (_Character), effectively unconsuming every potion handle we added for that character to the database.

=== Using a Query as a Subroutine ===
----
While queries can be used as conditions, they can also be used to call specific procedures/calls before the main rule reaches that section of the flow.

Let's try a simple example that runs when we unconsume a potion. Change our status removed event code to this:

<pre>
IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_ZombieCheck(_Character)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "UNDEAD", 1)
AND
CharacterGetDisplayName(_Character, _, _Name)
AND
StringConcatenate("[WT_FS] ", _Name, _Str1)
AND
StringConcatenate(_Str1, " is a zombie! Ahh! Burn it!", _Message)
THEN
ApplyStatus(_Character, "BURNING", 1.0);
DebugBreak(_Message);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
THEN
DB_NOOP(1);
</pre>

Which this, our query will apply burning if the character is tagged as UNDEAD. Note how we added a second QRY rule that always evaluates as true - this is to keep the rest of our rule in the CharacterStatusRemoved event running, undead or not.

Practically speaking, using queries as subroutines is ideal when:
* You need specific calls/procedures to run before iterating through a database. Calling your query before retrieving variables from a database ensures that those calls will only run once.
* You need to debug a rule to ensure it reaches a certain section of the conditions. If you're not sure if a specific condition is passing, adding a query with a DebugBreak message right before/after it is a good way to debug that situation.

== Bonus Tips ==

* In the story editor, select "File -> Open Story Header" for a list of all available events, queries, and calls. Heavily reference this file when you find yourself unsure if a specifc method exists, as not all methods appear in the auto-complete.

* If you use databases to store global mod settings, and your mod users have played with that mod, changing that information post-mod install will not automatically remove that data from existing saves - you need to handle this update internally within your mod.
** More on implementing an update system here: [[Osiris_Tips#Updating_Databases|Manual Mod Updates]].

* By using custom procedures and queries, you can reduce your rule redundancy and extend desired calls/conditions to multiple rules.

* To make your life with Osiris easier, wrap your rule blocks in regions with the following:
<pre>
//REGION MY_REGION_NAME

//END_REGION
</pre>
* In the story editor, right click inside your script sections (INIT, KB, or EXIT) and "Expand All" or "Collapse All" to expand/collapse all regions, respectively.

* Procedures can be called from the EXIT and INIT section of scripts.

* Use the INIT section of your scripts as a way to store commented references to your databases. As an example from our previous script, placing this inside your INIT section is a good way to remember such a database exists (since we don't initialize it in the INIT section):
<pre>
//DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
</pre>
Then, when you wish to use this database, you have a quick way to copy/paste that code into other sections of your script.

[[Category:Osiris]]

Osiris Tips and Examples

2018-01-27T18:35:55Z

LaughingLeader: /* Databases Queries for Data Retrieval */

The following is a collection of practical examples and tips that will aid in your journey to learn how to power your mod through story script usage.

== Rule Flow ==
Story scripts run on "rules". Every frame, Osiris will evaluate the rules for every running story goal.

The flow of every rule is:
<pre>
IF
Event
AND
Query
THEN
Call();
</pre>

Queries between the event and the call section of a rule are optional. You can simply go from event to call if you desire:
<pre>
IF
Event
THEN
Call();
</pre>

Queries are both gatekeepers to the call section, and a way to retrieve information.

== Databases ==
Databases can be used to store specific data (such as characters entering a trigger), or as a way to story settings used in your rules.

=== Database Use Within Rules ===
----
Databases may be used in all three rule sections:
;IF
:Databases used in the event section will run when a new entry is added. It will never run when an entry is removed.
;AND
:Databases used in the query section can be used to evaluate if an entry exists, does not exist, or as a way to run subsequent lines on the whole database, or entries that match a particular value.
;THEN
:In the call section, new entries are added to databases, or existing entries are removed (i.e. NOT DB_MyDatabase(_VariableA, _VariableB).

=== Database Queries ===
----
Used as a query, databases are powerful ways to retrieve data, or create complex conditions.
==== Databases Queries for Conditions ====
Passing values into Databases is an easy way to create dynamic conditions:
<pre>
IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You're been a bad guy this year! Coal for you!");
ItemTemplateAddTo("QUEST_Coal_df215b50-e18f-4527-a2ac-e7eec6cba576", _Target, 1);

IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
NOT DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You've been good this year! Have a present!");
ItemTemplateAddTo("QUEST_Present_29f926ff-bfb3-4c0f-b4a4-e356d6b88cf0", _Target, 1);
</pre>
This example assumes that characters were already added to a database, and uses it to determine which item to give to a target, when Santa casts his skill.

==== Databases Queries for Data Retrieval ====
Now we'll use a database to iterate through a number of targets dynamically.
<pre>
IF
SkillCast(_Santa, "Shout_SpreadCheer", _)
AND
DB_Santa_NiceList(_Target)
THEN
ApplyStatus(_Target, "HOLIDAY_CHEER", -1.0);
PlayEffect(_Target, "RS3_FX_Santa_HolidayExplosion_01");
</pre>
Since the value of _Target is not specified in the database query, it acts as an out variable, calling subsequent lines on each entry added to DB_Santa_NiceList.

=== Database Gotchas ===
----
While databases are a powerful way to create complex scripting logic, there are a few crucial concepts to keep in mind:
* Unless you take steps to clear it out, database data persists in existing saves, even if you no longer support a particular database in a later version of your mod.
* Consider keeping the number of database columns at a manageable size. Databases can be cross-referenced with other databases if needed.
* Inherited types from GUIDSTRING (CHARACTERGUID, ITEMGUID, TRIGGERGUID) need to be declared once in a database, to properly set the type.

=== System Methods ===
----
A few system methods, hidden from auto-complete, exist to enhance database use:

;call [[Osiris/API/SysClear|SysClear]]((STRING)_Predicate, (INTEGER)_Arity)
* Predicate is the name of the database ("DB_MyDatabase"), while arity are the number of columns (DB_MyDatabase("Apples", 10) would be 2 arity).
* SysClear provides an ideal way of clearing older saves of old databases from previous version of your mod, or paving the way for a full reset of a database.
;query [[Osiris/API/SysCount|SysCount]]([in](STRING)_Predicate,[in](INTEGER)_Arity,[out](INTEGER)_Count)
* SysCount is a way to count the entries in a database. This is especially useful when creating conditions in reference to a database that is added to dynamically through gameplay (i.e. the number of players inside a trigger, the number of characters who had a particular status applied, and so on).

=== Cross-Database Referencing ===
----
Using a consistent entry across multiple databases allows you to utilize various databases to dynamically enhance your mod.

==== Adventure Mod Example ====
----

First, we'll create a few databases to store some settings.

INIT:
<pre>
//DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
DB_MyAdventureMod_Triggers("MyLevel_FrontDoor", (TRIGGERGUID)TRIGGERGUID_S_MyLevel_DoorEntry_b5ab6a49-b015-4908-8f49-7b152d6c5d30);
DB_MyAdventureMod_Triggers("MyLevel_HallwayAmbush", TRIGGERGUID_S_MyLevel_Ambush1_1d089d37-fc5e-4cc6-807e-51d0535dc0cc);
DB_MyAdventureMod_Triggers("MyLevel_GolemBoss", TRIGGERGUID_S_MyLevel_Boss1_0a009ed0-61f5-4670-9d26-1417ebf02922);

//DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_FrontDoor", "12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_HallwayAmbush","12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_GolemBoss","2052f790-d2d7-4cf7-95f0-4de478e98d28");

//DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonLeader_584db8ce-8dcf-4906-bc6f-e51eb057de08");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonMage1_61bf204e-ba2e-412f-ac86-e132a3930105");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonRanger1_f7bd3244-e1e7-4079-ac95-fef6145a236e");
</pre>

By using multiple databases together, we now only need to worry about the TRIGGERGUID in one database, while the others rely on the string name. This is easier to deal with in the long run.

Next, we'll look for when a player enters one of these triggers, and store when it first activates.

KB:
<pre>
IF
CharacterEnteredTrigger((CHARACTERGUID)_Character, (TRIGGERGUID)_TriggerID)
AND
DB_IsPlayer(_Character)
AND
DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
AND
NOT DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
THEN
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID);
</pre>

We'll then look for when a trigger is added to the "TriggerActivated" database, and create rules for changing the atmosphere and spawning enemies.

KB:
<pre>
IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
THEN
TriggerSetAtmosphere(_TriggerID, _Atmosphere);

IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
AND
GetRandomPositionInTrigger(_TriggerID, _X, _Y, _Z)
AND
CharacterCreateAtPosition(_X, _Y, _Z, _CharacterTemplate, 1, _Enemy)
THEN
DB_MyAdventureMod_SpawnedEnemies(_TriggerName, _Enemy);
</pre>

We now have a good basis for changing atmosphere, spawning enemies, and tracking which enemies were spawned. This could easily be extended to support sounds, dialogs that need to start, and more.

=== Updating Databases ===
----
When you use databases as a way to store settings, this information will persist on existing saves unless you purposefully remove it.

As an example, say you have a script like this:

'''MyMod_ExampleScript.txt'''

INIT:
<pre>
//DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_A_7e24b009-f2bc-47c0-a635-b776407833aa", 1);
</pre>

KB:
<pre>
IF
SkillCast(_Character, _Skill, _)
AND
DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
THEN
ItemTemplateAddTo(_ItemTemplate, _Character, (INTEGER)_Count, 1);
</pre>
Later, after releasing your mod, you decide that you want "Target_MyMod_DiamondTransmutation" to spawn a different diamond item template. To properly do this, in a way that won't spawn the previous template for an existing save, you need to delete the previous entry from the database.

==== Database Update Example ====
----
One way to implement internal mod "updates" for your databases is by storing a "mod version" in a database, and checking against this version when a save is loaded.

In a top-level goal (one that will run before all others), enter the following:

'''MyMod__MainScript.txt'''
INIT:
<pre>
//The current mod version.
DB_MyMod_Version("1.1.1");
</pre>

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
DebugBreak("[MyMod] Mod update detected. Updating databases.");

IF
SavegameLoaded(_,_,_,_)
AND
NOT DB_MyMod_Version("1.1.1")
THEN
MyMod_Update_UpdateDatabases();
SysClear("DB_MyMod_Version", 1); // Clear existing mod versions.
DB_MyMod_Version("1.1.1");
</pre>

"MyMod_Update_UpdateDatabases()" is a custom PROC we've created to handle updating databases. In the individual goals that we want to update databases for, creating new rules with the same PROC name will run our PROC when the top-level goal's PROC is triggered:

'''MyMod_ExampleScript.txt'''

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
SysClear("DB_MyMod_Skill_ItemCreation", 3);
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_B_Black_VW_94933c36-393e-4077-abec-95e04341fc92", 1);
</pre>

Now when the main script triggers the update, our second script will also run its own update, clearing out the previous database data and adding our new settings.

=== Updating Mods: Beyond Databases ===
----
Beyond changing databases, updating your mod can be a more extensive ordeal, as there's a variety of factors to keep in mind. More on that here: [[Modding:_Versioning|Modding: Versioning]].

== Further Information ==
More in-depth information on Osiris can be read on the following pages:
* [[Osiris Overview]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]
* [[Your First Story Script]]
* [[:Category:Osiris_APIs|Osiris APIs]]
* [[:Category:Osiris_Calls|Osiris Calls]]

[[Category:Osiris]]

Osiris Tips and Examples

2018-01-27T18:34:58Z

LaughingLeader: /* Databases Queries for Data Retrieval */

The following is a collection of practical examples and tips that will aid in your journey to learn how to power your mod through story script usage.

== Rule Flow ==
Story scripts run on "rules". Every frame, Osiris will evaluate the rules for every running story goal.

The flow of every rule is:
<pre>
IF
Event
AND
Query
THEN
Call();
</pre>

Queries between the event and the call section of a rule are optional. You can simply go from event to call if you desire:
<pre>
IF
Event
THEN
Call();
</pre>

Queries are both gatekeepers to the call section, and a way to retrieve information.

== Databases ==
Databases can be used to store specific data (such as characters entering a trigger), or as a way to story settings used in your rules.

=== Database Use Within Rules ===
----
Databases may be used in all three rule sections:
;IF
:Databases used in the event section will run when a new entry is added. It will never run when an entry is removed.
;AND
:Databases used in the query section can be used to evaluate if an entry exists, does not exist, or as a way to run subsequent lines on the whole database, or entries that match a particular value.
;THEN
:In the call section, new entries are added to databases, or existing entries are removed (i.e. NOT DB_MyDatabase(_VariableA, _VariableB).

=== Database Queries ===
----
Used as a query, databases are powerful ways to retrieve data, or create complex conditions.
==== Databases Queries for Conditions ====
Passing values into Databases is an easy way to create dynamic conditions:
<pre>
IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You're been a bad guy this year! Coal for you!");
ItemTemplateAddTo("QUEST_Coal_df215b50-e18f-4527-a2ac-e7eec6cba576", _Target, 1);

IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
NOT DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You've been good this year! Have a present!");
ItemTemplateAddTo("QUEST_Present_29f926ff-bfb3-4c0f-b4a4-e356d6b88cf0", _Target, 1);
</pre>
This example assumes that characters were already added to a database, and uses it to determine which item to give to a target, when Santa casts his skill.

==== Databases Queries for Data Retrieval ====
Now we'll use a database to iterate through a number of targets dynamically.
<pre>
IF
SkillCast(_Santa, "Shout_SpreadCheer", _)
AND
DB_Santa_NiceList(_Target)
THEN
ApplyStatus(_Target, "HOLIDAY_CHEER", -1.0);
PlayEffect(_Target, "RS3_FX_Santa_HolidayExplosion_01");
</pre>
Since _Target was never set before the database query, it acts as an out variable, calling subsequent lines on each entry added to DB_Santa_NiceList.

=== Database Gotchas ===
----
While databases are a powerful way to create complex scripting logic, there are a few crucial concepts to keep in mind:
* Unless you take steps to clear it out, database data persists in existing saves, even if you no longer support a particular database in a later version of your mod.
* Consider keeping the number of database columns at a manageable size. Databases can be cross-referenced with other databases if needed.
* Inherited types from GUIDSTRING (CHARACTERGUID, ITEMGUID, TRIGGERGUID) need to be declared once in a database, to properly set the type.

=== System Methods ===
----
A few system methods, hidden from auto-complete, exist to enhance database use:

;call [[Osiris/API/SysClear|SysClear]]((STRING)_Predicate, (INTEGER)_Arity)
* Predicate is the name of the database ("DB_MyDatabase"), while arity are the number of columns (DB_MyDatabase("Apples", 10) would be 2 arity).
* SysClear provides an ideal way of clearing older saves of old databases from previous version of your mod, or paving the way for a full reset of a database.
;query [[Osiris/API/SysCount|SysCount]]([in](STRING)_Predicate,[in](INTEGER)_Arity,[out](INTEGER)_Count)
* SysCount is a way to count the entries in a database. This is especially useful when creating conditions in reference to a database that is added to dynamically through gameplay (i.e. the number of players inside a trigger, the number of characters who had a particular status applied, and so on).

=== Cross-Database Referencing ===
----
Using a consistent entry across multiple databases allows you to utilize various databases to dynamically enhance your mod.

==== Adventure Mod Example ====
----

First, we'll create a few databases to store some settings.

INIT:
<pre>
//DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
DB_MyAdventureMod_Triggers("MyLevel_FrontDoor", (TRIGGERGUID)TRIGGERGUID_S_MyLevel_DoorEntry_b5ab6a49-b015-4908-8f49-7b152d6c5d30);
DB_MyAdventureMod_Triggers("MyLevel_HallwayAmbush", TRIGGERGUID_S_MyLevel_Ambush1_1d089d37-fc5e-4cc6-807e-51d0535dc0cc);
DB_MyAdventureMod_Triggers("MyLevel_GolemBoss", TRIGGERGUID_S_MyLevel_Boss1_0a009ed0-61f5-4670-9d26-1417ebf02922);

//DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_FrontDoor", "12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_HallwayAmbush","12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_GolemBoss","2052f790-d2d7-4cf7-95f0-4de478e98d28");

//DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonLeader_584db8ce-8dcf-4906-bc6f-e51eb057de08");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonMage1_61bf204e-ba2e-412f-ac86-e132a3930105");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonRanger1_f7bd3244-e1e7-4079-ac95-fef6145a236e");
</pre>

By using multiple databases together, we now only need to worry about the TRIGGERGUID in one database, while the others rely on the string name. This is easier to deal with in the long run.

Next, we'll look for when a player enters one of these triggers, and store when it first activates.

KB:
<pre>
IF
CharacterEnteredTrigger((CHARACTERGUID)_Character, (TRIGGERGUID)_TriggerID)
AND
DB_IsPlayer(_Character)
AND
DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
AND
NOT DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
THEN
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID);
</pre>

We'll then look for when a trigger is added to the "TriggerActivated" database, and create rules for changing the atmosphere and spawning enemies.

KB:
<pre>
IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
THEN
TriggerSetAtmosphere(_TriggerID, _Atmosphere);

IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
AND
GetRandomPositionInTrigger(_TriggerID, _X, _Y, _Z)
AND
CharacterCreateAtPosition(_X, _Y, _Z, _CharacterTemplate, 1, _Enemy)
THEN
DB_MyAdventureMod_SpawnedEnemies(_TriggerName, _Enemy);
</pre>

We now have a good basis for changing atmosphere, spawning enemies, and tracking which enemies were spawned. This could easily be extended to support sounds, dialogs that need to start, and more.

=== Updating Databases ===
----
When you use databases as a way to store settings, this information will persist on existing saves unless you purposefully remove it.

As an example, say you have a script like this:

'''MyMod_ExampleScript.txt'''

INIT:
<pre>
//DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_A_7e24b009-f2bc-47c0-a635-b776407833aa", 1);
</pre>

KB:
<pre>
IF
SkillCast(_Character, _Skill, _)
AND
DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
THEN
ItemTemplateAddTo(_ItemTemplate, _Character, (INTEGER)_Count, 1);
</pre>
Later, after releasing your mod, you decide that you want "Target_MyMod_DiamondTransmutation" to spawn a different diamond item template. To properly do this, in a way that won't spawn the previous template for an existing save, you need to delete the previous entry from the database.

==== Database Update Example ====
----
One way to implement internal mod "updates" for your databases is by storing a "mod version" in a database, and checking against this version when a save is loaded.

In a top-level goal (one that will run before all others), enter the following:

'''MyMod__MainScript.txt'''
INIT:
<pre>
//The current mod version.
DB_MyMod_Version("1.1.1");
</pre>

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
DebugBreak("[MyMod] Mod update detected. Updating databases.");

IF
SavegameLoaded(_,_,_,_)
AND
NOT DB_MyMod_Version("1.1.1")
THEN
MyMod_Update_UpdateDatabases();
SysClear("DB_MyMod_Version", 1); // Clear existing mod versions.
DB_MyMod_Version("1.1.1");
</pre>

"MyMod_Update_UpdateDatabases()" is a custom PROC we've created to handle updating databases. In the individual goals that we want to update databases for, creating new rules with the same PROC name will run our PROC when the top-level goal's PROC is triggered:

'''MyMod_ExampleScript.txt'''

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
SysClear("DB_MyMod_Skill_ItemCreation", 3);
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_B_Black_VW_94933c36-393e-4077-abec-95e04341fc92", 1);
</pre>

Now when the main script triggers the update, our second script will also run its own update, clearing out the previous database data and adding our new settings.

=== Updating Mods: Beyond Databases ===
----
Beyond changing databases, updating your mod can be a more extensive ordeal, as there's a variety of factors to keep in mind. More on that here: [[Modding:_Versioning|Modding: Versioning]].

== Further Information ==
More in-depth information on Osiris can be read on the following pages:
* [[Osiris Overview]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]
* [[Your First Story Script]]
* [[:Category:Osiris_APIs|Osiris APIs]]
* [[:Category:Osiris_Calls|Osiris Calls]]

[[Category:Osiris]]

Osiris Tips and Examples

2018-01-26T16:25:14Z

LaughingLeader: Did some testing on databases with more than 6 arity, and they seem to compile and work correctly.

The following is a collection of practical examples and tips that will aid in your journey to learn how to power your mod through story script usage.

== Rule Flow ==
Story scripts run on "rules". Every frame, Osiris will evaluate the rules for every running story goal.

The flow of every rule is:
<pre>
IF
Event
AND
Query
THEN
Call();
</pre>

Queries between the event and the call section of a rule are optional. You can simply go from event to call if you desire:
<pre>
IF
Event
THEN
Call();
</pre>

Queries are both gatekeepers to the call section, and a way to retrieve information.

== Databases ==
Databases can be used to store specific data (such as characters entering a trigger), or as a way to story settings used in your rules.

=== Database Use Within Rules ===
----
Databases may be used in all three rule sections:
;IF
:Databases used in the event section will run when a new entry is added. It will never run when an entry is removed.
;AND
:Databases used in the query section can be used to evaluate if an entry exists, does not exist, or as a way to run subsequent lines on the whole database, or entries that match a particular value.
;THEN
:In the call section, new entries are added to databases, or existing entries are removed (i.e. NOT DB_MyDatabase(_VariableA, _VariableB).

=== Database Queries ===
----
Used as a query, databases are powerful ways to retrieve data, or create complex conditions.
==== Databases Queries for Conditions ====
Passing values into Databases is an easy way to create dynamic conditions:
<pre>
IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You're been a bad guy this year! Coal for you!");
ItemTemplateAddTo("QUEST_Coal_df215b50-e18f-4527-a2ac-e7eec6cba576", _Target, 1);

IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
NOT DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You've been good this year! Have a present!");
ItemTemplateAddTo("QUEST_Present_29f926ff-bfb3-4c0f-b4a4-e356d6b88cf0", _Target, 1);
</pre>
This example assumes that characters were already added to a database, and uses it to determine which item to give to a target, when Santa casts his skill.

==== Databases Queries for Data Retrieval ====
Now we'll use a database to iterate through a number of targets dynamically.
<pre>
IF
SkillCast(_Santa, "Shout_SpreadCheer", _)
AND
DB_Santa_NiceList(_Target)
THEN
ApplyStatus(_Target, "HOLIDAY_CHEER", -1.0);
PlayEffect(_Target, "RS3_FX_Santa_HolidayExplosion_01");
</pre>
Since _Target was never set beforehand, it acts as an out variable, calling subsequent lines on each entry added to DB_Santa_NiceList.

=== Database Gotchas ===
----
While databases are a powerful way to create complex scripting logic, there are a few crucial concepts to keep in mind:
* Unless you take steps to clear it out, database data persists in existing saves, even if you no longer support a particular database in a later version of your mod.
* Consider keeping the number of database columns at a manageable size. Databases can be cross-referenced with other databases if needed.
* Inherited types from GUIDSTRING (CHARACTERGUID, ITEMGUID, TRIGGERGUID) need to be declared once in a database, to properly set the type.

=== System Methods ===
----
A few system methods, hidden from auto-complete, exist to enhance database use:

;call [[Osiris/API/SysClear|SysClear]]((STRING)_Predicate, (INTEGER)_Arity)
* Predicate is the name of the database ("DB_MyDatabase"), while arity are the number of columns (DB_MyDatabase("Apples", 10) would be 2 arity).
* SysClear provides an ideal way of clearing older saves of old databases from previous version of your mod, or paving the way for a full reset of a database.
;query [[Osiris/API/SysCount|SysCount]]([in](STRING)_Predicate,[in](INTEGER)_Arity,[out](INTEGER)_Count)
* SysCount is a way to count the entries in a database. This is especially useful when creating conditions in reference to a database that is added to dynamically through gameplay (i.e. the number of players inside a trigger, the number of characters who had a particular status applied, and so on).

=== Cross-Database Referencing ===
----
Using a consistent entry across multiple databases allows you to utilize various databases to dynamically enhance your mod.

==== Adventure Mod Example ====
----

First, we'll create a few databases to store some settings.

INIT:
<pre>
//DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
DB_MyAdventureMod_Triggers("MyLevel_FrontDoor", (TRIGGERGUID)TRIGGERGUID_S_MyLevel_DoorEntry_b5ab6a49-b015-4908-8f49-7b152d6c5d30);
DB_MyAdventureMod_Triggers("MyLevel_HallwayAmbush", TRIGGERGUID_S_MyLevel_Ambush1_1d089d37-fc5e-4cc6-807e-51d0535dc0cc);
DB_MyAdventureMod_Triggers("MyLevel_GolemBoss", TRIGGERGUID_S_MyLevel_Boss1_0a009ed0-61f5-4670-9d26-1417ebf02922);

//DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_FrontDoor", "12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_HallwayAmbush","12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_GolemBoss","2052f790-d2d7-4cf7-95f0-4de478e98d28");

//DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonLeader_584db8ce-8dcf-4906-bc6f-e51eb057de08");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonMage1_61bf204e-ba2e-412f-ac86-e132a3930105");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonRanger1_f7bd3244-e1e7-4079-ac95-fef6145a236e");
</pre>

By using multiple databases together, we now only need to worry about the TRIGGERGUID in one database, while the others rely on the string name. This is easier to deal with in the long run.

Next, we'll look for when a player enters one of these triggers, and store when it first activates.

KB:
<pre>
IF
CharacterEnteredTrigger((CHARACTERGUID)_Character, (TRIGGERGUID)_TriggerID)
AND
DB_IsPlayer(_Character)
AND
DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
AND
NOT DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
THEN
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID);
</pre>

We'll then look for when a trigger is added to the "TriggerActivated" database, and create rules for changing the atmosphere and spawning enemies.

KB:
<pre>
IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
THEN
TriggerSetAtmosphere(_TriggerID, _Atmosphere);

IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
AND
GetRandomPositionInTrigger(_TriggerID, _X, _Y, _Z)
AND
CharacterCreateAtPosition(_X, _Y, _Z, _CharacterTemplate, 1, _Enemy)
THEN
DB_MyAdventureMod_SpawnedEnemies(_TriggerName, _Enemy);
</pre>

We now have a good basis for changing atmosphere, spawning enemies, and tracking which enemies were spawned. This could easily be extended to support sounds, dialogs that need to start, and more.

=== Updating Databases ===
----
When you use databases as a way to store settings, this information will persist on existing saves unless you purposefully remove it.

As an example, say you have a script like this:

'''MyMod_ExampleScript.txt'''

INIT:
<pre>
//DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_A_7e24b009-f2bc-47c0-a635-b776407833aa", 1);
</pre>

KB:
<pre>
IF
SkillCast(_Character, _Skill, _)
AND
DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
THEN
ItemTemplateAddTo(_ItemTemplate, _Character, (INTEGER)_Count, 1);
</pre>
Later, after releasing your mod, you decide that you want "Target_MyMod_DiamondTransmutation" to spawn a different diamond item template. To properly do this, in a way that won't spawn the previous template for an existing save, you need to delete the previous entry from the database.

==== Database Update Example ====
----
One way to implement internal mod "updates" for your databases is by storing a "mod version" in a database, and checking against this version when a save is loaded.

In a top-level goal (one that will run before all others), enter the following:

'''MyMod__MainScript.txt'''
INIT:
<pre>
//The current mod version.
DB_MyMod_Version("1.1.1");
</pre>

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
DebugBreak("[MyMod] Mod update detected. Updating databases.");

IF
SavegameLoaded(_,_,_,_)
AND
NOT DB_MyMod_Version("1.1.1")
THEN
MyMod_Update_UpdateDatabases();
SysClear("DB_MyMod_Version", 1); // Clear existing mod versions.
DB_MyMod_Version("1.1.1");
</pre>

"MyMod_Update_UpdateDatabases()" is a custom PROC we've created to handle updating databases. In the individual goals that we want to update databases for, creating new rules with the same PROC name will run our PROC when the top-level goal's PROC is triggered:

'''MyMod_ExampleScript.txt'''

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
SysClear("DB_MyMod_Skill_ItemCreation", 3);
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_B_Black_VW_94933c36-393e-4077-abec-95e04341fc92", 1);
</pre>

Now when the main script triggers the update, our second script will also run its own update, clearing out the previous database data and adding our new settings.

=== Updating Mods: Beyond Databases ===
----
Beyond changing databases, updating your mod can be a more extensive ordeal, as there's a variety of factors to keep in mind. More on that here: [[Modding:_Versioning|Modding: Versioning]].

== Further Information ==
More in-depth information on Osiris can be read on the following pages:
* [[Osiris Overview]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]
* [[Your First Story Script]]
* [[:Category:Osiris_APIs|Osiris APIs]]
* [[:Category:Osiris_Calls|Osiris Calls]]

[[Category:Osiris]]

Osiris Tips and Examples

2017-12-21T11:25:01Z

LaughingLeader:

The following is a collection of practical examples and tips that will aid in your journey to learn how to power your mod through story script usage.

== Rule Flow ==
Story scripts run on "rules". Every frame, Osiris will evaluate the rules for every running story goal.

The flow of every rule is:
<pre>
IF
Event
AND
Query
THEN
Call();
</pre>

Queries between the event and the call section of a rule are optional. You can simply go from event to call if you desire:
<pre>
IF
Event
THEN
Call();
</pre>

Queries are both gatekeepers to the call section, and a way to retrieve information.

== Databases ==
Databases can be used to store specific data (such as characters entering a trigger), or as a way to story settings used in your rules.

=== Database Use Within Rules ===
----
Databases may be used in all three rule sections:
;IF
:Databases used in the event section will run when a new entry is added. It will never run when an entry is removed.
;AND
:Databases used in the query section can be used to evaluate if an entry exists, does not exist, or as a way to run subsequent lines on the whole database, or entries that match a particular value.
;THEN
:In the call section, new entries are added to databases, or existing entries are removed (i.e. NOT DB_MyDatabase(_VariableA, _VariableB).

=== Database Queries ===
----
Used as a query, databases are powerful ways to retrieve data, or create complex conditions.
==== Databases Queries for Conditions ====
Passing values into Databases is an easy way to create dynamic conditions:
<pre>
IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You're been a bad guy this year! Coal for you!");
ItemTemplateAddTo("QUEST_Coal_df215b50-e18f-4527-a2ac-e7eec6cba576", _Target, 1);

IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
NOT DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You've been good this year! Have a present!");
ItemTemplateAddTo("QUEST_Present_29f926ff-bfb3-4c0f-b4a4-e356d6b88cf0", _Target, 1);
</pre>
This example assumes that characters were already added to a database, and uses it to determine which item to give to a target, when Santa casts his skill.

==== Databases Queries for Data Retrieval ====
Now we'll use a database to iterate through a number of targets dynamically.
<pre>
IF
SkillCast(_Santa, "Shout_SpreadCheer", _)
AND
DB_Santa_NiceList(_Target)
THEN
ApplyStatus(_Target, "HOLIDAY_CHEER", -1.0);
PlayEffect(_Target, "RS3_FX_Santa_HolidayExplosion_01");
</pre>
Since _Target was never set beforehand, it acts as an out variable, calling subsequent lines on each entry added to DB_Santa_NiceList.

=== Database Gotchas ===
----
While databases are a powerful way to create complex scripting logic, there are a few crucial concepts to keep in mind:
* Unless you take steps to clear it out, database data persists in existing saves, even if you no longer support a particular database in a later version of your mod.
* Osiris may have issues with databases containing more than 6 columns.
* Inherited types from GUIDSTRING (CHARACTERGUID, ITEMGUID, TRIGGERGUID) need to be declared once in a database, to properly set the type.

=== System Methods ===
----
A few system methods, hidden from auto-complete, exist to enhance database use:

;call [[Osiris/API/SysClear|SysClear]]((STRING)_Predicate, (INTEGER)_Arity)
* Predicate is the name of the database ("DB_MyDatabase"), while arity are the number of columns (DB_MyDatabase("Apples", 10) would be 2 arity).
* SysClear provides an ideal way of clearing older saves of old databases from previous version of your mod, or paving the way for a full reset of a database.
;query [[Osiris/API/SysCount|SysCount]]([in](STRING)_Predicate,[in](INTEGER)_Arity,[out](INTEGER)_Count)
* SysCount is a way to count the entries in a database. This is especially useful when creating conditions in reference to a database that is added to dynamically through gameplay (i.e. the number of players inside a trigger, the number of characters who had a particular status applied, and so on).

=== Cross-Database Referencing ===
----
Using a consistent entry across multiple databases allows you to utilize various databases to dynamically enhance your mod.

==== Adventure Mod Example ====
----

First, we'll create a few databases to store some settings.

INIT:
<pre>
//DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
DB_MyAdventureMod_Triggers("MyLevel_FrontDoor", (TRIGGERGUID)TRIGGERGUID_S_MyLevel_DoorEntry_b5ab6a49-b015-4908-8f49-7b152d6c5d30);
DB_MyAdventureMod_Triggers("MyLevel_HallwayAmbush", TRIGGERGUID_S_MyLevel_Ambush1_1d089d37-fc5e-4cc6-807e-51d0535dc0cc);
DB_MyAdventureMod_Triggers("MyLevel_GolemBoss", TRIGGERGUID_S_MyLevel_Boss1_0a009ed0-61f5-4670-9d26-1417ebf02922);

//DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_FrontDoor", "12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_HallwayAmbush","12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_GolemBoss","2052f790-d2d7-4cf7-95f0-4de478e98d28");

//DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonLeader_584db8ce-8dcf-4906-bc6f-e51eb057de08");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonMage1_61bf204e-ba2e-412f-ac86-e132a3930105");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonRanger1_f7bd3244-e1e7-4079-ac95-fef6145a236e");
</pre>

By using multiple databases together, we now only need to worry about the TRIGGERGUID in one database, while the others rely on the string name. This is easier to deal with in the long run.

Next, we'll look for when a player enters one of these triggers, and store when it first activates.

KB:
<pre>
IF
CharacterEnteredTrigger((CHARACTERGUID)_Character, (TRIGGERGUID)_TriggerID)
AND
DB_IsPlayer(_Character)
AND
DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
AND
NOT DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
THEN
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID);
</pre>

We'll then look for when a trigger is added to the "TriggerActivated" database, and create rules for changing the atmosphere and spawning enemies.

KB:
<pre>
IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
THEN
TriggerSetAtmosphere(_TriggerID, _Atmosphere);

IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
AND
GetRandomPositionInTrigger(_TriggerID, _X, _Y, _Z)
AND
CharacterCreateAtPosition(_X, _Y, _Z, _CharacterTemplate, 1, _Enemy)
THEN
DB_MyAdventureMod_SpawnedEnemies(_TriggerName, _Enemy);
</pre>

We now have a good basis for changing atmosphere, spawning enemies, and tracking which enemies were spawned. This could easily be extended to support sounds, dialogs that need to start, and more.

=== Updating Databases ===
----
When you use databases as a way to store settings, this information will persist on existing saves unless you purposefully remove it.

As an example, say you have a script like this:

'''MyMod_ExampleScript.txt'''

INIT:
<pre>
//DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_A_7e24b009-f2bc-47c0-a635-b776407833aa", 1);
</pre>

KB:
<pre>
IF
SkillCast(_Character, _Skill, _)
AND
DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
THEN
ItemTemplateAddTo(_ItemTemplate, _Character, (INTEGER)_Count, 1);
</pre>
Later, after releasing your mod, you decide that you want "Target_MyMod_DiamondTransmutation" to spawn a different diamond item template. To properly do this, in a way that won't spawn the previous template for an existing save, you need to delete the previous entry from the database.

==== Database Update Example ====
----
One way to implement internal mod "updates" for your databases is by storing a "mod version" in a database, and checking against this version when a save is loaded.

In a top-level goal (one that will run before all others), enter the following:

'''MyMod__MainScript.txt'''
INIT:
<pre>
//The current mod version.
DB_MyMod_Version("1.1.1");
</pre>

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
DebugBreak("[MyMod] Mod update detected. Updating databases.");

IF
SavegameLoaded(_,_,_,_)
AND
NOT DB_MyMod_Version("1.1.1")
THEN
MyMod_Update_UpdateDatabases();
SysClear("DB_MyMod_Version", 1); // Clear existing mod versions.
DB_MyMod_Version("1.1.1");
</pre>

"MyMod_Update_UpdateDatabases()" is a custom PROC we've created to handle updating databases. In the individual goals that we want to update databases for, creating new rules with the same PROC name will run our PROC when the top-level goal's PROC is triggered:

'''MyMod_ExampleScript.txt'''

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
SysClear("DB_MyMod_Skill_ItemCreation", 3);
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_B_Black_VW_94933c36-393e-4077-abec-95e04341fc92", 1);
</pre>

Now when the main script triggers the update, our second script will also run its own update, clearing out the previous database data and adding our new settings.

=== Updating Mods: Beyond Databases ===
----
Beyond changing databases, updating your mod can be a more extensive ordeal, as there's a variety of factors to keep in mind. More on that here: [[Modding:_Versioning|Modding: Versioning]].

== Further Information ==
More in-depth information on Osiris can be read on the following pages:
* [[Osiris Overview]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]
* [[Your First Story Script]]
* [[:Category:Osiris_APIs|Osiris APIs]]
* [[:Category:Osiris_Calls|Osiris Calls]]

[[Category:Osiris]]

Osiris Tips and Examples

2017-12-21T11:24:42Z

LaughingLeader:

The following is a collection of practical examples and tips that will aid in your journey to learn how to power your mod through story script usage.

== Rule Flow ==
Story scripts run on "rules". Every frame, Osiris will evaluate the rules for every running story goal.

The flow of every rule is:
<pre>
IF
Event
AND
Query
THEN
Call();
</pre>

Queries between the event and the call section of a rule are optional. You can simply go from event to call if you desire:
<pre>
IF
Event
THEN
Call();
</pre>

Queries are both gatekeepers to the call section, and a way to retrieve information.

== Databases ==
Databases can be used to store specific data (such as characters entering a trigger), or as a way to story settings used in your rules.

=== Database Use Within Rules ===
----
Databases may be used in all three rule sections:
;IF
:Databases used in the event section will run when a new entry is added. It will never run when an entry is removed.
;AND
:Databases used in the query section can be used to evaluate if an entry exists, does not exist, or as a way to run subsequent lines on the whole database, or entries that match a particular value.
;THEN
:In the call section, new entries are added to databases, or existing entries are removed (i.e. NOT DB_MyDatabase(_VariableA, _VariableB).

=== Database Queries ===
----
Used as a query, databases are powerful ways to retrieve data, or create complex conditions.
==== Databases Queries for Conditions ====
Passing values into Databases is an easy way to create dynamic conditions:
<pre>
IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You're been a bad guy this year! Coal for you!");
ItemTemplateAddTo("QUEST_Coal_df215b50-e18f-4527-a2ac-e7eec6cba576", _Target, 1);

IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
NOT DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You've been good this year! Have a present!");
ItemTemplateAddTo("QUEST_Present_29f926ff-bfb3-4c0f-b4a4-e356d6b88cf0", _Target, 1);
</pre>
This example assumes that characters were already added to a database, and uses it to determine which item to give to a target, when Santa casts his skill.

==== Databases Queries for Data Retrieval ====
Now we'll use a database to iterate through a number of targets dynamically.
<pre>
IF
SkillCast(_Santa, "Shout_SpreadCheer", _)
AND
DB_Santa_NiceList(_Target)
THEN
ApplyStatus(_Target, "HOLIDAY_CHEER", -1.0);
PlayEffect(_Target, "RS3_FX_Santa_HolidayExplosion_01");
</pre>
Since _Target was never set beforehand, it acts as an out variable, calling subsequent lines on each entry added to DB_Santa_NiceList.

=== Database Gotchas ===
----
While databases are a powerful way to create complex scripting logic, there are a few crucial concepts to keep in mind:
* Unless you take steps to clear it out, database data persists in existing saves, even if you no longer support a particular database in a later version of your mod.
* Osiris may have issues with databases containing more than 6 columns.
* Inherited types from GUIDSTRING (CHARACTERGUID, ITEMGUID, TRIGGERGUID) need to be declared once in a database, to properly set the type.

=== System Methods ===
----
A few system methods, hidden from auto-complete, exist to enhance database use:

;call [[Osiris/API/SysClear|SysClear]]((STRING)_Predicate, (INTEGER)_Arity)
* Predicate is the name of the database ("DB_MyDatabase"), while arity are the number of columns (DB_MyDatabase("Apples", 10) would be 2 arity).
* SysClear provides an ideal way of clearing older saves of old databases from previous version of your mod, or paving the way for a full reset of a database.
;query [[Osiris/API/SysCount|SysCount]]([in](STRING)_Predicate,[in](INTEGER)_Arity,[out](INTEGER)_Count)
* SysCount is a way to count the entries in a database. This is especially useful when creating conditions in reference to a database that is added to dynamically through gameplay (i.e. the number of players inside a trigger, the number of characters who had a particular status applied, and so on).

=== Cross-Database Referencing ===
----
Using a consistent entry across multiple databases allows you to utilize various databases to dynamically enhance your mod.

==== Adventure Mod Example ====
----

First, we'll create a few databases to store some settings.

INIT:
<pre>
//DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
DB_MyAdventureMod_Triggers("MyLevel_FrontDoor", (TRIGGERGUID)TRIGGERGUID_S_MyLevel_DoorEntry_b5ab6a49-b015-4908-8f49-7b152d6c5d30);
DB_MyAdventureMod_Triggers("MyLevel_HallwayAmbush", TRIGGERGUID_S_MyLevel_Ambush1_1d089d37-fc5e-4cc6-807e-51d0535dc0cc);
DB_MyAdventureMod_Triggers("MyLevel_GolemBoss", TRIGGERGUID_S_MyLevel_Boss1_0a009ed0-61f5-4670-9d26-1417ebf02922);

//DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_FrontDoor", "12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_HallwayAmbush","12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_GolemBoss","2052f790-d2d7-4cf7-95f0-4de478e98d28");

//DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonLeader_584db8ce-8dcf-4906-bc6f-e51eb057de08");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonMage1_61bf204e-ba2e-412f-ac86-e132a3930105");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonRanger1_f7bd3244-e1e7-4079-ac95-fef6145a236e");
</pre>

By using multiple databases together, we now only need to worry about the TRIGGERGUID in one database, while the others rely on the string name. This is easier to deal with in the long run.

Next, we'll look for when a player enters one of these triggers, and store when it first activates.

KB:
<pre>
IF
CharacterEnteredTrigger((CHARACTERGUID)_Character, (TRIGGERGUID)_TriggerID)
AND
DB_IsPlayer(_Character)
AND
DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
AND
NOT DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
THEN
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID);
</pre>

We'll then look for when a trigger is added to the "TriggerActivated" database, and create rules for changing the atmosphere and spawning enemies.

KB:
<pre>
IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
THEN
TriggerSetAtmosphere(_TriggerID, _Atmosphere);

IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
AND
GetRandomPositionInTrigger(_TriggerID, _X, _Y, _Z)
AND
CharacterCreateAtPosition(_X, _Y, _Z, _CharacterTemplate, 1, _Enemy)
THEN
DB_MyAdventureMod_SpawnedEnemies(_TriggerName, _Enemy);
</pre>

We now have a good basis for changing atmosphere, spawning enemies, and tracking which enemies were spawned. This could easily be extended to support sounds, dialogs that need to start, and more.

=== Updating Databases ===
----
When you use databases as a way to store settings, this information will persist on existing saves unless you purposefully remove it.

As an example, say you have a script like this:

'''MyMod_ExampleScript.txt'''

INIT:
<pre>
//DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_A_7e24b009-f2bc-47c0-a635-b776407833aa", 1);
</pre>

KB:
<pre>
IF
SkillCast(_Character, _Skill, _)
AND
DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
THEN
ItemTemplateAddTo(_ItemTemplate, _Character, (INTEGER)_Count, 1);
</pre>
Later, after releasing your mod, you decide that you want "Target_MyMod_DiamondTransmutation" to spawn a different diamond item template. To properly do this, in a way that won't spawn the previous template for an existing save, you need to delete the previous entry from the database.

==== Database Update Example ====
----
One way to implement internal mod "updates" for your databases is by storing a "mod version" in a database, and checking against this version when a save is loaded.

In a top-level goal (one that will run before all others), enter the following:

'''MyMod__MainScript.txt'''
INIT:
<pre>
//The current mod version.
DB_MyMod_Version("1.1.1");
</pre>

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
DebugBreak("[MyMod] Mod update detected. Updating databases.");

IF
SavegameLoaded(_,_,_,_)
AND
NOT DB_MyMod_Version("1.1.1")
THEN
MyMod_Update_UpdateDatabases();
SysClear("DB_MyMod_Version", 1); // Clear existing mod versions.
DB_MyMod_Version("1.1.1");
</pre>

"MyMod_Update_UpdateDatabases()" is a custom PROC we've created to handle updating databases. In the individual goals that we want to update databases for, creating new rules with the same PROC name will run our PROC when the top-level goal's PROC is triggered:

'''MyMod_ExampleScript.txt'''

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
SysClear("DB_MyMod_Skill_ItemCreation", 3);
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_B_Black_VW_94933c36-393e-4077-abec-95e04341fc92", 1);
</pre>

Now when the main script triggers the update, our second script will also run its own update, clearing out the previous database data and adding our new settings.

=== Updating Mods: Beyond Databases ===
----
Beyond changing databases, updating your mod can be a more extensive ordeal, as there's a variety of factors to keep in mind. More on that here: [[Modding:_Versioning|Modding: Versioning]].

== Further Information ==
More in-depth information on Osiris can be read on the following pages:
* [[Osiris Overview]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]
* [[Your First Story Script]]
* [[:Category:Osiris_APIs|Osiris APIs]]
* [[Category:Osiris_Calls|Osiris Calls]]

[[Category:Osiris]]

Your First Story Script

2017-12-21T11:24:15Z

LaughingLeader:

Note: this tutorial assumes you have already created a mod project. More on that here: [[Project browser]]. For the purposes of this tutorial, we will be using a basic Addon project that inherits from Story and targets Story.

== Overview ==
Story scripts are a way to implement global logic with your mod, in a way that is compatible with other mods. Before we get started, some basic tips to keep in mind:

=== Starting Tips ===
----
* When opening the story editor in a new project, always generate definitions (File -> Generate Definitions) and exit/re-open the story editor. This will generate the files necessary for auto-complete and syntax highlighting.

* Prefix your goals (a.k.a. your script files), databases, queries, and procs in a way that will make then unique and least likely to conflict with other mods. For example, if our mod is called "Better Cupcakes", and our username is "SuperChef", we'd prefix our mod entries with SCBC, or SC_BetterCupcakes, or some combination of the two.
** This idea should also be used for entries in the stats editor, as multiple entries with the same name will conflict.

== Recommended Reading ==
* [[Osiris Overview]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]
* [[Osiris_Tips_and_Examples|Osiris Tips and Examples]]
* [[:Category:Osiris_APIs|Osiris APIs]]
* [[:Category:Osiris_Calls|Osiris Calls]]

== Implementing a Basic Story Script ==
=== Getting Started ===
----
# Open the [[Story editor]] by clicking the icon that looks like a book ([[File:StoryEditor_Icon.png|24px]]) under the "Editors" section, at the top-right of the Divinity Engine 2 editor.
# Inside the story editor, Click "File -> Generate Definitions and Build" on the top left.
#* This is an important step in generating the appropriate files. Any time you create new definitions (databases, PROCs, or queries), you need to generate definitions.
#* Building is as equally important, as your changes won't compile until you build.
#* Reloading the story is necessary to see your changes in-game. You can either do this from the story editor ("File -> Reload Story"), or from the main editor with "File -> Reload Level and Story".
# Close the story editor and open it again to essentially reload the syntax highlighting and auto-complete features.

=== Creating a Parent Goal ===
----
For organizational purposes, creating a parent story goal is recommended.
# Inside the story editor, at the goal list on the left, right click and select "Add New Item".
[[File:FirstStoryScript_AddNewItem.png|thumb]]
# Name this script something unique to your mod in a prefix format (Username_ModName), such as "SuperChef_BetterCupcakes". This has the best chance of not potentially conflicting with any other mod.
# After clicking OK, your script will automatically open. Hit CTRL+S to automatically save this script. Scripts with unsaved changes display and asterisk (*) next to their name.

==== Tip: Story Script Naming ====
----
Goals in the story are ran in alphabetical order. This is important to keep in mind if you use a particular story goal as a sort of "top-level" script that has methods and databases your other goals reference to.

With proper naming, you can control the order your scripts are run. For example, naming your top-level goal "WT_FS__Main", and your second goal "WT_FS_Skills" ensures "WT_FS__Main" will always run before "WT_FS_Skills".
[[File:FirstStoryScript_ScriptOrder.png|thumb|WT_FS__Main will always run before WT_FS_Skills.]]

=== Completing the Parent Goal ===
----
Parent goals need to "complete" before their sub-goals will run. This is done by calling "GoalCompleted;" within the parent script. We have a few options for how to go about this:

==== Completion Events ====
----
The following events are recommended to use for completing your parent goals:
; [[Osiris/API/GameStarted|GameStarted]]
: Thrown when a level has been loaded and is ready at both the server and client side. This will ensure all the base game scripts have already initialized.
; [[Osiris/API/RegionStarted|RegionStarted]]
: Thrown when the level has been loaded and is ready at the server side, but not yet at the client side.

Both of these events can be used with specific level names, as a way to make your goal only complete once that level is loaded (as a way to create level-specific logic).

==== Example Goal Completion ====
----
Inside the KB section of your goal, enter the following:
<pre>
IF
GameStarted(_Level, _EditorMode)
AND
StringConcatenate("[WT_FS] WikiTutorial_FirstStory has initialized. Level[", _Level, _Str1)
AND
StringConcatenate(_Str1, "] EditorMode(", _Str2)
AND
IntegertoString(_EditorMode, _ModeStr)
AND
StringConcatenate(_Str2, _ModeStr, _Str3)
AND
StringConcatenate(_Str3, ")", _Message)
THEN
DebugBreak(_Message);
GoalCompleted;
</pre>
# Save, then select "File -> Generate Definitions, Build and Reload".
# Minimize the story editor, then clear the message log by clicking "Clear".
# Load a level in the main editor. Inside the message log, you should see the message we added with DebugBreak.
[[File:FirstStoryScript_ParentGoalComplete.png|thumb|The debug message appears in the message log once the game is started.]]

===== Standard Goal Completion =====
----
For a regular approach, without any debug messages or string combining, use this:
<pre>
IF
GameStarted(_,_)
THEN
GoalCompleted;
</pre>
In this code block, the variables for _Level and _EditorMode are underscores, which means we're ignoring their values.

=== Adding a Sub-Goal ===
----
With the parent goal completing properly, sub-goals that are parented to the previous goal will now run.

==== Creating a Sub-Goal ====
----
Let's create a basic script that will display some text when a skill is cast.

# Double click on your parent goal to have it selected.
#* Currently, there's a bug where not having your parent goal open may cause a sub-item created to not properly parent under the right goal. If this happens, simply click and drag the new goal to your parent goal, and it should move underneath it.
# Click "Add New Sub Item...", then name it something appropriate, like "WikiTutorial_FirstStory_Skills".
# Save the new script (CTRL+S).

==== Creating a Rule ====
----
In the KB section of our new script, add the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Good job!");
CharacterResetCooldowns(_Character);
</pre>

This rule will run when the player casts "Encourage", displaying some text, and resetting their cooldowns. The Encourage skill is added automatically to the player if they lack it.

# Save, then "Generate Definitions and Build".
# In the main editor, select "File -> Reload Level and story".
# Hit the "Switch Game/Editor" button to get in-game. [[File:FirstStoryScript_GameEditorButton.png|thumb|Click this button to switch between game and editor mode.]]
# In whatever level you're working in, your provided dummy character should spawn and be given the Encourage skill.
# Cast the skill to test that your script is working properly.
[[File:FirstStoryScript_SkillCast_Result.png|thumb|Our script in action.]]

===== Notes =====
----
'''HTML Font Formatting'''
* HTML font formatting can be used in DisplayText, CharacterStatusText, and in various text entries (skill descriptions, status names/descriptions, book text, and more).

'''SkillCast '''
* This event runs when the skill's animation reaches the CastTextEvent value specified by the skill stats (which is "cast" in most cases).
* The textkey "cast" is a common textkey used in skill cast animations.
* To view the textkeys present in an animation, open it within the [[Content_browser|Resource Manager]].
* Example: Open the resource manager and search for the "Humans_Hero_Female_ABC_Skill_Cast_Aoe_Air_01_Cast" animation under the Shared folder. Double click on the resource to open the animation preview to see the different textkeys. [[File:FirstStoryScript_SkillCast_Textkey.png|thumb|The cast textkey.]]

'''DB_IsPlayer'''
* This is a base game database that is populated with all the current player characters when the game is started.
* By passing in the _Character value from the event parameters to DB_IsPlayer, we're matching the character against the database of player characters, to have the following code only run if the caster is a player-controlled character.
* Using DB_IsPlayer as an event makes the subsequent code run when a character is added to the DB_IsPlayer database.

== Taking the Script Further ==
Now that we have a basic script heirarchy working, let's take the script further.

=== Randomization ===
----
We can add randomization to the displayed text in our previous script to make the result more interesting.

We'll do this by creating a custom procedure.

;Procedure Tips:
: Procedures are declared with a "PROC" at the top of the block, and follow the same flow as a rule.
: Parameters for a procedure can be customized. You must declare their type.
: Procedures are called within the "call" section of a rule or a custom query.

Add this to the INIT section:
<pre>
//DB_WikiTutorial_FirstStory_RandomText(_Ran, _Text, _FontColor, _FontSize)
DB_WikiTutorial_FirstStory_Skills_RandomText(0, "Woo!", "00CED1", "23");
DB_WikiTutorial_FirstStory_Skills_RandomText(1, "Good job!", "00FF00", "30");
DB_WikiTutorial_FirstStory_Skills_RandomText(2, "I did it!", "DEB887", "20");
DB_WikiTutorial_FirstStory_Skills_RandomText(3, "I'm da best!", "A52A2A", "26");
</pre>

Change the code in the KB section to the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

PROC
WikiTutorial_FirstStory_Skills_DisplayRandomMessage((CHARACTERGUID)_Character)
AND
Random(4, _Ran)
AND
DB_WikiTutorial_FirstStory_Skills_RandomText(_Ran, _Text, _FontColor, _FontSize)
AND
StringConcatenate("", _Str4)
AND
StringConcatenate(_Str4, _Text, _Str5)
AND
StringConcatenate(_Str5, "", _Message)
AND
IntegertoString(_Ran, _RanStr)
AND
StringConcatenate("[WT_FS] Rolled a ", _RanStr, _DebugMessage)
THEN
DisplayText(_Character, _Message);
DebugBreak(_DebugMessage);

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload".
# Switch back to the main editor and hit the play button to get in-game.
# Cast the Encourage skill a few times in game mode to ensure the script is working properly. You should see the different messages, font colors, and font sizes.

===== Notes =====
----
'''Procedures'''
* WikiTutorial_FirstStory_Skills_DisplayRandomMessage is a custom subroutine call, called a PROC. By splitting our message logic off into a separate procedure, this ensures the calls for this rule are ran regardless of the result of our message logic (so CharacterResetCooldowns will always run if a player casts this skill). This also allows us to use this procedure elsewhere, and possible extend it further.

'''Databases'''
* We create our "RandomText" settings in the INIT section by using a database we create, called "DB_WikiTutorial_FirstStory_Skills_RandomText". Using databases in this way is a powerful way to design your script logic in a way that is extensible.

'''[[Osiris/API/Random|Random]]'''
* [[Osiris/API/Random|Random]] returns a random integer value between 0 and (_Modulo - 1). Since our DB_WikiTutorial_FirstStory_Skills_RandomText has 4 entries, we want our random number to be between 0 and 3, so we use 4 as our _Modulo.

=== Using Queries ===
----
Mastering queries is essential for creating complex conditions for your rules. "OR" logic is done within Osiris with multiple rules, subscribing to the same events, that look for different conditions through the use of queries.

Let's add to our skills script. Add this to the KB section, so your SkillCast rules look like this:

<pre>
IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
NOT DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Win... Please! Ahhhh!");
ApplyStatus(_Character, "FEAR", 1.0, 1);
</pre>

By simpling adding a NOT before our database check, our second rule will now run on any character (who's not a player) that casts Encourage, and apply fear. You can test this by loading an inherited level that contains some human enemies, or adding human enemies yourself to your test level.

=== Creating a Custom Query ===
----
Taking this idea further, we'll create a custom query.

Custom queries are defined with the keyword "QRY" at the top of a block, and follow the same flow as a rule.

Add the following code to your KB section:

<pre>
QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "HUMAN", 1)
THEN
DB_NOOP(1);

QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "DWARF", 1)
THEN
DB_NOOP(1);
</pre>

By adding two query blocks with the same name, we're effectively adding an "OR" condition. This query will evaluate as true if the character is tagged as either a human or a dwarf.

"DB_NOOP(1);" is a dummy database fact. Since rules must have a call, DB_NOOP is used to have a rule succeed without using any actual calls.

==== Implementing the Custom Query ====
----

Below our query code, in the KB section, add the following:
<pre>
IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Perception_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Perception_Potion");

IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
NOT WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Constitution_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Constitution_Potion");

IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload". Since we added a query and another database, we must generate the definitions again.
# Go in-game and test out the changes by casting Encourage on an human or dwarf (it will work on yourself as well).

===== Notes =====
----
'''NOT'''
* By adding two rules for the same event, and checking for the opposite of our query, we're effectively adding an OR condition to this event.

'''CharacterConsume/CharacterUnconsume'''
* Since CharacterConsume returns a value, it's a query instead of a call. We store the out value from the query (_Handle) in a database to later unconsume the potion effect when ENCOURAGED ends.

'''Removing Database Entries'''
* When unconsuming the potion handle, notice we also remove that entry from the database by calling "NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);" as a call. Using NOT before a database entry (in the call section) removes that entry.
* By using DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion) in the query section, the _Handle and _Potion value is returned with all entries that match the value we pass in (_Character), effectively unconsuming every potion handle we added for that character to the database.

=== Using a Query as a Subroutine ===
----
While queries can be used as conditions, they can also be used to call specific procedures/calls before the main rule reaches that section of the flow.

Let's try a simple example that runs when we unconsume a potion. Change our status removed event code to this:

<pre>
IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_ZombieCheck(_Character)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "UNDEAD", 1)
AND
CharacterGetDisplayName(_Character, _, _Name)
AND
StringConcatenate("[WT_FS] ", _Name, _Str1)
AND
StringConcatenate(_Str1, " is a zombie! Ahh! Burn it!", _Message)
THEN
ApplyStatus(_Character, "BURNING", 1.0);
DebugBreak(_Message);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
THEN
DB_NOOP(1);
</pre>

Which this, our query will apply burning if the character is tagged as UNDEAD. Note how we added a second QRY rule that always evaluates as true - this is to keep the rest of our rule in the CharacterStatusRemoved event running, undead or not.

Practically speaking, using queries as subroutines is ideal when:
* You need specific calls/procedures to run before iterating through a database. Calling your query before retrieving variables from a database ensures that those calls will only run once.
* You need to debug a rule to ensure it reaches a certain section of the conditions. If you're not sure if a specific condition is passing, adding a query with a DebugBreak message right before/after it is a good way to debug that situation.

== Bonus Tips ==

* In the story editor, select "File -> Open Story Header" for a list of all available events, queries, and calls. Heavily reference this file when you find yourself unsure if a specifc method exists, as not all methods appear in the auto-complete.

* If you use databases to store global mod settings, and your mod users have played with that mod, changing that information post-mod install will not automatically remove that data from existing saves - you need to handle this update internally within your mod.
** More on implementing an update system here: [[Osiris_Tips#Updating_Databases|Manual Mod Updates]].

* By using custom procedures and queries, you can reduce your rule redundancy and extend desired calls/conditions to multiple rules.

* To make your life with Osiris easier, wrap your rule blocks in regions with the following:
<pre>
//REGION MY_REGION_NAME

//END_REGION
</pre>
* In the story editor, right click inside your script sections (INIT, KB, or EXIT) and "Expand All" or "Collapse All" to expand/collapse all regions, respectively.

* Procedures can be called from the EXIT and INIT section of scripts.

* Use the INIT section of your scripts as a way to store commented references to your databases. As an example from our previous script, placing this inside your INIT section is a good way to remember such a database exists (since we don't initialize it in the INIT section):
<pre>
//DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
</pre>
Then, when you wish to use this database, you have a quick way to copy/paste that code into other sections of your script.

[[Category:Osiris]]

Your First Story Script

2017-12-21T11:24:04Z

LaughingLeader:

Note: this tutorial assumes you have already created a mod project. More on that here: [[Project browser]]. For the purposes of this tutorial, we will be using a basic Addon project that inherits from Story and targets Story.

== Overview ==
Story scripts are a way to implement global logic with your mod, in a way that is compatible with other mods. Before we get started, some basic tips to keep in mind:

=== Starting Tips ===
----
* When opening the story editor in a new project, always generate definitions (File -> Generate Definitions) and exit/re-open the story editor. This will generate the files necessary for auto-complete and syntax highlighting.

* Prefix your goals (a.k.a. your script files), databases, queries, and procs in a way that will make then unique and least likely to conflict with other mods. For example, if our mod is called "Better Cupcakes", and our username is "SuperChef", we'd prefix our mod entries with SCBC, or SC_BetterCupcakes, or some combination of the two.
** This idea should also be used for entries in the stats editor, as multiple entries with the same name will conflict.

== Recommended Reading ==
* [[Osiris Overview]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]
* [[Osiris_Tips_and_Examples|Osiris Tips and Examples]]
* [[:Category:Osiris_APIs|Osiris APIs]]
* [[Category:Osiris_Calls|Osiris Calls]]

== Implementing a Basic Story Script ==
=== Getting Started ===
----
# Open the [[Story editor]] by clicking the icon that looks like a book ([[File:StoryEditor_Icon.png|24px]]) under the "Editors" section, at the top-right of the Divinity Engine 2 editor.
# Inside the story editor, Click "File -> Generate Definitions and Build" on the top left.
#* This is an important step in generating the appropriate files. Any time you create new definitions (databases, PROCs, or queries), you need to generate definitions.
#* Building is as equally important, as your changes won't compile until you build.
#* Reloading the story is necessary to see your changes in-game. You can either do this from the story editor ("File -> Reload Story"), or from the main editor with "File -> Reload Level and Story".
# Close the story editor and open it again to essentially reload the syntax highlighting and auto-complete features.

=== Creating a Parent Goal ===
----
For organizational purposes, creating a parent story goal is recommended.
# Inside the story editor, at the goal list on the left, right click and select "Add New Item".
[[File:FirstStoryScript_AddNewItem.png|thumb]]
# Name this script something unique to your mod in a prefix format (Username_ModName), such as "SuperChef_BetterCupcakes". This has the best chance of not potentially conflicting with any other mod.
# After clicking OK, your script will automatically open. Hit CTRL+S to automatically save this script. Scripts with unsaved changes display and asterisk (*) next to their name.

==== Tip: Story Script Naming ====
----
Goals in the story are ran in alphabetical order. This is important to keep in mind if you use a particular story goal as a sort of "top-level" script that has methods and databases your other goals reference to.

With proper naming, you can control the order your scripts are run. For example, naming your top-level goal "WT_FS__Main", and your second goal "WT_FS_Skills" ensures "WT_FS__Main" will always run before "WT_FS_Skills".
[[File:FirstStoryScript_ScriptOrder.png|thumb|WT_FS__Main will always run before WT_FS_Skills.]]

=== Completing the Parent Goal ===
----
Parent goals need to "complete" before their sub-goals will run. This is done by calling "GoalCompleted;" within the parent script. We have a few options for how to go about this:

==== Completion Events ====
----
The following events are recommended to use for completing your parent goals:
; [[Osiris/API/GameStarted|GameStarted]]
: Thrown when a level has been loaded and is ready at both the server and client side. This will ensure all the base game scripts have already initialized.
; [[Osiris/API/RegionStarted|RegionStarted]]
: Thrown when the level has been loaded and is ready at the server side, but not yet at the client side.

Both of these events can be used with specific level names, as a way to make your goal only complete once that level is loaded (as a way to create level-specific logic).

==== Example Goal Completion ====
----
Inside the KB section of your goal, enter the following:
<pre>
IF
GameStarted(_Level, _EditorMode)
AND
StringConcatenate("[WT_FS] WikiTutorial_FirstStory has initialized. Level[", _Level, _Str1)
AND
StringConcatenate(_Str1, "] EditorMode(", _Str2)
AND
IntegertoString(_EditorMode, _ModeStr)
AND
StringConcatenate(_Str2, _ModeStr, _Str3)
AND
StringConcatenate(_Str3, ")", _Message)
THEN
DebugBreak(_Message);
GoalCompleted;
</pre>
# Save, then select "File -> Generate Definitions, Build and Reload".
# Minimize the story editor, then clear the message log by clicking "Clear".
# Load a level in the main editor. Inside the message log, you should see the message we added with DebugBreak.
[[File:FirstStoryScript_ParentGoalComplete.png|thumb|The debug message appears in the message log once the game is started.]]

===== Standard Goal Completion =====
----
For a regular approach, without any debug messages or string combining, use this:
<pre>
IF
GameStarted(_,_)
THEN
GoalCompleted;
</pre>
In this code block, the variables for _Level and _EditorMode are underscores, which means we're ignoring their values.

=== Adding a Sub-Goal ===
----
With the parent goal completing properly, sub-goals that are parented to the previous goal will now run.

==== Creating a Sub-Goal ====
----
Let's create a basic script that will display some text when a skill is cast.

# Double click on your parent goal to have it selected.
#* Currently, there's a bug where not having your parent goal open may cause a sub-item created to not properly parent under the right goal. If this happens, simply click and drag the new goal to your parent goal, and it should move underneath it.
# Click "Add New Sub Item...", then name it something appropriate, like "WikiTutorial_FirstStory_Skills".
# Save the new script (CTRL+S).

==== Creating a Rule ====
----
In the KB section of our new script, add the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Good job!");
CharacterResetCooldowns(_Character);
</pre>

This rule will run when the player casts "Encourage", displaying some text, and resetting their cooldowns. The Encourage skill is added automatically to the player if they lack it.

# Save, then "Generate Definitions and Build".
# In the main editor, select "File -> Reload Level and story".
# Hit the "Switch Game/Editor" button to get in-game. [[File:FirstStoryScript_GameEditorButton.png|thumb|Click this button to switch between game and editor mode.]]
# In whatever level you're working in, your provided dummy character should spawn and be given the Encourage skill.
# Cast the skill to test that your script is working properly.
[[File:FirstStoryScript_SkillCast_Result.png|thumb|Our script in action.]]

===== Notes =====
----
'''HTML Font Formatting'''
* HTML font formatting can be used in DisplayText, CharacterStatusText, and in various text entries (skill descriptions, status names/descriptions, book text, and more).

'''SkillCast '''
* This event runs when the skill's animation reaches the CastTextEvent value specified by the skill stats (which is "cast" in most cases).
* The textkey "cast" is a common textkey used in skill cast animations.
* To view the textkeys present in an animation, open it within the [[Content_browser|Resource Manager]].
* Example: Open the resource manager and search for the "Humans_Hero_Female_ABC_Skill_Cast_Aoe_Air_01_Cast" animation under the Shared folder. Double click on the resource to open the animation preview to see the different textkeys. [[File:FirstStoryScript_SkillCast_Textkey.png|thumb|The cast textkey.]]

'''DB_IsPlayer'''
* This is a base game database that is populated with all the current player characters when the game is started.
* By passing in the _Character value from the event parameters to DB_IsPlayer, we're matching the character against the database of player characters, to have the following code only run if the caster is a player-controlled character.
* Using DB_IsPlayer as an event makes the subsequent code run when a character is added to the DB_IsPlayer database.

== Taking the Script Further ==
Now that we have a basic script heirarchy working, let's take the script further.

=== Randomization ===
----
We can add randomization to the displayed text in our previous script to make the result more interesting.

We'll do this by creating a custom procedure.

;Procedure Tips:
: Procedures are declared with a "PROC" at the top of the block, and follow the same flow as a rule.
: Parameters for a procedure can be customized. You must declare their type.
: Procedures are called within the "call" section of a rule or a custom query.

Add this to the INIT section:
<pre>
//DB_WikiTutorial_FirstStory_RandomText(_Ran, _Text, _FontColor, _FontSize)
DB_WikiTutorial_FirstStory_Skills_RandomText(0, "Woo!", "00CED1", "23");
DB_WikiTutorial_FirstStory_Skills_RandomText(1, "Good job!", "00FF00", "30");
DB_WikiTutorial_FirstStory_Skills_RandomText(2, "I did it!", "DEB887", "20");
DB_WikiTutorial_FirstStory_Skills_RandomText(3, "I'm da best!", "A52A2A", "26");
</pre>

Change the code in the KB section to the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

PROC
WikiTutorial_FirstStory_Skills_DisplayRandomMessage((CHARACTERGUID)_Character)
AND
Random(4, _Ran)
AND
DB_WikiTutorial_FirstStory_Skills_RandomText(_Ran, _Text, _FontColor, _FontSize)
AND
StringConcatenate("", _Str4)
AND
StringConcatenate(_Str4, _Text, _Str5)
AND
StringConcatenate(_Str5, "", _Message)
AND
IntegertoString(_Ran, _RanStr)
AND
StringConcatenate("[WT_FS] Rolled a ", _RanStr, _DebugMessage)
THEN
DisplayText(_Character, _Message);
DebugBreak(_DebugMessage);

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload".
# Switch back to the main editor and hit the play button to get in-game.
# Cast the Encourage skill a few times in game mode to ensure the script is working properly. You should see the different messages, font colors, and font sizes.

===== Notes =====
----
'''Procedures'''
* WikiTutorial_FirstStory_Skills_DisplayRandomMessage is a custom subroutine call, called a PROC. By splitting our message logic off into a separate procedure, this ensures the calls for this rule are ran regardless of the result of our message logic (so CharacterResetCooldowns will always run if a player casts this skill). This also allows us to use this procedure elsewhere, and possible extend it further.

'''Databases'''
* We create our "RandomText" settings in the INIT section by using a database we create, called "DB_WikiTutorial_FirstStory_Skills_RandomText". Using databases in this way is a powerful way to design your script logic in a way that is extensible.

'''[[Osiris/API/Random|Random]]'''
* [[Osiris/API/Random|Random]] returns a random integer value between 0 and (_Modulo - 1). Since our DB_WikiTutorial_FirstStory_Skills_RandomText has 4 entries, we want our random number to be between 0 and 3, so we use 4 as our _Modulo.

=== Using Queries ===
----
Mastering queries is essential for creating complex conditions for your rules. "OR" logic is done within Osiris with multiple rules, subscribing to the same events, that look for different conditions through the use of queries.

Let's add to our skills script. Add this to the KB section, so your SkillCast rules look like this:

<pre>
IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
NOT DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Win... Please! Ahhhh!");
ApplyStatus(_Character, "FEAR", 1.0, 1);
</pre>

By simpling adding a NOT before our database check, our second rule will now run on any character (who's not a player) that casts Encourage, and apply fear. You can test this by loading an inherited level that contains some human enemies, or adding human enemies yourself to your test level.

=== Creating a Custom Query ===
----
Taking this idea further, we'll create a custom query.

Custom queries are defined with the keyword "QRY" at the top of a block, and follow the same flow as a rule.

Add the following code to your KB section:

<pre>
QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "HUMAN", 1)
THEN
DB_NOOP(1);

QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "DWARF", 1)
THEN
DB_NOOP(1);
</pre>

By adding two query blocks with the same name, we're effectively adding an "OR" condition. This query will evaluate as true if the character is tagged as either a human or a dwarf.

"DB_NOOP(1);" is a dummy database fact. Since rules must have a call, DB_NOOP is used to have a rule succeed without using any actual calls.

==== Implementing the Custom Query ====
----

Below our query code, in the KB section, add the following:
<pre>
IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Perception_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Perception_Potion");

IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
NOT WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Constitution_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Constitution_Potion");

IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload". Since we added a query and another database, we must generate the definitions again.
# Go in-game and test out the changes by casting Encourage on an human or dwarf (it will work on yourself as well).

===== Notes =====
----
'''NOT'''
* By adding two rules for the same event, and checking for the opposite of our query, we're effectively adding an OR condition to this event.

'''CharacterConsume/CharacterUnconsume'''
* Since CharacterConsume returns a value, it's a query instead of a call. We store the out value from the query (_Handle) in a database to later unconsume the potion effect when ENCOURAGED ends.

'''Removing Database Entries'''
* When unconsuming the potion handle, notice we also remove that entry from the database by calling "NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);" as a call. Using NOT before a database entry (in the call section) removes that entry.
* By using DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion) in the query section, the _Handle and _Potion value is returned with all entries that match the value we pass in (_Character), effectively unconsuming every potion handle we added for that character to the database.

=== Using a Query as a Subroutine ===
----
While queries can be used as conditions, they can also be used to call specific procedures/calls before the main rule reaches that section of the flow.

Let's try a simple example that runs when we unconsume a potion. Change our status removed event code to this:

<pre>
IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_ZombieCheck(_Character)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "UNDEAD", 1)
AND
CharacterGetDisplayName(_Character, _, _Name)
AND
StringConcatenate("[WT_FS] ", _Name, _Str1)
AND
StringConcatenate(_Str1, " is a zombie! Ahh! Burn it!", _Message)
THEN
ApplyStatus(_Character, "BURNING", 1.0);
DebugBreak(_Message);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
THEN
DB_NOOP(1);
</pre>

Which this, our query will apply burning if the character is tagged as UNDEAD. Note how we added a second QRY rule that always evaluates as true - this is to keep the rest of our rule in the CharacterStatusRemoved event running, undead or not.

Practically speaking, using queries as subroutines is ideal when:
* You need specific calls/procedures to run before iterating through a database. Calling your query before retrieving variables from a database ensures that those calls will only run once.
* You need to debug a rule to ensure it reaches a certain section of the conditions. If you're not sure if a specific condition is passing, adding a query with a DebugBreak message right before/after it is a good way to debug that situation.

== Bonus Tips ==

* In the story editor, select "File -> Open Story Header" for a list of all available events, queries, and calls. Heavily reference this file when you find yourself unsure if a specifc method exists, as not all methods appear in the auto-complete.

* If you use databases to store global mod settings, and your mod users have played with that mod, changing that information post-mod install will not automatically remove that data from existing saves - you need to handle this update internally within your mod.
** More on implementing an update system here: [[Osiris_Tips#Updating_Databases|Manual Mod Updates]].

* By using custom procedures and queries, you can reduce your rule redundancy and extend desired calls/conditions to multiple rules.

* To make your life with Osiris easier, wrap your rule blocks in regions with the following:
<pre>
//REGION MY_REGION_NAME

//END_REGION
</pre>
* In the story editor, right click inside your script sections (INIT, KB, or EXIT) and "Expand All" or "Collapse All" to expand/collapse all regions, respectively.

* Procedures can be called from the EXIT and INIT section of scripts.

* Use the INIT section of your scripts as a way to store commented references to your databases. As an example from our previous script, placing this inside your INIT section is a good way to remember such a database exists (since we don't initialize it in the INIT section):
<pre>
//DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
</pre>
Then, when you wish to use this database, you have a quick way to copy/paste that code into other sections of your script.

[[Category:Osiris]]

Osiris Tips and Examples

2017-12-21T11:17:44Z

LaughingLeader:

The following is a collection of practical examples and tips that will aid in your journey to learn how to power your mod through story script usage.

== Rule Flow ==
Story scripts run on "rules". Every frame, Osiris will evaluate the rules for every running story goal.

The flow of every rule is:
<pre>
IF
Event
AND
Query
THEN
Call();
</pre>

Queries between the event and the call section of a rule are optional. You can simply go from event to call if you desire:
<pre>
IF
Event
THEN
Call();
</pre>

Queries are both gatekeepers to the call section, and a way to retrieve information.

== Databases ==
Databases can be used to store specific data (such as characters entering a trigger), or as a way to story settings used in your rules.

=== Database Use Within Rules ===
----
Databases may be used in all three rule sections:
;IF
:Databases used in the event section will run when a new entry is added. It will never run when an entry is removed.
;AND
:Databases used in the query section can be used to evaluate if an entry exists, does not exist, or as a way to run subsequent lines on the whole database, or entries that match a particular value.
;THEN
:In the call section, new entries are added to databases, or existing entries are removed (i.e. NOT DB_MyDatabase(_VariableA, _VariableB).

=== Database Queries ===
----
Used as a query, databases are powerful ways to retrieve data, or create complex conditions.
==== Databases Queries for Conditions ====
Passing values into Databases is an easy way to create dynamic conditions:
<pre>
IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You're been a bad guy this year! Coal for you!");
ItemTemplateAddTo("QUEST_Coal_df215b50-e18f-4527-a2ac-e7eec6cba576", _Target, 1);

IF
CharacterUsedSkillOnTarget(_Santa, (CHARACTERGUID)_Target, "Target_GiveGift", _)
AND
NOT DB_Santa_NaughtyList(_Target)
THEN
DisplayText(_Santa, "Ho ho ho! You've been good this year! Have a present!");
ItemTemplateAddTo("QUEST_Present_29f926ff-bfb3-4c0f-b4a4-e356d6b88cf0", _Target, 1);
</pre>
This example assumes that characters were already added to a database, and uses it to determine which item to give to a target, when Santa casts his skill.

==== Databases Queries for Data Retrieval ====
Now we'll use a database to iterate through a number of targets dynamically.
<pre>
IF
SkillCast(_Santa, "Shout_SpreadCheer", _)
AND
DB_Santa_NiceList(_Target)
THEN
ApplyStatus(_Target, "HOLIDAY_CHEER", -1.0);
PlayEffect(_Target, "RS3_FX_Santa_HolidayExplosion_01");
</pre>
Since _Target was never set beforehand, it acts as an out variable, calling subsequent lines on each entry added to DB_Santa_NiceList.

=== Database Gotchas ===
----
While databases are a powerful way to create complex scripting logic, there are a few crucial concepts to keep in mind:
* Unless you take steps to clear it out, database data persists in existing saves, even if you no longer support a particular database in a later version of your mod.
* Osiris may have issues with databases containing more than 6 columns.
* Inherited types from GUIDSTRING (CHARACTERGUID, ITEMGUID, TRIGGERGUID) need to be declared once in a database, to properly set the type.

=== System Methods ===
----
A few system methods, hidden from auto-complete, exist to enhance database use:

;call [[Osiris/API/SysClear|SysClear]]((STRING)_Predicate, (INTEGER)_Arity)
* Predicate is the name of the database ("DB_MyDatabase"), while arity are the number of columns (DB_MyDatabase("Apples", 10) would be 2 arity).
* SysClear provides an ideal way of clearing older saves of old databases from previous version of your mod, or paving the way for a full reset of a database.
;query [[Osiris/API/SysCount|SysCount]]([in](STRING)_Predicate,[in](INTEGER)_Arity,[out](INTEGER)_Count)
* SysCount is a way to count the entries in a database. This is especially useful when creating conditions in reference to a database that is added to dynamically through gameplay (i.e. the number of players inside a trigger, the number of characters who had a particular status applied, and so on).

=== Cross-Database Referencing ===
----
Using a consistent entry across multiple databases allows you to utilize various databases to dynamically enhance your mod.

==== Adventure Mod Example ====
----

First, we'll create a few databases to store some settings.

INIT:
<pre>
//DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
DB_MyAdventureMod_Triggers("MyLevel_FrontDoor", (TRIGGERGUID)TRIGGERGUID_S_MyLevel_DoorEntry_b5ab6a49-b015-4908-8f49-7b152d6c5d30);
DB_MyAdventureMod_Triggers("MyLevel_HallwayAmbush", TRIGGERGUID_S_MyLevel_Ambush1_1d089d37-fc5e-4cc6-807e-51d0535dc0cc);
DB_MyAdventureMod_Triggers("MyLevel_GolemBoss", TRIGGERGUID_S_MyLevel_Boss1_0a009ed0-61f5-4670-9d26-1417ebf02922);

//DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_FrontDoor", "12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_HallwayAmbush","12f866ca-a2e9-4da2-831c-d7d031638160");
DB_MyAdventureMod_TriggerAtmosphere("MyLevel_GolemBoss","2052f790-d2d7-4cf7-95f0-4de478e98d28");

//DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonLeader_584db8ce-8dcf-4906-bc6f-e51eb057de08");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonMage1_61bf204e-ba2e-412f-ac86-e132a3930105");
DB_MyAdventureMod_TriggerSpawns("MyLevel_HallwayAmbush", "MyMod_SkeletonRanger1_f7bd3244-e1e7-4079-ac95-fef6145a236e");
</pre>

By using multiple databases together, we now only need to worry about the TRIGGERGUID in one database, while the others rely on the string name. This is easier to deal with in the long run.

Next, we'll look for when a player enters one of these triggers, and store when it first activates.

KB:
<pre>
IF
CharacterEnteredTrigger((CHARACTERGUID)_Character, (TRIGGERGUID)_TriggerID)
AND
DB_IsPlayer(_Character)
AND
DB_MyAdventureMod_Triggers(_TriggerName, _TriggerID)
AND
NOT DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
THEN
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID);
</pre>

We'll then look for when a trigger is added to the "TriggerActivated" database, and create rules for changing the atmosphere and spawning enemies.

KB:
<pre>
IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerAtmosphere(_TriggerName, _Atmosphere)
THEN
TriggerSetAtmosphere(_TriggerID, _Atmosphere);

IF
DB_MyAdventureMod_TriggerActivated(_TriggerName, _TriggerID)
AND
DB_MyAdventureMod_TriggerSpawns(_TriggerName, _CharacterTemplate)
AND
GetRandomPositionInTrigger(_TriggerID, _X, _Y, _Z)
AND
CharacterCreateAtPosition(_X, _Y, _Z, _CharacterTemplate, 1, _Enemy)
THEN
DB_MyAdventureMod_SpawnedEnemies(_TriggerName, _Enemy);
</pre>

We now have a good basis for changing atmosphere, spawning enemies, and tracking which enemies were spawned. This could easily be extended to support sounds, dialogs that need to start, and more.

=== Updating Databases ===
----
When you use databases as a way to store settings, this information will persist on existing saves unless you purposefully remove it.

As an example, say you have a script like this:

'''MyMod_ExampleScript.txt'''

INIT:
<pre>
//DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_A_7e24b009-f2bc-47c0-a635-b776407833aa", 1);
</pre>

KB:
<pre>
IF
SkillCast(_Character, _Skill, _)
AND
DB_MyMod_Skill_ItemCreation(_Skill, _ItemTemplate, _Count)
THEN
ItemTemplateAddTo(_ItemTemplate, _Character, (INTEGER)_Count, 1);
</pre>
Later, after releasing your mod, you decide that you want "Target_MyMod_DiamondTransmutation" to spawn a different diamond item template. To properly do this, in a way that won't spawn the previous template for an existing save, you need to delete the previous entry from the database.

==== Database Update Example ====
----
One way to implement internal mod "updates" for your databases is by storing a "mod version" in a database, and checking against this version when a save is loaded.

In a top-level goal (one that will run before all others), enter the following:

'''MyMod__MainScript.txt'''
INIT:
<pre>
//The current mod version.
DB_MyMod_Version("1.1.1");
</pre>

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
DebugBreak("[MyMod] Mod update detected. Updating databases.");

IF
SavegameLoaded(_,_,_,_)
AND
NOT DB_MyMod_Version("1.1.1")
THEN
MyMod_Update_UpdateDatabases();
SysClear("DB_MyMod_Version", 1); // Clear existing mod versions.
DB_MyMod_Version("1.1.1");
</pre>

"MyMod_Update_UpdateDatabases()" is a custom PROC we've created to handle updating databases. In the individual goals that we want to update databases for, creating new rules with the same PROC name will run our PROC when the top-level goal's PROC is triggered:

'''MyMod_ExampleScript.txt'''

KB:
<pre>
PROC
MyMod_Update_UpdateDatabases()
THEN
SysClear("DB_MyMod_Skill_ItemCreation", 3);
DB_MyMod_Skill_ItemCreation("Target_MyMod_DiamondTransmutation", "LOOT_Gems_Diamond_B_Black_VW_94933c36-393e-4077-abec-95e04341fc92", 1);
</pre>

Now when the main script triggers the update, our second script will also run its own update, clearing out the previous database data and adding our new settings.

=== Updating Mods: Beyond Databases ===
----
Beyond changing databases, updating your mod can be a more extensive ordeal, as there's a variety of factors to keep in mind. More on that here: [[Modding:_Versioning|Modding: Versioning]].

== Further Information ==
More in-depth information on Osiris can be read on the following pages:
* [[Osiris Overview]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]
* [[Your First Story Script]]
* [[:Category:Osiris_APIs|Osiris APIs]]

[[Category:Osiris]]

Your First Story Script

2017-12-21T11:15:43Z

LaughingLeader: Updated page link.

Note: this tutorial assumes you have already created a mod project. More on that here: [[Project browser]]. For the purposes of this tutorial, we will be using a basic Addon project that inherits from Story and targets Story.

== Overview ==
Story scripts are a way to implement global logic with your mod, in a way that is compatible with other mods. Before we get started, some basic tips to keep in mind:

=== Starting Tips ===
----
* When opening the story editor in a new project, always generate definitions (File -> Generate Definitions) and exit/re-open the story editor. This will generate the files necessary for auto-complete and syntax highlighting.

* Prefix your goals (a.k.a. your script files), databases, queries, and procs in a way that will make then unique and least likely to conflict with other mods. For example, if our mod is called "Better Cupcakes", and our username is "SuperChef", we'd prefix our mod entries with SCBC, or SC_BetterCupcakes, or some combination of the two.
** This idea should also be used for entries in the stats editor, as multiple entries with the same name will conflict.

== Recommended Reading ==
* [[Osiris Overview]]
* [[Osiris Design Patterns]]
* [[Osiris Gotchas]]
* [[Osiris_Tips_and_Examples|Osiris Tips and Examples]]
* [[:Category:Osiris_APIs|Osiris APIs]]

== Implementing a Basic Story Script ==
=== Getting Started ===
----
# Open the [[Story editor]] by clicking the icon that looks like a book ([[File:StoryEditor_Icon.png|24px]]) under the "Editors" section, at the top-right of the Divinity Engine 2 editor.
# Inside the story editor, Click "File -> Generate Definitions and Build" on the top left.
#* This is an important step in generating the appropriate files. Any time you create new definitions (databases, PROCs, or queries), you need to generate definitions.
#* Building is as equally important, as your changes won't compile until you build.
#* Reloading the story is necessary to see your changes in-game. You can either do this from the story editor ("File -> Reload Story"), or from the main editor with "File -> Reload Level and Story".
# Close the story editor and open it again to essentially reload the syntax highlighting and auto-complete features.

=== Creating a Parent Goal ===
----
For organizational purposes, creating a parent story goal is recommended.
# Inside the story editor, at the goal list on the left, right click and select "Add New Item".
[[File:FirstStoryScript_AddNewItem.png|thumb]]
# Name this script something unique to your mod in a prefix format (Username_ModName), such as "SuperChef_BetterCupcakes". This has the best chance of not potentially conflicting with any other mod.
# After clicking OK, your script will automatically open. Hit CTRL+S to automatically save this script. Scripts with unsaved changes display and asterisk (*) next to their name.

==== Tip: Story Script Naming ====
----
Goals in the story are ran in alphabetical order. This is important to keep in mind if you use a particular story goal as a sort of "top-level" script that has methods and databases your other goals reference to.

With proper naming, you can control the order your scripts are run. For example, naming your top-level goal "WT_FS__Main", and your second goal "WT_FS_Skills" ensures "WT_FS__Main" will always run before "WT_FS_Skills".
[[File:FirstStoryScript_ScriptOrder.png|thumb|WT_FS__Main will always run before WT_FS_Skills.]]

=== Completing the Parent Goal ===
----
Parent goals need to "complete" before their sub-goals will run. This is done by calling "GoalCompleted;" within the parent script. We have a few options for how to go about this:

==== Completion Events ====
----
The following events are recommended to use for completing your parent goals:
; [[Osiris/API/GameStarted|GameStarted]]
: Thrown when a level has been loaded and is ready at both the server and client side. This will ensure all the base game scripts have already initialized.
; [[Osiris/API/RegionStarted|RegionStarted]]
: Thrown when the level has been loaded and is ready at the server side, but not yet at the client side.

Both of these events can be used with specific level names, as a way to make your goal only complete once that level is loaded (as a way to create level-specific logic).

==== Example Goal Completion ====
----
Inside the KB section of your goal, enter the following:
<pre>
IF
GameStarted(_Level, _EditorMode)
AND
StringConcatenate("[WT_FS] WikiTutorial_FirstStory has initialized. Level[", _Level, _Str1)
AND
StringConcatenate(_Str1, "] EditorMode(", _Str2)
AND
IntegertoString(_EditorMode, _ModeStr)
AND
StringConcatenate(_Str2, _ModeStr, _Str3)
AND
StringConcatenate(_Str3, ")", _Message)
THEN
DebugBreak(_Message);
GoalCompleted;
</pre>
# Save, then select "File -> Generate Definitions, Build and Reload".
# Minimize the story editor, then clear the message log by clicking "Clear".
# Load a level in the main editor. Inside the message log, you should see the message we added with DebugBreak.
[[File:FirstStoryScript_ParentGoalComplete.png|thumb|The debug message appears in the message log once the game is started.]]

===== Standard Goal Completion =====
----
For a regular approach, without any debug messages or string combining, use this:
<pre>
IF
GameStarted(_,_)
THEN
GoalCompleted;
</pre>
In this code block, the variables for _Level and _EditorMode are underscores, which means we're ignoring their values.

=== Adding a Sub-Goal ===
----
With the parent goal completing properly, sub-goals that are parented to the previous goal will now run.

==== Creating a Sub-Goal ====
----
Let's create a basic script that will display some text when a skill is cast.

# Double click on your parent goal to have it selected.
#* Currently, there's a bug where not having your parent goal open may cause a sub-item created to not properly parent under the right goal. If this happens, simply click and drag the new goal to your parent goal, and it should move underneath it.
# Click "Add New Sub Item...", then name it something appropriate, like "WikiTutorial_FirstStory_Skills".
# Save the new script (CTRL+S).

==== Creating a Rule ====
----
In the KB section of our new script, add the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Good job!");
CharacterResetCooldowns(_Character);
</pre>

This rule will run when the player casts "Encourage", displaying some text, and resetting their cooldowns. The Encourage skill is added automatically to the player if they lack it.

# Save, then "Generate Definitions and Build".
# In the main editor, select "File -> Reload Level and story".
# Hit the "Switch Game/Editor" button to get in-game. [[File:FirstStoryScript_GameEditorButton.png|thumb|Click this button to switch between game and editor mode.]]
# In whatever level you're working in, your provided dummy character should spawn and be given the Encourage skill.
# Cast the skill to test that your script is working properly.
[[File:FirstStoryScript_SkillCast_Result.png|thumb|Our script in action.]]

===== Notes =====
----
'''HTML Font Formatting'''
* HTML font formatting can be used in DisplayText, CharacterStatusText, and in various text entries (skill descriptions, status names/descriptions, book text, and more).

'''SkillCast '''
* This event runs when the skill's animation reaches the CastTextEvent value specified by the skill stats (which is "cast" in most cases).
* The textkey "cast" is a common textkey used in skill cast animations.
* To view the textkeys present in an animation, open it within the [[Content_browser|Resource Manager]].
* Example: Open the resource manager and search for the "Humans_Hero_Female_ABC_Skill_Cast_Aoe_Air_01_Cast" animation under the Shared folder. Double click on the resource to open the animation preview to see the different textkeys. [[File:FirstStoryScript_SkillCast_Textkey.png|thumb|The cast textkey.]]

'''DB_IsPlayer'''
* This is a base game database that is populated with all the current player characters when the game is started.
* By passing in the _Character value from the event parameters to DB_IsPlayer, we're matching the character against the database of player characters, to have the following code only run if the caster is a player-controlled character.
* Using DB_IsPlayer as an event makes the subsequent code run when a character is added to the DB_IsPlayer database.

== Taking the Script Further ==
Now that we have a basic script heirarchy working, let's take the script further.

=== Randomization ===
----
We can add randomization to the displayed text in our previous script to make the result more interesting.

We'll do this by creating a custom procedure.

;Procedure Tips:
: Procedures are declared with a "PROC" at the top of the block, and follow the same flow as a rule.
: Parameters for a procedure can be customized. You must declare their type.
: Procedures are called within the "call" section of a rule or a custom query.

Add this to the INIT section:
<pre>
//DB_WikiTutorial_FirstStory_RandomText(_Ran, _Text, _FontColor, _FontSize)
DB_WikiTutorial_FirstStory_Skills_RandomText(0, "Woo!", "00CED1", "23");
DB_WikiTutorial_FirstStory_Skills_RandomText(1, "Good job!", "00FF00", "30");
DB_WikiTutorial_FirstStory_Skills_RandomText(2, "I did it!", "DEB887", "20");
DB_WikiTutorial_FirstStory_Skills_RandomText(3, "I'm da best!", "A52A2A", "26");
</pre>

Change the code in the KB section to the following:
<pre>
IF
DB_IsPlayer(_Player)
AND
CharacterHasSkill(_Player, "Shout_InspireStart", 0)
THEN
CharacterAddSkill(_Player, "Shout_InspireStart");
DebugBreak("[WT_FS] Added Encourage to player.");

PROC
WikiTutorial_FirstStory_Skills_DisplayRandomMessage((CHARACTERGUID)_Character)
AND
Random(4, _Ran)
AND
DB_WikiTutorial_FirstStory_Skills_RandomText(_Ran, _Text, _FontColor, _FontSize)
AND
StringConcatenate("", _Str4)
AND
StringConcatenate(_Str4, _Text, _Str5)
AND
StringConcatenate(_Str5, "", _Message)
AND
IntegertoString(_Ran, _RanStr)
AND
StringConcatenate("[WT_FS] Rolled a ", _RanStr, _DebugMessage)
THEN
DisplayText(_Character, _Message);
DebugBreak(_DebugMessage);

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload".
# Switch back to the main editor and hit the play button to get in-game.
# Cast the Encourage skill a few times in game mode to ensure the script is working properly. You should see the different messages, font colors, and font sizes.

===== Notes =====
----
'''Procedures'''
* WikiTutorial_FirstStory_Skills_DisplayRandomMessage is a custom subroutine call, called a PROC. By splitting our message logic off into a separate procedure, this ensures the calls for this rule are ran regardless of the result of our message logic (so CharacterResetCooldowns will always run if a player casts this skill). This also allows us to use this procedure elsewhere, and possible extend it further.

'''Databases'''
* We create our "RandomText" settings in the INIT section by using a database we create, called "DB_WikiTutorial_FirstStory_Skills_RandomText". Using databases in this way is a powerful way to design your script logic in a way that is extensible.

'''[[Osiris/API/Random|Random]]'''
* [[Osiris/API/Random|Random]] returns a random integer value between 0 and (_Modulo - 1). Since our DB_WikiTutorial_FirstStory_Skills_RandomText has 4 entries, we want our random number to be between 0 and 3, so we use 4 as our _Modulo.

=== Using Queries ===
----
Mastering queries is essential for creating complex conditions for your rules. "OR" logic is done within Osiris with multiple rules, subscribing to the same events, that look for different conditions through the use of queries.

Let's add to our skills script. Add this to the KB section, so your SkillCast rules look like this:

<pre>
IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
DB_IsPlayer(_Character)
THEN
WikiTutorial_FirstStory_Skills_DisplayRandomMessage(_Character);
CharacterResetCooldowns(_Character);

IF
SkillCast(_Character, "Shout_InspireStart", _)
AND
NOT DB_IsPlayer(_Character)
THEN
DisplayText(_Character, "Win... Please! Ahhhh!");
ApplyStatus(_Character, "FEAR", 1.0, 1);
</pre>

By simpling adding a NOT before our database check, our second rule will now run on any character (who's not a player) that casts Encourage, and apply fear. You can test this by loading an inherited level that contains some human enemies, or adding human enemies yourself to your test level.

=== Creating a Custom Query ===
----
Taking this idea further, we'll create a custom query.

Custom queries are defined with the keyword "QRY" at the top of a block, and follow the same flow as a rule.

Add the following code to your KB section:

<pre>
QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "HUMAN", 1)
THEN
DB_NOOP(1);

QRY
WikiTutorial_FirstStory_QRY_CanApplyBonus((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "DWARF", 1)
THEN
DB_NOOP(1);
</pre>

By adding two query blocks with the same name, we're effectively adding an "OR" condition. This query will evaluate as true if the character is tagged as either a human or a dwarf.

"DB_NOOP(1);" is a dummy database fact. Since rules must have a call, DB_NOOP is used to have a rule succeed without using any actual calls.

==== Implementing the Custom Query ====
----

Below our query code, in the KB section, add the following:
<pre>
IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Perception_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Perception_Potion");

IF
CharacterStatusApplied(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
NOT WikiTutorial_FirstStory_QRY_CanApplyBonus(_Character)
AND
CharacterConsume(_Character, "POTION_Minor_Constitution_Potion", _Handle)
THEN
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, "POTION_Minor_Constitution_Potion");

IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);
</pre>

# Save, then "File -> Generate Definitions, Build and Reload". Since we added a query and another database, we must generate the definitions again.
# Go in-game and test out the changes by casting Encourage on an human or dwarf (it will work on yourself as well).

===== Notes =====
----
'''NOT'''
* By adding two rules for the same event, and checking for the opposite of our query, we're effectively adding an OR condition to this event.

'''CharacterConsume/CharacterUnconsume'''
* Since CharacterConsume returns a value, it's a query instead of a call. We store the out value from the query (_Handle) in a database to later unconsume the potion effect when ENCOURAGED ends.

'''Removing Database Entries'''
* When unconsuming the potion handle, notice we also remove that entry from the database by calling "NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);" as a call. Using NOT before a database entry (in the call section) removes that entry.
* By using DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion) in the query section, the _Handle and _Potion value is returned with all entries that match the value we pass in (_Character), effectively unconsuming every potion handle we added for that character to the database.

=== Using a Query as a Subroutine ===
----
While queries can be used as conditions, they can also be used to call specific procedures/calls before the main rule reaches that section of the flow.

Let's try a simple example that runs when we unconsume a potion. Change our status removed event code to this:

<pre>
IF
CharacterStatusRemoved(_Character, "ENCOURAGED", (CHARACTERGUID)_Causee)
AND
WikiTutorial_FirstStory_QRY_ZombieCheck(_Character)
AND
DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
THEN
CharacterUnconsume(_Character, _Handle);
NOT DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
AND
IsTagged(_Character, "UNDEAD", 1)
AND
CharacterGetDisplayName(_Character, _, _Name)
AND
StringConcatenate("[WT_FS] ", _Name, _Str1)
AND
StringConcatenate(_Str1, " is a zombie! Ahh! Burn it!", _Message)
THEN
ApplyStatus(_Character, "BURNING", 1.0);
DebugBreak(_Message);

QRY
WikiTutorial_FirstStory_QRY_ZombieCheck((CHARACTERGUID)_Character)
THEN
DB_NOOP(1);
</pre>

Which this, our query will apply burning if the character is tagged as UNDEAD. Note how we added a second QRY rule that always evaluates as true - this is to keep the rest of our rule in the CharacterStatusRemoved event running, undead or not.

Practically speaking, using queries as subroutines is ideal when:
* You need specific calls/procedures to run before iterating through a database. Calling your query before retrieving variables from a database ensures that those calls will only run once.
* You need to debug a rule to ensure it reaches a certain section of the conditions. If you're not sure if a specific condition is passing, adding a query with a DebugBreak message right before/after it is a good way to debug that situation.

== Bonus Tips ==

* In the story editor, select "File -> Open Story Header" for a list of all available events, queries, and calls. Heavily reference this file when you find yourself unsure if a specifc method exists, as not all methods appear in the auto-complete.

* If you use databases to store global mod settings, and your mod users have played with that mod, changing that information post-mod install will not automatically remove that data from existing saves - you need to handle this update internally within your mod.
** More on implementing an update system here: [[Osiris_Tips#Updating_Databases|Manual Mod Updates]].

* By using custom procedures and queries, you can reduce your rule redundancy and extend desired calls/conditions to multiple rules.

* To make your life with Osiris easier, wrap your rule blocks in regions with the following:
<pre>
//REGION MY_REGION_NAME

//END_REGION
</pre>
* In the story editor, right click inside your script sections (INIT, KB, or EXIT) and "Expand All" or "Collapse All" to expand/collapse all regions, respectively.

* Procedures can be called from the EXIT and INIT section of scripts.

* Use the INIT section of your scripts as a way to store commented references to your databases. As an example from our previous script, placing this inside your INIT section is a good way to remember such a database exists (since we don't initialize it in the INIT section):
<pre>
//DB_WikiTutorial_FirstStory_ConsumeHandles(_Character, _Handle, _Potion)
</pre>
Then, when you wish to use this database, you have a quick way to copy/paste that code into other sections of your script.

[[Category:Osiris]]

Talk:Osiris Tips

2017-12-21T11:14:44Z

LaughingLeader: LaughingLeader moved page Talk:Osiris Tips to Talk:Osiris Tips and Examples: Pairing Osiris tips with practical examples is really the main purpose of this page.

#REDIRECT [[Talk:Osiris Tips and Examples]]