Let's discuss the technical background first, so we get an idea how things work in the background when we mod the game.

The game tracks so called "asset folders" which are home to all assets used by the game. An asset is therefore basically a file inside an assets folder. These assets can be textures, models, sounds or lua-scripts. When starting the game, it scans it's current directory for asset folders. You can see examples for these if you inspect the "assets.aexassets" file or the "customFlagPresets" folder in the game install directory. The assets file is packed to speed up the loading process, so we will look at the "customFlagIcons" folder instead.

An assets folder requires a "assets.json" file at its root. This file tells the game that this folder is meant to be an assets folder and contains a few information like the priority. The priority is relevant if a file is present in more than one asset folder. In this case, the game will load the asset from the asset folder with the higher priority.
Yes, you can utilize this feature to effectively replace assets. But be aware that doing so can cause weird behavior which is hard to debug. Because of this we are NOT officially supporting this feature. You can play around with it or even replace whole menus, but we won't offer support if this causes bugs.

Back to the asset folders. Every asset has a "unique" asset ID. It's constructed using the relative path of the file inside the assets folder followed by the filename. So if the file "fi_research.png" is located in the assets folder "customFlagIcons" in the sub-directory "textures/flagIcons", its asset ID is "textures/flagIcons/fi_research.png". The "unique" is in quotes because there can be assets with the exact same asset ID in different asset folders. But this shouldn't concern you, as long as you are not trying to replace existing assets and choose meaningful names for your new assets.

Why we are telling you about asset folders? That's because mods are technically also realized as asset folders!

We are registering mods via a lua script. This script can contains different functions. The function "registerMod" is always required and has to return the title, a description and a priority. If this function fails the mod won't be registered.

The mandatory mod script must be located in its mod directory in the path "scripts/mods/". It will be saved there automatically when you create a new mod via the Editor (explained in the next section). Besides the mod script all other assets introduced by the mod must be located in its assets folder too. Our suggested good practice is having separate folders like "textures", "models", "scripts", "sounds", etc.

To assist you in debugging issues while creating your mods, we made it possible to show the terminal of the game. You can do so by passing "-console" as a start parameter to the game. It will show when launching the game. Closing the terminal will instantly terminate the game!

The editor is available besides the base game Planet S. You can either choose it when launching the game via Steam or, if you selected the base game as the default start option, by choosing Planet S-Tools manually.
Obviously the editor requires a internet connection to be able to create and update mods.


On startup the editor will show you a "Welcome!" popup, showing you three options. Their names reveal their purpose. To create a new mod we want to click "Create a new mod".



Then a new window pops up, requiring you to enter a name for your mod, a short description text and a priority.
The mod name will be used as the name of mod ingame, as well as for the title in the Steam Workshop. If you want to change it later, you have to edit it in the mod script for the ingame name and in Steam for the Workshop item title.
The description will only be used ingame. The priority will be used as the priority of the mods assets folder. You can leave it on its default value of 0. You can edit both values in the generated files later.



