FakeFish guide: Modding reference

Overview

This is the first edition of a general-purpose modding reference guide. It will hopefully be of assistance to anyone who mods, or would like to mod Barotrauma, even in its current, largely work-in-progress state. Please use the comments section to let us know what kind of documentation should be added in the future!

Hello and welcome to modding Barotrauma!

We want to make Barotrauma as modder-friendly as we can. To that end, the game comes with a couple of editors, and we have separate, more in-depth guides for the Submarine and Character editors.

This guide you’re reading now is intended to cover what happens outside the editors. We hope you find it helpful, and we’d be happy to hear what you think should be added to it in the future!

Content packages

Content packages are essentially files that tell the game which content files to use and where they are located. This includes items, structures, monsters, random events, level generation parameters, jobs and so on. By default the game uses a content package called “Vanilla 0.9”, which you can find in Content/Data/ContentPackages/Vanilla 0.9.xml. Any other content package can be considered a modification of the game content, that is, a “mod”.

The content packages are in a format called XML[en.wikipedia.org], as almost all other moddable content in Barotrauma. If you have no prior experience with the XML format, don’t worry – even though it may look intimidating at first, the format is pretty simple. Please see the “XML” section later in this guide for further details.

Note that if you just want to publish a custom submarine in the workshop, you don’t need to worry about content packages – you can just select the submarine from the “Publish item” tab in the Workshop menu, and the game automatically creates a folder and content package for your mod.

If you use the built-in character editor for creating a new character, you will have to select or create a content package for it. You cannot use the vanilla content package, because modifying the vanilla content package would make your game incompatible with the other players.

When playing in multiplayer mode, the players generally need to have the same mods installed as the server, or they will be unable to join. However, this does not apply to all types of content: for example, the clients can use mods that modify the UI or sounds without causing incompatibility with servers. See the “Content types” section for more info on which types of content cause compatibility issues.

A very simple content package could be configured as follows:

This mod would simply add an extra item to the game (or items if there are multiple ones configured in the potatogun.xml file).

Most mods are usually not core content packages, but instead add things to or modify things in the Vanilla content package (= the default content of the game).

Core packages are packages that contain all the necessary files to make the game run, instead of just adding some extra files on top of another content package. There can only be one core package selected at a time.

Here’s an example of a simple core package:

This content package would replace all the items in the game with whatever items are configured in the “Mods/BestModEver/items.xml” file. It would also use a modified version of the human characters and have all the monsters in the game replaced with Crawlers and Cthulhus. The random events have also been changed – perhaps by adding a new event that spawns Cthulhu and removing the events that spawn monsters/items which aren’t included in the mod.

Note that the content package should be saved with the file name “filelist.xml” in the Mods folder, in this case “Mods/BestModEver/filelist.xml”.

XML

Most of Barotrauma’s content (monsters, items, structures, random events, jobs, etc) is defined in XML files[en.wikipedia.org]. These code files may seem daunting if you’ve never used them before, but they’re actually quite simple to understand even if you’ve never done any sort of programming.

The XML files can be edited with almost any text editor, even notepad, but we recommend using a text editor that supports code highlighting and is able to point out mistakes in the file. For example, Notepad++[notepad-plus-plus.org] is a free, easy to use software that supports XML code highlighting. Other good options are Sublime Text[www.sublimetext.com] and Visual Studio Code/Community[visualstudio.microsoft.com].

XML files consist of elements, which in Barotrauma’s case could be for example an item. The elements are defined as follows:

An element can also have attributes, which usually give some additional information about the element. For example:

Elements can also have child elements. Barotrauma’s item elements for example have a child element called “Sprite” which determines what the item looks like.

Note that the Item element now looks a little different. The previous examples defined the element on a single line, and the “/>” symbols marked where the element ends. Now when we needed to add a child element inside the Item element, the Item had to be split into multiple lines, </Item> marking where the element ends.

Overriding content

Usually you are not creating a total conversion mod, but you might still want to override parts of the original content. This can be done by using the “override” elements in the xml configuration files.

Overriding is based on identifiers (where applicable), meaning that the identifier of the new item must match the identifier of the old item. If you try to override an item that is not found in the game, you will get an error in the console.

For example, the content of the potatogun.xml file included in the previous content package example could be something like this:

This mod would replace the vanilla “Harpoon Gun” with a “Potato Gun”. The behavior of the gun is omitted in the example, but we would probably want to change the texture of the gun. In that case, we would replace the original “Sprite” element with a custom, like so:

In order to get the new item to function like the vanilla counterpart, make sure to include all the tags of the original item. You can add tags, but don’t remove them (unless you really know what you are doing), or the item might not work as it should.

Note that for some content types, like items, you can override multiple definitions by simply adding the override element as the parent of the main element, like this:

Overriding is already implemented for most content types, but not every single one of them. In the future, you will be able to modify all the content types. Next, let’s have a look at the various content types we have.

Content types

In the previous examples the content packages included a couple of different types of content files: items, characters, structures, jobs, random events and the game executable. Here’s the full list of all supported content types. Unfortunately we don’t yet have a full documentation available for modifying all of the content types, but you can use the Vanilla content files as a reference to see how they work; most of them are pretty straight-forward.

Some types of content prevent players from joining servers if both the player and the server don’t have the same content installed, while some can be freely installed without compatibility issues.
The ones that cause multiplayer incompatibility are Jobs, Item, Character, Structure, LocationTypes, MapGenerationParameters, LevelGenerationParameters, Missions, LevelObjectPrefabs, RuinConfig, Outpost, Afflictions and Orders.

