Ever wanted to make this garbage gun more useful? Something seems to be too OP for you? Want to build an invulnerable meme machine? Or planning a big and serious rebalance mod? This guide is here to help you.

Do not forget to check my Total Rebalance mod (1.151):Nexus[www.nexusmods.com]


Disclaimer: the guide is not complete (and probably never will be), so sections may be either too brief or miss completely. However, it covers all the basic material and should enable you to discover new modding approaches on your own. Enjoy!

History:
01.03.2022: Initial version;
24.07.2022: Major edit, updated mod tools, updated save files section, added levels section;
25.07.2022: Updated save files section (spawning new SGs);
05.04.2023: Updated GH links in the Modding Tools section.
22.11.2023: Greatly expanded the Save Editing section (cities, inventories, tarkhans, ship perks, other additions); OL.seria and parts.seria section updates; spelling.
23.11.2023: Updated the Modding Tools section, new ModLoader section.

The game versions considered are 1.151 and 1.163.

Save files, ships and part configs share the common format and are stored in .seria files. Getting familiar with their structure is the first thing you should to know before taking on modifying values or adding new entries, since it will keep you from fixing the annoying syntax errors.

A .seria consists of nodes, each of which which is enclosed by {...} parentheses. Parentheses always exclusively occupy a new line, there is nothing else on it. All nodes except the root also have a header—some attribute-value pair, where a value is typically some integer. A header value should not be unique and is meaningless on its own.

An example of a non-root node (contents replaced by "..."):


Node contents may be a combination of the following:

• An attribute-value pair
  m_children=15 { ... m_classname=Body ... }
• A nested node
  m_children=15 { ... m_mesh=1073741827 { ... } }
• (Only for mesh nodes) A sequence of floats
  { m_classname=Mesh m_size=4 -3.53553 5.32097 -3.53553 -5.32097 3.53553 -5.32097 3.53553 5.32098 }

See the Libraries/parts.seria section for more info on meshes.

Attribute-value pairs may repeat:

That's how the game handles arrays. For example, the 360 "m_sectors" entries denote a firing or a sensor arc in a ship file, one for each degree.

If you want to parse/edit .seria,
DO NOT
EVER
INDENT
—this will break a file.

Armed with this knowledge, now you should be able to parse a .seria file, modify it and write it back so it remains valid. Also note that the syntax structure is quite similar to C++, so it's convenient to use C++ parsers for syntax highlighting and collapsing.

The Libraries/OL.seria is the first of the two config file related to parts. It stores parameters which don' require keeping their states in a save file, so you can tweak them and changes will apply immediately after relaunch, even within an ongoing campaign. It also contains the particularly interesting attribute which encodes the part category, which is discussed in details at the end of the section.

Luckily, the parameters belong to ones you are most likely to tweak—clip size, reload speed, cost, fuel amount, thrust/consumption and many more.

The structure is very simple—each part got a entry without nested nodes. The incomplete list of interesting entries is:

Global
Guns
Missiles

This subsection is based on the A220 Man, Cruiser Fodder post in the unofficial Discord[discord.com].

m_category is a 32bit integer attribute where each bit is responsible for providing the part with a particular logic. The table is given below

The Libraries/parts.seria file is another of the two part-related files. It describes:

• Auxiliary fields such as part type and logic
  
• Sprites
  
• Meshes
  
• State variables (current and max HP, amount, fuel (in addition to fuel entries in OL.seria)...)
  
• Joints

These are being written in a ship/save file—technically, a config entry is being cloned with minor changes addressing the part usage. This implies that anything you tweak in the parts.seria will not transfer into already existing ship files and saves. Only parts freshly picked and installed in the shipworks will have new stats.

However, there is a way to update already existing ship .seria's to new values—see the Modding tools section.

The structure of the file is multi-level:

Along with attr=value pairs the part entry also contains additional level of nested nodes. The child node types are m_mesh (single), m_sprites (multiple) and m_slots (optional, multiple).

Potentially interesting attributes:


A mesh structure is fixed:
N.B.: the X/Y axes are directed right/down respectively. If you want to visualise a mesh in-game, simply select a part and its white contour will be its mesh.

Mass. The game doesn't expose any particular mass stat. Instead, it computes the mass dynamically by the following formula:

Mass = Mesh Volume x m_density
Mesh Volume = min(Mesh Width, Mesh Height) x Mesh Area

