[Tutorial] Modding Basic Concepts

[BMac]

Follow-up tutorials: Adding New Icons, Adding Items to a Store, How to Upload Mods to the Steam Workshop.

This is a text version of the video tutorial available here: 

 

In this tutorial, I'm going to show you how to create a simple data mod for Pillars of Eternity II: Deadfire. By creating your own game data bundle files, you can create new items, abilities, classes, and other content; modify existing content; and also modify how some parts of the game work, as I'm about to do.

First, you need to create a folder to put your modified files in. Locate the Pillars of Eternity II: Deadfire folder. I've installed the game using Steam, so my game is in the steamapps folder.

Inside the folder "PillarsOfEternityII_Data", create a folder called "override", if it doesn't exist already. This is where all your mods and mods you download from the internet will go.

Inside the "override" folder, create a folder for your mod.

Next, you need to provide some information about your mod. Inside your mod folder, create a file called "manifest.json".

Open that file in a text editor, and type the following text into it.

{
    "Title" : {
        "en" : "Per-Rest Resources"
    },
    "Description" : {
        "en" : "Changes spells and class resources to reset on rest instead of after each encounter."
    },
    "Author" : "BMac",
    "ModVersion": "1.0",
    "SupportedGameVersion" : {
        "Min" : "1.1.0",
        "Max" : "1.2.0"
    }
}

• "Title" is the name of the mod. You can provide the text in multiple languages, each identified by its standard two-letter language code. In this example, I only provide English - "en".
• "Description" is a short, one-sentence description of the mod, and can also be provided in multiple languages.
• "Author" is the name or handle of the mod's creator.
• "ModVersion" is the version number of your mod. You should increase this each time you release a new version of your mod.
• "SupportedGameVersion" specifies the minimum and maximum versions of Pillars of Eternity II: Deadfire that your mod is known to be compatible with. The game will warn your users if they are using your mod with an incompatible version, but your mod will still load if it's enabled.

Change the contents of this file to describe your mod, then save and close the file.

You may also create a thumbnail image that will represent your mod in the Mod Manager UI. This image will go in your mod's folder. It needs to be named "thumb.png" and the dimensions should be 149x84.

Now you're ready to actually modify the game's data. For this mod, I'm going to change spells and class resources from resetting after each encounter to resetting on rest.

Let's take a look at the vanilla game data, the data the unmodified game uses. This data is located at "PillarsOfEternityII_Data/exported/design/gamedata". I happen to know that the data I want is in the "global" gamedata bundle. Open that file in a text editor.

