Modding FAQ

This guide answer common questions about modding, both for users and mod makers.

Divinity Original Sin 2 Modding FAQ

This guide purpose is to answer common questions about how to use and how to create mods in Divinity Original Sin 2 (Definitive Edition).

For users (part 1)

Golden rule : always read mods descriptions. A kitten dies every time you don’t.

Q: Where can I get mods ?

A: Steam workshop and Nexus Mods[www.nexusmods.com]. If you have a GoG version of the game and want to download Steam workshop mods, you can use this tool : {LINK REMOVED}https://steamworkshopdownloader.io/

Q: Loading time is very long with mods. How can I speed that up ?

A: Norbyte’s script extender disables unnecessary processing during mods loading. You can install it by following this guide : https://steamcommunity.com/sharedfiles/filedetails/?id=2031669903

Q: Mods disable achievements. Can I re-enable them ?

A: Ditto: https://steamcommunity.com/sharedfiles/filedetails/?id=2031669903

Q: Mods are a real pain to manage with the in-game menu !

A: Use LaughingLeader’s mod manager[github.com]

Q: If someone hosts a game and uses mods, do the players that join that game also need the mods ?

A: Yes. A simple way to share the mods is to create a collection on the Steam workshop and share the link to the other players, or send them the content of Mods folder (Documents\Divinity Original Sin 2 Definitive Edition\Mods).
Alternatively, the game will download mods directly from the host if it detects you lack a mod. You will see an “installing screen” in that case, however this is much, much slower than downloading the mods from the workshop. Can be fine for a couple of light mods, but this is definitely not recommended if you use more than a dozen of mods. Also this method is prone to create desynchronization described below.

Q: I see Gift Bags on the main menu of the game. What are these ?

A: Gift Bags are community mods that have been hastily implemented directly into the game, that you can choose to enable at any moment in your game. Most of them are generally rough copies of the original community mods which you should prioritize since they give several advantages : they are less buggy, have more features and they can be deactivated at any time. Gift bags on the other hand, cannot be deactivated at all. Moreover, Gift Bags are forcingly loaded last and so can mess with all other mods you activated.
Here’s the list of the gift bag mods corresponding to their community counterpart (do a simple search on the Steam workshop) :

Gift Bag	Community
8 Actions Points	8 Max AP by baardvark
Nine Lives	Black Cat+ by The Composer
Herb Gardens	Grow Your Herbs by deadlyessence01
Source Meditation	Resting Restores Source by SimranZenov
From the Ashes	Rest-urrect by Calipark
Animal Empathy	Free Pet Pal by LadyCassandra
Hagglers	Bartering Tweaks by LaughingLeader
Combat Randomizer	Enemy Upgrade Overhaul by LaughingLeader
Crafter’s Kit	Crafting Overhaul by Elvasat (though Crafter’s kit has quite a different scope and can be plainly considered)
Enhanced Spirit Vision	Infinite Spirit Vision by Rockfire
Fort Joy Magic Mirror	Relocated For Joy Respec Mirror by LaughingLeader
Improved Organization	Organized Containers by SimranZenov
Pet Power	Summon Rework Core by Vincent H.L. OR Szmmon Overhaul by BibleThump (ported DE by SlenderDodger) OR Buff All Summons by Helaene
Sourcerous Sundries	Automatic Item Leveling by frasdoge OR Level Up Equipment Potion by RobotGodzilla
Endless Runner	Toggle Sprint by LaughingLeader

Only Divine Talents and Crafter’s Kit propose original content which isn’t copy-pasted from the community. Gift bags are mostly destined for console users who don’t have access to mods, so as a form of respect for modders, please use their mods instead of the gift bags when possible.

Q: Is it safe to disable a mod during a playthrough ?

A: It depends. Lightweight and quality of life mods are generally unimpactful, however major overhauls and mods changing stats or story can leave undesirable leftovers (incorrect HP/armour values, objects disappeared, etc…) and sometimes just make the game crash. Make a backup of your save every time you enable or disable a mod.

Q: Is mod X compatible with mod Y ? In what order should I put the mods ?

A: Compatibility and load order is generally mentioned in mods descriptions. If not, a rule of thumb is that what is loaded last will have the last word if two mods change the same thing.

Q : What is Norbyte’s script extender ? Why do so many mods require it ?

