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. There is only one exception to this, which is the use of the SQL command file *data.sql* to make changes to the game's Data Database whenever the game starts*.*

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 activate your testmod by starting the game and picking to activate it from the game's main menu. Notably, this puts the mod's ID into the mod\_config.txt file in your game's install directory.

> Star Traders Frontiers/modversion/mod\_config.txt
>
>

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

### Modding Test Content and

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 the Mod Configuration menu
3. You've put some modded content into your folder and confirmed the game will load it.

## Uploading Your Mod

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

It is recommended that you type all of your text into another window while buliding your mod entry. The Uploader may clear all of your entered text if you click on other windows.

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 from the drop down ("Ship", "Profession", etc)
4. **Set your mod to Private** at first so that you can test it before publishing it to public.
5. Place a square PNG (recommended size 256x256) 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.
* All icon previews should be PNG files.

### Updating 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.

## Recovering your mod in the Star Traders Frontiers Uploader

The STF Mod Uploader only allows upload to Steam, it doesn't allow you to download a mod or sync with Steam. If you lose your STF Mod Uploader install and files (and don't have a source code storage solution), you may need to rebuild your files.

1. Reinstall the Star Trades Frontiers Mod Uploader
2. Download your mod from Steam.
3. Create a subdirectory in <steam library>/Star Traders Frontiers Mod Uploader/WorkshopContent with the *contentfolder* string from your manifest.json file.
4. Copy your mod files into this subdirectory.
5. Move your icon file to the /WorkshopContent directory and rename it to the *previewfile* string from your manifest.json file.
6. Move your manifest.json tile to the /WorkshopContent directory and rename it to "<mod name>.workshop.json".

## 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 will continue to receive updates. Our intention is to keep these updates non-breaking, meaning that you do not need to update 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 any SQL changes as carefully as possible.

## 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 game's installation folder. Then each activated mod may apply changes to this database through its *data.sql* file. If present, the *data.sql* file is read and the SQL commands contained within are executed against the data database. The order of priority determines which mod's SQL commands are executed first (lowest priority) and last (highest priority).

The data.sql file has some formatting requirements and recommendations:

* The build of SQLITE3 in Star Traders: Frontiers lacks the math functions features (CEIL, FLOOR, etc) so you will need to be creative.
* Comments starting with -- are very helpful to keep your SQL file organized
* Use high values for your \_id fields of any new items you INSERT to avoid conflicting with the base game or other modders.

While oddly named, the *data.mp3* file is an unencrypted SQLite database. You can examine it with any SQLite editor. SQLiteSTudio is a great free and open-source tool for this kind of work. All of your SQL changes in your mod's *data.sql* will be run against this data.base

* 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.
* If you attempt to open data.mp3 with a SQLite tool but find it is not a database, be sure to check that you are using the file in the modversion/ folder and not in the base install.
* If you want to test out changes to the database file, consider copying data.mp3 to data.db and playing around in that sandbox, which will have no effect on the game.

For example, the following 3 lines of SQL in *data.sql* create empty, 0 mass components for Small, Medium and Large slots. This is the data.sql file of the Empty Ship Component mod on the Workshop.

