Difference between revisions of "Ships and General Mod Creation"

From FreeSpace Wiki
Jump to: navigation, search
m (Added link to Modular Tables in tbm vs tbl)
m (Getting Started:: Cleaning up this awkward construction.)
 
(17 intermediate revisions by 4 users not shown)
Line 5: Line 5:
 
===Your New Best Friends===
 
===Your New Best Friends===
  
By arriving at and closely reading this page you have taken your first steps to making the most important friend every freespace modder has, the modding portal of the freespace wiki.  Within the Wiki's pages is a gold mine of information created by the SCP team and community members who have spent a huge amount of time and effort making sure things work and that how they work is well enough documented which is also why there are a few short, sharp "go read the wiki" comments on the forums.
+
By closely reading this page, you have taken your first steps of making the most important friend every FreeSpace modder has - the Modding Portal of the FreeSpace Wiki.  Within the Wiki's pages is a gold mine of information created by the SCP team and community members who have spent a huge amount of time and effort making sure things work, and how they work is well documented.
  
  
Your next best friends are in your FreeSpace 2\data folder and they are fs2_open.log and fred2_open.log . These two files are the logs generated by the debug builds of FreeSpace 2 and the FRED 2 mission/campaign editor.  The way to tell between a regular/retail and debug build is that after the build cycle number in the file name there is a d for debug or r for regular, eg 3.6.12d.  any information after this point in the file name is information that tells the support guys exactly which file version you are using.  Whenever you are running a debug build of FreeSpace or FRED the program creates a constant record of the programs activity and lists any error messages where possible that occur and stores that record in the listed log files, also debug builds try to catch every error they can while r builds try to ignore them so are an invaluable tool for error checking.  To open the logs simply double click on them and if prompted select any text editor, though a word processor might render the log easier to read.
+
Your next best friends are in your FreeSpace2\data folder, and they are fs2_open.log and fred2_open.log. These two files are the logs generated by the debug builds of FreeSpace 2 and the FRED2 editor.  The way to tell between a release and debug build is that after the build cycle number in the file name there is a d for debug or r for regular, eg 3.6.12d.  any information after this point in the file name is information that tells the support guys exactly which version you are using.  Whenever you are running a debug build of FreeSpace or FRED, the program creates a constant record of the program's activity and lists any error messages where possible that occur and stores that record in the listed log files. Debug builds try to catch every error they can while release builds try to ignore them, making debug build an invaluable tool for error-checking.  To open the logs, simply double click on them and, if prompted, select any text editor.
  
 +
===Required:===
  
===Required:===
+
The following are required to create mods for FreeSpace Open:
  
A working and legitimate copy of Freespace 2, FreeSpace Open executables (preferably the latest Stable build or nightly) and a bit of imagination.  An internet connection you can readily access helps.
+
*A working and legitimate copy of FreeSpace 2
 +
*FreeSpace Open executable (preferably the latest stable build or, if you know what you are doing, a Nightly build)
 +
*Imagination
  
 
==Getting Started:==
 
==Getting Started:==
  
The first thing to know when modifying FreeSpace 2 is to understand how the mod structure works.  Each mod needs it's own folder within the FreeSpace 2 folder, for example Wings of Dawn on my computer is C:\Games\Freespace 2\Wings of Dawn . All files that directly relate to the WoD mod are found within this folder on my PC, though a file within the folder tells FreeSpace to go and look for the Media VPs mod, yes Media VPs are a mod, but the Mod structure allows for mods to be chained together in a simple fashion but that will be covered later. Within the mod folders is another folder called data, The data folder is not present in mods relying on .[[VP]] files, which are container files which mimic the mod structure and are used to make distributing and installing mods easier, again I will talk more about .VP files later. Within data are the sub folders which the files that make the mod are stored, the sub folders are there to keep everyone sane and make everything easy to find, the majority are self explanatory but a detailed breakdown can be found in [[FS2_Data_Structure]] but below I have summarized the information important to this tutorial.
+
The first thing to know when modifying FreeSpace 2 is to understand how the mod structure works.  Each mod needs its own folder within the FreeSpace 2 folder. For example, Wings of Dawn on my computer is C:\Games\Freespace2\Wings of Dawn. All files that directly relate to the WoD mod are found within this folder on my PC, though a file (mod.ini) within the folder tells FreeSpace to go and look for the mediavps mod. The mod structure allows for mods to be chained together in a simple fashion. Within the mod folders is another folder called data. The data folder is not present in mods relying on .[[VP]] files, which are container files that mimic the mod structure and are used to make distributing and installing mods easier. Within the data folder are the subfolders which the files that make the mod are stored. The subfolders are there to keep everyone sane and make everything easier to find. The majority are self-explanatory but a detailed breakdown can be found in [[FS2_Data_Structure]]. Below is a summary of important information relating to this tutorial.
 
 
''Cache'' - To reduce loading times, the engine will generate a cache file for each model it encounters. Since cache generation can take quite long for more complex models, you should always include cache files for unique mods.
 
 
 
