View source for FS2 Data Structure

<font color=cyan>Although some expert hand has been through the page, where the (original) writer has doubts is marked in blue colour.</font>


==Introduction==
::<font color=red>Through all this page, SCP fs2_open and FRED2_open additions over retail behaviour will be marked in red font.</font>


Apart from the game engine or the mission editor, FRED, the game needs data to run; it needs missions, sounds, 3D models, textures... FreeSpace 2 is highly moddable because nearly none of these data are embedded inside the game executable. In this way the user can always change nearly all game behaviour and appearance.

Like all your applications you'll have FreeSpace 2 installed in one folder in your hard disk drive. We will call this folder '''/freespace2''', although it can have any other name (''/fs2'', ''/fspace2'', or whatever). Inside this folder, FreeSpace 2 stores all its game data in three places (retail version just in two):
#Unpacked, ie. individual files, inside '''data''' folder within FreeSpace 2 installation folder, ie. in '''/freespace2/data'''. ('''data''' name is compulsory).<br>Inside '''data''' folder, the game contents are classified and stored in several subfolders. [[FS2_Data_Structure#data_subfolders|Below]], you have the full list of '''data''' subfolders with their description and contents, (remember that all their names are compulsory). The most commonly used and changed are:
#*[[FS2_Data_Structure#effects|effects]] contains all the textures and animations used in all explosions, weapon glows, smoke, particles and so on.
#*[[FS2_Data_Structure#maps|maps]] contains all the textures, (and animated textures), used over ship models.
#*[[FS2_Data_Structure#missions|missions]] contains all the mission ([[%2A.FS2]]) and campaign ([[%2A.FC2]]) definition files.
#*[[FS2_Data_Structure#models|models]] contains all 3D models ([[%2A.POF]]).
#*[[FS2_Data_Structure#music|music]] contains all the music files.
#*[[FS2_Data_Structure#sounds|sounds]] contains all ingame sound effect files.
#*[[FS2_Data_Structure#tables|tables]] contains all table files. Tables define all the behaviour the game components have. They are the most important thing for modders to know. See [[Tables]] section for deeper info.
#*[[FS2_Data_Structure#voice|voice]] contains all the ingame voices.
#Packed in vp archives. This kind of archives just contain individual files in a similar way as "normal" archives like rar or zip do. They are placed in '''/freespace2''' folder. Special software, like [[VPMage]], is needed to build them. Another really good utility is [[Maja|WMCoolmon's Maja]] which comes in a Java cross-platform executable. You can grab it from [http://wmc.freespacemods.net/repository/ WMC::Repository]. If you just want to browse or extract files from existing vps, but not editing or building them, then use [[VPView]]. You've got two versions of it in [http://www.descent-network.com/descman Descent Network download page]<br>vp archives also follow the data structure, so, even while packed in a vp archive, your missions will be in /data/missions and your ship 3D models in /data/models. All retail data come packed in several vps. The next, and only the next, are the original game contents (when patched to v1.2):
#*root_fs2.vp (6,255 KB - 157 files - checksum of 0xce10d76c): Mainly [[FS2_Data_Structure#tables|tables]] and [[FS2_Data_Structure#missions|missions]].<br><font color=red>(Number of files and checksum as reported in fs2_open.log when running a fs2_open ''debug'' build. Please notice that vp can actually contain more files than the reported number, but these are the pure game data files. As example root_fs2.vp contains 160 files with three useless ''vssver.scc'' in tables, images and squads).</font>
#*smarty_fs2.vp (120,241 KB - 10 files - checksum of 0xddeb3b1e): [[FS2_Data_Structure#intelanims|Intelligence animations]].
#*sparky_fs2.vp (254,457 KB - 3027 files - checksum of 0x164fe65a): Most of the game data, mainly [[FS2_Data_Structure#models|models]], [[FS2_Data_Structure#maps|maps]], [[FS2_Data_Structure#effects|effects]], [[FS2_Data_Structure#hud|hud]], [[FS2_Data_Structure#interface|interface]] and [[FS2_Data_Structure#sounds|sounds]] data.
#*sparky_hi_fs2.vp (259,026 KB - 1337 files - checksum of 0xa11d56f1): Extra [[FS2_Data_Structure#hud|hud]] and [[FS2_Data_Structure#interface|interface]] data for hi res (1024x768).
#*stu_fs2.vp (169,108 KB - 2355 files - checksum of 0xd77da83a): [[FS2_Data_Structure#voice|Voice]] data.
#*tango1_fs2.vp (191,297 KB - 32 files - checksum of 0x4c25221e): 1st pack of [[FS2_Data_Structure#cbanims|Command briefing animations]].
#*tango2_fs2.vp (71,073 KB - 15 files - checksum of 0x86920b82): 2nd pack of [[FS2_Data_Structure#cbanims|Command briefing animations]].
#*tango3_fs2.vp (49,314 KB - 10 files - checksum of 0x705e8d71): 3rd pack of [[FS2_Data_Structure#cbanims|Command briefing animations]].
#*warble_fs2.vp (116,073 KB - 52 files - checksum of 0xd85c305d): [[FS2_Data_Structure#music|Music]] data.
#*[[%2A.MVE]] movies (cutscenes). They are not originally installed in the user hard disk drive. They are read from game CDs.
#<font color=red>'''One of the most important SCP fs2_open additions:''' Auxiliary data folders loaded through [[Command-Line_Reference#-mod|-MOD launcher flag]]. Retail game only use former both places. But fs2_open, (and FRED2_open), can use any other auxiliary folder in /freespace2 as game data holder. This feature allows installing and using several different mods without having undesired cross-effects.</font>

The most important consequence of having several available locations for game data, is that several versions of each file can exist. '''There's a priority order between different locations''' as explained in [[Command-Line_Reference#-mod|-MOD launcher flag help]]. Due to this order, '''only the highest priority version of each file will be used'''. This feature allows the user to quickly replace existing ''mission.fs2'' or ''ShipModel.pof'' by new or improved versions, placing them in a higher priority place. There's no need to remove obsolete files.

<font color=red>The use of [[Command-Line_Reference#-mod|-MOD launcher flag]] implies that there will be two or more /data folder structures. Some game data, mainly model cache files ([[Model files#IBX|*.IBX]]), can be regenerated by the game itself. Unless explicitly specified, these autogenerated files will be placed in the ''highest'' priority /data folder structure.</font>

==data subfolders==

===cache===
*'''Contents:''' Model cache files. In versions of FS2Open prior to 3.7.4, model files were processed to extract the actual render geometry. In 3.7.4, that processing step was optimized so that performing this extraction at runtime was just as fast as reading cache files off of the disk; as a consequence, it was decided to remove the cache file reading and writing code.

*'''Notes:'''
**This folder and its contents are obsolete as of FS2Open Release 3.7.4.

===cbanims===
*'''Contents:''' Command and mission briefing animations. (They are assigned to missions through FRED2 editor).
*'''Supported files:''' [[%2A.ANI]] animations.


===config===
*<font color=red>'''Contents''':</font> Used by the SCP Builds. Contains (usually by reference) additional data as loaded by Scripts.
*<font color=red>'''Supported files''':</font> [[%2A.CFG]] files.
{{table38|[[%2A.TBL]], [[%2A.TBM]], [[%2A.XML]] and [[%2A.CSV]] files.}}


===demos===
*'''Contents:''' This is probably where recordable demos would have been saved.  If you look in the source code, there are functions in place to record events and play the recordings back at a later time.  This code is does not (and in all likely hood will never) work.
*'''Supported files:''' [[%2A.FSD]] (FreeSpace Demo) files.


===effects===
*'''Contents:''' Bitmaps and animations for every game effect:
**All the explosions and weapon effects.
**Damage smoke animation.
**Particle animations.
**Thruster glows and <font color=red>afterburner trails</font>.
**All the background images, sun bitmaps, <font color=red>sun glares</font> and space motion debris (see [[Stars.tbl]] table).
**Warp-in / warp-out animations.
**Anything more you can think of in this category. If you have a texture which you know it doesn't belong to [[FS2_Data_Structure#maps|maps folder]], put it here. If you have doubts, put it here too.
**<font color=red>Since 3.6.10. version (including previously released nightly builds): GLSL shaders. See [[OpenGL_Shaders_(GLSL)|OpenGL Shaders (GLSL)]]</font>
*'''Supported files:'''
**Retail: [[%2A.PCX]] for bitmaps, (example, backgrounds) and [[%2A.ANI]] for animations (example: explosions).
**<font color=red>SCP fs2_open: Both formats and: [[%2A.JPG]], [[%2A.TGA]], [[%2A.PNG]], [[%2A.DDS]], for images, and [[.EFF]] for animations.</font>
**<font color=red>Since 3.6.10. version (including previously released nightly builds): [[%2A.SDR]] shader files. See [[OpenGL_Shaders_(GLSL)|OpenGL Shaders (GLSL)]]</font>
**<font color=cyan>[[%2A.NEB]] files ?????? </font>
*'''Notes:'''
**Some effect bitmaps or animations can be assigned by table entries. But the name of many others  is hardcoded, (example particlesmoke01).
**Not all the effects support animations. Example background bitmaps.
**<font color=red>[[%2A.PNG]] or [[%2A.DDS]] as/and [[%2A.EFF]] are the preferred formats.
**See [[Texturing]] section for important info about this aspect of the game. It is more important for [[FS2_Data_Structure#maps|maps folder]] contents, (ie. ship textures), but it also applies here.</font>


===fonts===
*'''Contents:''' This folder contains font files for the engine to use. Its native format are .VF ("Volition Font") files, which are bitmapped fonts created using the fonttool.
{{Table373|TrueType Fonts (ttf) are also supported.}}
*'''Supported files:''' <font color=cyan>[[%2A.VF]] files, [[%2A.TTF]] files</font>

===force feedback===
*'''Contents:''' <font color=cyan>???????</font>
*'''Supported files:''' <font color=cyan>???????</font>


===freddocs===
*'''Contents:''' This is where the help files for FRED are stored.  Since the help files are viewed in a web browser, they were not able to be stored in the VP files.
*'''Supported files:''' *.html, *.gif, *.jpg, *.png.


===hud===
*'''Contents:''' All HUD building bricks. Anything you see on your HUD while flying is defined through this folder contents.
*'''Supported files:'''
**Retail: [[%2A.PCX]] and [[%2A.ANI]].
**<font color=red>SCP fs2_open: The former ones and [[%2A.TGA]], [[%2A.PNG]] and [[%2A.DDS]] formats.</font>
*'''Notes:'''
**Most of this folder contents have a hardcoded name.
**Most of this folder contents are "false" animations. It means that the [[%2A.ANI]] file is only used to pack several related images. Example: every ship shield graphic uses five images, (the ship bitmap and then, front, right, back and left shield quadrants) packed in one [[%2A.ANI]].


===intelanims===
*'''Contents:''' Intelligence animations used in ''Technical Database'' > ''Intelligence'' section. They are used through [[Species.tbl]] table.
*'''Supported files:''' [[%2A.ANI]] animations and <font color=red>[[%2A.EFF]]</font>.


===interface===
*'''Contents:'''
**All the game screens and optional mission loading screens.
**All the button, mouse and icon bitmaps.
**Map ship icons in ''Briefing'' screen.
**Ship and weapon animations in ''Ship selection'' and ''Weapon loadout'' screens. These weapon animations are also used in ''Technical Database'' > ''Weapons'' section.
*'''Supported files:'''
**Retail: [[%2A.ANI]] animations and [[%2A.PCX]] bitmaps.
**<font color=red>SCP fs2_open: The former ones and [[%2A.TGA]], [[%2A.PNG]], [[%2A.DDS]] and [[%2A.EFF]] formats.</font> 
*'''Notes:'''
**<font color=red>Most people use [[Command-Line_Reference#-ship_choice_3d|-ship_choice_3d]] and [[Command-Line_Reference#-weapon_choice_3d|-weapon_choice_3d]] command-line flags. With these flags, only primary weapon animations are needed for the ''Weapon loadout'' screen. There's no need for ship or secondary weapon animations. Moreover, some mods need a compulsory use of these flags because they have no available animations for their ships or missiles.</font>


===maps===
*'''Contents:''' All the textures used by 3D [[%2A.POF]] models. [[%2A.POF]] models use textures to "paint" their surfaces and to simulate glow points. [[%2A.POF]] files only have links to the names of their used textures, they don't have embedded textures. All their used textures are read from this folder.
*'''Supported files:'''
**Retail: [[%2A.PCX]] bitmaps.
**<font color=red>SCP fs2_open: The former and: [[%2A.JPG]], [[%2A.TGA]], [[%2A.PNG]], [[%2A.DDS]] formats. Some of the textures, (example: glow maps), support animated textures so [[%2A.EFF]] and [[%2A.ANI]] are also supported.</font>
*'''Notes:'''
**See [[Texturing]] section for important info about this aspect of the game.
**<font color=red>[[%2A.DDS]] and [[%2A.EFF]] are the preferred formats.</font>


===missions===
*'''Contents:''' All the mission and campaign files.
*'''Supported files:''' Each mission is one [[%2A.FS2]] file and each campaign is one [[%2A.FC2]] file.
**<font color=cyan>[[%2A.NTL]] and [[%2A.SSV]] files ????? </font>
*'''Notes:'''
**In ''Mission Simulator'' screen, ''Single Missions'' are just available [[%2A.FS2]] mission files which are not pointed by any of the available [[%2A.FC2]] campaign files. This is the only way to play this kind of missions.


===models===
*'''Contents:''' All the 3D models used by ships, asteroid and debris fields, missiles, subspace model, <font color=red>3D shockwaves, 3D warp-in/warp-out effects and background star-holding model</font>.
*'''Supported files:''' [[%2A.POF]] model files.
*'''Notes:'''
**[[%2A.POF]] models have direct relation with [[FS2_Data_Structure#maps|maps]] and [[FS2_Data_Structure#cache|cache]] folder contents.
**<font color=red>3D warp-in/warp-out effects need the usage of [[Command-Line_Reference#-3dwarp|-3dwarp launcher flag]].</font>


===<font color=red>movies</font>===
*<font color=red>'''Contents:''' Game cutscenes.
*'''Supported files:''' [[%2A.MVE]], [[%2A.OGG]], [[%2A.AVI]] and [[%2A.MPG]] clip files.

*'''Notes:'''</font>
**<font color=red>This folder is a fully SCP addition. Retail game reads [[%2A.MVE]] cutscenes from game CDs.
**[[%2A.AVI]] and [[%2A.MPG]] formats are decoded through system player. Their support is [[Deprecation|deprecated]] and therefore not guaranteed in future fs2_open versions.
**Retail uncompressed [[%2A.MVE]] and Theora compressed [[%2A.OGG]] formats are the preferred ones. fs2_open has built-in support for them both.
**All the movies can have custom names, (their loading trigger is defined in FRED), but start-up movie. This movie must be called '''Intro'''.</font>


===multidata===
*'''Contents:''' <font color=cyan>???????</font>
*'''Supported files:''' [[%2A.PCX]], <font color=red>[[%2A.DDS]], [[%2A.PNG]]</font> and [[%2A.FS2]] files.


===music===
*'''Contents:''' Music files used through [[Music.tbl]] table.
*'''Supported files:'''
**Retail: PCM [[%2A.WAV]] sound clips up to 16bit - 22kHz - 2 channels.
**<font color=red>SCP fs2_open adds support for compressed [[%2A.OGG]] Vorbis sound clips.</font>


===players===
*'''Contents:''' All game player data. 
**It has 4 subfolders, each one has a deeper explanation below:
***[[FS2_Data_Structure#images|images]]: Selectable appearances of the player in ''Barracks'' screen.
***[[FS2_Data_Structure#multi|multi]]: Game data of multiplayer pilots
***[[FS2_Data_Structure#single|single]]: Game data of single player pilots
***[[FS2_Data_Structure#squads|squads]]: Selectable squad insignias of the player in ''Barracks'' screen.
**The main '''players''' folder just contains HUD appearance presets, ([[%2A.HCF]] files), which can be loaded, edited and saved in ''Options'' screen > ''HUD Config'' screen. From this screen they can be also applied to player's HUD settings.
*'''Supported files:''' [[%2A.HCF]] HUD configuration files.
*'''Notes:'''
**<font color=red>Only '''/freespace2/data/players''' main folder '''is used''' despite the [[Command-Line_Reference#-mod|-MOD launcher flag]] settings. Only [[FS2_Data_Structure#images|images]] and [[FS2_Data_Structure#squads|squads]] subfolders are read from any other locations (vp archives or other /mod/data/players folders).</font>
**Of course, [[%2A.HCF]] files can be generated by the game itself, and are the settings for the HUD Options screen.

====images====
*'''Contents:''' Selectable appearances of the player in ''Barracks'' screen, ie. the player's photograph.
*'''Supported files:''' [[%2A.PCX]] images
**'''<font color=red>SCP fs2_open''': [[%2A.PNG]] and [[%2A.DDS]] files.</font>

====multi====
*'''Contents:''' Game data of multiplayer pilots.
*'''Supported files:''' [[%2A.PLR]] files.
*'''Notes:'''
**<font color=red>Only '''/freespace2/data/players/multi''' folder '''is used''' despite the [[Command-Line_Reference#-mod|-MOD launcher flag]] settings.</font>
**Of course, multi player data is generated and updated by the game itself.

====single====
*'''Contents:''' Game data of single player pilots.
*'''Supported files:'''
**Each pilot consists of several files:
***One [[%2A.PL2]] file, (let's call it ''MyPilot.pl2''), which contains main pilot data.
***Several [[%2A.CS2]] files. Each of these files is generated for each played campaign. They have the form ''MyPilot.Campaign name.cs2''.
***<font color=red>FSO: [[%2A.PLR]], [[%2A.CSG]] and [[%2A.CSS]] files.</font>
*'''Notes:'''
**<font color=red>Only '''/freespace2/data/players/single''' folder '''is used''' despite the [[Command-Line_Reference#-mod|-MOD launcher flag]] settings.</font>
**Of course, single player data is generated and updated by the game itself.
**Do not use pilot names longer than 32 characters. The game has problems with them, ie. use short pilot names.

====squads====
*'''Contents:''' Selectable squadron insignias of the player in ''Barracks'' screen.
*'''Supported files:'''
**Retail: [[%2A.PCX]] bitmaps.
**<font color=red>fs2_open: The above format and: [[%2A.PNG]], [[%2A.DDS]] images can be also used. But in order to maintain backwards and multiplayer compatibility, a [[%2A.PCX]] copy of the same insignia '''MUST''' be available. More info can be found in [http://scp.indiegames.us/mantis/view.php?id=1834 Mantis report 1834].</font>


===<font color=red>scripts</font>===
*<font color=red>'''Contents:''' <font color=cyan>This has something to do with LUA scripting SCP addition, but I know NOTHING about it. Please some expert fill it.</font></font>
*<font color=red>'''Supported files:''' <font color=cyan>[[%2A.LUA]] and [[%2A.LC]] files. ???????</font></font>.


===sounds===
*'''Contents:''' All the game sound effects. [[FS2_Data_Structure#music|Music tracks]] or [[FS2_Data_Structure#voices|ingame speech]] which have their own subfolders.
**It has two folders, [[FS2_Data_Structure#8b22k|8b22k]] and [[FS2_Data_Structure#16b11k|16b11k]] to classify the sounds depending on their quality. <font color=cyan>But using them is not needed, all the sounds can go in the main folder.</font>
*'''Supported files:'''
**Retail: PCM [[%2A.WAV]] sound clips <font color=cyan>up to 16bit - 22kHz - 2 channels</font>.
**<font color=red>SCP fs2_open adds support for compressed [[%2A.OGG]] Vorbis sound clips.</font>
*'''Notes:'''
**In game sounds are used through [[Sounds.tbl]] table.
**<font color=cyan>Normally, game sounds only have one channel. Depending on the sound source location, the game will generate different right and left channel volumes.</font>

====8b22k====
*'''Contents:''' Low quality sounds, but just use the main [[FS2_Data_Structure#sounds|sounds]] folder.

====16b11k====
*'''Contents:''' High quality sounds, but just use the main [[FS2_Data_Structure#sounds|sounds]] folder.


===tables===
*'''Contents:''' Data tables which set the whole game behaviour.
*'''Supported files:'''
**Retail: [[%2A.TBL]] tables.
**<font color=red>One of the most important SCP fs2_open additions: [[%2A.TBM]] [[Modular_Tables|modular table]] files.</font>
*'''Notes:'''
**Tables are just the most important thing for modders to know.
**There is a lot of useful info about them in [[Tables]] section of the Wiki.


===text===
*'''Contents:''' <font color=cyan>???????</font>
*'''Supported files:''' <font color=cyan>[[%2A.TXT]] and [[%2A.NET]] files.</font>


===voice===
*'''Contents:''' In game speech. This speech is separated in six different types. Each of them is located in its own subfolder inside voice folder.
**Campaign command briefing speeches. They are loaded from [[FS2_Data_Structure#command_briefings|command_briefings]] subfolder.
**Mission briefing explanation speeches. They are loaded from [[FS2_Data_Structure#briefing|briefing]] subfolder.
**Mission debriefing speeches. They are loaded from [[FS2_Data_Structure#debriefing|debriefing]] subfolder.
**Mission scripted speech. The voice files are loaded from [[FS2_Data_Structure#special|special]] subfolder.
**Random speech generated by flying mates or enemies. The voice files are loaded from [[FS2_Data_Structure#personas|personas]] subfolder.
**A "training" category- identical to [[FS2_Data_Structure#special|special]], but used by Volition to organize training messages.
*'''Supported files:''' All the speech kinds support these formats:
**Retail: PCM [[%2A.WAV]] sound clips <font color=cyan>up to 16bit - 22kHz - 2 channels</font>.
**<font color=red>SCP fs2_open adds support for compressed [[%2A.OGG]] Vorbis sound clips.</font>

====briefing====
*'''Contents:''' Mission briefing explanation speeches. They are set through FRED editor in each [[%2A.FS2]] mission file.

====command_briefings====
*'''Contents:''' General command briefing speeches you can see before some missions. As example, the  first mission usually have command brienfing. They are set through FRED editor. They are attached to the next mission file.

====debriefing====
*'''Contents:''' Mission debriefing explanation speeches. They are set through FRED editor in each [[%2A.FS2]] mission file.

====personas====
*'''Contents:''' Random speech generated by flying ships or your command, for example to warn the player about "Bandit on your tail" or to praise him with "Good shoot!!" . This feature is used through [[Messages.tbl]] table.

====special====
*'''Contents:''' Scripted speech files in every mission. This speech is set through FRED SEXPs (mainly ''send-message-list'').

====training====
*'''Contents:''' Identical to '''special''', but used by Volition for training messages.


==Loading order==
Although each kind of game data has its right folder, they are really looked for in some related folders. As an example, the game looks for ship textures in [[FS2_Data_Structure#maps|maps]] folder but also in [[FS2_Data_Structure#effects|effects]] folder. Also if you have one effect and one ship texture with the same name you are going to have trouble.

Just for reference and troubleshooting, here you have the loading order and searched extensions of each subfolder. '''But always try to put every file in its right place'''. (You may see strange locations for some files, please don't use them).

 /   (mve, avi, mpg, ogg, vp)
 /data  (cfg, log, txt)
 /data/maps   (pcx, ani, jpg, tga, eff, png, dds)
 /data/text   (txt, net)
 /data/missions   (fs2, fc2, ntl, ssv)
 /data/models  (pof)
 /data/tables  (tbl, tbm)
 /data/sounds  (wav, ogg)
 /data/sounds/8b22k  (wav, ogg)
 /data/sounds/16b11k   (wav, ogg)
 /data/voice  ()
 /data/voice/briefing  (wav, ogg)
 /data/voice/command_briefings  (wav, ogg)
 /data/voice/debriefing  (wav, ogg)
 /data/voice/personas  (wav, ogg)
 /data/voice/special  (wav, ogg)
 /data/voice/training  (wav, ogg)
 /data/music  (wav, ogg)
 /data/movies  (mve, msb, avi, mpg, ogg)
 /data/interface  (pcx, ani, jpg, tga, eff, png, dds)
 /data/fonts  (vf)
 /data/effects  (neb, pcx, ani, jpg, tga, eff, png, dds)
 /data/hud  (pcx, ani, tga, png, dds)
 /data/players  (plr, csg)
 /data/players/images (pcx, png, dds)
 /data/cache  (clr, tmp, ibx)
 /data/players  (hcf)
 /data/players/single  (pl2, cs2, plr, csg, css)
 /data/players/multi  (plr)
 /data/multidata  (pcx, png, dds, fs2)
 /data/config  (cfg)
 /data/players/squads  (pcx, png, dds)
 /data/demos  (fsd)
 /data/cbanims  (ani, eff, png, dds)
 /data/intelanims  (ani, eff, png, dds)
 /data/scripts  (lua, lc)


[[Category:Modding]]