View source for Tutorial - How to make a mod from scratch

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

{| class="wikitable sortable mw-collapsible mw-collapsed"
|- 
! style="background-color:brown" | Text
! style="background-color:brown" | Picture
|- 
| First you will need to create a Nebula account and log in with it on Knossos.
| [[Image:Tuto1.jpg|800px|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.
| [[Image:Tuto2.jpg|800px|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.
| [[Image:Tuto3.jpg|800px|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.'''
| [[Image:Tuto4.jpg|800px|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.
| [[Image:Tuto5.jpg|800px|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.
| [[Image:Tuto6.jpg|800px|Package folder]]
|}


===With wxLauncher===


TODO


=Step 2: Modifying a ship=

===Example 1: Modular tables, the Myrmidon and the Harpoon===

{| class="wikitable sortable mw-collapsible mw-collapsed"
|- 
! style="background-color:brown" | Text
! style="background-color:brown" | 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"
| [[Image:Tuto2-1.jpg|800px|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).
| <pre>
#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
</pre>
|- 
| 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.
| [[Image:Tuto2-2.jpg|800px|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).
| [[Image:Tuto2-3.jpg|800px|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==

{| class="wikitable sortable mw-collapsible mw-collapsed"
|- 
! style="background-color:brown" | Text
! style="background-color:brown" | 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. 
| [[Image:Seraphim MVP.jpg|400px|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.
| [[Image:Tuto2-2-1.jpg|800px|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.
| [[Image:Tuto2-2-3.jpg|800px|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.
| [[Image:Tuto2-2-4.jpg|800px|Tables folder]]
|- 
| I will save you the trouble of trying to locate the property we're looking for, the [[Ships.tbl#Ships.tbl_flags|"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 :
<pre>
$Name:	SB Seraphim
+nocreate
$Flags:	( "bomber" "player_ship" )
</pre>
| <pre>
#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
</pre>
|- 
| 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.
| [[Image:Tuto2-2-5.jpg|800px|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).
| [[Image:Tuto2-2-6.jpg|800px|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.
| [[Image:Tuto2-2-8.jpg|800px|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 [[5_easy_steps_towards_your_FREDucation|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.
| [[Image:Tuto2-2-9.jpg|800px|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.
| [[Image:Tuto2-2-10.jpg|500px|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.
| [[Image:Tuto2-2-11.jpg|800px|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.
| <pre>
$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" )
</pre>
|- 
| Congratulations, your Seraphim is now ready to... erm, fly? or well, slowly move places I guess.
| [[Image:Tuto2-2-12.jpg|800px|Seraphim Done]]
|}

[[Category:Modding]]