Modding:Basics

* Modding
* Modding:Basics
* Modding:Intermediate

# Introduction

Modding is accomplished in SCL by the extraction of game *assets* (i.e. database files, xml files, meshes, textures, etc.). The developer has used the Unity3D gaming engine to develop SCL. When creating your game in Unity, the engine stores all of the assets in a compressed format called an *asset file*. Further compression can be done by adding these to an *asset-bundle file*. These will be explained a bit more later.

Using only a small handful of free, easy-to-learn tools, you can access all of these files, and create your own mods to share with friends and the community!

# Directories

For the purposes of modding, there are four directories of interest.

Installation Directory
By default, *C:\Program Files (x86)\Steam\SteamApps\common\Sword Coast Legends*. This is the game's main installation folder, and contains the \*.exe file of the game.
Game Data Directory
*%Installation Directory%\SwordCoast\_Data*. This is where you will find most of your non-graphical assets.
Assets Directory
*%Game Data Directory%\StreamingAssets\Assetbundles\Desktop\Assets*. This is where you will find most of your graphical assets, such as meshes and 2d Textures.
Mod Directory
*%Game Data Directory%\StreamingAssets\Mods*. This is where you will add all mods, so that the game can easily recognize which files to use, when running a modified game.
# File Types

For the purposes of non-graphics modding of SCL, there are four main file-formats that you will need to recognize:

.assets
These are the Unity Asset files that archive and serialize game data. Example: most mesh and texture data, as well as game databases, described below.
.unity3d
These are the Unity Asset-Bundle files that contains compressed bundles of Unity Assets. Example: the game's UI.
.XML
A file that contains a human readable set of rules. Example: Vendor inventory tables.
.JSON
A lightweight data-exchange format. This allows information to be easily stored, accessed, and modified. Example: Skill parameters, creature statistics
Both \*.XML and \*.JSON files are located inside of the \*.assets and \*.unity3d files that are used by SCL.

# Files of Interest

The assets most people would be interested in modding are located in one of two files.

resources.assets
This is located in the *SwordCoast\_Data* directory of the game's main installation folder. This contains the vast majority of the files of interest, such as XML files dictating dungeon layouts and loot tables, and JSON files encompassing stats, scaling, leveling and ability information of all sorts. This is where most people (other than graphical modders) will find their files.
ui.unity3d
This is located in the *..\SwordCoast\_Data\StreamingAssets\AssetBundles\Desktop\Assets* directory. This contains fewer files, but houses files for the User Interface, including the World Maps, and the Icon Sheets. Graphical modders will be interested in this file, in addition to others not listed in this basic tutorial.

# Setup

In order to add mods to the game, you have to do just a little bit of prep work. Go to your mod folder (see above for directory path) and create a new folder inside that you can name whatever you like. For example, mine says "scln". Then go to your installation directory (see above for directory path) and open the GameConfig.JSON file. If it doesn't automatically open, you can right click it and Open With either WordPad or NotePad.

Inside the brackets you'll see a pair of quotation marks. Add your mod folder's name inside. for example, mine would say "Mod":"scln". Save that file and you are now all ready to get started.

One nice side note is that this system allows you to have as many mods downloaded as you would like. To change which mod loads you simply edit your GameConfig.JSON file to point to a different mod project folder. That easy.

# Tools

To mod SCL you will primarily be working with three tools: a text editor (XML & JSON) and a tool to extract game files out of .assets. For new modders, these tools are recommended to keep it easy:

* Text Editors - XML
	1. NotePad ++ - Simple and still advanced enough for extended use.
* Text Editors - JSON
	1. JSONEdit - Allows for structured editing of JSON files
* Unity Assets Bundle Extractor (UABE), 1.8b or later by DerPoPo, to unpack *.assets*
	+ Install Package: https://7daystodie.com/forums/showthread.php?22675-Unity-Assets-Bundle-Extractor
	+ GitHub - Bug Tracking: https://github.com/DerPopo/UABE
* PowerShell
	+ This is a useful tool for Windows users. You can do mass renaming of files, mass movement's, or basically anything that the old File Explorer just wont do, with the benefits of Object Oriented iterations and capabilities

