Content Packages/Creation

From Official Barotrauma Wiki
Revision as of 13:01, 30 December 2023 by G3jzer (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The following is the text found in Barotrauma's files, relating to the creation of Content Packages.

Modding info/tips

When doing an automatic update through the launcher, any old/unnecessary files in the Content folder will be deleted. This also includes any new files you may have added to the folder.

It is recommended to save all modifications to the Mods folder, or in the case of custom subs, to the 'Submarines folder.

Content Packages

Content packages determine which configuration files the game will be using. This includes the configuration files for items, map structures, characters, monsters and jobs.

In the multiplayer mode, players are required to use the same content package as the server or they won't be able to join.

If you are making a mod for the game, it is recommended to create a new content package instead of just replacing existing files in the content folder. This way you and anyone else using the mod can easily change between different mods and the vanilla version, without having to manually replace files in the Content folder or keep backups of different files.

The content packages are configured in XML files which are saved in Data\ContentPackages.


A very simple content package could be configured as follows:

<contentpackage name="BestModEver" path="Data\ContentPackages\BestModEver"> <Item file="Mods\BestModEver\items.xml" /> <Character file="Mods\BestModEver\Human\human.xml" /> <Character file="Mods\BestModEver\Cthulhu\cthulhu.xml" /> <Character file="Content\Characters\Crawler\crawler.xml" /> <Structure file="Content\Map\StructurePrefabs.xml" /> <Jobs file="Content\Jobs.xml" /> <RandomEvents file="Mods\BestModEver\randomevents.xml" /> <Executable file="Barotrauma.exe" /> </contentpackage>

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.

Creature modding

All the creatures/characters in the game are configured in XML files.

The XML files should be formatted in the following way: <character name="something"> <ragdoll attribute1="something" attribute2="something">

<limb id = 0> <sprite texture="texturepath" sourcerect="0,0,width,height"/> <attack type="something"/> </limb>

<limb id = 1> <sprite texture="texturepath" sourcerect="0,0,width,height"/> </limb>

<joint limb1="0" limb1anchor="x,y" limb2="1" limb2anchor="x,y"/> </ragdoll>

<ai attribute1="something" attribute2="something"/> </character>




- has to be the root element of the file


name: the name of the creature humanoid: true/false, if set to true the character is animated using a bipedal animator (like humans) needsair: true/false, does the character drown/suffocate without oxygen (false by default) drowningtime: how fast the character drowns (in seconds) doesbleed: if set to false, the character takes no bleeding damage health: self explanatory (100.0 by default)


- has to be a child element of the character element


headposition: how high from the ground the head of the character should be when the character is standing (50.0 by default) headangle: an angle which the head is rotated to when the character is walking (0.0 by default, meaning that the head will face straight forward) torsoposition: same as headposition but for torso (50.0 by default) torsoangle: an angle which the torso is rotated to when the character is walking (0.0 by default, meaning that it will face straight forward) waveamplitude, wavelength: if the character is not a humanoid, it will do a "wave-like" swimming movement with the selected amplitude and wavelength. To put it simply, amplitude affects how large up-and-down movement the character will do and wavelength affects how fast the character does the movement (both 0.0 by default) flip: should the entire character be "mirrored" over the y-axis when it switches its movement direction from left to right or vice versa, or should it just rotate along the z-axis (false by default) walkspeed, swimspeed: how fast the character should move on land and in water, (the actual speeds are also affected by the weight, shape and steerforces of individual limbs) (both 1.0 by default) swimspeed: how fast the character should move in water


- an individual part of the ragdoll - has to be a child element of the ragdoll element


id: an integer that is used to distinguish between limbs when connecting them with joints. The first limb should have the id "0", the second "1" and so on. radius, width, height: used for setting the dimensions of the physics body of the limb. If only radius is set, the limb will be a circle with the selected radius. If width and height are set, it will be a rectangle. If radius and height are set, it will be a capsule. density: the mass of the limb will be area_of_the_limb * density (default 10.0) friction: the friction coefficient of the limb (0.3 by default) flip: true/false, if set to true the limb will be "flipped" from one side to another when the character turns around (as in, if a character is facing left and has an arm extended left, the arm will be extended to the right when the character faces to the right) (false by default) ignorecollisions: true/false, should the limb collide with walls (true by default) impacttolerance: if the limb receives an impact larger than this value, it takes damage (20.0 by default) type: determines how the limb should be animated and what kind of items can be equipped on the limb. Can be set to None, LeftHand, RightHand, LeftArm, RightArm, LeftLeg, RightLeg, LeftFoot, RightFoot, Head, Torso, Waist, Tail, Legs, RightThigh or LeftThigh pullpos: when animating the character, forces will be applied to this point of the physics body of the limb. Defaults to "0.0, 0.0" which is the center of the limb. refjoint: index of the joint that is used as the "center point" along the x-axis when doing a walking animation. For example, if the joint between a characters thigh and waist is set as refjoint, the feet of the character will be moved directly under said joint when the character is standing still. steerforce: how much force is applied to the limb when the character moves (0.0 by default) armorsector: an armored sector between two angles (in degrees). For example, -90,90 would make the front sector of the limb armored (0.0,0.0 by default) armor: how effective the armor is: damage is divided by this value if an attack hits the armored sector (1.0 by default)


- a child element of a limb element


texture: file path of the texture sourcerect: which part of the texture should be used. If either width or height are 0, they will be set to the width or height of the texture. (0,0,0,0 by default) origin: what point in the sprite is considered the "middle point". "0,0" is the upper left corner of the sprite and "1,1" the lower right corner. ("0.5, 0.5" by default) depth: Affects the order which sprites are drawn in. Sprites with a depth of 1.0 will be drawn under sprites that have the depth set to 0.9 for example. Note that setting several limbs to the same depth value may cause them to "flicker" on top of each other, so it's recommended that every sprite has a slightly different depth.


- a child element of a limb element


type: affects the logic for moving the attacking limb. At the moment the only types are None, PinchCW and PinchCW

PinchCW: the limb rotates clockwise when attacking (or counter-clockwise if the character is facing left). Useful for attacks like biting or slashing PinchCCW: the same as PinchCW, but in the limb is rotated in the opposite direction Hit: the limb will "punch" the target

damage: damage done to other characters (0.0 by default) bleedingdamage: how much the attack affects the bleeding rate (0.0 by default) structuredamage: damage done to structures (0.0 by default) stun: how long the target is stunned (in seconds, 0.0 by default) range: how close the limb doing the attack has to be to the target to do damage (0.0 by default, but should be set to a higher value or otherwise it will only do damage if the limb is exactly at the position of the target, so practically never) duration: how long the attack lasts - if set to zero, it will be a "one-hit" attack, otherwise it will be active for a while and the damage values will be damage per second priority: can be used for adjusting how likely the character is to use specific attacks. For example, if a character has two attacks, first one having the priority 2.0 and the second 1.0, the character is twice as likely to use the first one.


- a revolute joint connecting two limbs to each other - a child element of the ragdoll element

Attributes: limb1, limb2: thes id of the limbs that should be connected limb1anchor, limb2anchor: the points where the joint is attached to on the limbs (0.0, 0.0 being the center) lowerlimit, upperlimit: how much the joint can turn. If both are set to 0.0, the joint can rotate freely.

Editing items

(A more extensive tutorial coming up in the future)

Items are also configured in XML files. An item consist of several components which determine the functionality of the item. See the existing item files for examples on the components.

Base item elements

Majority of items includes the following components:

  • Sprite -- a reference to the image file that defines how item should look when in-game. This tag accepts several paramters:
  1. file -- used to define location of sprite. Without directory given, this parameter will refer to file with entered name in same directory as item file.
  2. sourcerect -- array of four numbers used to define the section of image used as item's sprite. Source rect selection syntax is defined like this: [selection_start_left],[selection_start_top],[width_from_left],[height_from_top]. For example, sourcerect=0,64,64,64 will select area of 64x64 on left edge and 64 pixels down from top edge.
  3. scale -- float number that indicates the size of item in-game compared to source sprite size. For example, scale=0.5 will make item two times smaller than sprite's initial size.
  4. depth -- defines the Z axis offset of item's sprite in-game, where 0.001 is foreground and 0.999 is background.
  5. origin -- offset of sprite's central point. Consists of two float numbers: [origin_x],[origin_y], where value of 0 is left or top edge and value of 1 is right or bottom edge. Majority of sprites are considered to be displayed with sprites located in the middle, which is origin=0.5,0.5. Pay attention that float numbers are defined with dot as divider rather than comma, as comma plays role of value separation in array.
  • InventoryIconSprite -- representation of item in inventory bar. Takes same parameters as Sprite tag. Item will be present with main sprite as inventory icon once this tag is omitted.
  • Upgrade -- usually defines the game version item is defined to be used in with respective parameter gameversion=... as it's required for proper operation of game's equipment upgrade system.
  • Body -- definition of item hitbox and behavior once put in water. Takes three parameters: width, height and density, where density=10 makes item neutrally buoyant (staying still in water while idle). Not needed for stationary items such as machinery.


In-Game Dedicated Servers

Campaign Settings



Console Commands

Hosting a Dedicated Server

List of Config Files

Enabling Mods on a Dedicated Server

Tools & Modding
Editors XML Other

Submarine Editor

Official Guide to the Submarine Editor (Diving deeper)

Character Editor

Official Guide to the Character Editor

Creating mods

XML and how Barotrauma uses it

Content packages (Content types)


Installing mods

Publishing to Steam Workshop