Modding, Mission Design, and Coding > The FRED Workshop

Campaign pre-release checklist

(1/1)

TopAce:
This thread was written and stickied for those new campaign makers/modders who are about to release their own campaigns/mods. These guidelines help campaign developers adhere to the community's requirements, standards and conventions.

Note that this is merely a fraction of all possible pitfalls. Mission-specific pet peeves (such as the absence of escort lists) do not belong here.

For more details, check the FreeSpace Wiki's FRED portal, or the index of all FRED-related articles.

---------------------------
Optimization for Most Recent SCP Builds
Any FREDder who wishes to publish his campaign should make sure that the widest possible range of players will be able to play their campaign with the newest FreeSpace Open (FSO) builds, and possibly with future builds as well. Whenever someone comes across your released campaign - be it at the time of the actual release, or four years later -, they'll use the most recent and most stable build to play the campaign. To materialize this aim, the FREDder must be aware of each and every available possibility to hunt down bugs.

FreeSpace Open builds come out in two versions: the release (...r) build, and the debug (...d) build. Release builds are intended for players, while the d notation could easily stand for "developer." The d build will report every issue it runs into. Debug builds are specifically designed to look for errors and report them. Any error reported by the debug build potentially confuses or downright crashes the release build, forcing the player to troubleshoot for himself, which veteran players can do (if they're willing), but those with substantially less modding and troubleshooting experience will simply stop playing. The r builds also make note of these errors, but they assume that whoever is running the game wants to play, so it'll try to ignore the given error as much as possible. It is crucial that the most recent debug build runs without error messages, because these errors, while skipped by the release build, may cause crashes, unexpected errors, and oddities while playing.

In the most ideal scenario, even campaigns developed on retail FreeSpace will be tested on the most recent FSO build, on the assumption that the majority of the players will play it on FreeSpace Open. Many community members can't run the retail version anymore, so make sure everyone can run your campaign without error messages.

Modular Table Files
The number of modular table files need to be as few as one can make. If it's possible to merge some modular table entries into the corresponding main table, do so. Though modular tables by themselves don't cause crashes, using many one-entry modular tables are potentially crash-inducing.

The Campaign (.fc2) File
Assuming you're not releasing disconnected missions, you need a campaign file to tell the game which mission follows which and what the requirements are for progression. If the campaign file is set up wrong, the player may be stuck at a certain mission without being able to continue with the campaign. On the other side of the coin: if the campaign lets you progress no matter the outcome of the mission, there'll be no point in the player trying to accomplish the missions.

The campaign file must use the end-campaign operator in the last tier of the campaign tree. Note: This is not the end-campaign SEXP that you use in the Event Editor!

As soon as you're done setting up the campaign file, start a new pilot and see if everything works as it should. By using a brand-new pilot file, you're simulating what every new player will experience. The one-pilot-per-mod rule has become standard, as using one pilot for multiple mods causes unexpected and unforeseeable errors.

mod.ini
The mod.ini has two main uses: to set mod dependencies, such as the FreeSpace Port or The Babylon Project; and to enable the use of the MediaVPs. It's safe to assume that 90% of the campaigns need to enable only the MediaVPs. For some more information about the mod.ini and how to set it up, consult this article.

The VP Files
To make installation of your mod much simpler (and adhere to convention), you'll need to put your files into a VP (Volition Package) file. VP files are like any archive formats, except they're designed particularly for Volition games. Include those, and only those, files that your final release actually uses. The community has made some VP manager programs that can be used to work with VP files.

All files inside the  mod's \data folder must be included except for the .bak files in the \missions folder. These backup files are used during development; players have no business with .bak files. The \cache folder is not recommended unless there are really complex models in your mod.

Use the most economical file formats in your VP files to save download and loading time. Graphical files are ideally compressed DDS files, while sounds are OGGs. While DDS files take up more space on average than PCXs, they are better compressed, take up less actual memory, and load faster. These formats are not available by default for most non-commerical programs, but relevant plugins are available for download. GIMP, a free 2D graphical progam, can be used to convert into DDS via a plugin. Consult Herra Tohtori's GIMP thread for more information on the graphical formats.

After creation of your VP files, set up a separate folder for all the VPs and miscellaneous files that you'll release and see if it works. You may have forgotten to include some textures, which will result in some invisible surfaces in game.

Where to Put the Files?
It is no longer preferable to put your campaign's VP file into FreeSpace 2 root or into \data. FreeSpace Open works best if each mod has its own folder. Namely, if a user has the MediaVPs and three mods set up properly, and yours will be the fourth, his FreeSpace 2 folder will look like this:
-FreeSpace 2
--data
--mediavps
--mod1
--mod2
--mod3
--yourmod
where the \yourmod folder will contain all the required VP files for your mod and the mod.ini. The VP file(s) may go into \yourmod\data, too; but the mod.ini must be in \yourmod root. It doesn't matter what you name the folders, the point is that each mod must have its separate folder to prevent file conflicts.

Only the retail VP files can be in FreeSpace 2 root directory. The retail files are:

* root_fs2.vp
* sparky_fs2.vp
* sparky_hi_fs2.vp
* stu_fs2.vp
* tango1_fs2.vp
* tango2_fs2.vp
* tango3_fs2.vp
* warble_fs2.vp
* smarty_fs2.vpIn addition to these .vp files, there are three .vp files that you can have in \freespace2\: FS2OGGcutscenepack.vp, multi-mission-pack.vp and multi-voice-pack.vp. They are not necessary, but they won't cause issues with any mods or retail FS2 itself.
No other .vp files are allowed to be in the root directory. If you do have some redundant VPs in your root or some similarly redundant files in data\, move them somewhere else and see if your mod works fine. Players who download and play your campaign won't have those file there.

Credits
Give credit to all modders whose material you used in your campaign. It doesn't have to be in the release thread, or strictly in the readme.txt, but make it apparent.

Compression
Depending on the number of assets you include in your mod, the total size can vary from a few megabytes to several hundred megabytes. Especially when talking about the latter, it is always good to compress your mod files into an archive. Bandwidth is a precious resource and some people actually have download quotas, so you'll be doing a great service to all the potential players if you reduce the amount of data they have to download. For example, Relentless, which was a partial reason for the creation of this checklist, is 84.4MB in size, but when packed into a .7z file with 7-Zip using the Ultra settings, the resulting file is 33.2MB in size. Less than half of the original. Not bad, eh? I'm sure you can see how this can be beneficial. With larger file sizes, the difference becomes even more apparent. So please, before uploading your mod somewhere, pack it with 7-Zip, WinRAR, Winzip or a similar archive tool.

Checksums
This is not meant as a discouragement, but the harsh reality is that sooner or later, someone will experience problems while running your mod. But not to worry; there are many people at HLP who are always willing to help those in distress. And you can make things easier for those people by delivering the following three things with your mod: checksums for the .vp files, .vp file numbers and MD5 checksums for the .vp files.

Checksums
The non-MD5 checksums can be generated with debug FSO builds. Just run your mod with a debug build (for example, fs2_open_3_6_10d.exe or fs2_open_3_6_12d_INF_RC2.exe) until you get to the pilot selection screen. Then quit the game. There is now a file called fs2_open.log in your \freespace2\data\ folder. You can open the file with any text editor, such as Notepad for example. The checksums will look like the following (taken from Ancient-Shivan War):

--- Code: ---Found root pack 'C:\Games\FreeSpace2\ASW\ASW1.vp' with a checksum of 0x36eb6b27
Found root pack 'C:\Games\FreeSpace2\ASW\ASW1_Animaps.vp' with a checksum of 0x31613271
Found root pack 'C:\Games\FreeSpace2\ASW\ASW1_Normals.vp' with a checksum of 0x09e4b581
Found root pack 'C:\Games\FreeSpace2\ASW\ASW_Interface.vp' with a checksum of 0xd912cb06
Found root pack 'C:\Games\FreeSpace2\ASW\ASW_Intro.vp' with a checksum of 0xd8d071b9
--- End code ---
What's important here is the .vp files in your mod and their checksums. Include those in a text file, such as the readme, and you will make it easier for a lot of people to figure out whether someone might have corrupted files.

.vp file numbers
The .vp file numbers are also generated by debug builds. They can be found right after the checksums and they look like this:

--- Code: ---Searching root pack 'C:\Games\FreeSpace2\ASW\ASW1.vp' ... 1167 files
Searching root pack 'C:\Games\FreeSpace2\ASW\ASW1_Animaps.vp' ... 237 files
Searching root pack 'C:\Games\FreeSpace2\ASW\ASW1_Normals.vp' ... 28 files
Searching root pack 'C:\Games\FreeSpace2\ASW\ASW_Interface.vp' ... 982 files
Searching root pack 'C:\Games\FreeSpace2\ASW\ASW_Intro.vp' ... 1 files
--- End code ---
Side note: Jeff Vader really likes these numbers.
Include these numbers into your mod release as well. They are a really quick way to determine if a person has corrupted files, as corrupted .vp files tend to include less files than they're supposed to.

MD5 checksums
MD5 checksums can be generated with a variety of programs. HashTab was used for BP: AoA. Use it to generate MD5 checksums for the files you are setting up to be downloaded and include them into your release thread (and possibly the readme). The following example checksums were taken from BP: AoA:

--- Code: ---bp-core.7z F607CD762608EDB5B56A7353971E4FCA
bp-core.vp 89EB00CC94F84493C1049D2A80851B72
bp-visuals1.7z 89790df6ea1d55838616e0187f59aad8
bp-visuals1.vp 252d3b80121d2e959be8cc12cfd15555
bp-visuals2.7z 61E74399B150708AABBA82DB7E8DB9A4
bp-visuals2.vp E8EF7B2EDB064047AC59423E2F8B683B
bp-audio1.7z 489120ce0bffae2171d5f0b0ea8680c3
bp-audio1.vp 71bb6bfc84d55d389f4c41bc4299f96c
bp-audio2.7z ed364ae78e7d273cf52bbc649384eb92
bp-audio2.vp dc8527642b50bf0833885f88814da80f
bp-adv-core.7z c845c550a367decd889981654c0d99d1
bp-adv-core.vp 4619c5c5aa1b92667e274217d7c290ba
bp-adv-visuals.7z 9A782A7F540A1DCE10D20E744267DABF
bp-adv-visuals.vp 246ea6ebdd739a9561ff958db1ff48af
--- End code ---
If the player experiences problems, he can generate the MD5 checksums for the files he downloaded on his end and compare them to the ones you generated. If they don't match, the player can quickly deduce that his files got corrupted during download and that he must redownload.
---------------------------

Ideas for further refinement are welcome as well as feedback about the passages I wrote. Post any possible ideas and feedback to the discussion thread.

Updates:
- 2010-06-02: Added stuff about checksums. --Jeff Vader
- 2010-04-11: Added some stuff about packing the files into a zip/rar/7z. --Jeff Vader

Navigation

[0] Message Index