Tutorial - How to make a mod from scratch

From FreeSpace Wiki
Jump to: navigation, search

Introduction

This tutorial covers the creation of a simple FS mod step by step with no prior knowledge required. It assumes you have FS2 and the latest MediaVPs installed, but the concept is globally the same (with different filenames and paths) if you wish to edit another mod or a Total Conversion.


Step 1: creating your "sandbox" mod

For a lot of reasons, we do not want to modify retail or MVP files directly. Those reasons include not breaking compatibility, facilitating debugging and facilitating backward compatibility - the vast majority of mods assume both the retail and the MVP data to be intact in order to function.

With Freespace Open, you can isolate all the files you modify, and only the files you modify in their own mod folder, and add dependencies (usually the MediaVPs) that contain the rest of the files you need.


With Knossos

Text Picture
First you will need to create a Nebula account and log in with it on Knossos. Logging in on Knossos
In develop > Create, enter a name and a unique ID for your mod. Don't worry, this mod will not be published on Knossos until we decide to do so.

Leave the fields Type = Mod and Parent mod = Retail FS2 as they are by default.

Creating a mod on Knossos
Like Knossos helpfully tells you, you must create at least one package before we can get started, so click the + Package button.

We're not doing a very complex mod, so just call it Root.

Adding a package
You will now have a tab with the name of your package. In it, we want to do two things : 1) set the status as Required, and 2) add the MediaVPs as a dependency (caution: look for Freespace Upgrade MediaVPs in alphabetical order in the dropdown list).

Make sure to press Save at the bottom of the page after your changes.

Adding dependancies
Your package tab should look like this once properly saved.

You can now press Play to start the mod. It should look identical to starting the MediaVPs, as we've only added the dependency and not changed anything yet.

To start the actual modding, click on the Mod Path to reach the folder Knossos uses to store and load the modded files we will create.

Dependancies added
At this point, the mod folder only contains your package's folder and a few json files. Ignore the json files and create a folder named "data" inside the package (which we named root here). This is where we will start adding files in Step 2. Package folder


With wxLauncher

TODO


Step 2: Modifying a ship

Example 1: Modular tables, the Myrmidon and the Harpoon

Text Picture
We're going to start with something simple : create a modular ship table that replaces the Helios compatibility with the Harpoon for the GTF Myrmidon.

Whether you used Knossos or wxLauncher in Step 1, you should now have an explorer window opened on a folder named "data". Inside this folder, create a new folder named "tables".

In this folder, you will create a text file named "mymod-shp.tbm". Make sure you have file name extensions enabled in the explorer, as we really want it to be "mymod-shp.tbm" and not "mymod-shp.tbm.txt"

Tables folder
Open this file in a plain text editor like Windows' Notepad, or a third party program like Notepad++ or Sublime Text, then copy this text into it and save the file (I'll explain what this does later).
#Ship Classes

$Name:	GTF Myrmidon
+nocreate
+Tech Description:
XSTR("We changed the description here so we can quickly check that our mod works.", -1)
$end_multi_text
$Allowed SBanks:	( "Rockeye" "Hornet" "Tornado" "Tempest" "Trebuchet" "Stiletto II" "Hornet#Weak" "EMP Adv." "Infyrno" "Harpoon" )

#End
Back in Knossos or wxLauncher, start the game again. If you go in the tech room and select the GTF Myrmidon, you should see that the tech description has been changed. New description
Congratulations, you have successfully modded the game !

