Latest revision as of 22:43, 29 September 2018

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 pages to download mods from, please check the description on the page 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.

One exception: You’ll be opening the Divinity Engine 2 Definitive Edition instead of the regular one, and where the guide talks about linking the Engine to the Original Sin 2 Data, be sure to link to the Definitive Edition data.

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.

Imported Custom Content

Imported Materials

Some materials parameters have changed slightly to improve performance.
Your material files might not be loadable from the start. If they are pink, you need to convert them. But that can be done easily!
Open your material in the Resource Browser and simply save.
Be wary that (since your material was broken before) your material will only be loaded again after a mod reload or editor restart!

Imported Stats

As stats were tweaked, some definitions changed. Makes some pages (e.g. Potions), incompatible.
But again, conversion is easy! It will happen auto-magically when importing/opening your DE project.
Beware though that some columns might have changed and we tweaked several base values, so be sure to go over your stats changes, to ensure they still do exactly what you intend them to do.

As before, the Engine does not support manually editing the stats .txt files. Only stats made in the Engine's Stats Editor can be converted.

Imported Resources

After import, resources can suffer from outdated Source File path properties. To that end the Path Fixer has been added to the Content browser:

When opening the path fixer, you'll get an overview of all resources with outdated file paths and the suggested correction. For each file the correction can be toggled on/off. When happy with the proposed correction, press Ok on the bottom of the window and all files will be updated and resaved. Be aware that this may take some time, depending on the amount of resources.

Imported Texture Atlases

Texture atlases will also suffer from outdated paths. Simply resave your custom texture atlases in the Texture Atlas editor to make them work again in your DE project.

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
• Sound Volume Triggers
• The Effect Editor
• The Story Editor (*)

(*) Two new calls have been added to allow playing a sound through story scripting:

• CharacterPlayHUDSoundResource
• PlaySoundResource

GM Story Scripting

GM Story scripting and GM add-on support in general (when playing the campaign) will be brought live on the first patch after release.

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

Always make sure you make save all changes before making save games. Otherwise, If you alter the save game but not the project data, you could cause the game to crash due to missing data.

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 in 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. Additionally, when loading your mod in the editor, a random character from this database will be selected as player character in the editor's game mode. Note: since this happens when the mod loads, you will have to quit and restart the editor to get a new character from this database (or to get any character at all from it if you just have added the first entries to this database and recompiled story). Additionally, 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_GLO_FirstLevelAfterCharacterCreation("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.

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!

• Osiris
• Behaviour Scripting

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.