''Cbanims'' - is where command and mission briefing animations are stored
 
 
 
''Effects'' - weapon and other 2d effects
 
 
 
''fonts'' - font files are kept here, unless you are aiming at a total conversion you will in all likelyhood not need this folder
 
 
 
''force feedback'' - unused in any mod that i know
 
 
 
''freddocs'' - the documents that are opened when you hit help in fred so just ignore again unless you are using a custom branch of Freespace engine
 
 
 
''hud'' - custom hud graphics
 
 
 
''intelanims'' - animations used in the techroom for weapons and intel sections
 
 
 
''interface'' - images and animations used in the menu system, note not everything you would expect to be a still is stored as a still so research carefully before changing anything.  Again only larger mods and total conversions generally go into this stuff as it is very heavy going to do properly
 
 
 
''maps'' - Texture files for ships and other model based objects
 
 
 
''missions'' - where FRED2 should be storing mission files and the only place where FS2 will look for missions both single player and campaign
 
 
 
''models'' - .pof files go here no matter what purpose
 
 
 
''multidata'' - This is where the game stores player icons and other stuff downloaded during multiplayer sessions
 
 
 
''music'' - in game music files go here
 
 
 
''players'' - the files behind the Pilot screen on startup are stored here, not modding related except in very limited circumstances and is best just ignored unless the support guys tell you to go in there
 
 
 
''sounds'' - sound effects like weapons fire in here
 
 
 