The file is hard to read because it isn't formatted. There are many tools available for formatting JSON data. I'm using Visual Studio Code, so I just need to press Shift+Alt+F to format this document and make it easier to read (note: you'll need to associate the .gamedatabundle extension with the JSON format. link).

Now I'm going find the properties I want to edit.  I'll just use my text editor's search function (Ctrl+F) and search for the text "spell".

To learn what all of these properties do, refer to the Game Data Documentation.

I found the data. It's on the object called "GlobalGameSettings", so that's the object I need to override in my mod. I won't be changing all the values on this object, but I'm going to copy the whole thing for now, starting from the curly brace "{" shown below, all the way to the matching closing curly brace.

Create a new .gamedatabundle file in your mod directory. Enter the text shown, and paste the object you copied.

{
    "GameDataObjects":[
        (PASTE OBJECT HERE)
    ]
}

Now I'll remove the data I don't want to override. Note that I always need to leave the "$type" and "ID" properties of the object, and the "$type" property of any components I want to alter.  That leaves me with this:

{
    "GameDataObjects":[
        {
            "$type": "Game.GameData.GlobalGameSettingsGameData, Assembly-CSharp",
            "ID": "eddfc852-ccb9-4884-b901-e77e8ca31b48",
            "Components": [
                {
                    "$type": "Game.GameData.CharacterStatsSettingsComponent, Assembly-CSharp",
                    "PowerPoolUsageType": "PerEncounter"
                },
                {
                    "$type": "Game.GameData.SpellSettingsComponent, Assembly-CSharp",
                    "SpellUsageType": "PerEncounter"
                }
            ]
        }
    ]
}

Now I'll change all spells and class power pools to reset on rest instead of after each encounter by changing "PowerPoolUsageType" and "SpellUsageType" from "PerEncounter" to "PerRest".

{
    "GameDataObjects":[
        {
            "$type": "Game.GameData.GlobalGameSettingsGameData, Assembly-CSharp",
            "ID": "eddfc852-ccb9-4884-b901-e77e8ca31b48",
            "Components": [
                {
                    "$type": "Game.GameData.CharacterStatsSettingsComponent, Assembly-CSharp",
                    "PowerPoolUsageType": "PerRest"
                },
                {
                    "$type": "Game.GameData.SpellSettingsComponent, Assembly-CSharp",
                    "SpellUsageType": "PerRest"
                }
            ]
        }
    ]
}

That's it. My mod is now ready to test.

Edited June 18, 2019 by BMac
fix images for forum update

[kilay]

EDIT : Found it

 

Thnks, great start

Edited July 6, 2018 by kilay

[house2fly]

Thanks for this, as a newb it's very helpful

[TT1]

149x84???? Why, Lord, why???

 

My OCD is screaming for 150x85!

[AndreaColombo]

My OCD is screaming for 150x85!

 

My OCD can relate.

[Redicular]

149x84???? Why, Lord, why???

 

My OCD is screaming for 150x85!

 

That has to be intentional, some coder wanted to annoy some artist... no way you pick 149 by accident

[kilay]

 

149x84???? Why, Lord, why???

 

My OCD is screaming for 150x85!

 

That has to be intentional, some coder wanted to annoy some artist... no way you pick 149 by accident

 

 

i guess that the other 1 px x 1 px is taken by the border

 

EDIT : Nope i'm wrong, there isn't a border

Edited July 7, 2018 by kilay

[zilbest]

I try to add new spells in a progression table and it seems you have to include all of the entries for that class.

[SiliconMage]

I try to add new spells in a progression table and it seems you have to include all of the entries for that class.

 

I can attest to this as well; you do have to include all other abilities in the Progression Tables, even if you are just adding new ones.

[peardox]

Apologies to anyone who's native language ain't English. Only my Italian contact is around ATM - we're both positive a load of the text not in English or Italian is garbage

So - the point of this one is that BMac missed off localisation

Here's one I'm playing with (sorry rest of world for Google Translate)

 

{
    "Title" : {
		"de" : "Einfaches Segeln",
        "en" : "Plain Sailing",
		"es" : "Vela llana",
		"fr" : "Voile simple",
		"it" : "Navigazione Semplice",
		"pl" : "Całkiem proste",
		"pt" : "Navegação simples",
		"ru" : "Гладко",
		"zh" : "一帆风顺"
    },
    "Description" : {
		"de" : "Viel weniger Unterbrechungen durch die Crew",
        "en" : "Far less interruptions by the crew",
		"es" : "Mucho menos interrupciones por parte de la tripulación",
		"fr" : "Beaucoup moins d'interruptions par l'équipage",
		"it" : "Molte meno interruzioni da parte dell'equipaggio",
		"pl" : "Znacznie mniej przerw w pracy załogi",
		"pt" : "Muito menos interrupções pela tripulação",
		"ru" : "Менее меньше перерывов экипажа",
		"zh" : "船员不会中断"
    },
    "Author" : "Peardox",
    "ModVersion": "1.2",
    "SupportedGameVersion" : {
        "Min" : "1.1.0",
        "Max" : "1.3.0"
    }
}

This is properly formatted JSON with additional languages

The effect of the extra languages is that if you switch language (this is dangerous - you may get stuck in something you can't read) - practice switching languages if you wanna verify everything - buttons are always in the same places - I'm about t try Russian + Chinese but not before a few rounds of languages I can at least guess what means what.

 

I just tested this (with my Italian friend on standby) and switched to Italian. The manifest got picked up and displayed correctly. Cool - time for some Chinese (I may get stuck here )

[peardox]

I can now confirm that only thumb.png works - I did a JPG first time around

[peardox]

OK - Been thru every language, it all checks out (got confused about which buttons to press @ the end)

 

This is not a racialist comment, I'm sure that a Chinese developer would get as confused as I did by a few of the nine supported languages - our hard to read ones would differ, of course

[kilay]

Is there a way to comment out a string inside gamedatabundle?

Edited July 18, 2018 by kilay

[peardox]

// Commented out

 

Depends on how good their JSON is

 

In a Mod - I'll go hack first_mod

[peardox]

Tried it with first_mod

 

Breaks the mod

 

Dev PM time

 

you're quite correct, @kilay, we should be able to comment out mods

[peardox]

Done Devs with specific reqs

 

Single line, embedded and multi-part should be parsed out of any Mod

 

So..

 

// Some stuff is ignored

      "ID":"abcdef.....", // Something awesome becomes without this comment

 

/*

  Just ignore me

*/

 

Standard C-Style syntax

[Xaratas]

Done Devs with specific reqs

 

Single line, embedded and multi-part should be parsed out of any Mod

 

So..

 

// Some stuff is ignored

      "ID":"abcdef.....", // Something awesome becomes without this comment

 

/*

  Just ignore me

*/

 

Standard C-Style syntax

It's json, where is the place you would see a comment handler in a json parser?

Show me a C# json library with such crazy feature, and then it has a tiny chance obsidian like it and include it.

[kilay]

I only found that about ability (and the same note there is also in progression table).

I wonder if we can add that structure format also to others components

 

 

 

EDIT:

I can confirm that It works also in other components

Edited August 1, 2018 by kilay

[Wodehouse_44]

How would I create a new version of the Gipon Prudensco, with the same effects/enchantments of the Sharpshooter's Garb, and place it in a shop in Port Maje?

[peardox]

See First Mod sticky

 

I explain exactly how to do this there

 

You just need to replace the Great Word with a modded your thing with some new GUID

This was the simplest mod I could think of to get ppl started

[house2fly]

How would I create a new version of the Gipon Prudensco, with the same effects/enchantments of the Sharpshooter's Garb, and place it in a shop in Port Maje?

The short version is:

following peardox's first mod guide, create a new directory for your mod and a new .gamedatabundle file inside it.

In the game files, find Gipon Prudensco in items.gamedatabundle. Copy all the data into your gamedatabundle file.

Use the online UUID generator to replace the item ID (you can also just come up with a UUID yourself but don't use any letters after F)

Find the sharpshooter's garb in items.gamedatabundle. Copy everything in the square brackets after "ItemMods"- an itemmod is what the game calls an enchantment, or any property of an item.

Go back to your gamedatabundle and replace everything in the square brackets after "ItemMods" with what you just copied.

 

Voila, a new version of the Gipon Prudensco, with the same effects/enchantments of the Sharpshooter's Garb.

This doesn't include upgrades though. If you want to add those, search for the names of the enchantments you want in items.gamedatabundle, copy their IDs, and paste them into the ItemMods square brackets.

 

To add to a vendor, follow peardox's guide in the First Mod thread

[Rolor]

Is it possible to remove stats scaling on a status effect?

 

I wanted to remove the way Deleterious Alacrity's DoT's dmg and duration respectively scale on might and intelligence, however I saw nothing about that in the status effect objects, so I infered that what stats affect which value is directly linked to the StatusEffectType property. There is a list of those types at the end of the statuseffects bundle, each with a datatype property, but I haven't found anything beyond this to help me.

 

Thanks.

[kilay]

Is it possible to remove stats scaling on a status effect?

 

I wanted to remove the way Deleterious Alacrity's DoT's dmg and duration respectively scale on might and intelligence, however I saw nothing about that in the status effect objects, so I infered that what stats affect which value is directly linked to the StatusEffectType property. There is a list of those types at the end of the statuseffects bundle, each with a datatype property, but I haven't found anything beyond this to help me.

 

Thanks.

 

No, cuz those effects doesn't have increased duration/healing/damage due a scaling mechanics, those bonuses are flat bonuses receveid from attributes that affect 'any' game mechanics (so any spell/ability)

 

 

 

 

Edited August 13, 2018 by kilay

[Rolor]

Yet this still has to be defined somewhere, it doesn't come out of nowhere. Deflection and armor rating maluses from Exposing vulnerabilities are not set to scale/receive bonus from any stat, because those status effect types are not defined as such.

[peardox]

God, I'm doing a @kilay answer (soz mate)

Yep you can do the kinda thing you describe

 

I'd write a sample simply to defend my friend

 

NOT GONNA (I am intensely protective of the team, as they of me)

 

Hey guys - look @ the count (not me, this jerk)