Definitive Edition
Contents
Welcome, brave Sourcerer!
So you have some old modifications you’d like to bring up to date for this new day and age? Well, look no further!
Many things changed in Divinity: Original Sin 2 Definitive Edition, but we've got you covered!
Below, you can find a guide containing all essential information needed to make your content Definitive Edition - ready.
For more information on topics mentioned in the guide, look at the information on this page.
Essential Conversion Guide
Finding Definitive Edition Mods
On the Steam workshop, updated mods can be found under the Definitive Edition tag. (A new filter that is automatically applied when publishing in the Definitive Engine).
New mods will get their own download page, so classic mods will still be available for download/maintenance via their respective pages, as they are now.
For all other sources of mods, please check the description or ask the content creator to find information on the version the mod is made for.
Installing the Divinity Engine 2 Definitive Edition
The game and the tool are available under the same game page on whichever store you use. So, simply use the existing setup guide.
 |
Importing 3.0 Mods
We added a handy, little “Import Project” button to the Project Browser.
When pressing “Import Project”, you’ll be prompted with a File Explorer window.
Navigate to the Data folder of Divinity Original Sin 2 (classic edition) and select the following:
Divinity Original Sin 2\Data\Mods\{YourMod}
The editor will then copy all project data over to the Definitive Edition data folder and give your project a new ID.
Later on, when publishing, this will ensure that your project will have a separate page on the workshop and will be recognized as a different mod in-game.
No Backwards Compatibility. Conversion Is Required.
We would like to remind you at this point that Classic Mods are not compatible with the Definitive Edition and vice versa.
If you happen to have an incompatible mod in your game’s mod folder, the Mod Menu in-game will show you that that mod is incompatible and block loading/enabling that mod.
Sound Modding
Sound Resource updated to recognize external .wav files.
This .wav support is provided everywhere where sound resources are used, with the exception of Music Volume Triggers.
More specifically, this means you can use custom music files (.wav extension) in the following cases:
- Point Sound Triggers
- Point Volume Triggers
- The Effect Editor
- The Script Editor (*)
(*) Two new calls have been added to allow playing a sound through story scripting:
GM Story Scripting
Story (Osiris) scripting in Game Master mode is now fully supported!
This means that all your add-on scripting will work in Game Master, the same way it does in Story mode.
As always, simply make sure in your Project Settings (CTRL + P) that your project has the correct game mode enabled as Target.
Your project only works for the modes it targets! In this case, the target would be GM.
Save/Load Support
Saving/Loading of save games is supported in the Divinity Engine 2 Definitive Edition.
All your save games are loaded into the editor and available through the Level Browser
|
Unified Character Creation
The basic Character Creation scripting has been unified into one spot.
This way, your mod will always have character creation logic without you having to add that by hand!
Furthermore, it is easily moddable by overriding the new files.
The basic Character Creation (CC) functionality has been moved to the Shared mod and has been documented.
You can find the code in the story goals Z_Shared_CharacterCreation and Z_SharedCharacterCreation_AfterEvents.
Character creation code that is specific to the DOS2 main campaign (DivinityOrigins mod) can be found in Shared_DOS_CharacterCreation.
The names of these goals (and their parent goal) start with Z_ because story goals are initialised in alphabetical order,
and this way any database (specifically, the databases described below) defined story goals with names that do not start with “Z” initialise before the generic CC scripting tries to use them.
You can detect that Character Creation pipeline from the Shared mod has completely finished by the fact that at this point the procedure PROC_Shared_CharacterCreationFinished() gets called.
This happens both when testing a mod in the editor (and hence no character creation ever happened, in which case a random character from the DB_Origins() database gets selected the first time you enter game mode in a session), and in a regular game.
The Shared_DOS_CharacterCreation goal also overloads the ProcSetupGenericOrigin((CHARACTERGUID)_Char) procedure.
This procedure gets called with as parameter the random character that was selected when starting game mode in the editor.
You can perform extra tweaks to that character at this time.
The code in Shared_DOS_CharacterCreation randomly turns that character into an undead to encourage people to test their situations also with undead characters.
Standard CC for adventure that does not load data
In a goal that is initialised before or when the GameModeStarted(“Campaign”, _) event fires:
DB_Origin((CHARACTERGUID)Your_OriginCharacter1);
DB_Origin((CHARACTERGUID)Your_OriginCharacter2);
...
The generic character creation code will turn all of these characters into player characters when character creation starts, and make them NPCs again once it is finished if they were not selected by anyone.
Note that these characters also need to be prepared as described in The Custom Origin Character Tutorial either in your own mod, or in a mod on which you depend.
You can also add characters from the DB_GenericOrigins() database to the DB_Origins() database.
If you do this, then when starting a level from this mod in the editor you may also be assigned a generic character rather than an origin character.
Before Character Creation finishes (can be in the init section of the same goal as above):
DB_CharacterCreationTransitionInfo("StartLevel",(TRIGGERGUID)StartTrigger,"StartMovie");
You can define multiple of these databases.
Which one gets used is defined by the next database.
The StartMovie can be empty if no movie should be shown between character creation and the start of the first level.
StartTrigger has to be a global trigger.
StartLevel is just an identifier; it does not have to be an actual level name.
Before Character Creation finishes (can be in the init section of the same goal as above)
DB_CharacterCreationTransitionInfo("StartLevel");
This database determines which of the DB_CharacterCreationTransitionInfo entries gets used, i.e., to which start trigger and with which movie the players are teleported after Character Creation finishes.
<p>
<p>
In addition, there are a number of optional databases that you can define.
See the comments in the INIT section of the Z_Shared_CharacterCreation goal for more information.
In general, you won’t have to touch these.
Standard CC for an adventure that loads data
This is for mods that load data from Story, GM, and/or Arena.
All of these mods contain a functional Character Creation already.
Story (DivinityOrigins mod) uses the Character Creation scripts from Shared as described in the previous point.
GM and Arena contain custom character creation code due to their specific nature.
Custom CC
If you wish to create a custom character creation script, you can do so by overriding the Z_Shared_CharacterCreation and/or Z_Shared_CharacterCreation_AfterEvent goals in your own mod.
Make sure to carefully read the original code and to provide support for all edge cases such as the lobby level (even it works fine by default, it may not when you start switching mods within a single session) and testing in the editor.
No CC
If you do not wish to have a Character Creation at all and instead statically define the player characters, then
- Override the Z_Shared_CharacterCreation goal, and
- Copy everything from the INIT section of the original goal to the new one
- Copy the PROC_Shared_CharacterCreation_Init() from the original goal to the new one
- Copy the “Lobby level support” region from the original goal to the new one
- In your mod, go to the Project -> Project Settings, and set the Startup Level to the level in which you wish the game to start. Clear the Character Creation Level.
- Override the Z_Shared_CharacterCreation_AfterEvents goal and add the following code to it:
IF
RegionStarted(_Level)
AND
IsGameLevel(_Level, 1)
AND
DB_CharacterCreationDummy(_Npc)
THEN
CharacterMakeNPC(_Npc);
- Change the properties of all characters that you wish players to be able to control as follows:
- Check their “Global” property
- Check their “Player” property
Scripting
Both Behaviour as well as Story (Osiris) Scripting have received a plethora of new calls as well as changes to exiting ones.
All for the better, of course!
Orphan Databases/Queries
Sometimes, the Osiris compiler did not catch typos in database names. For example:
IF
CharacterDied(_Player)
AND
DB_FreeResurrect(_Player)
AND
DB_Player(_Player)
THEN
// Free resurrect for players!
CharacterResurrect(_Player);
// Not twice in a row
NOT DB_FreeResurrected(_Player);
The DB_Player in the above fragment should read DB_IsPlayer, and the DB_FreeResurrected should be DB_FreeResurrect.
Osiris did not notice anything wrong with this fragment because it can infer the type of the _Player variable from the CharacterDied event signature.
In order to catch such errors, the Osiris compiler now gives warnings (which are treated as errors) for all databases that either only checked or only defined in all story goals of the current mod and any mod it depends on.
After all, such checks will always fail and such defines will never be used.
However, this can result in false positives.
A common example is helpers in the Shared mod, which often check databases that will only be defined in other mods that actually make use of these helpers.
To suppress these false positives, a new file can be added in the Story directory of a mod, with the name story_orphanqueries_ignore_local.txt.
Every line of this file contains the name of a database followed by its arity (= number of fields/parameters).
When compiling a mod, the contents of all story_orphanqueries_ignore_local.txt files from the dependent mod and this mod are merged, so the ones defined in the Shared mod will also apply to your own mod.
In addition to the previous file, there are two more files you may now see in the Story directory of a Mod:
- story_orphanqueries_ignore.txt: this file is recreated by the story editor every time you compile story (so no need to restart after changing the story_orphanqueries_ignore_local.txt file). It simply contains the contents of all relevant story_orphanqueries_ignore_local.txt files: the one from the current mod and any mod it depends on. This is the file that is read by the Osiris compiler to determine which warnings it should not show. Since it gets overwritten every time, don’t make changes to it since they will get lost.
- story_orphanqueries_found.txt: this file is generated by the Osiris compiler every time you build story, and contains all of the databases for which it gave the aforementioned warning. These databases are in the same format as used by story_orphanqueries_ignore_local.txt, so you can just copy/paste its contents in case these are new false positives that should be suppressed.
One final note: the line number printed for these warnings is bogus, as no line number information is available anymore at the time it gets shown. In general ctrl-shift-f for the database name will be the easiest way to find the location(s) where it is used/defined.