```
insert into ShipComponent (\_id, componentSize, componentType, componentName, componentDesc, componentPng, componentLevel, shipWeaponId, skPilot, skShipOps, skGunnery, skElectronics, skNavigation, skExplorer, holdsCargo, holdsCrew, holdsOfficer, jumpCost, armorBonus, fuelBonus, holdsGuest, holdsPrisoner, holdsCraft, medicalRating, shipEffectId, deflectionBonus, mass, shipEngineId, driveMass, installCost, installValue, installTime, subType, signature, sortPriority, factionId, gameState, minEcon, minMil, minStar, unlockId) values (1001, 1, 27, "Empty Slot", "", "ship\_comp\_boosters.png", 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 36, 0, 0, 0, 0, 0, 0, 0, 0);
insert into ShipComponent (\_id, componentSize, componentType, componentName, componentDesc, componentPng, componentLevel, shipWeaponId, skPilot, skShipOps, skGunnery, skElectronics, skNavigation, skExplorer, holdsCargo, holdsCrew, holdsOfficer, jumpCost, armorBonus, fuelBonus, holdsGuest, holdsPrisoner, holdsCraft, medicalRating, shipEffectId, deflectionBonus, mass, shipEngineId, driveMass, installCost, installValue, installTime, subType, signature, sortPriority, factionId, gameState, minEcon, minMil, minStar, unlockId) values (1002, 2, 27, "Empty Slot", "", "ship\_comp\_boosters.png", 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 36, 0, 0, 0, 0, 0, 0, 0, 0);
insert into ShipComponent (\_id, componentSize, componentType, componentName, componentDesc, componentPng, componentLevel, shipWeaponId, skPilot, skShipOps, skGunnery, skElectronics, skNavigation, skExplorer, holdsCargo, holdsCrew, holdsOfficer, jumpCost, armorBonus, fuelBonus, holdsGuest, holdsPrisoner, holdsCraft, medicalRating, shipEffectId, deflectionBonus, mass, shipEngineId, driveMass, installCost, installValue, installTime, subType, signature, sortPriority, factionId, gameState, minEcon, minMil, minStar, unlockId) values (1003, 3, 27, "Empty Slot", "", "ship\_comp\_boosters.png", 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 36, 0, 0, 0, 0, 0, 0, 0, 0);

```

## 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

### Sprite Sheets Specifications

Star Traders Frontiers uses **sprite sheets** to store some graphical assets. A sprite sheet is a collection of smaller images (sprites) combined into a single file (sprite sheet). Using a single sprite sheet instead of individual sprites improves game performance (allows for draw call batching, lower memory usage, etc. ). A sprite sheet consists of a **single PNG** and an **atlas file.** The atlas file contains the location and characteristics of the individual sprites in the sprite sheet. If your mod replaces a sprite sheet, you must include also both the updated sprite sheet and the atlas file (even if you do not change the atlas file).

For example, if you replace the image of a ship in the top down ship view, you would need to:

* Provide a new sprite sheet containg your new ship: *sprites/ship\_carrier.png*
* Provide a new atlas file: *sprites/ship\_carrier.txt*

Star Traders Frontiers sprite sheets are located in:

* *charactersprites/ --* Character Animation Resources: Sprites used when showing animationed characters. The following files are used:
	+ images ("LibGDX" or "Spine" format depending on sprite sheet packer, png filetype and extension),
	+ atlases (text format, txt filetype and file extension), and
	+ animation script (optional, json format, json filetype and extension).
* *sprites/ --* Ship Animation Resources. The following files are used:
	+ images ("LibGDX" or "Spine" format depending on sprite sheet packer, png filetype and extension),
	+ atlases (text format, txt filetype and file extension),
	+ and animation script (optional, json format, json filetype and extension).
