Adding Shipsets

From Star Ruler 2 Wiki
Jump to: navigation, search

Basics of a Shipset

Shipsets are located in data/shipsets. Each subdirectory in there is taken as a separate shipset.

Some of the important files that should be in a shipset and their meanings:


Has any extra material definitions that the game should load for this shipset. These materials are loaded even if the shipset isn't chosen.


Has any extra model definitions that the game should load for this shipset. These models are loaded even if the shipset isn't chosen.


Basic definition file for the shipset, contains its identifier, name and a list of every Hull in that the shipset should use. The hulls listed refered to by this file should be defined in the shipset's hulls.txt.


Contains a list of hull definitions that the shipset adds. Hulls have quite a few parameters, listed in the next section.

additional resources

Shipsets should contain any .png, .obj, other otherwise files that they need inside their shipset directory. Shipsets are allowed to refer to any files in the base game or its shipsets as well.

Hull Definitions


Defines a new hull. The identifier for the hull should be put as the value on this line, and this identifier should be used inside the shipset.txt file to add the hull to the shipset.


Name of the hull when listed in the interface.


Reference to the model definition that this hull should use.


The material that the model is rendered with, decides its textures and such.


Material that is rendered with the model when it is displayed behind a design in the GUI. Usually a 'blue' version of the normal material, but can be set to match the regular material as well if


This is a scale factor to the size of the model when it is displayed behind a design in the GUI. 1.0 generally means that the design will take up the whole blueprint area, while lower numbers like 0.9 or 0.7 make the model smaller relatively.


Hull tags are generally used to indicate which type of ship gets built with this hull. Should be set to one of "Support", "Flagship" or "Station".


A hull can also indicate one or more subsystems that should be added to all ships of that hull. Note that the subsystem will have 0 hexes, so regular subsystems that rely on Hexes will get a 0 size if added this way.

You should generally only use this to add the hull subsystem for the hull type here, so one of "FlagshipHull", "SupportHull" or "StationHull", depending on what you entered for 'Tags'. Only add different hull subsystems if you are doing something specific as a part of a larger mod that isn't just a shipset.


Minimum size a ship has to be to use this hull. This is mainly used to make sure that expensive high-polygon models aren't used for the thousands of tiny little gunships that a fleet can have.


Maximum size a ship can be to use this hull. Can be used to make sure that the cheap low-polygon models aren't used for very large ships that would look ugly with them. Make sure that there is always a hull available for any arbitrary size in each of the three hull types!


The designer tries to choose a hull that most closely matches the shape the player draws on their blueprint. In order to do this, it needs to know what ship shape the model corresponds to.

The Shape value you set points to a .png file that should show the hull shape that should be mathed to the player's design. Any pixel that is not normally part of the design should be fully transparent, any pixel that is part of the shape should just be set to white.

Shapemaps can be tricky to create, since they also need to account for the empty space on the grid that the design is not on. To help debug your shapemap, you can go into scripts/gui/tabs/, and set SHOW_HULL_WEIGHTS to the value true instead of false. If you start the game then, the design editor will show a number on top of every hex, indicating the "cost" of a hex for that shape - this is based on the shape map. Hexes inside the design should say 0, indicating no cost, whereas hexes further away from the actual hull should say progressively higher numbers. (Note that the base game's shape maps were made simply by making a screenshot of an empty design with that hull, cropping out the section that displays the hex grid and re-drawing the shape of the blue hull in the background as a white overlay. Silly, but effective.)

The game will automatically generate a matching ".map.png" file for each shape image when you first start the game with the shipset. This is a cached distance map used to speed up the internal algorithm. You can normally just ignore this.

When you change the .png file you refer to, make sure to delete any matching .map.png files that the game has created and cached in your shipset folder, or the changes won't be seen.

Old Variables

In the base game's shipset there are a number of old, deprecated values in the hulls file. These were used in the past but are no longer necessary, and should be removed from any shipsets you make as they have no effect.

These values are: GuiIcon, IconSheet, IconIndex, FleetIcon, GridSize, GridOffset and the big ASCII grid of #s, -s and Xs.

The base game's shipsets still contain these values for certain backwards compatibility reasons, but may at some point in the future lose them as well.

Other Concerns


The game expects all models to be inside a unit sphere in their .obj files. Models with coordinates exceeding that 1-unit sphere, or that are significantly smaller than it will appear the wrong size in the game compared to what their physical size as an object in the game world is.

When exporting the .obj file, make sure you export it with normals. Models without normals will not be shown by the game, so your ships will be invisible.

Default Designs

The game uses the hulls present in the shipset to choose which default designs to add into the empire. If no designs are present for a particular shipset, it loads the default volkur designs.

If you want to add special default designs, add designs to your mod in the data/designs/ folders. Inside default/, gate/, hyperdrive/, not_hyperdrive/ and slipstream/ you can find folders for each shipset, containing the .design files of the default designs to load. You'll want to put your own default designs for your shipset in the equivalent folders. (Designs exported from the game can normally be found in Documents/My Games/Star Ruler 2/base/designs).

When adding new default designs, make sure they actually refer to the hulls in your shipset by opening the .design file in a text editor and checking that the hull listed in the "hull": parameter is set to one of your hulls. You can change it and save the file if you want.

Please note that naming the designs anything different from the default names of Gunship, Heavy Carrier, etc will cause the empire to not spawn with any default starting fleets unless you also mod the government traits in data/traits/government/ to ALSO spawn a fleet with your new names - that is, make two separate SpawnShip() hooks. Whichever hook refers to designs the empire actually has, that hook will be ran.