A: The script extender made by Norbyte (github : https://github.com/Norbyte/ositools) is a powerful extension of the game engine which allows modders to do stuff that is impossible to do in the base game (e.g. new UIs, complex gameplay mechanic changes, …). It doesn’t change the game files so you don’t risk any form of cheat ban (which is non-existent in that game anyway), and it’s safe
security-wise (anyone can review the code on the github repository).
The script extender doesn’t work on Mac versions of the game, however.

Q : I installed the script extender but my multiplayer peers don’t. Do they also require it ?

A: If the mods you’re using don’t require it, no. However, it is nonetheless recommended to install it for the advantages it provides.

Q : When loading into the game, I get a message “Unable to cre1ate a working story” and/or I get 4 additional characters that were not in my party !

A: Make sure to check that if one of the mods you’re using requires the script extender, it is correctly installed.

Q: When I delete mods from the Mods folder in Documents folder or I unsubscribe to a mod on the workshop, it keeps reappearing in the game !

A: A disabled mod will not do anything unless the author explicitly said to overwrite some game files (which is a very bad thing to do, unless it concerns meta.lsx files !). To completely remove a mod, unsubscribe and remove the pak file from the Mods folder.

Q: In a multiplayer game, I or one of my peers have skills, items, etc… that are completely unmatching their real use, or I witness a really weird behavior !

A: This is called desynchronization. It happens when a player has a different version of a mod than the host, which shouldn’t happen most of the time if you have the extender since it will deny the connection attempt. However, if the mod author updated their work but didn’t change the version number, it can still happen. To avoid that issue, make sure to use LaughingLeader’s mod manager[github.com] before booting the game. Alternatively, the host can send their Mods folder to the clients.

For users (part 2)

Q: I subscribed to a mod on Steam, but I don't see it in-game !

A: Make sure the mod you subscribed to is compatible with Definitive Edition. If so, then you should use LaughingLeader's mod manager.[github.com]. There is a known issue with this game where the mods are downloaded after subscription, but it is not copied to the Mods folder of the game. The mod manager can take care of this issue easily.

For developers

Golden citation I heard from a wise man : “If you need help, don’t come to me. Search for a solution for 15 to 30 minutes, make sure to dig the available resources you have or look for some you may have missed. Then if you’re really stuck after doing that work, I will gladly help you.”

When you ask for help, make sure you show that you have searched and worked on your side. Nobody wants to help lazy bums so if someone catches you copy-pasting code/resource an experienced modder gave you without working it, forget about looking for more help. Also, credits. They are important.

A mod contains 4 folders :

• Editor : contains editor data. Mandatory for maps and FX editing.
  
• Mods : contains maps data and story scripts (+lua scripts).
  
• Project : contains the project metadata
  
• Public : contains the rest (stats, resources, behavior scripts, …)

Make sure to regularly backup your project files, especially for maps.LaughingLeader’s Source control generator can do it very easily for you: https://github.com/LaughingLeader/SourceControlGenerator

Q: How do I get started with modding ?

A: Join Larian’s discord server : https://discord.gg/LarianStudios
The #modding-resources channel contains plenty of links to get started with
modding generally and on specific subjects.
Golden tip : always start modding with a small mod. Changing parts of
the game require knowledge of the engine which you can only acquire by
practicing. You will only make yourself frustrated and/or also more experienced
modders trying to help you if you don’t take the time to learn how modding this
game works.

Q: What scripting languages are used in the Divinity Engine 2 ?

A: It uses 2 scripting languages : Osiris, used for Story scripting, and a no-named language we generally refer to as “Behavior scripting”. Norbyte’s script extender adds support for a 3rd language : Lua. (Note : the script extender adds new Osiris calls, event and queries)
Osiris is a declarative language which makes it very different from the way most common programming languages work. It works with statements and databases, which is great for designing quests. However, it is very inefficient for programming gameplay features.
Overview: https://docs.larian.game/Osiris_Overview
Behavior scripting is tied to items and characters of the game. It is somewhat similar to Osiris syntax-wise, but it works in its own way.
https://docs.larian.game/Category:Behaviour_Scripts
Lua is a procedural programming language with possibility for OOP design. It is widely known for its usage in games modding (World of Warcraft, Garry’s Mod, Roblox, …) and is easy to use. Using it in DOS2 requires a small setup described here : https://github.com/Norbyte/ositools/blob/master/LuaAPIDocs.md#getting-started
Lua has many advantages over Osiris since the extender makes available a lot of functions that are not usable in Osiris. For gameplay features programming, Lua is much more concise than Osiris.
Extender osiris API :
https://github.com/Norbyte/ositools/blob/master/APIDocs.md
Extender-only documentation and API : https://github.com/Norbyte/ositools/blob/master/LuaAPIDocs.md
https://github.com/Norbyte/ositools/blob/master/OsiInterface/Misc/ExtIdeHelpers.lua

Q : How do I setup my mod to use the extender functions and Lua ?

A: See LaughingLeader's tutorial[github.com]

Q: How do I enable the extender console ?

A: Two ways : either with LaughingLeader’s mod manager > Settings > Open Preferences > Script Extender Tab > Enable Console. Don’t forget to hit Save.
Second way is to go directly in the installation folder of the game : Divinity Original Sin 2\DefEd\bin and create OsirisExtenderSettings.json if it’s not there, and put inside:

{
  “CreateConsole”: true
}

You need to restart the game and the console should open in a separate window.
Never use CTRL+C in the console windows.
Highlighting stuff in the console windows without clearing it with Enter will hold the game in its current state (and thus can block loadings).

Q: Can I create new talents, or change the effects of existing ones ?

A: Yes and no. Talents are hardcoded in the game, which means you cannot create new ones. Some existing talents have their effects modulated by a variable contained in Data stats. You could wrap existing talents with scripting to give them additional effects, or add “new” talents by using unused talents that are still in the game files (most of them are DOS1 remnants : https://docs.larian.game/Talent_list).

Q: Why does loading a map that I extracted from a mod just make the engine crash?

A: Maps require files in the project Editor folder, which aren’t present in the pak file of the mod. If you want to modify a map from the workshop, ask the author if they can provide you with the said files.

Q: How do I do X or Y, which is not described here ?

A: First, verify the feature (or a similar feature) you want to implement doesn’t already exist in a mod. If it’s the case, download that mod, unpack it with https://docs.larian.game/Pak_Extractor_Guide and start looking at the different files to see how it’s done. Take your time to understand, especially if the mod is big or complex. If you still have a doubt, then feel free to ask the author of the mod, or ask in the modding channels of the Larian discord server.

Credits

The Composer, Norbyte, LaughingLeader, doctorbeetus

[TheGaySecretary]

under "Q : What is Norbyte’s script extender ? " You need a space after the link, it reads the link as /ositools) and 404s.

[Vio]

Thank you!