Osiris: Introduction to Debugging
This page covers basic debugging using the Osiris Log. We recommend first reading Introduction to Osiris and Osiris: Using the Story Editor before diving into this guide.
Basic Debugging with the Osiris Log
Even if a script builds successfully, once you start testing it in-game, you’re likely to discover bugs.
There are a couple of files that can help you debug:
- story.div
- the Osiris Log (also known as the Story Log)
ⓘ The first time you try to open one of the above files, you will be asked to choose a program with which to open it. All the files are plain text, so feel free to choose your favourite text editor. We recommend Notepad++ or Visual Studio Code.
Story.div
This file includes all the current Osiris goals, compiled in one single file, following the same structure as explained in Osiris: Using the Story Editor: from top to bottom, as they appear in the left sidebar of the Story Editor.
You can open this file from the Story Editor via File > Open Story.div, or by looking for story.div in ...\Data\Mods\<YourMod>\Story.
The general structure of the file is:
- Goal(goal_number).Title(name_of_goal): The start of a specific compiled goal.
- INIT: The init section of the goal.
- KB: The section with the rules of the goal.
- END: The logic that plays when the goal is closed.
Osiris Log
The Osiris Log contains the entire Osiris trace from the moment you load a level, load a savegame, or reload story in the Editor. It is where you will spend most of your time when debugging scripts.
This file includes all events, all calls to PROCs and QRYs, and every time an entry was added to or removed from a DB in the current game session.
It is located in your Steam or GOG installation folder of the Toolkit (for example, ...\steamapps\common\Baldurs Gate 3 Toolkit\) and named osirislog.[date_of_creation].log. The Editor will always save the last 11 logs, so don’t worry about losing your logs if you reload story.
Another way to open it is via File > Open Story Log in the Story Editor.
The Osiris Log is a bit more difficult to read than Story.div. Every time something happens (an event was fired or an entry was added or removed from a DB), the Osiris Log registers it and starts executing the rules accordingly.
The trace will be saved in the log file for you to check what happened and see where it failed, or what is currently running in Osiris.
- Events: Lines starting with
>>> eventcorrespond to events fired by the game (e.g. a flag was set or cleared, a spell was cast, or someone entered a trigger). - Queries:
exec [DIV/Osi user query]indicates when a QRY was checked.DIVqueries correspond to engine queries whileOsi useris for Osiris-defined queries. They will always include the parameters with which they were called, if any.- Parameters with the
[out]prefix are for returning parameters from the engine. When a query fails, it will explicitly say*** Query Failed! ***at the end of its line.
ⓘ Queries that succeed in returning something, even if the result is not what was expected, will not return Query Failed. In the example below, we’re checking if a weapon has an active status. The query itself succeeded and returned a result, but the result is that the weapon does not have the status active and hence does nothing.
exec [DIV query] HasActiveStatus( WPN_GOB_Shortbow_A_0_6f92d9b1-8d54-346f-e477-c1a9abbf80d3, "WYR_GORTASH_GRENADE_DETONATE", [out] 1 )
Query returns: HasActiveStatus( WPN_GOB_Shortbow_A_0_6f92d9b1-8d54-346f-e477-c1a9abbf80d3, "WYR_GORTASH_GRENADE_DETONATE", 0 )
- Procedures: Calls to procedures, followed by other queries, DB loops, or
RuleActionPart. These lines end with[Osiris procedure call].
As you follow the execution of each rule through the Osiris Log, you will see that many lines start with X---->. X represents how deep you are in the trace. The more nested PROCs and QRYs you have in a given rule, the bigger the number might end up being. Be careful with how many you have, as it will make debugging more difficult.