* *sheets/* -- Static Resources. A large number of resources, such as: buttons, icons, banners, etc. The following files are used:
	+ sprite sheets ("cocos2d" format, png filetype and extension)
	+ and sprite sheet atlases (plist format, txt filetype and file extension plist).

### Mod-Specific Sprite Sheets

In order to avoid competing over the same common sprite sheets when adding or replacing graphics, each mod can provide its own sprite sheet which is loaded into the game in priority order of mod\_config.txt. Therefore, you can overwrite images in a common sprite sheet provided by the game (such as in sheets/gear\_0.plist) by using your own mod-specific sprite sheet.

**Important Exception***,* this mod-specific sprite sheet can only overwrite images in the *sheets/* folder and is not a technique available to add or overwrite parts of the character or ship spines, as they require all images to be in a single sprite sheet. In addition, some icons (e.g., mapmarks) in the *mapbatch.png* sprite sheet are not able to be overwritten using mod-specific sprite sheets and require a full sprite sheet replacement instead.

Each mod can provide its own sprite sheet by creating a sprite sheet atlas (a .plist in the "cocos2d" format) and a large PNG packed as described in Packing Sprite Sheets below.

The two files (shown below) should be included in the root folder of your mod (not *sheets/*). Their name should match the folder name of your mod, which, in the case of using Steamworks will be a long ID number.

* <Mod ID>.plist
* <Mod ID>.png

### 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.

```
{
"MaleOutfits" : 21,
"FemaleOutfits" : 22,
"MaleHeads" : 49,
"FemaleHeads" : 51,
"Hats" : 14,
"Glasses" : 7,
"Armbands" : 5,
"Gloves" : 5
}

```

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:

* Asset-apecific Rules
	+ Head, hats or glasses
		- You must add the same number of hats or glasses to both masculine and feminine characters. You cannot have 5 feminine hats and 10 masculine hats.
		- You can have different numbers of heads between masculine and feminine.
		- Required Images
			* A single 400x410 PNG image is stored in *characters/* folder for each head, hat or glasses.
			* a sprite sheet in *charactersprites/* containing these assets.
	+ Gloves or armbands
		- you must add the same number to both masculine and feminine characters. You cannot have 5 feminine gloves and 10 masculine gloves.
		- Required Images
			* No images are needed for the *characters*/ folder. They are only needed for upper body assets.
			* a sprite sheet in *charactersprites/* containing these assets.
	+ Outfits
		- Any changes or additions must be both made to the *characters/* folder and *charactersprites/* sprite sheets
		- You can have different numbers of outfits between masculine and feminine.
		- Each outfit uses 7 individual sprites and 1 spritesheet
		- Required Images
			* 1 Upper body image
				+ A single 400x410 PNG image in *characters/* folder for each outfit
			* a sprite sheet in *charactersprites/* containing these 6 outfit piece PNGs.
				+ 6 Individual outfit pieces (replace XXX with the outfit number)
					- outfit\_XXX\_torso.png
					- outfit\_XXX\_arm\_right.png
					- outfit\_XXX\_forearm\_right.png
					- outfit\_XXX\_arm\_left.png
					- outfit\_XXX\_overchest.png
					- outfit\_XXX\_legs.png
			* Existing masculine outfits are numbered 1 to 21 while feminine outfits start at 101 and are numbered to 122.
			* The 6 individuals images are not required, but may be included to make revisions and updates easier.

* General Requirements
	+ 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.

### Packing Sprite Sheets

#### Sprite Resources

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. The folder contains all of the different sprite sheet source for each version of the game, named *TPS.zip*. The TPS.zip file contains the game images and TexturePacker Configuration files.

#### Sprite Sheet Tools

The Developers of STF use TexturePacker to develop spritesheets. TexturePacker is a paid solution for packing sprite sheets, but is not required. Other sprite packing tools such as: Free Texture Packer or SpriteSheet Packer will also work. The output of other tools usually requires some modifications to match the output of TexturePacker (for example, you may need to modify the generated plist file, see below Modifying PLIST). Regardless of your tool, generate the sprite sheet and its atlas using either the "LibGDX" or "Spine" format for text file or "cocos2d" format for plist file (these are popular formats supported by sprite sheet packer tools).

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).

```
 <dict>
 <key>format</key>
 <integer>2</integer>
 <key>pixelFormat</key>
 <string>RGBA8888</string>
 <key>premultiplyAlpha</key>
 <false/>
 <key>realTextureFileName</key>
 <string>gear_0.png</string>
 <key>size</key>
 <string>{4096,4096}</string>
 <key>smartupdate</key>
 <string>$TexturePacker:SmartUpdate:a7246423f553423a1dba1a40a1b4db37:5c33737ec3d8f9380906175434c4d155:b12db622244c64fd6058a885149932ab$</string>
 <key>textureFileName</key>
 <string>gear_0.png</string>
 </dict>

```

### 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