Some of the content files are mandatory in core content packages. For example, you cannot have a core content package that does not include any items, characters or a game executable. The required types are Jobs, Item, Character, Structure, Outpost, Text, Executable, ServerExecutable, LocationTypes, MapGenerationParameters, LevelGenerationParameters, RandomEvents, Missions, RuinConfig, Afflictions, UIStyle, EventManagerSettings and Orders.

A submarine file. Even though the game automatically loads all submarine files from the Submarines folder, if you publish a submarine in the Steam workshop, a content package containing only that submarine will be generated to tell the game where to find the submarine file.

The character’s jobs; Captain, Engineer, Mechanic and so on.

An item file that may contain one or more items.

A group of multiple items that may be pre-wired or pre-configured. Item assemblies can be created in the submarine editor.

A character configuration file defines visual things like sounds and particle effects as well as functional things, like how the character acts, how much health does it have, and whether or not it can walk. A character configuration file also contains references to the ragdoll and animation files.

Note that, at least for now, the character configuration file must match the species name. So the character configuration file for a character with the species name “Mygreatcharacter”, for example, should be Mygreatcharacter.xml. The species name is used like the identifier for items, so it has to be unique.

Editing characters in xml can be difficult, unless you really know what you do. Fortunately, we have a built-in editor for creating and editing the characters. There still is a few things you cannot adjust in the editor, but in general, you don’t have to manually edit the .xml files anymore to edit the characters. For further information about creating and editing characters, see the character editor guide.

A structure configuration file; decorative background walls, solid wall pieces, etc.

An outpost used in the campaign mode. The outposts are technically static, immovable submarines and can be created using the submarine editor.

A file that defines in-game texts, which can be anything from texts you see in the menus to item names, and from error messages to loading screen texts. Mods don’t usually need to define new text files, but if you for example are creating a mod that adds new items and want the item names and descriptions to be translatable to multiple languages, you need to create text files for all the languages you want to support and define the names and descriptions there.

Where the game executable itself is stored. Only for advanced users: this may be useful if you’ve compiled a custom version of the game and want to create a mod that uses the custom executable instead of the normal Barotrauma.exe.

Similar to Executable; defines the path of the dedicated server executable.

Defines the types of locations that can appear on the campaign map (City, Outpost, Military, Research…)

Defines how the campaign map is generated. This includes the size, the amount and placement of locations, how the map looks and the number of difficulty zones, among other things.

Defines how the in-game levels are generated. This includes the size and shape, how the level looks like, the amount of smaller caves and ruins and many other things. You can create and test your own level generation parameters in the in-game level editor which can be accessed using the console command “editlevels”.

Defines the environmental objects such as plants, decorative rock formations, water currents, hydrothermal vents. These can also be edited in the level editor.

Defines the random events that can occur during rounds.

Defines the missions that are available in the campaign and the mission mode.

Defines the decorative, non-interactable background creatures that wander around the levels.

Defines music and sound files. Do note that item-specific and character-specific sounds are defined in the item and character configuration files – the sound configuration files only define “global” sounds such as music, ambient, fire and water that aren’t related to some specific item/character.

Defines how alien ruins are generated, including their layout, which structures they are made of and how items are laid out inside them.

Defines particle effects such as explosions, fire, splashes, etc. These can be edited using the in-game particle editor which can be accessed using the console command “editparticles”.

Defines decals such as blood spatters, explosion damage and burnt walls.

Defines the random NPC conversations and dialog lines.

Defines afflictions such as blood loss, internal damage, addictions, infections, etc.

Defines the tutorial configurations. Do note that modifying the tutorials or creating your own ones will most likely require changes to the game’s source code and recompiling the game.

Defines UI style files which determine how UI elements look. These can be used to, for example, modify how the in-game menus or device interfaces look.

Defines traitor missions.

Items

Items consist of one or more “item components” that determine the functionality of the item. For example, an item could have a “Holdable” component that makes it possible to pick it up and hold it in your hands and an “ItemContainer” component that lets you contain other items inside it.

If you are familiar with Unity, you can think of items as Unity’s GameObjects, and item components as the Components attached to the GameObjects.

In the following sections we will go over all the available item components and their editable properties.

Let’s start with the properties shared by all the item components.

Item component reference (A–D)

No editable properties.

Item component reference (E–G)

Item component reference (H–I)

Item component reference (L)

No editable properties.

Item component reference (M–Mo)

Item component reference (Mu–O)

No editable properties.

No editable properties.

Item component reference (P–Pow)

No editable properties.

Item component reference (Pr–Pu)

Item component reference (R–Rel)

Item component reference (Rep–Sm)

Item component reference (So–Su)

Item component reference (T–Tri)

Item component reference (Tur–X)

No editable properties.

No editable properties.

Publishing your mod

Mods need to be shared with other players so that you can play together with them in multiplayer mode.

Fortunately, publishing a mod is fairly simple: first you need to go the the “Publish” tab in the Steam Workshop menu and select your newly created content package. The folder where the content package resides (for example, “Mods/MyMod/”) and all its contents will be uploaded to the Workshop.

Make sure all the files required for your mod are present inside the folder: textures, audio, xml files and so on. Your content package can also reference content outside the mod’s folder, but this content will not be uploaded into workshop — generally you would only do this if you want to make a core package that uses some of the vanilla files without having to bundle the vanilla files with your mod.

Once everything is ready, simply click ‘Publish item’. The mod should now be found in Steam workshop, where others can find and download it.

Thanks for reading!

Hopefully you found this guide helpful. It is still pretty bare-bones – please let us know which features you would like more guidance on to give us an idea of what we should prioritize when working on this guide. If you have any questions, please use the #baro-modding channel of our Discord[discord.gg] or the Workshop Discussions subforum here on Steam.