Creating Mods

Mod creation can take many forms. You might update the game's graphics, replace existing content, rebalance combat or add all new content, ships, weapons, stories or jobs to the game.

How Mods Work
Before you try to create a mod, it is important to understand how they work. You create a mod by creating a folder that partially mirrors the game and then adding your modified files into that folder structure.

When a mod is loaded, any files that are in its folder structure are used instead of the game's default files. Therefore, in the most basic example, you could replace a single PNG file by creating a mod that has a PNG with the same name as can be found under the modversion/ folder of the game.

As shown in this example, the moddable version of the game has an image modversion/tiles/ui_mainmenu_logo.png which is the Star Traders: Frontiers title graphic. To create mod that would replace that image, you'd need to create a folder structure that has your own tiles/ui_mainmenu_logo.png. In the example, the STF logo is replaced by a mod with the Cyber Knights: Flashpoint title.



Regardless of what mod you are trying to create, the mechanism is always the same -- any files with the same name in the same folder path replace the game's default files. The most powerful example of this is to replace the game's Data Database, named data.mp3.

Your mods may also include new content that is not included in the base game, for example if you have added more ship or weapon artwork to the game.

Creating Your First Mod
To test out your very first mod, you can do all the work on the file system and without the Mod Uploader Tool or the Steam Workshop.

Find the Steam Workshop Folder
First to help locate the Steam Workshop installation on your machine, Subscribe to a public mod such as the Empty Ship Component example mod. Then restart your Steam client or Verify Game Files for Star Traders: Frontiers. Either action will kick off a download of the new mod content. (Alternatively just create the subdirectory 335620 in your workshop\content directory).

Find the mod content in your Steam installation. It's Steam ID is "2486984011" for which you could search. Otherwise, on a typical Windows machine, it will likely in the steamapps folder, in a workshop folder, in the game's folder (Star Traders: Frontiers game App ID is 335620), such as this: "example for Windows: C:\Program Files (x86)\Steam\steamapps\workshop\content\335620\2486984011"

Create Your Test Folder
In the same directory as the 2486984011 folder, create a new folder called testmod.

"example for Windows: C:\ProgramFiles (x86)\Steam\steamapps\workshop\content\335620\testmod"

Create Your Test Config
Now configure the game to use testmod by creating a new text file. Go to your main Star Traders Frontiers Folder and create a new empty file called mod_config.txt.

"Star Traders Frontiers/modversion/mod_config.txt"

"example for Windows: C:\Program Files (x86)\Steam\steamapps\common\Star Traders Frontiers\modversion\mod_config.txt"

Put the name of your new mod folder (testmod) into this text file and nothing else.

Mod Some Content and Test
We will mod the game's main menu title image.

Return to your mod folder and create a subfolder of testmod called tiles. "testmod\tiles" "example for Windows: C:\Program Files (x86)\Steam\steamapps\workshop\content\335620\testmod\tiles" Copy the Star Traders Frontiers\modversion\tiles\ui_mainmenu_logo.png into this folder. Then modify the file in some way. You could use your OS preview tool to rotate it 180 degrees or open it in paint and scrawl away.

From the Steam client, run the game and choose to play the moddable version of the game. You should see your modified main menu graphic.

Summary


 * 1) You've created a mod folder to put your overwrite content into.
 * 2) You've configured the game to load that mod through mod_config.txt
 * 3) You've put some modded content into your folder and confirmed the game will load it.

Mod Upload Tool
When you have finished your mod or are ready to update an existing mod that you own, you will need to use the Mod Uploader Tool to push that content to the Steam Workshop.

To download the Mod Upload Tool, search your Steam client library Tools section for Star Traders: Frontiers Mod Uploader and install this tool.

Once installed, when you are ready to upload your mod to the Workshop or update your mod, launch the tool from the Steam client.

Create a New Mod Entry
To create a new mod entry, enter its name in the bottom left corner. This name will be used for a filename on your system so do not use special characters. Then click "Create Item".



Creating an Item will publish the name to Steam Workshop as a new private Workshop Item under your account. The newly created mod ID is stored into the configuration JSON file of the same name (use a good name, yah!). Creating a "Empty Slot Mod" will create the following JSON config file and empty folder:


 * Star Traders Frontiers Mod Uploader/WorkshopContent/Empty Slot Mod.workshop.json
 * Star Traders Frontiers Mod Uploader/WorkshopContent/Empty Slot Mod/