where mesh area can be computed with the Gauss formula for polygon.

So, if we change a side of a square mesh (keeping it square) the mass will grow cubic; if we extend the longer side of a rectangle mesh, then the mass will grow linearly.

The sprite subnode doesn't have any children: The sprite attributes are not well documented yet. Here are the known ones:


Slots are module attachments. They may be either side attachments or internal attachments (like ones provided by hull).

Ship files contain:

• Module entries very similar to ones in the parts.seria
  
• Joint entries which define connections between parts
  
• Special Creature entry with ship global stats

Example:

• m_children=15 are part nodes
  
• m_joints=8589934595 are joint nodes

The list of the parts on the first nested level is not complete—these are guns, legs, gimbaled engines and dummy nodes without mass and density. The rest of the modules are the children of the m_children=31 node:

The first m_children=15 child node there is unique—that's the bridge:

And finally—the m_children=47 node, which keeps the ship global stats:

This node contains the ship global stats, which indicate how far/fast/long it can fly/see/be seen. It's important to know that there's no sense to change them if you want to alter ship's speed, range or sensor strength; these are used mostly for spawn computations or GUI visualisations. What's really important there is the m_flagship flag which you may set to "true" is you want the ship to be recognised as a flagship:

If you want to mess with ship stats, it's better to change ship module stats and then force the game to recompute the global stats. Module entries are very similar to the ones in parts.seria, with some differences:

• Guns, sensors, jammers, missiles—everything with an arc—gets the m_sectors repeating attribute, 360 entries per part. It's one/zero for guns/missiles, ELINT power value for ELINT (zero, full or half if obstructed) and radar range in km for radars (zero/full/half).
  
• m_position.*, m_scale.* and m_angle attributes now make sense and define the module location. m_scale is being used to flip symmetric parts like legs/engines.
  
• Other minor changes in tech attributes, like parent ids.

Read the Ship Replacements and Updating section about updating the ship stats after you changed module values.

This section is relatively brief since the save editing is not well documented; however, there already are some tools to alter your campaign experience significantly. Note that editing an ongoing campaign is tied to large risks and may render your save broken beyond repair, so always make backups.


It's possible to change the amount of starting cash bonus by tweaking the m_scores root attribute:
You can also unlock ships by flipping a binary flag near a ship name:
Note that many ships cannot be unlocked through playing, and some of them come straight from early builds.

This timer in days is responsible for triggering the darkness event. Increase it if you want to postpone.


It is possible to change or spawn new strike groups (as well as other enemy squadron) via save editing. If a ship structure wasn't changed since the spawn (no parts damaged, no missiles fired, etc.), it is being stored in a save file in a compacted form, with includes only the bridge instead of a complete part description tree. This makes it easy to remove, replace or place a new ship into an existing enemy fleet.

At the moment when a ship structure changes, it's being stored verbosely with a full description and its name changes to a generic one, making it harder to tell different enemy groups. This is an aspect one should consider if they want to write a script which will tweak enemy compositions.


See the Modding Tools section for the tools which automate the process. The manual algorithm is:

1. Clone an existing SG entry (the m_escadras=327 node containing SG-specific ship subnodes);
   
2. Edit its coordinates and the callsign;
   
3. Change the m_intels=515 nodes to correspond to other fleet stats. The first one with the callsign and the current coordinates is the first to edit;
   
4. Edit fleet composition if you want to. Note that some ship fields get added or modified when the ship entry from its .seria gets cloned into the save, so refer to the modding tool code for this.

These attributes are stored inside the Creature node of the player ship.

Cities also can be modified by save editing. The roads are not stored in the save, and seem to be randomly generated between non-hidden cities within a certain distance. The city node is two-level, with the m_locations=199 root node storing the main city info, the m_items=2199023255555 child nodes denoting the ammo stored in the city, and the single m_world_trade=7 child node containing several m_children=15 children nodes for parts (generic hull, generic armor, engines, guns, ...) sold in the city. Note that the m_world_trade nodes generate only after you visit a city!

Root node selected attributes:

m_items attributes:

City inventories are tricky to edit by several reasons, the main one being that they lazily generate only after you visit it. Another one is that instead of a plain list of items, the city inventory structure follows basically a ship convention of cloned parts.seria entries. Note that the parts requiring "resources" to be built (hull, fuel tanks, armor) are stored as a generic part (ITEM_HULL. ITEM_ARMOR, ITEM_FUEL) instead of particular hull pieces:
Also note the m_count attribute, which denotes the amount of the parts in the city inventory.