After filling out the text fields and clicking "Create new mod", the mod will be created. The generated files will be located in the game install directory, in the mods folder. There will be a sub-folder with the same name which you entered for your mod. In there you will find the "assets.json" and the mod script, as described in chapter 1 "Mod files". The mod script will also have the name of the mod and is a ".lua" file. If you open it, you will see a pre-generated "registerMod" function. For editing lua files we use "Visual Studio Code" which is available for free (https://code.visualstudio.com/).

Important to know is that you can inspect which mod the editor is currently "attached" to. Clicking on the "Modding" tab at the top will reveal the current state. If a mod is set, you will see its title and the unique workshop item ID. After creating a mod (or opening one) it should like this:



If you clicked "Just edit assets" or something went wrong while communicating with the Steam backend, the "Modding" tab will look like this:




To edit an existing mod you first have to make sure you have the mod files. As you are the creator of the mod, you should usually have them on your PC. If you lose them, you have to subscribe your mod in the Steam Workshop and copy the files to the location where they once were created in the game install directory.

If you have the files, you start the editor and click "Open an existing mod" in the welcome popup. There you are required to select the mod script of the mod you want to edit. In the combo box "Steam workshop item" you select the correct workshop item. It contains all Planet S workshop items of which you are the owner. You can identify them by their name or their unquie workshop item ID. You can compare it with the number in the URL of the Steam page of the respective workshop item.



If everything works out, you will be able to see the mod details in the "Modding" tab again!


To define a thumbnail in the workshop, you have to place a PNG-file into the mod folder named "thumbnail". It will be uploaded automatically when updating the mod.




Everytime you change your mod you have to upload it to Steam. The editor does that for you by uploading all files inside your mod's directory. You can update your mod by clicking "Update mod..." in the "Modding" tab mentioned before. Doing so will open another popup:



In there you can edit the mod title displayed in the Steam workshop and enter a change note. This is also the place where you can set the tags of your mod. They are orientated to the categories we configured for the Planet S workshop. Ideally they tell which content types are added by your mod.

A click on "Update mod" starts the upload to the Steam backend. This can take a few seconds, depending on your internet connection speed. You will see a success notification in the bottom right corner of the editor when the upload finished. Don't close the editor prior to that to prevent issues!


Besides creating and updating workshop items, the editors main purpose is creating and editing Planet S assets. While textures, models and sounds have to be created somewhere else, the editor is a tool to create Planet S assets. These are:

• Ambient objects (planet decoration)
  
• Resources (resource deposits like clay or iron)
  
• Buildings
  
• Spaceships
  
• Particle types
  
• Texture packs

You can have multiple different assets open at once. To create an asset, click on "File...", then on "New...". The "New asset" popup appears:



In there you select a name and a type. The asset location will be determined automatically. A click on "Create" creates an empty asset file and opens your new asset so you can start editing it.
You can also edit an existing asset. For that you click on "Open..." instead and select the asset file.
NOTE: To be able to select any type of file, select "All files" in the combo box in the bottom right of the file dialog.

To avoid updating your mod to the Steam workshop each time you change something, you can simply let the base game load your mod as a local one.

For that you have to copy your mod into the "mods" folder in the game install directory. To find the game install directory you right-click Planet S in your Steam library --> "Manage" --> "Local files". In there you will find the folders "editor" and "mods".

In "editor" there is also a mods folder, containing the mod you created from Planet S Tools. You just copy the mod folder (e.g. named "Cryptoworld" or <yourModNameHere>) into the mods folder besides the "editor" folder. The base games scans it on startup and will find and load your mod.

Make sure to re-copy your mod if you change something. Planet S Tools uploads your mod files from the "editor/mods" folder.

REMINDER: Add the start option "-console" to the game via Steam to open up the game console. It can help you find problems more easily!

In the newly created mod script you will see a bunch of pre-generated functions. If the mod is active, the game will invoke these functions at certain points to get the content registered by the mod. Normally you don't want to touch the "registerMod" function and leave it as it was generated. You can remove the other functions if you don't need them, as they are optional. Whether they are present won't affect the mod tags in the Steam workshop.

The game registers content in a certain order. This is:

1. World types
   
2. Items
   
3. Tile cultivation modes
   
4. Population types
   
5. Resources
   
6. Ambient objects
   
7. Planet types
   
8. Rockets
   
9. Turrets
   
10. Buildings
    
11. Building menu entries
    
12. Spaceships
    
13. Technologies

The register functions don't have to be in this order. Having it in order just helps understand a few dependencies between the content types. Imagine you are trying to register a new resource type and mention it in your custom planet type too. Now something goes wrong and your resource type can't be registered properly and is discarded. When the game now registers your planet type, it can't find your resource type and discards it from the planet type too. The planet will be registered without your resource.

We introduce to you: the ContentRegistry! It's purpose is to register and manage all types of game content. For each type there is a function requiring certain parameters.

In the following we describe all register functions and their parameters. We recommend you download our example mod "Cryptoworld" from the Steam workshop. In the mod script you see examples for all functions. It serves as a helpful reference.

To start things off easy and understandable, we will start with item types instead of world types. Let's look at an example for registering items:

ContentRegistry.registerItem("i_coins", "i_coins.png", 100, ITEM_CATEGORY_CONSUMABLES, 1, 5, false, "Coins")

The function header therefore looks like this:

ContentRegistry.registerItem(<String>, <String>, <Number>, <Enum>, <Number>, <Number>, <Boolean>, <String>)

ContentRegistry.registerWorldType(<String>, <Table>)


The second parameter, the Lua-table, is hard to describe. It's best you look at the example. Anyway we want to describe the possible parameters and their effects here:


NOTE: The parameter names inside lua tables are case-sensitive!

ContentRegistry.registerPopulationType(<String>, <Table>)


Table parameters:

ContentRegistry.registerCultivationMode(<String>, <Table>)


Table parameters:

ContentRegistry.registerAmbientObjects(<String>, <String>)

ContentRegistry.registerResource(<String>, <Table>)


Table parameters:

ContentRegistry.registerPlanetType(<String>, <Table>)


Table parameters:

ContentRegistry.registerRocket(<String>, <Table>)


Table parameters:

ContentRegistry.registerTurrets(<String>, <Table>)


Turrets can have the type TURRET_TYPE_PROJECTILE or TURRET_TYPE_LASER. Because their parameters are fundamentally different, we present them in separate tables.

type = TURRET_TYPE_PROJECTILE:

type = TURRET_TYPE_LASER:

ContentRegistry.registerBuilding(<String>, <Table>)


Table parameters:

There are many types of building modules. Some can combined with eachother, others can't. Generally speaking, you can't / shouldn't combine building modules which produce UI.


Each module type requires different parameters. The following tables describes them:

Module ID "inventory":

Module ID "logistic":

The module type "pwr_consuming" doesn't have any parameters.

Module ID "pwr_producing":

Module ID "farming":

Module ID "extracting":

Module ID "mining":

Module ID "assembling":

The module type "constructing" doesn't have any parameters.

Module ID "residential":

Module ID "military":

Module ID "shieldProjector":

Module ID "laser":

Module ID "rocketSilo":

Module ID "terraforming":

There are actually two functions to know here. You can either create a new civilization tab or add a building menu entry to an existing one. An example for a civilization tab is the "Science" tab in the building menu. It has the sub-tabs "Developers", "Researchers" and "Visionaries". To create a new tab use this function:

ContentRegistry.registerBuildingMenuCivilizationTab(<String>, <Table>)


Table parameters:


Next we want to add building menu entries to a civilization sub-tab. This can be done using this function:

ContentRegistry.registerBuildingMenuEntry(<String>, <String>, <Table>)


Table parameters:

ContentRegistry.registerSpaceship(<String>, <Table>)


Table parameters:

ContentRegistry.registerTechnology(<String>, <Enum>, <Table>)


Table parameters:


NOTE: To be able to research a technology, its unlock condition has to be fullfilled AND one of the requried technologies has to be researched, if defined.

There are three different effects types available:


Depending on the choosen effect type, different values need to be given in the effect-table:

To override or extend existing content objects you simply call the "register<X>" function again (e.g. "registerPlanetType"). Every element contained in your call will replace the previous elements, such as "modules" in buildings.
There are only a few exceptions:

• Planet rings in world types can only be added, not replaced
  
• Generated resources and ambient objects can only be added (threfore overriding the amount of the generated resources can be done indirectly by passing the new min / max values)
  
• "overrideItem" can be used to override specific elements instead of passing all parameters again
  
• The tiers in a civilization tab can only be added, not replaced

We hope this guide helped you understand how the modding for Planet S works. As mentioned before, looking at the files of the example mod "Cryptoworld" will help you a lot, as this guide is help pretty theoretical and abstract.

If you have any suggestions what may be missing in this guide, feel free to tell us in the comments.

We also want to point at our Discord server (https://discord.com/invite/JhA5M5EvXS) where you can discuss the modding with us and other players.