By clicking on the mod item in the top left, you can fill in the mod's metadata to publish it to Steam:


 * 1) Add a mod title that clearly describes your mod
 * 2) Fully describe the mod and all the notable changes it makes to the game.
 * 3) Include mod tags separated by commas, using tags that describe your additions ("job, combat")
 * 4) Set your mod to Private at first so that you can test it before publishing it to public.
 * 5) Place a square image into the WorkshopContent/ subfolder (not the mod's named subfolder) and enter the name of the image into the Preview image filename.  Then click on another field and you should immediately see the image appear in the white square to the left of the filename box.
 * 6) Finally, place all of your mod files into the subfolder created by the tool. If you want the mod to overwrite files in the game's top level directly, the file should be a top level child of the subfolder.
 * 7) When complete, press Submit
 * 8) Visit the the Workshop for Star Traders: Frontiers to confirm your mod successfully uploaded.
 * 9) Test your mod by subscribing, configuring and Playing your Mod.  For a new mod, you may need to select "Files you've posted" under "Your files" at the right.



Troubleshooting Uploader

 * If a mod fails to upload, always try to Verify Game Files for the Mod Uploader in the Steam Client to ensure you have the latest version.
 * If you gets stuck "Preparing Content" then you may have an empty mod subfolder (in the example above, WorkshopContent/Empty Ship Components/ cannot be empty!)
 * If you get stuck "Validating mod pack" then you probably have failed to set the required preview image. The image must be in the WorkshopContent/ folder right next to the JSON file. The tool's form must show the image in the box.

Update your Mod
Updating your mod is easy. Open the Mod Uploader tool and select it from the list of mods on the left hand side. Update any metadata you wish to change. Be sure to include a clear change log with each new update to your mod. Ensure that all of the mod files are in the subfolder for the mod (such as Star Traders Frontiers Mod Uploader/WorkshopContent/Empty Slot Mod/) and then re-Submit the mod.

A good rule of thumb is to always set your mod to "Private" when you first upload it. Then test it yourself as described in Playing Mods before updating your mod to set it to public.

Be sure to test any changes to your mod before uploading them to the Workshop because subscribed players will get the changes immediately.

Testing and Development
Once you have uploaded your own mod, you can make change to the files inside Steam's workshop/ folder directly to speed up your mod testing. The game needs to be restarted after each change in order to reload your mod.

Be sure to backup your mod files or commit them to a source code control system after each set of changes.

From Steam Workshop
You can use the Workshop site to uploaded more images, screenshots and metadata for your mod beyond what the upload tool supports.

You can enable Comments on your mod on the Workshop site as well. If you do so, it is recommended to interact with players who have questions.

Add some form of contact to your mod's Workshop page so that any players who have an issue can reach out to you.

Game Updates and Mods
If you create a mod, we want to ensure that updates to the base game do not conflict with or break your mod. Therefore, the moddable version of the game is a completely separate installation of the game. If the Trese Brothers release a update for the regular version of the game it has no impact on your mod or the modded version of the game. You do not need to make any changes to your mod for players to be able to continue to play your mod.

The moddable version of the game may occasionally receive updates. During the private mod creators beta, it is likely to receive updates. Our intention is to keep these updates non-breaking, meaning that you do not need to update your mod. If there are specific changes required when an update comes out, we will preview them to the community and include instructions on how to integrate them into your mod.

If you are interested in keeping your mod up to date with the baseline game, you should reference the public Dropbox shared folder that includes the different versions of the game's internal, moddable resources. It will have a sub folder for each new release to the main version of the game. In order to make your changes as easy as possible to apply to new versions of the game's data database, be sure to write your changes as a series of SQL commands which can then be reapplied. However, you have no need or responsibility to upgrade your game to the latest revision.

Modding the Data Database
Whenever the modded version of the game starts, the Data Database (which contains all read-only data about the game) is read from the data.mp3 file. This may be read from either the default game files  or  from a single modded database. To override the default Data Database, your mod will need to be the highest priority mod in the mod_config.txt file.

While oddly named, the data.mp3 file is an unencrypted SQLite database. You can modify it with any SQLite editor. SQLiteSTudio is a great free and open-source tool for this kind of work. For your changes to appear you must commit (save) the changes to data.mp3 and place it in your mod directory (many SQLite editor auto-commit).
 * The schema documentation for the SQLite database can be found here Data Database Modding.
 * The Data Database for different production versions of the game can be downloaded here if you intend to update your data database to newer versions of the game.

It is recommended that you write and keep your SQL commands you have used to edit the game's database. You should also use high values for your _id fields of any new items you are adding so that they do not conflict with any future additions if you decide to update your mod's data database to a newer version. In the event of an update to the modded version of the Data Database, you will be in the best position to easily re-run the SQL to achieve your changes. Additionally, the Frontier Mod Manager (see below) will allow you to non-destructively apply your SQL commands making development of your mod (and other mods) much easier.