The save file contains multiple m_npcs entries, most of which seem to correspond to some unused/unshown/technical characters. However, some of them belong to tarkhans you can recruit, and here's their stat table:

Localization files editing is not only interesting for translation and adding ship description reasons, but also because this allows to tweak dialogue trees in story or random events.

The files are located at the Data/Dialogs folder. Refer to this guide for more details:
Dialogue (and now Character) Modification

There are two entries you need to edit if you want to add a ship description:
The SHIP_NAME_* entry is mainly needed for Russian version where it allows to add a cyrillic ship name. The * should be replaced with the ship m_name root node attribute value.

SHIP_DESC_* stores the ship description visible at the campaign start. Note that a ship name substituted for * is uppercase. Also note that the tag and the value are being separated by tabulations and have no newlines.

If you want to add a module entry there, you will need an entry for a name, type and description (MDL_*, MDL_*_SDESC, MDL_*_DESC where * is the module m_oid).

Dialogue files also store some rewards or penalties you get from events. While some outcomes are hardcoded (like new ships, forced stays, no repairs/refueling in a city, ...), cash/rep/morale may be tweaked there.
A dialogue "direction" in terms of sprites/fade effects can also be tweaked there.

Before moving on making new parts it's worth to mention what we are not able to do:

• We cannot add new parts into an existing campaign. There is no mod yet which will spawn new parts in cities; however, parts requiring resources to build can appear in campaign, while the rest can be added via save editing.

Also note that this section got partially outdated after the release of the ShipworksExtended mod by Logdot; in particular, the mod automates the bullets 3 and 4 and simply loads new parts.seria entries into the shipworks without replacing any of the existing parts, so you only need to focus on creating proper OL.seria and parts.seria nodes. Refer to the ModLoader section to find more details on that, while I list the old approach there for educational reasons.

The process is very similar to the one described in this guide, with minor differences:
Making Wheels Available in Ship Editor

The algorithm is following:

1. Choose a vanilla module which is closest to something you're going to make.
   
2. Duplicate its entry in OL.seria, tweak its m_oid and stats.
   
3. Go to Libraries/constructor.seria (make a backup) and remove the
   
   m_children=15 { ... m_oid=ITEM_EMERGENCY ... }
   node to free some space.
   
4. Go to parts.seria, pick a vanilla module entry and paste it into constructor.seria instead of a deleted node.
   
5. Set m_oid, m_master_id (IMPORTANT, the value is the constructor.seria root node m_id value, otherwise your game will freeze).
   
6. Tweak the stuff you want—HP, density, mass, ...
   
7. Do not forget about module mesh, sprites, slots.
   
8. Start the game and go to shipworks.

Now the last module category will be replaced with the module you just created. Note that you don't need an entry in parts.seria—once you install a part on a ship, it will be written in a ship file and will only refer to OL.seria.


The game got some unsused sprites, but there isn't much. OTOH, you can still create new visuals if you are creative with the sprites you already have. For example, the M-22 180mm cannon was created based on a Mk-1-180 sprite with a new barrel made of Sprint+flare and a muzzle brake made of a hull block.

Do not forget to create corresponding entries in dialogue files, otherwise the name and description will be empty.

Another potential mod you may want to develop is vanilla ship replacements. Vanilla ships are treated in a separate way and are kept in Objects/Designs folder. They cannot be deleted in the game neither overwritten in the shipworks.

If you're going to replace a vanilla ship with your own, the pipeline is following:

1. Open both vanilla and custom ships in text editor
   
2. Change the custom ship m_name (root node attr) to the vanilla ship value
   
3. Change the name in m_card_caption (global stats section) to the vanilla name
   
4. Change the m_ship_name stat (global stats section) to the vanilla name
   
5. (Optional) change the m_combatvalue stat, which affects how many instances of the ship will spawn in-combat and within enemy squadrons. If your replacement combat value is too high, it may not spawn at all due to the cap on the total combat value for garrisons or other enemy groups.
   
6. (Optional) change the m_card_snapshot path (global stats section) to the vanilla snapshot path (which you will also need to replace)

You may want to update all the ships (including vanilla) after you tweak parts.seri or ship modules. There are 79 vanilla ships, so pick a vacation and start from Archa...

