Larian Studios Forums Divinity - Original Sin Divinity Original Sin - Mods Character and Item Scripts [Tutorial]

The story editor (Osiris System) is a very powerful tool. It has almost complete control over the game world and fully drives your story. But it does have at least one very big limitation. That is it can only affect global objects. For most users this means the little check box on the side bar of the editor -this means Osiris is allowed to interact with it. Modders may be tempted to program all the behavior of their characters in this one system. However if you have too many global entities in your game, Osiris will catch all the events they throw (that means every time does something mildly noteworthy) significantly affecting performance. Imagine if every villager in a city had to be processed every time they move which in a bustling city. It could slow down your game to the point of crippling it.
Another limitation of Osiris is it cannot make a character use a skill. This means something else needs to be used for the AI and non-global characters. This is where character and item scripts come in.

Character vs. Items
There are some minor but significant differences between Characters and Items. Characters can be in combat, have action points, movement speed (they can walk), and can use skills. Items on the other hand have a lot more freedom of whom by and how they are affected.

----------------------------------------------------------

Sections of Scripts
In a script there are several different major sections. Each has their own flavor of what they do and how they are used. Each major section begins with the major section title. They appear in purple. All but the INIT section can be mixed and matched.

INIT - initialization
A special section used once at the beginning of a script. In this section you will define what variables are to be maintained by each object with this script. These are more global variables that will be saved during a session (may be re-initialized upon loaded?).
The first variable is always (by convention?) <CHARACTER or ITEM>:__Me - This variable will allow the script to reference itself.
Other variables are prefaced with a '%'. Ex: INT:%Age
When you want to use this variable use %Age

EVENTS - Event based actions
Events are the most basic form of scripting. Essentially when something happens do this.
Format: begins each function with the EVENT keyword followed by a unique name (name should be separated by a space and no spaces should appear in the name). You may include a VARS block that defines variables that are only used and seem in this function (Note: these variables begin with '_' instead of '%'. Then there is the ON block, whenever any of the events in the block occurs do the actions. Finally the ACTIONS block is what actions are performed when the any of the events occur

BEHAVIOR - what it does
This major section deals with what actions an object will perform. This is the AI section essentially. Format: Each behavior begins with the REACTION keyword then the name of reaction followed by a coma and then a number (indicate priority). The higher the priority the more it will want to perform the reaction (zero or negative means it will not perform the action). (Note: there is a function setPriority which can be very useful changing behavior on the fly). On the following line you MUST then have the USAGE keyword followed by when the reaction is used (ie: COMBAT, ALL, PEACE, etc?. Next you may include a VARS block, same as an event function VARS block. Another block that is not necessary is CHECK which before doing the reaction it will perform these checks. If successful it will continue on and perform the ACTION block. The ACTIONS block performs actions which may include moving and using skills. Lastly the INTERRUPT block is optional but if an actions block fails for a specified reason do these actions (I know little of this block).

STORY - Can be told to do
This is the major section I know least about. As far as I am aware the only the story editor or dialogs may call SCRIPTFRAMES from this section to have objects perform certain tasks.
Each Script frame starts with keyword SCRIPTFRAME followed by the name.

------------------------------------------------------------

Adding scripts to your game

To add scripts to your game and make them usable takes a few steps. First step is to create an empty script file in script editor (small paper symbol with 1s and 0s on it, near the middle of your top bar). It should say ScriptDialog on the top of the window. You can create a new script by clicking the new button (blank paper symbol, left hand side of the icon bar). Name and choose the script type. Save the new script in your mod folder. Now you have a script, though it's not accessible to your game yet. For that to happen, we need to add it through the resource manager. In that window click on your mod folder and add a package, (little box with a + sign). I named mine Scripts you can rename this later. Now click on your new package (on left box in resource manager) and add a resource (top left corner of the top bar, looks like the resource symbol with a +). A new window should pop up and click Script. A small navigation window will open, navigate up to folder levels (up to public), and find your mod, then find the scripts folder inside. You should now see the script you made earlier. Open your script and name it (I recommend it being the same name as the file).
Your script is now in your game. Add it to a character or item by using the side bar (about 2/3 of the way down).
Note: I have noticed the need to restart the module in order for it to work properly. (load a different module then re-load your module)


-------------------------------------------------------

Keywords and Useful Tools

Variables
These are pieces of data that are stored and can be used and manipulated by your code. Each has a type (what kind of data is stored in them). The types changes what kind of operations can be performed on them. The types are
INT (integer counting numbers eg: 1,5,0,-100, etc)
FLOAT (floating point number 1.1,-5.3,1000.0,etc)
FLOAT3 (3 floats thrown together, used for position in game world)
CHARACTER (a specific character)
CHARACTERTEMPLATE (Template for a character in format: <name>_<GUID>)
More
Global Variable names defined in the INIT section begin with '%' local variables in a script function begin with '_'?

Comments
These are messages left by programmers that do not affect the program but are extremely useful in leaving notes about what each section does and how and why it's doing it. They can also be used to temporarily remove lines of code if you don't want to delete them so you may have them for later. Single line commenting is done with '//' everything after the slashes on that line will be commented out. Multi line commenting can be achieved with '/*' opens the comment and '*/' closes it. Comments are in green.

Conditions
Sometimes you need conditions to be met before other actions may occur, these include checking if character is alive, or invisible, etc Scripts use special syntax to make this work. After the name of the check (eg: IF, WHILE, CHECK) on the same line has in quotes how each condition is checked. For example: "c1&(c2|!c3)" means the first condition must be true and either the second condition must be true or the third condition must not be true in order to continue to the associated block of actions. '&' means and (both conditions must be true). '|' means either or both must be true. '!' Means negate the next statement (True becomes False and False becomes True). Something enclosed in parenthesis means evaluate this part first. Order of operations is from left to right (unsure order between & and |, so use '( )' ). Look up Boolean Algebra for more in depth information.

If/else statements
Must start with an IF have a THEN and end with an ENDIF. In this basic structure it would check the stuff in the IF block and if it passes performs actions in the following THEN block. You may also include any number of ELIF (else if) followed by another THEN block which would perform the checks in the ELIF block (if none of the previous IF or ELIF blocks were successful) and if successful would perform the following THEN block. You may also include one ELSE block after all ELIF (and IF) that executes the actions inside if none of the previous IF or ELIF(s) were successful.

While loops
When you want a set of actions to continue until certain conditions are not met use while loops. Must have a WHILE with conditions followed by DO set of actions and an ENDWHILE to close the loop.

Crtl + space
Pops up a drop down menu of what can be used to put in or finish where the cursor is. Extremely useful for learning all the possible function! This is especially useful since not all the same functions are available in one block/section

EXTERN
Keyword that may appear before variables in INIT section. These may be redefined on a case by case basis when you assign a script to an object (far right box will show up with have all extern variables that may be defined at start).

OVERRIDE (hypothesis)
Keyword that appears after the name of a function. It will allow you to use the same name as a previously defined function overriding it. Meaning it will always perform the override function instead of the non-override one.

#INCLUDE (hypothesis)
Keyword that may appear before the INIT section. Includes all the functions and variables of the included file (may only include 1 file?)

----------------------------------------------------------

The best way to learn is by doing and looking at Larian provided scripts for how they use certain function and scripts. DefaultCharacter is a good place to start.

Great job dude, this was a part of the editor i was completely unfamiliar with.