Now if you start a mission featuring both the Myrmidon and Harpoons, you will be able to equip the Harpoon and use it in-mission. For example, you can go in the Tech Room > mission Simulator and start SM1-06 The Great Hunt (if it isn't available because of campaign progress, press CTRL+SHIFT+S to unlock everything in the tech room, including missions).

You can equip Harpoons
So, how did we manage that? What did that file do?

Freespace follows a simple folder hierarchy when loading data. In our "data" folder, we created a "tables" folder, where FSO will look for table files (models are in the "models" folder, textures in the "maps" folder, missions in the "missions" folder, etc). You can find the detailed folder hierarchy in this page:

FS2 Data Structure

Back in retail (and early versions of FSO), you could only use full table files. What we created instead is a "modular table", mymod-shp.tbm (note the TBM extension instead of TBL). This allows us to only enter the data we want to change, and not the entirety of the ships data the game requires for every single ship.

The ships entry always starts with the "$Name:" entry. We follow it with "+nocreate" to tell the game that this is an existing ship we're modifying, and then the "+Tech Description:" and "$Allowed SBanks:" are the two entries we changed. You can find the details of the possible ships.tbl structure in Ships.tbl. Be careful, as the properties need to be in the order listed on this page.

Example 2: VP files, missions, and Making the Seraphim flyable

Text Picture
Now we are going to make a new ship playable. We don't want go too complicated, so we'll take a ship that's already in the game but is not player-flyable.

Instead of blindly telling you what to copy-paste in your table, let's have a look at the retail ships entry for the Seraphim.

In Example 1, we dropped a loose TBM file in a data/tables folder. Retail FS2 and most mods opt instead to pack the files in packages called VP (Volition Package). This is an uncompressed proprietary format that Volition also used for other games. If we want to look at the retail ships table, we will have to extract it from Root_fs2.vp first.

First, we need to locate your root FS2 folder.

The SB Seraphim
With Knossos

In the settings, find Library Path under the Knossos dropdown.

If you navigate there, you will find:

- a "bin" folder, that stores all the FS binaries (FSO and FRED executables)

- a "temp" folder Knossos uses for downloads and extractions, don't touch it

- one separate folder for each Total Conversion. You will find the FS2 folder there.

Tables folder
With wxLauncher

TODO

Now that we've located your FS2 retail VPs, we need a way to open them.

A simple tool for this is VPView32, which is actually the original tool developed by Volition. It can only read and extract files, and not create or modify VPs, which is enough for our purposes and comes with the additional safety that you can't accidentally screw up your retail VPs with it.

Install it, and open Root_fs2.vp with it.

You'll notice that the content of the VP files follows the same hierarchy as our mod's data folder, with a "tables" folder containing TBL files, as well as "missions" and "players" folders we don't need to concern ourselves about yet.

You can extract the ships.tbl file wherever you want with the "Extract to dir" button (also available as right-click). You will also be able to directly open files with a double-click once you've given a default program to .tbl files.

Tables folder
You'll notice ships.tbl contains the same kind of data that we put in out mymod-shp.tbm in Example 1. They are in the same order as they will appear in the Tech Room ingame.

The Seraphim is lower down in the file, line 7132. Now we need to find what to change to make it available to the player.

The totality of what you can see in this file, as well as all the SCP additions to the table format, are documented in the Ships.tbl page on the wiki, like all the other tables.

Tables folder
I will save you the trouble of trying to locate the property we're looking for, the "player_ship" flag.

So we want to add a SB Seraphim entry to our TBM (see Example 1), again with +nocreate because we're only modifying an existing ship, and with a modified "$Flags:" entry.

Be careful to keep the existing flags, in this case "bomber".

The result is as follows :

$Name:	SB Seraphim
+nocreate
$Flags:	( "bomber" "player_ship" )
#Ship Classes

$Name:	GTF Myrmidon
+nocreate
+Tech Description:
XSTR("We changed the description here so we can quickly check that our mod works.", -1)
$end_multi_text
$Allowed SBanks:	( "Rockeye" "Hornet" "Tornado" "Tempest" "Trebuchet" "Stiletto II" "Hornet#Weak" "EMP Adv." "Infyrno" "Harpoon" )

$Name:	SB Seraphim
+nocreate
$Flags:	( "bomber" "player_ship" )

#End
Of course at this point, we have made the Seraphim player-compatible, but you still can't play with it, because none of the existing missions have it in their available loadout.

So let's modify one!

First, create in your mod's data folder a "missions" folder, then extract into it a retail mission from Root_FS2.vp, for example SM1-01.fs2 (Surrender Belisarius).

Rename that mission file into something else like TEST.fs2. This is because SM1-01.fs2 is listed as part of a campaign, which will cause us problems later (unlocking ship classes, mostly).

The next step is to find and start FRED (FReespace EDitor), which we will use to open and edit the mission file.

Missions folder
With Knossos

Just go back in your Develop tab and click on the FRED2 button. If you can't see it, try restarting Knossos (happened to me earlier).

FRED in knossos
With wxLauncher

TODO

Go in File > Open, browse to your mod data/missions folder, and open the mission file you extracted earlier. Opening a mission
This is not a FREDing tutorial, so I will not give you a rundown of everything FRED can do (spoiler: it can do a lot. You can find a dedicated FRED tutorial here). What we want here is to add the Seraphim to the loadout so we can fly it, so let's go straight to the point.

Go in Editors > Team Loadout.

Team loadout
If you modified your TBM earlier, you should find the SB Seraphim at the bottom of the ship pool.

Check it. You can also change the number of ships available if you wish. Click OK and click File > Save.

Team loadout
You can now start your mod again, and you will find your modified mission in the Tech Room, under Mission Database > Single Missions

The Seraphim should now be available in the loadout! However, there's still a little snag.

Of course, non-player ships are not tabled to be compatible with player weapons. We can fix that.

Snag
We're going to copy the compatible loadout of another ship, like the Ursa, into our Seraphim.

If your open the retail ships.tbl again, you'll find the Ursa at line 1443.

We want the entries "$Allowed PBanks:" and "$Allowed SBanks:". Add them to our TBM file.

Remember that the entries need to be in the correct order as listed in the Ships.tbl page.

$Name:	SB Seraphim
+nocreate
$Allowed PBanks:        ( "Subach HL-7" "Akheton SDG" "Morning Star" "Prometheus S" "Prometheus R" "Lamprey" "Circe" "Maxim")
$Allowed SBanks:        ( "Rockeye"  "Tempest" "Harpoon" "Hornet" "Tornado" "Trebuchet" "Piranha" "Stiletto II" "Cyclops" "Cyclops#short" "Helios" "EMP Adv." "Infyrno" )
$Flags:	( "bomber" "player_ship" )
Congratulations, your Seraphim is now ready to... erm, fly? or well, slowly move places I guess. Seraphim Done