''tables'' - last of the important ones, but the most important one, this is where the tbl and tbm files go that tells the game how to use the majority of the information in the folders listed and also controls a number of other game aspects.
 
  
''Voice'' - Voice overs for mission chatter
+
*''Cache'' - To reduce loading times, the engine will generate a cache file for each model it encounters. Since cache generation can take quite long for more complex models, you should always include cache files for unique mods.
 +
{{Table374|
 +
:Cache files are no longer used or generated by the executable; since making a new mod should always be done on the latest stable release, you shouldn't have to worry about cache files anymore.}}
 +
*''Cbanims'' - This is where command and mission briefing animations are stored.
 +
*''Effects'' - Weapon and other 2D effects, stars, planets, nebulae, e.t.c.
 +
*''Fonts'' - Font files are kept here. Unless you are aiming at a total conversion, you will in all likelihood not need this folder.
 +
*''Hud'' - This is where custom HUD graphics go.
 +
*''Intelanims'' - Animations used in the Techroom for weapons and intel sections are located here.
 +
*''Interface'' - Images and animations used in the menu system go here. Not everything that you would expect to be a still is stored as a still, so research carefully before changing anything.  Only larger mods and total conversions generally go into this because it is hard to do properly.
 +
*''Maps'' - Texture files for ships and other model-based objects.
 +
*''Missions'' - This is where FRED should be storing mission files and the only place where FS2 will look for missions and campaigns, both single- and multi-player.
 +
*''Models'' - .pof files go here no matter what purpose.
 +
*''Music'' - In-game music files go here.
 +
*''Sounds'' - Sound effects like weapons fire belong here.
 +
*''Tables'' - This is where the .tbl and .tbm files go that tells the game how to use the majority of the information in the folders listed and also controls a number of other game aspects.
 +
*''Voice'' - Voice overs for mission chatter.
  
 
==Simple Modifications==
 
==Simple Modifications==
  
One of the simplest things to do is add a new weapon or ship created by the community and the two are often related as with new ships community members might decide they want to create a new weapon for it.
+
One of the simplest things to do is add a new weapons or ships created by the community. The two are often related as ships created by members might have their own custom weapons.
 
 
===Adding a ship===
 
 
 
First go to [[SC Lamia]] in [[User-made Ships]] and download it. 
 
Next create a folder in FreeSpace 2 called New Ship and a data folder inside of that.
 
Then open up sc_lamia.rar if you cant there are a few small programs such as winrar that work with this format.  Inside the file are 3 folders called maps, models and tables.  The folders listed are identical in name to the folder names used in modifying freespace so copy them into your New Ship\data folder as they are.  <b>Congratulations</b> you have just created your first mod.  if you look in the maps folder there will be 3 .dds image files which make up the ships texture, in the models folder will contain SCLamia.pof and in tables there are two tbm files, one for the ship and one for a custom weapon for that ship.  there is one more thing i want you to do though, open sclamia-shp.tbm in a text editor and find the line starting $flags: .  the full line reads ''$Flags:                ( "cruiser" )''  now add "in tech database" with the speech marks to the line between the brackets so it reads ''$Flags:                ( "cruiser" "in tech database" )'' , save and close the file.  Finally open your FreeSpace launcher and select New Ship as the mod and run the game, if you get an error message go back to the file and double check the flags line to the example I provided.  When you reach the main screen go to the techroom and at the bottom should be the Shivan cruiser you just added, the ship wont appear in any missions at this time because a mission file needs creating using the ship. FreeSpace is that easy to mod, just drop the assets in the correct folders, making sure any related tables are altered to use it and off you go.
 
 
 
===The mod.ini===
 
 
 
At first glance this is a strange little file that just sits there and defies the convention that everything goes somewhere in the data folder of a mod.  Instead this file goes in the main folder for the mod, eg Freespace 2\New Ship for the above example and is a very useful file which adds the final polish to a mod and performs useful tasks like linking into other mods.  Like many of the files in Freespace 2 this is basically a renamed txt file and can be opened my any text editor.  Let’s take a look at one.
 
 
 
‘# PLEASE NOTE ALL INI SETTINGS ARE *OPTIONAL*
 
 
 
 
 
‘# modname:      Display name only, so you can have spaces instead of underscores for multi word MOD's
 
 
 
‘# image255x112:  Location of a 255x112 bmp you wish to display in the launcher
 
 
 
‘# infotext:      Text that will appear in the launcher
 
  
‘# website:      Link to your website
+
===Adding A Ship===
  
‘# forum:         Link to your forum
+
The following will be an example of how to add a ship in FreeSpace:
  
 +
*Go to [[SC Lamia]] in [[User-made Ships]] and download it. 
 +
*Create a folder in FreeSpace2 directory called New Ship.
 +
*Within the New Ship directory,  create a folder called data.
 +
*Extract sc_lamia.rar. If you are unable to, you can download a file archiver such as 7-zip to extract the files.
 +
*Inside the file are three folders called maps, models, and tables. Copy them into your New Ship\data folder without altering them. 
 +
*Create a mod.ini by opening a text editor. The following are required for the mod.ini to work:
 +
**[launcher]
 +
**modname      = New Ship;
 +
**[multimod]
 +
**primarylist  = ;
 +
**secondarylist = mediavps_3612 ;
 +
***This is optional. By having the mediavps_3612 listed in your secondarylist, you will use the SC Lamia as well as the Mediavps instead of the Lamia with retail FS2 assets.
  
'[launcher]
 
  
'modname      = Mod Name
+
<b>Congratulations!</b> You have just created your first mod.  If you look in the maps folder there will be three .dds image files which make up the ship's texture. The models folder will contain SCLamia.pof, and in tables there are two .tbm files - one for the ship and one for a custom weapon for that ship.
  
'image255x112 = mod-logo.bmp;
+
There is one more thing I want you to do, though. Open sclamia-shp.tbm in a text editor and find the line starting $flags:. The full line reads ''$Flags: ( "cruiser" )''.  Add "in tech database" with the quotation marks to the line between the parentheses so it reads ''$Flags: ( "cruiser" "in tech database" )''. Save and close the file. This allows the Lamia to be viewed in the Techroom from the beginning. Open your FreeSpace launcher and select New Ship as the mod and run the game. If you get an error message, go back to the file and double-check the flags line to the example I provided.  When you reach the main screen go to the Techroom and at the bottom should be the Shivan cruiser you just added, the ship will not appear in any missions at this time because a mission file needs creating using the ship.
  
'infotext    = Here is a short blurb for the mod
+
===Mod.ini===
  
‘#website      = here is where a web address goes if your mod has one
+
Unlike other files, the mod.ini does not go in the data folder of a mod. Instead, this file goes in the main directory for the mod (e.g. Freespace2\New Ship for the above example) and adds the final polish to a mod. It performs useful tasks like linking other mods. Like many of the files in Freespace 2, this is basically a renamed .txt file and can be opened by any text editor. Let’s take a look at one.
  
‘#forum        = http://www.hard-light.net/forums
 
  
 +
# PLEASE NOTE ALL INI SETTINGS ARE *OPTIONAL*
 +
# modname:      Display name only, so you can have spaces instead of underscores for multi word MOD's
 +
# image255x112:  Location of a 255x112 bmp you wish to display in the launcher
 +
# infotext:      Text that will appear in the launcher
 +
# website:      Link to your website
 +
# forum:        Link to your forum
 +
[launcher]
 +
modname      = Mod Name
 +
image255x112 = mod-logo.bmp;
 +
infotext    = Here is a short blurb for the mod
 +
# website      = Here is where a web address goes if your mod has one
 +
# forum        = http://www.hard-light.net/forums
 +
 +
[multimod]
 +
primarylist  = ;
 +
secondarylist = mediavps_3612;
  
[multimod]
 
  
primarylist  = ;
+
This is the contents of the mod.ini for a sample mod.
  
secondarylist = MediaVPs_3612;
+
Anything following a # is a comment and is ignored by the launcher.
  
 +
The first section is information for the FreeSpace launcher and contains the following:
  
This is the contents of the mod.ini for a long term project I am working on with a few amendments.
 
  
Anything following a # is a comment and is ignored by any launcher reading it.
+
* modname: the name of the mod
 
+
* image255x112: the name of a 255x112 pixel .bmp to use as a mod image
The first section is information for the FreeSpace launcher and contains:
+
* infotext: the area where you can put info about the mod and/or a tag line
 
+
* website: the link to your website that will be linked to the Website button in the launcher
* modname, the mod’s name,
+
* forum: the link to your forum that will be linked to the Forum button in the launcher
 
 
* image255x112, the name of a 255x112 pixel bmp to use as a mod image
 
 
 
* infotext,  is where you can put a little bit of info about the mod and/or a tag line
 
 
 
* website,  activates the website button in the mod selection tab of your launcher and links it to your mod’s website if you have one
 
 
 
* forum, as above but for a forum.
 
  
  
 
In the example shown both website and forum are commented out but if you remove the # and save they will be read by the launcher.
 
In the example shown both website and forum are commented out but if you remove the # and save they will be read by the launcher.
  
The next bit links the mod into other ones, the example above will call the 3.6.12 version of the media vps to enhance the visuals of anything in Freespace 2 that is not touched by your mod, for example if you turn the Ravana green, because MediaVPs_3612 is in the secondary line it will not override this but it might do if you place it in primary.  Most of the time you will only use secondary list and this is the one you are recommended to use unless you know exactly what you are doing.
+
The next bit links the mod into other ones, the example above will call the 3.6.12 version of the mediavps to enhance the visuals of anything in FreeSpace 2 that is not touched by your mod. For example, if you turn the Ravana green, the Ravan will not be red because the mediaVPs_3612 is in the secondary line. However, it will become red if you have the mediavps_3612 in your primarylist.  Most of the time, you will only use secondary list. This is the one you are recommended to use unless you know exactly what you are doing.
  
***note
+
===Changing Other Mods===
If you copy and paste the above example you will need to remove the ‘ from in front of each line it occurs.
 
  
===Changing Other Mods===
+
You have downloaded some mod. You played it, and you have beaten it. However, you want to change something. Perhaps you feel the anti-fighter turrets are too weak or that there is a different ship you want to use. <b> Do NOT add, remove, or change anything in the actual folder!</b> This is because you will change the mod as long as the altered files are in there. What you should do is create a mod as explained in 'Adding A Ship' and place a mod.ini referencing the folder name for whatever mod you wish to alter in the secondary mod line. Then place the edit-that-you-want-to-make (e.g. model, .tbm, etc.) into this new mod. Once you have done all of that, select the new mod folder in the Freespace launcher’s mod tab and run.  Because of the reference to the original in the mod.ini, that and any mods referenced by that mod will be loaded, but the changes you made will override the original. This way, you get to play your twist on the mod whenever you want without having to alter the original mod to play it.
  
You have downloaded Blue Planet or some other mod, you played it and you have beaten it but you want to change something, perhaps you feel the anti-fighter turrets are too weak or that there is a different ship you want to use.  <b> Do Not Add, Remove Or Change Anything In The Actual Folder</b> this is because you will change the mod as long as the altered files are in there, what you should do is create a mod as explained in Adding a ship and place a mod.ini referencing the folder name for Blue Planet or which ever mod you wish to alter in the secondary mod line.  Then place the ship/tbm/whatever into this new mod.  Once you have done all of that select the new mod folder in the Freespace launcher’s mod tab and run.  Because of the reference to blue planet in the mod.ini that and mods referenced by Blue Planet will be loaded but the changes you made will override the original.  This way you get to play your twist on the mod whenever you want but you don’t have to delve into the mod folders to play it as originally intended you just play the mod like you did before.
+
==.VP==
  
==On VP files==
+
Because of the ease in damaging data key to a mod or indeed retail, <b>IT IS STRONGLY ADVISED THAT .VP FILES ARE NOT EDITED IN ANY WAY!</b>
  
Because of the ease in damaging data key to a mod or indeed retail <b>IT IS STRONGLY ADVISED THAT .VP FILES ARE NOT EDITED IN ANY WAY!</b>
+
The advantage of a .vp file is ease of distribution. A .vp file is a container used to maintain the file structure. All that is required is that they are all placed in the mod folder. The problem with changing them is that if you edit one and get it wrong, you may have to reinstall the mod because there is no way for mod/FSO support teams to know what you have done to the .vp, and they have enough on their plate without having to user fix a problem that shouldn't have happened.
  
The significant advantage of a VP file is ease of distribution. in simple terms a VP file is a container used to maintain the file structure between users because all that is required is that they are all placed in the Mod folder. the problem with changing them is that if you edit one and get it wrong the simple fix and in all likely hood the fix you will be told to do is to reinstall fs2/the mod as appropriate because there is no way for mod/FSO support teams to know what you have done to the VP and they have enough on their plate without having to user fix a problem that shouldn't have happened especially as the mod folders feature has been provided as a means achieving the same effect that requires no modifying of VPs.
+
==.TBM VS. .TBL==
  
==tbm vs tbl==
+
A .tbl is the core table file of that type, and only one can be loaded into FreeSpace at any one time. .tbl files provide the structure to the engine and require all basic elements to be present to work.
  
A tbl is the core table file of that type and only one can be loaded into freespace at any one time tbl files provide the structure to the engine and usually require all basic elements to be present to work.
+
A .tbm (called [[Modular Tables]]) file, on the other hand, is an additional file to the .tbl, usually providing additional data to the .tbl or overriding it if needed. Generally, you'll be using a .tbm unless you're planning on doing a total conversion. .tbm files also have the advantage that FS2 can handle multiple .tbm files of any given type, though a modder should avoid conflicting entries at all costs.
tbm (called [[Modular Tables]]) on the other hand is an additional file to the tbl, usually providing additional data to the tbl or overriding it if needed. Until you get to the stage of building mods for more than adding a few ships you will probably only use tbm if available for that table type. tbm also has the advantage that FS2 can handle multiple tbm files of any given type though avoid conflicting entries at all costs.
 
  
 
==Closing Words==
 
==Closing Words==
  
I cannot over state the usefulness of [[Portal:Modding]] and everything within its links, a good 90-95%of what I know about modding was learned in there and the rest was trial and error with a new newbie questions on the forum and IRC channel.   
+
I cannot overstate the usefulness of [[Portal:Modding]] and everything within its links. A good 90-95% of what I know about modding was learned in there and the rest was trial and error with a new newbie questions on the forum and IRC channel.   
  
Another thing is that it is as a matter of courtesy to credit people who’s resources you use, you are unlikely to get thrown out of the community for not doing so but it is always nice to have that little nod of thanks.
+
Another thing is that it is as a matter of courtesy to credit people whose resources you use. You are unlikely to get thrown out of the community for not doing so, but it is always nice to have that little nod of thanks.
  
Also on a side note don’t change the name of the folder for and existing/downloaded mod, many mods reference each other and changing the name for the folder will brake the links in the mod.ini of any mods that tries to use it, which increases the chance that there will be assets missing or you end up using old assets. On top of this when you report the issues cause by changing folder name you will be treated in a colder manner because you have broken the hard work that went into making sure the mod worked correctly in the first place through a deliberate act. Lets face it, how would you react if you got your mod working nicely and someone comes to you because the mod doesn’t work because they changed something? And then several people started to complain with the same avoidable problem?
+
Also on a side note: don’t change the name of the folder for and existing/downloaded mod. Many mods reference each other, and changing the name for the folder will break the links in the mod.ini of any mods that tries to use it. This increases the chance that there will be assets missing. On top of this, when you report the issues cause by changing folder name, you will be treated in a colder manner because you have broken the hard work that went into making sure the mod worked correctly in the first place. Lets face it. How would you react if you got your mod working nicely and someone comes to you because the mod doesn’t work by being renamed? And then several other people started to complain about the same problem?
  
Remember the most important thing when modding a game, FreeSpace or any other like any hobby is to have fun. Also it can be surprising how fun trial, error and figuring things out for yourself can be.
+
Remember the most important thing when modding a FreeSpace is to have fun. It can be surprising how fun trial, error, and figuring things out for yourself can be.
  
  
Good luck and if you really do get stuck dont be afraid to ask questions.
+
Good luck and if you really do get stuck do not be afraid to ask questions.
  
  
 
[[Category:Tutorials|General Mod Creation]]
 
[[Category:Tutorials|General Mod Creation]]

Latest revision as of 19:14, 30 August 2016

Thanks to the work of the Source Code Project (SCP) team modifying FreeSpace 2 is now very easy, though understanding everything by yourself is extremely difficult with to date only one major modification released that could be called a solo project (see WoD). Your best bet to start Modifying is to focus on one area, at least to begin with, then once you have a grasp of how things work or you decide you are no longer interested in it and you feel like other areas interest you can start looking at them. Modifying any game calls on a wide array of talents from general creative writing to table editing, model making and the ever in demand skills of texture artists. This page is intended as a getting started and confidence builder as an in depth how to is a massive undertaking and the detailed information on how to mod FreeSpace is found within the modding section of this wiki with issue specific help and advice available on the Hard Light Productions forum.

Before We Get Started

Your New Best Friends

By closely reading this page, you have taken your first steps of making the most important friend every FreeSpace modder has - the Modding Portal of the FreeSpace Wiki. Within the Wiki's pages is a gold mine of information created by the SCP team and community members who have spent a huge amount of time and effort making sure things work, and how they work is well documented.


Your next best friends are in your FreeSpace2\data folder, and they are fs2_open.log and fred2_open.log. These two files are the logs generated by the debug builds of FreeSpace 2 and the FRED2 editor. The way to tell between a release and debug build is that after the build cycle number in the file name there is a d for debug or r for regular, eg 3.6.12d. any information after this point in the file name is information that tells the support guys exactly which version you are using. Whenever you are running a debug build of FreeSpace or FRED, the program creates a constant record of the program's activity and lists any error messages where possible that occur and stores that record in the listed log files. Debug builds try to catch every error they can while release builds try to ignore them, making debug build an invaluable tool for error-checking. To open the logs, simply double click on them and, if prompted, select any text editor.

Required:

The following are required to create mods for FreeSpace Open:

  • A working and legitimate copy of FreeSpace 2
  • FreeSpace Open executable (preferably the latest stable build or, if you know what you are doing, a Nightly build)
  • Imagination

Getting Started:

The first thing to know when modifying FreeSpace 2 is to understand how the mod structure works. Each mod needs its own folder within the FreeSpace 2 folder. For example, Wings of Dawn on my computer is C:\Games\Freespace2\Wings of Dawn. All files that directly relate to the WoD mod are found within this folder on my PC, though a file (mod.ini) within the folder tells FreeSpace to go and look for the mediavps mod. The mod structure allows for mods to be chained together in a simple fashion. Within the mod folders is another folder called data. The data folder is not present in mods relying on .VP files, which are container files that mimic the mod structure and are used to make distributing and installing mods easier. Within the data folder are the subfolders which the files that make the mod are stored. The subfolders are there to keep everyone sane and make everything easier to find. The majority are self-explanatory but a detailed breakdown can be found in FS2_Data_Structure. Below is a summary of important information relating to this tutorial.

  • Cache - To reduce loading times, the engine will generate a cache file for each model it encounters. Since cache generation can take quite long for more complex models, you should always include cache files for unique mods.
FS2 Open, 3.7.4:
Cache files are no longer used or generated by the executable; since making a new mod should always be done on the latest stable release, you shouldn't have to worry about cache files anymore.
  • Cbanims - This is where command and mission briefing animations are stored.
  • Effects - Weapon and other 2D effects, stars, planets, nebulae, e.t.c.
  • Fonts - Font files are kept here. Unless you are aiming at a total conversion, you will in all likelihood not need this folder.
  • Hud - This is where custom HUD graphics go.
  • Intelanims - Animations used in the Techroom for weapons and intel sections are located here.
  • Interface - Images and animations used in the menu system go here. Not everything that you would expect to be a still is stored as a still, so research carefully before changing anything. Only larger mods and total conversions generally go into this because it is hard to do properly.
  • Maps - Texture files for ships and other model-based objects.
  • Missions - This is where FRED should be storing mission files and the only place where FS2 will look for missions and campaigns, both single- and multi-player.
  • Models - .pof files go here no matter what purpose.
  • Music - In-game music files go here.
  • Sounds - Sound effects like weapons fire belong here.
  • Tables - This is where the .tbl and .tbm files go that tells the game how to use the majority of the information in the folders listed and also controls a number of other game aspects.
  • Voice - Voice overs for mission chatter.

Simple Modifications

One of the simplest things to do is add a new weapons or ships created by the community. The two are often related as ships created by members might have their own custom weapons.

Adding A Ship

The following will be an example of how to add a ship in FreeSpace:

  • Go to SC Lamia in User-made Ships and download it.
  • Create a folder in FreeSpace2 directory called New Ship.
  • Within the New Ship directory, create a folder called data.
  • Extract sc_lamia.rar. If you are unable to, you can download a file archiver such as 7-zip to extract the files.
  • Inside the file are three folders called maps, models, and tables. Copy them into your New Ship\data folder without altering them.
  • Create a mod.ini by opening a text editor. The following are required for the mod.ini to work:
    • [launcher]
    • modname = New Ship;
    • [multimod]
    • primarylist = ;
    • secondarylist = mediavps_3612 ;
      • This is optional. By having the mediavps_3612 listed in your secondarylist, you will use the SC Lamia as well as the Mediavps instead of the Lamia with retail FS2 assets.


Congratulations! You have just created your first mod. If you look in the maps folder there will be three .dds image files which make up the ship's texture. The models folder will contain SCLamia.pof, and in tables there are two .tbm files - one for the ship and one for a custom weapon for that ship.

There is one more thing I want you to do, though. Open sclamia-shp.tbm in a text editor and find the line starting $flags:. The full line reads $Flags: ( "cruiser" ). Add "in tech database" with the quotation marks to the line between the parentheses so it reads $Flags: ( "cruiser" "in tech database" ). Save and close the file. This allows the Lamia to be viewed in the Techroom from the beginning. Open your FreeSpace launcher and select New Ship as the mod and run the game. If you get an error message, go back to the file and double-check the flags line to the example I provided. When you reach the main screen go to the Techroom and at the bottom should be the Shivan cruiser you just added, the ship will not appear in any missions at this time because a mission file needs creating using the ship.

Mod.ini

Unlike other files, the mod.ini does not go in the data folder of a mod. Instead, this file goes in the main directory for the mod (e.g. Freespace2\New Ship for the above example) and adds the final polish to a mod. It performs useful tasks like linking other mods. Like many of the files in Freespace 2, this is basically a renamed .txt file and can be opened by any text editor. Let’s take a look at one.


# PLEASE NOTE ALL INI SETTINGS ARE *OPTIONAL*
# modname:       Display name only, so you can have spaces instead of underscores for multi word MOD's
# image255x112:  Location of a 255x112 bmp you wish to display in the launcher
# infotext:      Text that will appear in the launcher
# website:       Link to your website
# forum:         Link to your forum
[launcher]
modname      = Mod Name
image255x112 = mod-logo.bmp;
infotext     = Here is a short blurb for the mod
# website      = Here is where a web address goes if your mod has one
# forum        = http://www.hard-light.net/forums

[multimod]
primarylist  = ;
secondarylist = mediavps_3612;


This is the contents of the mod.ini for a sample mod.

Anything following a # is a comment and is ignored by the launcher.

The first section is information for the FreeSpace launcher and contains the following:


  • modname: the name of the mod
  • image255x112: the name of a 255x112 pixel .bmp to use as a mod image
  • infotext: the area where you can put info about the mod and/or a tag line
  • website: the link to your website that will be linked to the Website button in the launcher
  • forum: the link to your forum that will be linked to the Forum button in the launcher


In the example shown both website and forum are commented out but if you remove the # and save they will be read by the launcher.

The next bit links the mod into other ones, the example above will call the 3.6.12 version of the mediavps to enhance the visuals of anything in FreeSpace 2 that is not touched by your mod. For example, if you turn the Ravana green, the Ravan will not be red because the mediaVPs_3612 is in the secondary line. However, it will become red if you have the mediavps_3612 in your primarylist. Most of the time, you will only use secondary list. This is the one you are recommended to use unless you know exactly what you are doing.

Changing Other Mods

You have downloaded some mod. You played it, and you have beaten it. However, you want to change something. Perhaps you feel the anti-fighter turrets are too weak or that there is a different ship you want to use. Do NOT add, remove, or change anything in the actual folder! This is because you will change the mod as long as the altered files are in there. What you should do is create a mod as explained in 'Adding A Ship' and place a mod.ini referencing the folder name for whatever mod you wish to alter in the secondary mod line. Then place the edit-that-you-want-to-make (e.g. model, .tbm, etc.) into this new mod. Once you have done all of that, select the new mod folder in the Freespace launcher’s mod tab and run. Because of the reference to the original in the mod.ini, that and any mods referenced by that mod will be loaded, but the changes you made will override the original. This way, you get to play your twist on the mod whenever you want without having to alter the original mod to play it.

.VP

Because of the ease in damaging data key to a mod or indeed retail, IT IS STRONGLY ADVISED THAT .VP FILES ARE NOT EDITED IN ANY WAY!

The advantage of a .vp file is ease of distribution. A .vp file is a container used to maintain the file structure. All that is required is that they are all placed in the mod folder. The problem with changing them is that if you edit one and get it wrong, you may have to reinstall the mod because there is no way for mod/FSO support teams to know what you have done to the .vp, and they have enough on their plate without having to user fix a problem that shouldn't have happened.

.TBM VS. .TBL

A .tbl is the core table file of that type, and only one can be loaded into FreeSpace at any one time. .tbl files provide the structure to the engine and require all basic elements to be present to work.

A .tbm (called Modular Tables) file, on the other hand, is an additional file to the .tbl, usually providing additional data to the .tbl or overriding it if needed. Generally, you'll be using a .tbm unless you're planning on doing a total conversion. .tbm files also have the advantage that FS2 can handle multiple .tbm files of any given type, though a modder should avoid conflicting entries at all costs.

Closing Words

I cannot overstate the usefulness of Portal:Modding and everything within its links. A good 90-95% of what I know about modding was learned in there and the rest was trial and error with a new newbie questions on the forum and IRC channel.

Another thing is that it is as a matter of courtesy to credit people whose resources you use. You are unlikely to get thrown out of the community for not doing so, but it is always nice to have that little nod of thanks.

Also on a side note: don’t change the name of the folder for and existing/downloaded mod. Many mods reference each other, and changing the name for the folder will break the links in the mod.ini of any mods that tries to use it. This increases the chance that there will be assets missing. On top of this, when you report the issues cause by changing folder name, you will be treated in a colder manner because you have broken the hard work that went into making sure the mod worked correctly in the first place. Lets face it. How would you react if you got your mod working nicely and someone comes to you because the mod doesn’t work by being renamed? And then several other people started to complain about the same problem?

Remember the most important thing when modding a FreeSpace is to have fun. It can be surprising how fun trial, error, and figuring things out for yourself can be.


Good luck and if you really do get stuck do not be afraid to ask questions.