View source for 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.

===Required:===

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.

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

''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.

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

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

‘# 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 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.

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

* modname, the mod’s name,

* 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.

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.

***note
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 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.

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

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

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

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.  

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.

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?

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.


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


[[Category:Tutorials|General Mod Creation]]