Frontiers Mod Manager
The FMM Mod Manager is a powerful tool to allow players to pick and choose which mods to install into their data database. In order to make your mod compatible with the FMM, you must include a SQL file in your mod that includes all of the database commands to enact your mod.

For example, the following 3 lines of SQL create empty, 0 mass components for Small, Medium and Large slots. These SQL commands are bundled as "EmptyShipComponent.sql" and included in the Empty Ship Component mod on the Workshop. If a player only wanted to gain these 3 extra components, they could use the data.mp3 file provided by the mod or they could use FMM to apply these 3 changes along with potentially other mods as well.

Modding the Graphics
Graphical mods can add or overwrite the game's graphics. Example types of graphical mods you could created would include:
 * Adding 5 new hats or 5 new outfits for crew combat characters
 * Overwrite some of the character faces or outfits in the game
 * Overwrite environmental art like the landing zones or starscapes
 * Overwrite ship or craft art

Graphic Config JSON
If your mod is changing the numbers of outfits, heads, hats, gloves, armbands or eyewear for characters you must include the graphicConfig.json file which is at the root of the modversion/ folder.

The default game comes with a number of these assets already. You can increase or reduce these counts based on your graphical changes. There are a number of rules you must follow:


 * Any changes or additions must be both made to the characters/ folder and charactersprites/ sprite sheets
 * A single 400x410 PNG image is stored in characters/ folder for each outfit, head, hat or glasses. As these are upper body shots, there are no resources for armbands or gloves in this folder.
 * In the sprite sheet in charactersprites/ each outfit is comprised of 7 PNGs -- such as outfit_124_torso.png, outfit_124_arm_right.png, outfit_124_forearm_right.png, outfit_124_arm_left.png, outfit_124_overchest.png, outfit_124_legs.png. If you increase the outfit count in graphicConfig.json you must include all 7 images for each new outfit. Masculine outfits are numbered 1 to 21 while feminine outfits start at 101 and are numbered to 122. Adding a new masculine outfit would require 7 PNG files such as outfit_22_*.png and adding a new feminine outfit would require 7 PNG files such as outfit_123_*.png
 * All filenames need to match the numerical patterns of the existing character assets.
 * You cannot skip any numbers. If you have 25 feminine outfits then there must be feminine outfits 1 to 25 without any gaps. The same goes for all types.
 * If you add hats, glasses, armbands or gloves you must add the same number to both masculine and feminine characters. You cannot have 5 feminine hats and 10 masculine hats.
 * You can (as shown in the default config) have different numbers of heads and outfits between masculine and feminine.

Packing Sprite Sheets
Many graphical assets in the game are packed into sprite sheets. Sprite sheet is one larger image that is composed by packing several smaller images (sprites) together. Loading the single larger image improves the game performance, allows for draw call batching and reduces the memory usage. A sprite sheet consists of a single large PNG and an atlas file (either a text file or plist) that includes the name and rectangle coordinates of all images that have been packed into the sheet. If you overwrite a sprite sheet in your mod (such as sprites/ship_carrier.png), you must include both the updated sprite sheet image as well as it's paired text file (in this case, sprites/ship_carrier.txt) even if no changes were made to the text file.

The game's sprite sheets are exclusively kept in two folders in the game's resources:


 * charactersprites/ -- these are used by character's when displayed in their full animated stance. As these are read and displayed by Spine animator they require their atlas to be text file and use sprite sheet data format "LibGDX" or "Spine" depending no the sprite sheet packer
 * sheets/ -- these are used by the game to in all sorts of places to to load and display static images. They require their atlas to be plilst file and use sprite sheet data format "cocos2d"
 * sprites/ -- these are used by the ship's when displaying them in animated context. As these are read and displayed by Spine animator they require their atlas to be text file and use sprite sheet data format "LibGDX" or "Spine" depending no the sprite sheet packer

The source files for all of the game's sprite sheets for different versions of the production game can be downloaded here from a public DropBox folder that contains all of the different sprite sheet source for each version of the game, named TPS.zip. Each sprite sheet used by the game has a matched TexturePacker configuration file (*.tps) that pairs with its folder of raw sprites. TexturePacker is a paid solution for packing sprite sheets but is not required. You could also configure and use another packer like the free and completely online Free Texture Packer site (but requires a modification to any generated plist file to work, see below Modifying PLIST) or SpriteSheet Packer which is a free, open source alternative. Whatever sprite sheet packer you chose, you will generate the sprite sheet and its atlas using either the "LibGDX" or "Spine" format for text file or "cocos2d" format for plist file, both of which are widely supported by sprite sheet packers.