Once downloaded, the JSON Editor and UABE packages should be placed somewhere you can easily find them. For new modders, place them on your Desktop (suggested location is inside a folder called SCLTools). Both of the packages are archived folders, so right click and Extract them, it is suggested to extract them to their own folders. You are now ready to commence modding!

## Power Shell scripts

1. Renaming - Remove 'txt' extension from files

```
# --------------------------------------------------------------------------------
#
# $dir - The directory to the location you exported the Unity Asset file(s) to.
#

$dir = ""
cd $dir
Get-ChildItem -Filter '*.txt' | Rename-Item -NewName {$_.Name -replace '.txt', ''} #-WhatIf

```

# Best Practices

Modding can easily be one of the most frustrating hobby activities you can engage in. Things won't work. You'll forget what you just did. You'll overwrite files. You'll accidentally turn custom NPCs into Bro... wait.

I have found that a couple of basic techniques can go a long way to making modding an easier and less screen-smashing experience.

1. ALWAYS make a backup of the original file that you are going to work on.
	* It is suggested to have two folders, Original and Modded. This will allow you to quickly check the original file(s) for reference, no matter how many edits you have made (and it saves you time compared to extracting the file(s) over and over again.)
2. ALWAYS use Save As instead of just Save.
	* Label your files with a simple version numbering system (such as, file00.filetype to file99.filetype to make it easy). Alternatively, you could use date-time style pattern, which ever suites your style editing. (example: file20160106.filetype OR file201601061358.filetype)
	* In modding, you will find that edits you make will have unintended consequences. A variable here, modifier there, you think you'll have it figured out and then suddenly you've dyed all your goblins neon pink despite only working on their ability sets. It saves you SO MUCH TIME being able to quickly revert the last change you made.
	* Keep a couple of older versions around in case something pops up later. If hard-drive space is an issue, zip up your "Live" Mod-pack into a version.
3. ALWAYS log your changes in a simple changelog document.
	* This doesn't need to be extensive patch notes, but it should tell you exactly which files you've touched and what variables you've changed.
	* This helps you squash bugs and trace your work flow in case something didn't work.
4. ALWAYS record successful work flows.
	* Knowing the process of modifying a particular kind of file or entry will save you a ton of time.
	* This could be noted in your changelog document and it could be something simple like "To add a custom monsterset, open thisfile.JSON, edit thisvariable for each monster, then open thisotherfile.JSON and add them to the DM UI by doing thisthing". Otherwise you'll constantly be relearning things rather than actually modding.
5. ALWAYS use a naming convention to be able to find your modifications inside the files.
	* For example, use the tag *scln\_* so you can quickly CTRL-F find any modification you have made to the base game files. A new monster set might be *dc\_scln\_new01* or a line of dialog might be *scln\_customdialog1000*.
6. ALWAYS keep a backup of your mod files in a place that can be recovered if your computer blows up.
	* Nothing sucks more than working several dozen hours on something and then having your cat eat a wire which fries your hard drive, lights your apartment on fire, and (most damaging) loses your mod.
	* Whether it's a file share like Dropbox or GoogleDrive or something more sophisticated like Github or SVN -- keep it safe!

# Extraction

Before we begin our first mod, we'll need a file to work with.

Jocolloman has created a repository of the game TextAssets should you want to download them directly, rather than export them from resources.assets.

* If you download them, you can skip this section regarding Extracting Assets.

Go to the folder where you unpacked UABE and double click AssetsBundleExtractor.exe.

1. The application will open in a small window.
2. Click File, then Open.
3. It will ask you to select which .assets you want to open.
4. If you navigate to your game data directory (see above for directory path), you will see 80+ .assets files.
	* Most everything you will ever need to mod in SCL can be found in the 1.3gb+ one called resources.assets.
5. Select it and click Ok.
	* It may take a while to open for you depending on how good your PC is. resources.assets contains thousands of files and weighs in at 1.3gb.

There are two useful ways to manipulate the file list.

