Tutorial - How to make a mod from scratch
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.
Step 2: Modifying a ship
Example 1: Modular tables, the Myrmidon and the Harpoon
|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"
|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.|
|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).
|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:
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
|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.
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.
|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.
|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.
|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.
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).
|Go in File > Open, browse to your mod data/missions folder, and open the mission file you extracted earlier.|
|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.
|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.
|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.
|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.|