The configuration settings must be exact, including:


 * Do not allow trimming
 * Do not allow rotation
 * Require Power of Two
 * Max size 4096x4096
 * For "LibGDX" or "Spine" be sure (if available) to use the option "Remove file extensions"

Here are two example configurations using the online Free Texture Packer to pack gear sprite sheet and crew male characters for Spine.

Modifying PLIST
If using a "cocos2d" plist, double check the end of the file to ensure that the filenames used both for realTextureFilename and textureFileName both have the full filename (gear_0.png not just gear_0).

Example Sprite Sheet Sets
For example, to look at the character outfits for masculine characters, the following files are used:


 * The source PNGs for the sprite sheet are kept at TPS.zip/spines/Spine Male
 * The TexturePacker configuration file for the sprite sheet is kept at TPS.zip/spines/spine_male.tps
 * When the sprite sheet is packed it uses the "LibGDX" data format and it creates 2 files (st2_char_male_1.png and the text file st2_char_male_1.txt) which should be placed into your mod at charactersprites/

Modding SFX or Music
To mod the SFX or music of the game, overwrite the game's sound resources in your mod. In order for your mod to function on multiple platforms, you must provide assets in different formats for each platform.


 * To replace Windows sound resources, provide WAV files in sfx_win32/
 * To replace Mac OS sound resources, provide CAF files in sfx_ios/
 * To replace Linux sound resources, provide OGG files in sfx_android/

Ship Weapons play an SFX based on their type. To mod the SFX played by any given weapon, set the data.ShipWeapon.sound field. This will override the default sound listed below. To override the explosion sound made if the attack hits an enemy ship or craft, set data.ShipWeapon.sound2.


 * Railguns SFX 6
 * Lance SFX 71
 * Gravity Driver SFX 48
 * Plasma Cannon SFX 70
 * Missiles SFX 9
 * Autocannon SFX 9
 * Torps SFX 40

Crew combat weapons play an SFX based on their type. To mod the SFX played by any given weapon, set the data.Weapon.sound field. This will override the default sound listed below. The field data.Weapon.sound2 is ignored for crew weapons.


 * Blade SFX 39
 * Rifle SFX 44
 * Pistol SFX 45
 * Plasma Pistol SFX 45
 * Grenade SFX 42
 * Snubber SFX 46
 * Sniper SFX 43

The following SFX numbers are reserved and used by the system for UI and interactions.


 * Button Click = SFX_1
 * Error = SFX_24
 * Combat Start Hit = SFX_4
 * Zone Landed = SFX_5
 * Orbit Entered = SFX_3
 * Starport Upgrade = SFX_14
 * Starport Repair = SFX_13
 * Starport Refuel = SFX_10
 * Earned Ach = SFX_15
 * Promote Officer = SFX_16
 * Recruit Crew = SFX_17
 * Level Up = SFX_18
 * Train Up = SFX_19
 * UI Highlight = SFX_20
 * Load Game = SFX_8
 * Pay Credits = SFX_11
 * Rx Credits = SFX_12
 * Picking CardExplorer = SFX_27
 * Pin Details View = SFX_34
 * Unpin Details View = SFX_34
 * Map Test Failed = SFX_35
 * Crew Combat Turn Start = SFX_2
 * Ship Combat Move Phase = SFX_26
 * Play Gate Jump = SFX_37
 * Ship CombatInserted = SFX_38
 * Play Music Game Over = MUSIC_5
 * Map Engine Start = SFX_73
 * Map Engine Stop = SFX_74
 * Stash Put = SFX_77
 * Star Click = SFX_78
 * Gain Trait = SFX_80
 * Gain Trait Negative = SFX_94
 * Rank Up = SFX_79
 * Ship Combat Engine Hit = SFX_38

Modding Other Binary Files
Any other file in the game's resources folders may be overwritten by simply placing a new file with the same name in same folder in your mod. This includes files such as:


 * Space backgrounds backgrounds (found in /tiles)
 * Environment and landing backgrounds (found in planets/)

Modders' Tools
Here is a helpful list of tools you might use while modding Star Traders: Frontiers:


 * SQLiteSTudio when modifying the game database SQL
 * When packing sprite sheets, TexturePacker from Code & Web is a paid solution for packing sprite sheets and SpriteSheet Packer is a free, open source alternative
 * Esoteric Software's Spine 2D Animator if changing the character animations
 * Tiled for editing maps