Modding Guidelines

[Goodspeed]

It is now much easier to mod Sunless Sea!

We've added a new directory called addons to your game, which will give you a safe place to store modded files where they will not be overwritten by game updates.
Today's changes will also enable us to add DLC to Sunless Sea beyond new stories. It's our first step toward preparing the core game for Zubmariner's arrival.

Now that we’ve made it easier to mod Sunless Sea, it seems an appropriate time to offer up some best practices that will help anyone get their first Mod up and running.

Where do I start?

Once you have updated Sunless Sea to V1.0.4.2118 and updated your Stories, you will see a new folder called ‘Addon’ in the following directory (varying slightly depending on your operating system):

PC Directory - C:\Users\**NAME**\AppData\LocalLow\Failbetter Games\Sunless Sea

Mac Directory - /Users/<username>/Library/Caches/unity.Failbetter Games.Sunless Sea (replacing '<username>' with your actual username).


This is where your mod will go. Create a new folder and give it a name, for example ‘Macs Mod’.

Within this folder we can place all the files we want to Mod. The files must be placed in the correct corresponding folder, for example Qualities.json must be within a folder named Entities.

So a mod directory that contains a modded Qualities.json might look like this:


C:\Users\**NAME**\AppData\LocalLow\Failbetter Games\Sunless Sea\addon\Macs Mod\entities\qualities.json.
Below is a list of all the folders that can be included within a Mod:

- Constants
- Encyclopaedia
- Entities
- Geography

What tools can I use?

