FS2 Data Structure

WARNING: THIS PAGE HAS BEEN WRITTEN WITHOUT EXPERT REVISION!!

Although some expert hand should revise all the page, where the writer HAS more doubts is marked in blue colour.

Introduction

Through all this page, SCP fs2_open and FRED2_open additions over retail behaviour will be marked in red font.

Apart from the game engine or the mission editor, FRED, the game needs data to run; it needs missions, sounds, 3D models, textures... Freespace2 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):

1. Unpacked, ie. individual files, inside data folder within Freespace 2 installation folder, ie. in /freespace2/data. (data name is compulsory).
   Inside data folder, the game contents are classified and stored in several 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:
   • effects contains all the textures and animations used in all explosions, weapon glows, smoke, particles and so on.
   • maps contains all the textures, (and animated textures), used over ship models.
   • missions contains all the mission (*.FS2) and campaign (*.FC2) definition files.
   • models contains all 3D models (*.POF).
   • music contains all the music files.
   • sounds contains all ingame sound effect files.
   • 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.
   • voice contains all the ingame voices.
2. 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 WMCoolmon's Maja which comes in a Java cross-platform executable. You can grab it from 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 Descent Network download page
   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: Mainly tables and missions.
   • smarty_fs2.vp: Intelligence animations.
   • sparky_fs2.vp: Most of the game data, mainly models, maps, effects, hud, interface and sounds data.
   • sparky_hi_fs2.vp: Extra hud and interface data for hi res (1024x768).
   • stu_fs2.vp: Voice data.
   • tango1_fs2.vp: 1st pack of Command briefing animations.
   • tango2_fs2.vp: 2nd pack of Command briefing animations.
   • tango3_fs2.vp: 3rd pack of Command briefing animations.
   • warble_fs2.vp: Music data.
   • *.MVE movies (cutscenes). They are not originally installed in the user hard disk drive. They are read from game CDs.
3. One of the most important SCP fs2_open additions: Auxiliary data folders loaded through -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.

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

The use of -MOD launcher flag implies that there will be two or more /data folder structures. Some game data, mainly model cache files (*.IBX), can be regenerated by the game itself. Unless explicitly specified, these autogenerated files will be placed in the highest priority /data folder structure.

data subfolders

cache

• Contents: Model cache files. models folder contains raw *.POF 3D model files. But the game has to "compile" them in order to use them. So each original AnyShip.pof generates one compiled and ready to use AnyShip.ibx file (and also one AnyShip.tsb in SCP fs2_open).
• Supported files:
  • Retail: *.IBX model cache files.
  • SCP fs2_open: The former ones and *.TSB files which contain associated normal map data, (since 3.6.10 version).
  • *.CLR and *.TMP files ????
• Notes:
  • The content of this folder can be autogenerated by FS2.
  • Generating cache files takes a bit of time. If you release a pack or mod with a lot of new models, providing their cache files too is a good idea because, on the very first run afterwards, the game will seem hung while it is generating them.
  • FS2 detects model upgrades so it rebuilds cache files if they don't match. BUT sometimes corrupted cache files can cause problems. So sometimes, while debugging or trying to solve problems, deleting cache contents can be useful. (See also -noibx launcher flag help).

cbanims

• Contents: Command and mission briefing animations. (They are assigned to missions through FRED2 editor).
• Supported files: *.ANI animations.

config

• Contents: ???????
• Supported files: *.CFG 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 likelyhood will never) work.
• Supported files: *.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 afterburner trails.
  • All the background images, sun bitmaps, sun glares 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 maps folder, put it here. If you have doubts, put it here too.
• Supported files:
  • Retail: *.PCX for bitmaps, (example, backgrounds) and *.ANI for animations (example: explosions).
  • SCP fs2_open: Both formats and *.DDS, *.JPG and *.TGA for bitmaps, and *.EFF for animations.
  • *.NEB files ??????
• 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.
  • *.DDS and *.EFF are the preferred formats.
  • Till version 3.6.9. (included), *.JPG and *.TGA formats require the usage of -jpgtga launcher flag. If not used they will be ignored. From this version, all the supported formats are always used.
  • See Texturing section for important info about this aspect of the game. It is more important for maps folder contents, (ie. ship textures), but it also applies here.

fonts

• Contents: ???????
• Supported files: *.VF files.

force feedback

• Contents: ???????
• Supported files: ???????

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: *.PCX and *.ANI.
  • SCP fs2_open: The former ones and *.DDS and *.TGA formats.Is jpg supported here? Are dds, jpg and tga fully supported for everything?
• Notes:
  • Most of this folder contents have a hardcoded name.
  • Most of this folder contents are "false" animations. It means that the *.ANI file is only used to pack several related bitmaps. Example: every ship shield graphic uses five bitmaps, (the ship bitmap and then, front, right, back and left shield quadrants) packed in one *.ANI.

intelanims

• Contents: Intelligence animations used in Technical Database > Intelligence section. They are used through Species.tbl table.
• Supported files: *.ANI animations.

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: *.ANI animations and *.PCX bitmaps.
  • SCP fs2_open: The former ones and *.DDS and *.TGA formats.Is jpg supported here? Are dds, jpg and tga fully supported for everything?
• Notes:
  • Most people use -ship_choice_3d launcher flag. With this flag, only primary weapon animations are needed in Weapon loadout screen. There's no need for ship or secondary weapon animations. Even, some mods need a compulsory use of this flag because they have no available animations for their ships or missiles.
  • As an exception, fs2_open doesn't require the usage of -jpgtga launcher flag for intro splash screen. But the rest of *.TGA format usage needs it (until version 3.6.9.).

maps