1. Sort by file type.
	* This is the Unity designation rather than the file extension, so don't be confused.
	* Right now we are interested in the Text Asset file type which includes JSON and XML.
2. Sort by name.
	* You can then click on any of the assets and begin typing and it will go alphabetically to the asset you are looking for.
	* Go ahead and do that and type the first few letters of StatGrowth. We'll be working with a file called StatGrowth.JSON for your first mod. Select it.

On the right hand side click the Plugins button.

* You will get a new box that allows you to Export to .txt. That will allow you to save a copy of the asset as a text file.
* Put this in a spot you will be able to find (like inside your mod folder).

IMPORTANT NOTE
Because the file is a non-language .JSON (language JSONs are English.json, Spanish.json, etc), you will need to manually remove the .txt extension from the exported file so you can open it in JSONEdit. You can do that by simply clicking the name of the file and deleting the .txt. Accept any prompt that changing the file type might make it not work. It'll be okay. JSONEdit doesn't like the language JSONs. I recommend editing those in a text editor.
# Editing

Now that you have a copy of StatGrowth.JSON and removed the .txt extension, let's open it up and try to understand how these files are organized.

In all cases of the JSON files, the first array is always the definition of the following values.

Think of the information as being like a Spreadsheet table, with two columns. (1) Name & (2) Value

```
    "levelxp": [
        {
            <description>: [
                <index>,
                <datatype>
            ]
        },
        {
            ....
        }
    ],

```

description
This would be the Value Description
index
where in the series of data-points is Value Description
datatype
What type of data will be contained. Currently, there are 5 main Data-Types identified: XRef (0), String (1), Resource (2), Integer (3), and Number (4)
The Column definition section, is in alphabetical order, so there is a possibility that the column at index 0 is at the end, index 1 could be in the middle and index 22 at the top of the list of the Column Definitions.

### Prime Example

Take the file **StatGrowth.JSON** and section **rt\_stats**:

```
"rt_stats": [
    {
        "abilitypool": [
            25,
            0
        ],
        "armorclass": [
            7,
            1
        ],
        "charisma": [
            5,
            1
        ],
        "charismasavebonus": [
            24,
            1
        ],
        "constitution": [
            2,
            1
        ],
        "constitutionsavebonus": [
            20,
            1
        ],
        "damagereduction": [
            17,
            2
        ],
        "dexterity": [
            1,
            1
        ],
        "dexteritysavebonus": [
            21,
            1
        ],
        "immunities": [
            15,
            2
        ],
        "intelligence": [
            3,
            1
        ],
        "intelligencesavebonus": [
            22,
            1
        ],
        "maxhealth": [
            6,
            1
        ],
        "perception": [
            9,
            1
        ],
        "proficiencybonus": [
            11,
            1
        ],
        "resistances": [
            14,
            2
        ],
        "saveproficiencies": [
            18,
            2
        ],
        "sneak": [
            10,
            1
        ],
        "strength": [
            0,
            1
        ],
        "strengthsavebonus": [
            19,
            1
        ],
        "unarmeddamage": [
            12,
            1
        ],
        "unarmeddamagetype": [
            13,
            2
        ],
        "vulnerabilities": [
            16,
            2
        ],
        "wisdom": [
            4,
            1
        ],
        "wisdomsavebonus": [
            23,
            1
        ],
        "xpvalue": [
            8,
            1
        ]
    },
    {
        "stats_abghoul": [
            "13,5pts",
            "15,6pts",
            "10,3pts",
            "7,ng",
            "10,ng",
            "6,ng",
            "75,meleehp",
            "9,enemyac",
            "7,medhighxp",
            "9,pg",
            "10,sg",
            "2,enemypb",
            "6,ng",
            "Slashing",
            null,
            "Necrotic,Poison,Charm,Unconscious",
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null,
            null
        ],
    }
],....

```

If you look at the NTP file (StatGrowth.NTP), the Field Definition is in the correct order:

```
     FORMAT
     {
          STRING           "Strength"
          STRING           "Dexterity"
          STRING           "Constitution"
          STRING           "Intelligence"
          STRING           "Wisdom"
          STRING           "Charisma"
          STRING           "MaxHealth"
          STRING           "ArmorClass"
          STRING           "XPValue"
          STRING           "Perception"
          STRING           "Sneak"
          STRING           "ProficiencyBonus"
          STRING           "UnarmedDamage"
          RESOURCE         ""    "UnarmedDamageType"
          RESOURCE         ""    "Resistances"
          RESOURCE         ""    "Immunities"
          RESOURCE         ""    "Vulnerabilities"
          RESOURCE         ""    "DamageReduction"
          RESOURCE         ""    "SaveProficiencies"
          STRING           "StrengthSaveBonus"
          STRING           "ConstitutionSaveBonus"
          STRING           "DexteritySaveBonus"
          STRING           "IntelligenceSaveBonus"
          STRING           "WisdomSaveBonus"
          STRING           "CharismaSaveBonus"
          XREF             ""    "AbilityPool"
     }

```

## JSON

Here is the basic process:

1. Go to the folder where you unpacked JSONEdit and double click JSONEdit.exe.
2. Click File then Open and find your .JSON file.
3. Once it loads, click the Tree formatting on the left hand side panel to make it easier to read in node format.
4. Change whatever values you want (we will actually do this in a second).
5. File and Save As your newly modded file.
6. Manually add the .txt extension back onto the file and remove any version numbers you might have added (so the game can read it).
7. Place your mod in your SCL mod folder! Make sure you only have 1 copy of any given file in there, you don't want conflicting data.

Go ahead and open StatGrowth.JSON.

Now let's look at the file structure itself. It's really quite basic. The first layer to it is the root. You won't ever do anything with root, so you can Expand it and forget it's there.

The second layer of nodes are the major categories in the JSON file.

In StatGrowth specifically you will see:

* levelxp: Determines how much XP a PC needs to reach the next level.
* rt\_stats: Determines the base stat of every creature in the game.
* rt\_growths: Determines how the base stats scale up based on level.
* rt\_trapvalues: Determines trap spot and disarm values by level.
* statbalance and datavalues we won't worry about because they are only needed if we are adding or subtracting nodes -- not for our first mod!

Each of these nodes has two different data arrays, [0] and [1]. In this case, [0] shows the definitions for each node in [1] in the order they appear. For example, if you expand levelxp[0] you see that we are defining xptonextlevel. If you expand levelxp[1] you'll see an array of levels 1-20.

Did your mind just flash thinking... wait, could I add more levels?

* If so, you're already in a modder's mindset, you ambitious apprentice.

Focus and the answer is an almost positive yes.

* Yes you will be able to (eventually, it isn't \*quite\* as easy as just adding nodes here).

Now, if we expand the [1]level1 node you will see that it has that defined field (xptonextlevel) value as an integer. In this case it's 300. Let's pretend we are tired of running Farming Modules to level up our characters. Let's change that to 1. Yes. One. XP.

1. Click File and save your work.
2. Re-add the .txt extension to your modded file.
3. Copy your new StatGrowth.JSON.txt to your mod folder.

Congratulations, you've officially made your first mod. Let's go test it out! You'll need to create a fresh level 1 PC with 0xp.

## XML

Coming Soon™! (XML files are currently unsupported by the mod folder with the exception of dungeon level XMLs)

# Known Limitations

The mod folder currently only works with JSON and dungeon level XML files.

One notable exception is the language.json files which are necessary to add custom strings (i.e. names) to the game.

* In other words, you can add custom creatures or abilities to the game, but the text will show up in game as an error: "DNF: scln\_customvendor1", for example.

Also, we are currently unsure which files need to be on which computers to work. To be safe, have all of your players install your mod folder and activate them in **GameConfig.json.**

The SCLN team has been producing more advanced mods that won't currently work with this method of modding, so we are debating either releasing it and teaching you the other method (in case nSpace takes a while to add the necessary functionality), or releasing it in a modular, unfinished way.

* JSON/XML List - Only files within this list will be replaced during mod loading using GameConfig.json activation.