All of the files you will be editing are .json file types, the best way to edit these is in Notepad/Notepad ++ or another Json editing tool. Personally I like to use both Notepad ++ which allows Json formatting and an online tool called Json Editor Online (http://www.jsoneditoronline.org/).

Dos and Don’ts

A lot of the process of modding will be trial and error and hopefully this list can be expanded with feedback from you folks, below are just a few pointers I would recommend any new modders take note of.

- Don’t include the whole file
If we have a Mod that has for example an Events.json file, when we launch Sunless Sea the game will look through every Event in your modded file and merge any new events with the default events. When duplicated events are found the Mod file will override the default ones. But we want the default files to stay up to date and be affected by new game updates, so we don’t want to override a bunch of events that we haven’t edited.

- Mod on Mod
Mods can and will work together, but conflicts can arise, if two mods are using the same Quality Id then the last Mod in the directory to be merged will replace the one before it. This is another reason it’s good practice to only include the content you want to edit.

- New Ids or Same Ids
If you’re creating/replacing for example qualities, it’s important to manipulate the Id field correctly. If you’re creating a new Quality, you want to make sure the Id is unique, to do so it’s probably best to start at a very high number and increment every new Quality you add from there, for example Id: 300001, Id: 300002. If you want to replace a Quality, you should leave the Id as it is, that way when your Mod is synced, the duplicate will be spotted and your Mod will override the default quality.

- New Images
If you want to add or manipulate images it’s best to create new ones. If you want to have a new image for ‘baldman’ DON’T place a new image with the same name in the image directory as it could be replaced during an update. Instead, create a new image called ‘baldman1’ and change the name of the image in all the events within Events.json where the baldman appears.

- Json file is corrupt!
When you start tinkering with Mod files this is a message you might see quite frequently when you launch a new game. It likely means that you’ve accidentally left out some important formatting and it’s probably going to be one of these from a line ending - [] {} , ‘.

- Like for like
If you want to create a new item it’s best to look at an example of another item that is already in the game. Likewise for Events if you want to create an event that links to another best to look for an example of where this is already being done.

[Tubzbuster]

Hooray!

[aardvarkpepper]

Yeeeeeee

[Cultist John]

Neat!

[arif.merchant]

Finally!!

[parker]

AWESOME

[the-truthseeker]

Zailing, zailing, under the Sunless Sea. While we wait for Zubs, and fixed the flubs, there are mods for you and me!


Thanks for doing this everybody at Failbetter!

People have been wanting this for quite a while now!
I'm sure we'll need to make things like mod loaders eventually for multiple mod conflict avoidance, but that's a happy necessity since we now have mods!


I look forward to our community making some grand things!

[windoverwasteland]

I've tried playing with the feature. Changing spawns, area descriptions and tiles worked fine.
But then I've hit the wall: nothing I do to that one file everyone loves to mod - addon/MyAddonName/constants/navigationconstants.json - has any effect.

Changing original navigationconstants.json works just fine, by the way.

In fact, if I mess up the syntax while editing areas.json or tiles.json in the addon folder, the game tells me my json file is corrupt, as it should. However, the game is silent even if I put complete gibberish into navigationconstants.json, as if it doesn't recognize the new file.

I've double-checked the path - in fact, I've copied the folder structure to make sure folder names are not messed up, but the result is still the same.

Can anyone else replicate this? Or am I missing something obvious?

[Hells_Razer]

no i noticed it also it does the same for me

[Cantorsdust]

Can confirm. It's odd because it worked for me after the first modding update, but not after this most recent fix. Did they break something again?

[MadameHardy]

Immediately after this update was pushed, most of the icons became blurry on my 13" Macbook Pro (Yosemite 10.10.5). Has anybody else noticed this happening? It looks as if they're being upscaled, badly.

[Hells_Razer]

Originally posted by MadameHardy:

Immediately after this update was pushed, most of the icons became blurry on my 13" Macbook Pro (Yosemite 10.10.5). Has anybody else noticed this happening? It looks as if they're being upscaled, badly.

I think the game reset the video options to default, check it out.

[Tystefy]

Yep, cannot change the navigation constants. Whenever I edit the Base Ship Speed to any other number other than 8, my ship sloooooooooows to a horrendous crawl. If I change the BSS back to 8 the ship speed doesn't revert itself... Good thing I've made duplicates of the original .json file!

[the-truthseeker]

So is it some universal call to default speeds causing this? I honestly have no idea why ship navigation speeds do that now.

[ChickenStrip]

What is the minimum amount that I can change and have my adjustments be properly merged? I am making a mod that adjust the game speed, which means changing speed parameters. For example, the Megalops:

{
"Name": "AuroralMegalops",
"HumanName": "Auroral Megalops",
"Description": null,
"PrefabName": "Fierce/Organic/AuroralMegalops",
"BehaviourName": "aggressive",
"DormantBehaviour": "Wandering",
"AwareBehaviour": "HuntingPlus",
"BeastieCharacteristicsName" : "LightShySwimmer",
"MovementSpeed" : 16,
"RotationSpeed" : 1,
"Life" : 20,
"CombatAttackNames": ["Ram01"],
"KillQualityEventId" : 148076,
"LootPrefabName" : "Blood"
},

Do I need to replace it with:

{
"Name": "AuroralMegalops",
"HumanName": "Auroral Megalops",
"Description": null,
"PrefabName": "Fierce/Organic/AuroralMegalops",
"BehaviourName": "aggressive",
"DormantBehaviour": "Wandering",
"AwareBehaviour": "HuntingPlus",
"BeastieCharacteristicsName" : "LightShySwimmer",
"MovementSpeed" : 48,
"RotationSpeed" : 3,
"Life" : 20,
"CombatAttackNames": ["Ram01"],
"KillQualityEventId" : 148076,
"LootPrefabName" : "Blood"
},

Or will this suffice?:

{
"Name": "AuroralMegalops",
"MovementSpeed" : 48,
"RotationSpeed" : 3,
},

I suspect that I am stuck doing the former due to how the JSON is structured, but being able to do the latter would be great.

[ChickenStrip]

Most of the changes I had made in the previous mod still work, except boat speed. I had only adjusted the base boat speed. Did something change with how movement speed was calculated since launch?