Divinity Engine Wiki
Advertisement
Under Construction: this article is very much a work in progress, collating various pieces of scripting information. Ultimately this information will be organised into a number of pages. Please don't expect it to make sense!

There are three? types of scripting in the Divinity Engine Toolkit: story scripting, which is done in the Story editor; character and item scripting, which is done in the Script editor; and dialog scripting, which is done in the Keyword editor. All three types use a syntax which is similar but is not the same.

Story scripting[]

Osiris is an event-based languages which means it only responds to events and will never do anything by itself.

Osiris only reacts to messages that get sent to it. While a player is playing the character or item scripts will generate these messages and send them to Osiris and Osiris decides if and how to react to them. These messages are called events.

Osiris can also send events to the game engine using "calls", for example GlobalSetEvent.

The way we can react to events is by rules. A rule (is very similar to a dialog condition) is a collection of one or more conditions. If all the conditions are met then it will execute the script that follows the condition. Rules are defined using IF and THEN.

Global Objects[]

Before you can use an object (character, item, etc.) in scripting it must be flagged as global (open side bar find the Global property and check it so it reads True)

Before use you must use the Generate Definitions menu option which causes Osiris to build/rebuild the list of global objects.

Goals[]

Goals are just files on your hard drive but it is a way to keep your scripting organised. Typically what we would do is make a goal for every quest so that the scripting for that quest is in one spot and not spread out over different files. Goals can have parents and children (show with + in the tree structure). Relationship can be crated by dragging a node onto another.

Goals have three sections: INIT, KB (knowledge base) and EXIT

  • INIT: where you do set up, assign dialogs etc. If a goal doesn't have a parent the INIT section is executed as soon as the game starts. If it does have a parent then the INIT section is only executed once the parent('s INIT section?) has completed.
  • KB: where you do most of your scripting, react to the events sent to Osiris
  • EXIT: clean up, remove things you don't need, etc.

Symbols[]

Regions:

ENDEXITSECTION
EXITSECTION
INITSECTION
KBSECTION

Keywords:

AND
IF
NOT
PROC
THEN

Data Types:

CHARACTER
INTEGER
ITEM
REAL
STRING
TRIGGER

Modifiers:

[in]
[out]

Method Types:

call
event
query
syscall
sysquery

Character and Item Scripting[]

Symbols[]

Directives:

#INCLUDE

Keywords:

ACTIONS
BEHAVIOUR
CHECK
DO
ELIF
ELSE
ENDIF
ENDWHILE
EVENT
EVENTS
EXTERN
IF
INIT
INTERRUPT
ON
REACTION
SCRIPTFRAME
STORY
THEN
USAGE
USING
VARS
WHILE

Data Types:

CHARACTER
CHARACTERTEMPLATE
COMPARE
COMPAREFUNC
DAMAGE
FIXEDSTRING
FLOAT
FLOAT3
INT
ITEM
POTION
RELATION
SKILL
STATUS
STRING
SURFACE
TRIGGER
WEAPON

Dialog Scripting[]

The only way for a dialog to communicate with Osiris is using flags: global flags or character flags

Conditions & Actions[]

In a dialog, conditions determine if a node, i.e. line, should be displayed and actions are executed either when the node is displayed (for an NPC line) or when the node is selected (for a PC line).

Symbols[]

Keywords:

ACTION
CHECK
CONDITION

Related Topics[]

Flags[]

Flags are arbitrary boolean values. Flags can be local and global. Global flags can be used in anywhere (i.e in dialogs and Osiris). Local flags can only be used in the current dialogs. Global flags should have unique names to avoid collisions. Values 0=false and 1=true.

Triggers[]

Triggers are logical entities in the games, they are not visible, you can't click on them but they are used for scripting reasons. There are two types Area triggers, which encompass an area, and Point triggers, which are just a location and a direction. Area triggers you would use for walking into a defined area. Point triggers you would use to put effects, characters, items on etc. Area triggers can be BoxTrigger or a PolyTrigger if you need a more complex (and more expensive in terms of performance) trigger.

A trigger has to be configured to react to objects (characters and items) entering or leaving, for example it can be configured to react to the players using TriggerRegisterForPlayers.

Facts[]

Osiris supports the creation of ad hoc "databases" of facts. Databases can have arbitrary number of columns and each column can be any of the supported data type. It is possible to have databases with the same name but different number of columns however all the entries in a particular column must have the same data type.

The convention is to prefix the name of the fact with "DB_" to distinguish it from procedures

To add a fact:

// create a fact with an INTEGER column
DB_PlayerDoesNotHaveAllApples(1);

// create a fact with an ITEM and a CHARACTER column
DB_JackApples(ITEM_OsirisDemo_JackApple,CHARACTER_NULL);

To remove a fact:

// clear a fact with an INTEGER column
NOT DB_PlayerDoesNotHaveAllApples(1);

// clear a fact with an ITEM and a CHARACTER column
NOT DB_JackApples(ITEM_OsirisDemo_JackApple,CHARACTER_NULL);

Procedures[]

Osiris supports the creation and calling of procedures. A procedure can have zero, one or more parameters. A procedure can be defined multiple times and when called Osiris will execute each definition in the order they are in the script.

The convention is to prefix the name of the procedure with "Proc" to distinguish it from a fact database.

PROC
ProcCheckIfPlayerHasAllApples((CHARACTER)_Player)
THEN
DialogueSetCharacterEvent("OsirisDemo_HasAllApples",_Player,0);

Notes[]

The underscore _ is a placeholder for "any object"

Characters can be "on stage" or "off stage". On stage means they are active in the world, the player can see them and interact with them. Off stage means they are not active, the player cannot see them or interact with them.

The Reload Story menu option resets the story's state so that you can test it from the start again.

The game's osirislog.log and the mod's story.div can be used together for debugging.

Advertisement