Preparations
The official has provided us with tools to make mods, which facilitate our development. First, search for The Divinity Engine in the Steam Library and download and install it (it should also be available on other platforms if you look carefully).
In addition, I recommend that you install the Script Extender script, which may be useful for writing script code later on. It adds many useful functions that can be called. Please refer to the following address for more information: https://steamcommunity.com/sharedfiles/filedetails/?id=2031669903
If you have installed the above script, a Console will appear when opening The Divinity Engine:
After opening The Divinity Engine, create your first project by selecting "Add-on" as the Project Type. Then, in the bottom right corner, choose "Story" and give your project a name:
After creating the project, wait a moment and a browse window will pop up asking you to select a scene. We don’t need it for now (you can choose to load the scene later), so click "Cancel" to close the dialog box.
Introduction to Common Functions of Toolbars
In the toolbar, there are some official mod tools provided. The ones we most commonly use are the orange-yellow ones:
They are:
- Material Editor: rarely used, but may be useful for mods that involve models.
- Script Editor: used to write gameScript scripts, which help to complete certain functions, especially for items and characters, i.e. the mine controller script is attached to every mine in game. By using the official skill templates provided in the data editor, you can easily replicate the existing skill mechanisms in the game. However, if you want to create a skill that combines existing mechanisms or even requires scripting to implement, the Script Editor and Story Editor will be necessary.
- Effect Editor: used to edit effects, such as skill casting effects or hit effects. This tool can be used to view existing effect names when editing skills.
- Story Editor:To distinguish it from gameScript scripts, the scripts written here are generally referred to as Osiris scripts. Here is official introductions to Story Editor . Overall, it can control events in the game world, but it cannot fully control the behavior of items or characters , so the Script Editor is needed to supplement functionality.
- Dialog Editor: used to edit interactive dialogues.
- TranslatedStringKey:used to manage localization string.
- Texture Atlas Editor: used when importing custom icons.
- Tag Editor: used to edit tag properties.
- Journal Editor:see official docs
- Stats Editor: very commonly used, allows you to add or edit game parameters, such as skill damage coefficients and attributes, status attributes, some talent bonuses, and certain game settings like the maximum number of summons.
- Treasure/Experience Analyzer
How to modify game stats
This tutorial intends to start with simple modifications and progress gradually. Therefore, let’s begin with the most commonly used and beginner-friendly tool, the Stats Editor. Here, you can see some game data, such as throw distance, engagement range, sneak damage multiplier, acceleration/deceleration rate, and more under Shared-ExtraData. After knowing which data can be modified, you may be able to customize your desired world attributes.
If you want to modify related attributes, simply right-click the item you want to modify and click override in - your project name
to edit and save it in the corresponding location:
After editing the data, press the Ctrl+S
shortcut key to save, or click the floppy disk icon to save.
Skill Types and Introduction
In The Divinity Engine, skill data is categorized by skill type. Clicking on "SkillData" will show the following categories (some descriptions are referenced from Element120’s documentation):
- Cone: Skills with cone area. You can define the
Range
andAngle
properties to determine the coverage radius and angle of a skill. In addition, there is a special property calledPushDistance
that defines the knockback distance, as seen in the skill "RadialBlowback". A typical skill example is the Lizard race skill "Flaming Breath". - Dome: A persistent skill with a hemispherical visual effect, such as the "Guardian Angel" skill of the Human race.
- Jump: A skill used for self-teleportation, such as the "Phoenix Dive" skill of the Scoundrel school. Although the Teleportation skill type can also be used for self-teleportation, the main difference between the two is that Jump can have an effect when jumping. You can use the
Damage On Jump
andDamage On Landing
properties to determine whether damage is dealt during takeoff and landing. - MultiStrike: A skill that hits multiple targets and teleports the caster, such as the "Blink Strike" skill of the Warfare school. When MaxAttacks is set to 1, it only hits one target, like the Assassination skill "Vault".The TargetRadius property specifies the casting distance for the first target, while AreaRadius specifies the maximum distance between subsequent targets (i.e., the maximum distance the caster can jump from one target to the next). The probabilities and decay rates for jumping to the next target can be defined with
NextAttackChance
andNextAttackChanceDivider
. - Projectile: A template for throwing skills that involve throwing one or more projectiles. This skill type has a wide range of applications, and by setting MovingObject to Caster, you can even throw yourself, as in the Polymorph school skill "Spread Your Wings". Setting MovingObject to another item ID allows you to throw other models, such as the implementation of grenade skills:
The Fireball skill of the Pyrokinetic school is a typical example of throwing skills.
The Ice Fan skill of the Hydrosophist school is a typical example of a skill that uses multiple projectiles.
The Chain Lightning skills of the Aerothurge school is a typical example of skills that have multiple forks. - ProjectileStrke: A template for throwing skills that involve projectiles falling from the sky.
ProjectileCount
sets the number of projectiles, which can be 1, as in the Aerothurge skill "Thunderstorm", or multiple, as in the Huntsman skill "Arrow Storm".
Note: The Windstorm and Thunderstorm skills are multi-turn, multi-attack skills defined in Storm, but each attack calls a sub-skill defined in ProjectileStrike. See the relevant descriptions for more details.
You can use theAngle
andHeight
properties to set the initial angle and height, where an Angle of 0 means a vertical drop.
The Thunderstorm skill of the Aerothurge school is a typical example of this type of skill. - Quake: A skill that generates an effect on the ground around the caster, in addition to dealing damage and causing screen shake. The Earthquake skill of the Geomancer school is a typical example of this type of skill.
- Rain: A template for skills that generate surfaces on the ground. The Rain skill of the Hydrosophist school is a typical example of this type of skill.
- Rush:A template for skills that involve a straight-line charge, where the caster charges along a path and deals damage and/or other effects. The Battle Stomp skill of the Warfare school is a typical example of this type of skill.
- Shout: A skill that affects the caster and/or an area around them. This can either be a self-buff or have a range effect. The Ice Breaker skill of the Hydrosophist school, the Supernova skill of the Pyrokinetic school, and the Play Dead racial skill are all examples of this type of skill.
- SkillSet: A set of pre-defined skills that can be modified in the character creation interface.
- Storm: A type of skill that deals multi-turn, multi-hit damage within a certain radius. The
LifeTime
property sets the number of turns the storm lasts, whileMinHitsPerTurn
andMaxHitsPerTurn
define the minimum and maximum number of hits per turn. TheProjectileSkills
property sets the projectile skills used during each turn of the storm. The Thunderstorm skill of the Aerothurge school is an example of this. - Summon: A skill that creates one or more objects or characters. The Summoning skill of the Summoning school is a typical example of this type of skill.
- Target: A skill that targets a single entity or an area without using projectiles. The Demonic Possession and Shackles of Pain skills of the Necromancer school are examples of this.
- Teleportation: A skill that teleports the caster or a targeted entity to a specified location. The Teleportation skill of the Aerothurge school is an example of this.
- Tornado: A skill that generates a path of destruction through a designated area, with the path being randomly "jostled" to create a zigzag pattern. The skill can generate surfaces on the ground or apply other effects along the path. The Tornado skill of the Aerothurge school is an example of this.
- Wall: A skill that generates a wall of surface and/or one or more specified objects along a designated path. The Poisonous Vines skill of the Geomancer school is an example of this.
- Zone: A skill that creates a rectangular or circular area effect, with
Shape
often being set toSquare
. The Laser Ray skill of the Pyrokinetic school is an example of this type of skill.
The above has listed the types of skills and some special properties in Divinity: Original Sin 2. The more commonly used properties will be introduced when creating / modifying skills later on.
How to edit or create status
Now we are going to introduce the Stats
:
In the game editor of Divinity: Original Sin 2, information about weapons, armor, shields, characters, and other elements can be found in their corresponding categories. However, we will focus on the most commonly used class called Potion
. Literally can be understood as effects gained from drinking potions, as well as other types of buffs or debuffs obtained from using skills or wearing items.
Within the Potion
class, you can find a variety of properties that provide different types of buffs or debuffs, such as strength, dexterity, intelligence, one-handed, two-handed, various skill schools, thievery, persuasion, elemental resistances, initiative, movement, health, accuracy, evasion, maximum action points, action point regeneration per turn, reduced action point cost, life steal, and more.
Under the Stats
category in the game editor of Divinity: Original Sin 2, there is a StatusData
class that defines various status effects such as blindness (Status_BLIND
) and knocked down (Status_KNOCKED_DOWN
). These classes share some common effects, such as receiving healing per turn. The status effects defined here are the ones that appear on the character portrait or detailed information page.
In contrast, the Potion
class under Stats
provides specific attribute boosts or reductions. For example, the KNOCKED_DOWN
status defined in the Status_KNOCKED_DOWN
class includes macro-level descriptions such as name and description, with its StatsId
set to Stats_KnockedDown
. It is the Stats_KnockedDown
defined in the Potion
class that provides the actual attribute buffs or debuffs.
The TreasureTable
category in the game editor of Divinity: Original Sin 2 defines classes related to loot. We use these classes when adding skill books or items to the game.
Alright, after introducing the framework of the game editor, we can start creating our first skill. As you may have noticed, I’m using the mod name EnhancedShieldWarrior
as an example. In this mod, I plan to create a series of skills to enhance the shield warrior class and make it more capable of carrying. Let’s start with a simple skill.
Firstly, in my vision, I want to enhance the taunt skill. Normally, when enemies are taunted, they should be angry, so we will give them a "fury" status that causes them to deal 100% critical damage, while also giving ourselves a high amount of counterattack damage to counter physical damage output classes. To achieve this, we need to give the character who uses taunt a buff that grants additional "retaliation" skill points. Additionally, to prevent them from being killed by enemies quickly, we will also grant them additional armor and magic armor.
Now we create a new Potion
stats in project :
Here are some descriptions of these properties (seems no Perseverance ??):
- Parent : In the game editor of Divinity: Original Sin 2, you can specify the object to inherit from. This is similar to the concept of inheritance in programming, where the child object inherits all properties that have not been modified from its parent object.
- Level、MinLevel、MaxLevel:The BUFF level can be left empty or set to -1 to follow the character’s level.
- StackId:The
StackId
is used to identify whether multiple buffs with the sameStackId
can stack or not. Only one buff with the sameStackId
can be active at a time. ThePriority
property determines which buff will be kept and which will be replaced when there are multiple buffs with the sameStackId
. - AuraRadius: Setting the
AuraRadius
property turns the buff into an aura that applies to all allies within a certain radius, rather than just the character who receives the buff. - AuraSelf/AuraAllies/AuraNeutrals/AuraEnemies/AuraItems: What status applied to target type
- AuraFX, Weight, Value jsut like their name
- Strength、Finesse、Intelligence、Constitution、Memory、Wits :basic properties
- SingleHanded、TwoHanded、Ranged、DualWielding:weapon mastery
- PhysicalArmorMastery、MagicArmorMastery:doesnt work for me
- VitalityMastery: doesnt work for me
- PainReflection: level of pain reflection
- WarriorLore、RangerLore、RogueLore:skill levels
- Sourcery:doesnt work for me
- Telekinesis:level of ability that allows an individual to move or manipulate objects using only their mind
- FireSpecialist、WaterSpecialist、AirSpecialist、EarthSpecialist:skill levels
- Necromancy、Polymorph、Summoning:skill levels
- Sneaking、Thievery、Loremaster、Barter、Persuasion、Luck:ability levels
- Repair、Leadership::crafting level(doesnt work for me)、ability level
- FireResistance、EarthResistance、WaterResistance、AirResistance:elemental resistance
- PoisonResistance、PiercingResistance、PhysicalResistance:other resistance
- Sight、Hearing:range of seeing/sound
- Initiative:determines the order of attack
- Movement、MovementSpeedBoost:movement related
- Vitality、VitalityBoost、VitalityPercentage:add health 、health boost(increase maximum)、recover health precentage(no increase maximum)
- ChanceToHitBoost、AccuracyBoost、DodgeBoost:just as name
- DamageBoost、RangeBoost
- APCostBoost、SPCostBoost:can be negative
- APMaximum、APStart、APRecovery
- CriticalChance
- Gain: doesnt work for me
- Armor、ArmorBoost:just like vitality but armor version
- MagicArmor、MagicArmorBoost
- Duration: normally set in skill property
- UseAPCost
- Reflection:Reflect percentage of received damage i.e.
20::Air:melee
,means reflect 20% of reveived melee damage to attacker - LifeSteal
- BloodSurfaceType
- MaxSummons
- StatusEffect effects when applied
- StatusIcon
- SavingThrow:The property specifies which stats the character is immune to. This is generally defined in the
StatusData
class, rather than in this property. - Priority
- Comment
Create a buff effect and apply it to a skill
As mentioned earlier, this mod aims to enhance the taunt skill by giving the character who uses it a buff that grants additional retaliation skill points and extra armor and magic armor to prevent them from being killed too quickly. This buff should also enhance the character’s defensive properties, so we will call it the "Defensive Stance" buff.
There are two ways to implement the high counterattack damage effect:
- Temporarily increase the
PainReflection
attribute. - Reflect a percentage of the damage back to the attacker using the
Reflection
attribute.
Both methods can achieve the desired effect, but they differ in implementation details. The first method reflects damage based on the retaliation level multiplied by the bonus damage percentage per level, and the reflected damage type is the same as the received damage type. You can find the bonus damage percentage per level under the Shared - ExtraData - CombatAbilityReflectionBonus
category in the data editor. Right-click and select "override in" to modify it.
Here i modified it to 7.5%.
The second method is more flexible as you can specify the type of damage to reflect as well as the type of damage to apply. The syntax for this is percentage::damage type:effective damage type, such as 20::Air:melee meaning reflecting 20% melee damage taken as air damage to the attacker. (Original reference):
"BaseLevelDamage""AverageLevelDamge""MonsterWeaponDamage""SourceMaximumVitality""SourceMaximumPhysicalArmor""SourceMaximumMagicArmor""SourceCurrentVitality""SourceCurrentPhysicalArmor""SourceCurrentMagicArmor""SourceShieldPhysicalArmor""TargetMaximumVitality""TargetMaximumPhysicalArmor""TargetMaximumMagicArmor""TargetCurrentVitality""TargetCurrentPhysicalArmor""TargetCurrentMagicArmor"
Create the a new list named "Stats_StandingFast" under Potion
, and fullfill these data:
"Stats_StandingFast""Reflection" "75::Physical""ArmorBoost" "50""MagicArmorBoost" "50""Duration" "3"
To make the effective state take effect, we need to create a "handler" that calls it, namely the StatusData
class. Click the "+" button to create a new StatusCONSUME
type.
Modify these value into:
"STANDINGFAST""DisplayName" "|STANDING FAST|""Description" "|Character is standing fast.|""Icon" "Skill_Warrior_ThickOfTheFight""StatusEffect" "RS3_FX_GP_Status_ThickOfTheFight_Hand_01:Dummy_L_HandFX,Dummy_R_HandFX""StatsId" "Stats_StandingFast"
One thing that needs to be emphasized is the StatusEffect
field, which represents the effect of attaching the status. This statement means that the RS3_FX_GP_Status_ThickOfTheFight_Hand_01
effect will be bound and displayed on the left and right hands. The name of the effect can be found in the Effect Editor, which will be explained in a later tutorial.
Next, we will modify the default taunting skill and attach the aforementioned effect to it. Locate the Taunt skill under the Shout category and incorporate it into our project by overriding it.
Just change the SkillProterties
property:
:TAUNTED,100,1;ENRAGED,100,1;SELF:STANDINGFAST,100,3
This statement consists of three parts, each representing an effect, and each ending with a semicolon. Each part also has three components: "the attached status, the success rate of application, and the duration in rounds." The attached status
needs to be defined in StatusData
, so in our statement, it is STANDINGFAST
instead of Stats_StandingFast
. In the third part, SELF:
specifies that the caster gains the status.
Okay, now we have completed the basic process of modifying/adding skills, and can try to see the effect in the game. Click on File - Load Level
in the upper left corner to load a scene. Let’s choose FortJoy for this example.
After waiting for the loading to complete, click on the leftmost button in the toolbar to switch to game mode.
Press F11 to open console:
On the right side is a list of available commands. Enter the command in the input box below and press enter to activate it. Here, enter levelup 2
to increase two levels and allocate 2 points to the War school (Taunt requires 2 points in War), and obtain the Taunt skill by using the command addSkill Shout_Taunt
. In the console, you can use TAB
to auto-complete commands. Additionally, when a character dies, hover the mouse over the character and use the shortcut CTRL+SHIFT+R
to quickly revive them.
When hovering the mouse over the skill icon, you can see that the skill description has changed.
After releasing the skill, the corresponding bonus is also added to the status bar. Now, what needs to be done is to process the displayed string.
Localization
In the string management tool, various texts can be easily used. Here, Chinese is taken as an example.
We can see these string in mod :
just edit them and save:
Additionally, since the Displayname under Potion was not automatically created, we will manually create an item here. Click on File-New:Potion_Stats_StandingFast
Alternatively, in the Stats
editor, click on FILE-Export Translated String Keys to regenerate the Translated String Keys. Let’s take a look at the effect:
In this tutorial, we have demonstrated the simple usage of the official tools and introduced commonly used tool editors. We have provided a brief explanation of skill types, which will help you understand the skill system in Divinity: Original Sin 2. We have also explained the properties of Potion
in the Stats
class, which can allow you to define many beneficial or detrimental effects. We then showed how to edit/create skills and attach bonus/malus status effects. We also briefly introduced the use of the console for debugging purposes. Finally, we briefly introduced the localization tool, which helps us display strings correctly.