Ships and General Mod Creation
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.
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)
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 - This 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 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 both single player and campaign.
- 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.
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:
- modname = New Ship;
- 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.
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.
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.
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.