JK, lol, there are some mechanisms implemented which are intended to help you with that:

• The game may update some stats by itself
  
• DIY scripts may be written to update ship files

If you launch a new version of the game first time, it will update everything in the Ships folder and will place the old copies in Ships_backup. What it does recompute:

• Weapon firing arcs
  
• Sensor arcs (it may fail there, manual tweaking can be needed)
  
• All global stats
  
• Density/mass
  
• Elevation

To force the game to do that, open Config.ini and change CORE_LAST_LOADED_VERSION=1.15 value to some older one, like 1.14 or 1.1.

However, it won't pull all the data from parts.seria by itself. If you modified the parts.seria and want a ship to get new values, before performing the step above you need to alter part entries in a ship file first. This is very tedious to do manually, so I released some Python scripts to do that, see the Modding Tools section.

In conclusion, the ship update pipeline is the following:

1. Pick a ship file
   
2. Alter by yourself/update with a script module entries there
   
3. Put it into Ships folder (make a folder backup, just in case)
   
4. Change the game version in Config.ini to some older one
   
5. Run the game

While most of changes can be technically done by hands, propagating part configuration updates or save editing is extremely tedious. While there is no dedicated mod software yet, there are some scripts and packed GUI programs to automate some portion of work.

The GUI app for modding is the ModTool v0.1:

Supports map browsing, spawning and editing enemy groups, and automated ship updates with new parts.seria stats. Note that enemy spawn function is somewhat buggy, so always backup your saves. Available on Nexus:

Nexus[www.nexusmods.com]

The raw Python scripts are published on GH:
Github[github.com]
Usage example:
Github[gist.github.com]

No docs provided, but the example is self-explanatory.

Again note, that some functionality can be missing, as well as be unstable or break something. Use at your own risk.

This section was intended to be the part of the previous Modding Tools one, but I decided to expand it since it deserves a particular attention.

The ModLoader by Logdot allows to perform code injections into the game to add additional functionality, which cannot be delivered otherwise:

ModLoader Github[github.com]

The usage is simple—you install the ModLoader, install the supported mods, configurate them to your taste and launch the game through the ModLoader. There are currently two mods which are supported by the loader: ShipworksExtended and ammo-extended.


This mod allows to load custom parts.seria entries into the shipworks without replacing existing ones. The usage is straightforward and well-described on the mod Github page[github.com], so I won't cover it there. Note that unlike the orthodox way of adding new parts described in the corresponding section, this requires keeping your new entry in the parts.seria file. Also note that the mod affects only the shipworks and will not spawn new parts in cities; however, parts requiring "resources" for construction may appear as buildable in campaign too.


This mod[github.com] allows to manipulate with shell parameters, including damage, speed, armor piercing capabilities and many others, as well as converting shells between different types.

The shell parameters can be configured by tweaking the ammo-extended.json config. Unlike the previous mod, this one is somewhat worse documented, so I will cover it there in more detail.

N.B.: This section is incomplete and will be updated in the future.

Levels are barely moddable for now, but some things still can be tweaked. Level files are stored in the Data/Levels folder.

An example level file:

Note the LVL_SCRIPT attribute—it defines a script attached to the level. Scripts seem to be responsible for all the level logic, including terrain generation if needed. However, some levels also contain child nodes with parts, like the City or Dungeon—probably to describe some predefined terrain.

Note that there don't seem to be separated script files in the game directory.


Combat levels contain the LVL_HIGH.x, LVL_HIGH.y, LVL_LOW.x, LVL_LOW.y attributes which define the level size. If you want to extend/shrink combat arena, you can change them. The supposed combat levels are:

There is no known way to add new levels into the game (since transitions seem to be done with scripts, which we cannot modify yet), but we can plug level files instead of existing ones, like the shipworks or the test level—simply rename the level file to Editor.seria, for example. The list of known hidden levels (currently incomplete, filling is in progress):



EditorExtended

• Expanding and branching existing events
  
• Triggering specific ones

How to edit and add some new.

• Existing files enumeration with some hints on content
  
• .res file structure
  
• Experiment on adding a new texture file for a new part
  
• Implementation of swappable/side-specific camos

Allows to do things which are otherwise undoable.

• Change weapon stats
  
• Change player stats
  
• Change enemy stats
  
• Further fiddling with variables