• Contents: All the textures used by 3D *.POF models. *.POF models use textures to "paint" their surfaces and to simulate glow points. *.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: *.PCX bitmaps.
  • SCP fs2_open: The former one and *.DDS, *.JPG and *.TGA formats. Some of the textures, (example: glow maps), support animated textures so *.EFF and *.ANI are also supported.
• Notes:
  • See Texturing section for important info about this aspect of the game.
  • *.DDS and *.EFF are the preferred formats.
  • Till version 3.6.9. (included), *.JPG and *.TGA formats require the usage of -jpgtga launcher flag. If not used they will be ignored. From this version, all the supported formats are always used.

missions

• Contents: All the mission and campaign files.
• Supported files: Each mission is one *.FS2 file and each campaign is one *.FC2 file.
  • *.NTL and *.SSV files ?????
• Notes:
  • In Mission Simulator screen, Single Missions are just available *.FS2 mission files which are not pointed by any of the available *.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, 3D shockwaves, 3D warp-in/warp-out effects and background star-holding model.
• Supported files: *.POF model files.
• Notes:
  • *.POF models have direct relation with maps and cache folder contents.
  • 3D warp-in/warp-out effects need the usage of -3dwarp launcher flag.

movies

• Contents: Game cutscenes.
• Supported files: *.MVE, *.OGG, *.AVI and *.MPG clip files.
  • *.MSB files ????
• Notes:
  • This folder is a fully SCP addition. Retail game reads *.MVE cutscenes from game CDs.
  • *.AVI and *.MPG formats are decoded through system player. Their support is not guaranteed in future fs2_open versions.
  • Retail uncompressed *.MVE and Theora compressed *.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.

multidata

• Contents: ???????
• Supported files: *.PCX and *.FS2 files. ???????

music

• Contents: Music files used through Music.tbl table.
• Supported files:
  • Retail: PCM *.WAV sound clips up to 16bit - 22kHz - 2 channels.
  • SCP fs2_open adds support for compressed *.OGG Vorbis sound clips.

players

• Contents: All game player data.
  • It has 4 subfolders, each one has a deeper explanation below:
    • images: Selectable appearances of the player in Barracks screen.
    • multi: Game data of multiplayer pilots
    • single: Game data of single player pilots
    • squads: Selectable squad insignias of the player in Barracks screen.
  • The main players folder just contains HUD appearance presets, (*.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: *.HCF HUD configuration files.
• Notes:
  • Only /freespace2/data/players main folder is used despite the -MOD launcher flag settings. Only images and squads subfolders are read from any other locations (vp archives or other /mod/data/players folders).
  • Of course, *.HCF files can be generated by the game itself.

images

• Contents: Selectable appearances of the player in Barracks screen, ie. the player's photograph.
• Supported files: *.PCX bitmaps.

multi

• Contents: Game data of multiplayer pilots.
• Supported files: *.PLR files.
• Notes:
  • Only /freespace2/data/players/multi folder is used despite the -MOD launcher flag settings.
  • 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 *.PL2 file, (let's call it MyPilot.pl2), which contains main pilot data.
    • Several *.CS2 files. Each of these files is generated for each played campaign. They have the form MyPilot.Campaign name.cs2.
  • *.PLR, *.CSG and *.CSS files ??????.
• Notes:
  • Only /freespace2/data/players/single folder is used despite the -MOD launcher flag settings.
  • Of course, single player data is generated and updated by the game itself.
  • Do not use pilot names longer than XXXXXX. 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: *.PCX bitmaps.
  • fs2_open: At least *.DDS bitmaps can be also used. But in order to maintain backwards and multiplayer compatibility, a *.PCX copy of the same insignia MUST be available. More info can be found in Mantis report 1834.

scripts

• Contents: This has something to do with LUA scripting SCP addition, but I know NOTHING about it. Please some expert fill it.
• Supported files: *.LUA and *.LC files. ???????.

sounds

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

8b22k

• Contents: Low quality sounds, but just use the main sounds folder.

16b11k

• Contents: High quality sounds, but just use the main sounds folder.

tables

• Contents: Data tables which set the whole game behaviour.
• Supported files:
  • Retail: *.TBL tables.
  • One of the most important SCP fs2_open additions: *.TBM modular table files.
• 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: ???????
• Supported files: *.TXT and *.NET files.

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 command_briefings subfolder.
  • Mission briefing explanation speeches. They are loaded from briefing subfolder.
  • Mission debriefing speeches. They are loaded from debriefing subfolder.
  • Mission scripted speech. The voice files are loaded from special subfolder.
  • Random speech generated by flying mates or enemies. The voice files are loaded from personas subfolder.
  • A "training" category- identical to special, but used by Volition to organize training messages.
• Supported files: All the speech kinds support these formats:
  • Retail: PCM *.WAV sound clips up to 16bit - 22kHz - 2 channels.
  • SCP fs2_open adds support for compressed *.OGG Vorbis sound clips.

briefing

• Contents: Mission briefing explanation speeches. They are set through FRED editor in each *.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 *.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 example, the game looks for ship textures in maps folder but also in 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)
/data  (cfg, log, txt)
/data/maps   (pcx, ani, eff, tga, jpg, 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, tga, dds)
/data/fonts  (vf)
/data/effects  (ani, eff, pcx, neb, tga, jpg, dds)
/data/hud  (ani, pcx, tga, dds)
/data/players  ()
/data/players/images (pcx)
/data/cache  (clr, tmp, ibx)
/data/players  (hcf)
/data/players/single  (pl2, cs2, plr, csg, css)
/data/players/multi  (plr)
/data/multidata  (pcx, fs2)
/data/config  (cfg)
/data/players/squads  (pcx)
/data/demos  (fsd)
/data/cbanims  (ani)
/data/intelanims  (ani)
/data/scripts  (lua, lc)