Difference between revisions of "Installing Mods for FS2 Open"

From FreeSpace Wiki
Jump to: navigation, search
(Important note regarding post-MVP 3.6.10: Update regarding the latest MediaVPs)
(30 intermediate revisions by 9 users not shown)
Line 1: Line 1:
 +
==Important Note==
 +
Before 3.7.0, it was recommended to create a new pilot for every campaign that you played. That is, one pilot for the main campaign, one for FSPort, etc. This would in most cases avoid the dreaded pilot file corruption problems that cropped up sometimes. Since FSO version 3.7.0, the pilot file format was completely overhauled and there should no longer be any problems caused by switching mods.
 +
 
== Improvements upon Retail ==
 
== Improvements upon Retail ==
 +
While installing mods for FreeSpace has never been hugely difficult, [[Source Code Project|FS2_Open]] has made considerable improvements to the way that they are handled. Under retail, installing more than one mod involved either installing several copies of FS2 or tiresome dragging and renaming of folders and files. Under FS2_Open, less than a minute's work when installing a mod can mean that you can swap between mods with nothing more than a click of a button.
 +
 +
== Installing the Media VP files ==
 +
To truly take advantage of FS2_Open's modding features, you should install the [[MediaVP|media VP]] files to a subfolder of your FreeSpace 2 folder. Although you can call this folder anything you like, the assumption that will generally be made is that if you have put them in a folder it will be called ''mediavps'', so it is probably best to stick to that. Now that you have put the media VP files in that folder, you must go to the mod tab on the Launcher and select "mediavps" as your mod when running FS2. If you don't do this, FS2 will run with none of the media VPs' features. It will be like playing retail again.
 +
 +
Using the MediaVPs for user-made mods that make use of retail ships is possible. However, standalone mods specifically require you to NOT use the MediaVPs to avoid file conflicts.
 +
 +
==Important note regarding post-MVP 3.6.10==
 +
The official installation instructions for MediaVPs 3.6.12 require you to place each official MediaVP release into its own folder, following the naming scheme "mediavps_3612" where "3612" is evidently the version number (since 2014, the version number has been replaced with the year it released, for example "mediavps_2014" where "2014" is the version year). Since mods that come before this paradigm shift presuppose your MediaVPs are in the "mediavps" folder, you have to open the [[mod.ini]] that comes with the mod and edit it to parse the appropriate "mediavps_3612" folder instead of "mediavps". See below on how to edit the mod.ini.
 +
 +
== Installing a mod ==
 +
Be very wary of what the readmes that come with mods tell you to do. Many mods were written before FS2_Open had these new features or by people only vaguely aware of what they do. For this reason, always remember this:
  
While installing mods for FreeSpace has never been hugely difficult FS2_Open has made considerable improvements to the way that they are handled. Under retail installing more than one mod involved either installing several copies of FS2 or tiresome dragging and renaming of folders and files. Under FS2_Open less than a minutes work when installing a mod can mean that you can swap between mods with nothing more than a click of a button.  
+
'''Do ''NOT'' install anything to Freespace2\data or into the root FreeSpace 2 folder regardless of what the instructions say.'''
  
== Imstalling the Media VP files ==
+
Installing files into Freespace2\data or the root FreeSpace folder is the method used for retail campaigns and very old SCP builds only. This guide is about installing mods for up-to-date FreeSpace Open builds.
  
To truly take advantage of FS2_Open's modding features you should install the media VP files to a subfolder of your Freespace2 folder. Although you can call this folder anything you like the assumption that will generally be made is that if you have put them in a folder it will be called MediaVPs so it is probably best to stick to that. Now that you have put the media VP files in that folder you must go to the mod tab on the launcher and select MediaVPs as your mod when running FS2. If you don't do this FS2 will run with none of the media VPs features. It will be like playing retail again.  
+
If you are following this guide, there is no reason to install files into either of the folders mentioned. Installing a mod to Freespace2\data means that FS2 retail and multiplayer will load the mod and probably break.
  
== Installing the mod ==
+
What you should do is make a separate folder for every mod within your FreeSpace 2 folder. '''If the mod consists completely of VP files, stick them all in a folder within the root FreeSpace 2 directory and you're done with this step.'''
  
Be very wary of what the readmes that come with mods tell you to do. Many mods were written before FS2 or FS2_Open had these new features or by people only vaguely aware of what they do. For this reason I'll give you a golden rule.  
+
If the mod's readme tells you to install to Freespace2\Data, make a new folder called Data within the one you just created and then follow the instructions using this new Data folder as if it were Freespace2\Data (i.e if the readme file instructs you to put a file in Freespace2\data\tables, put it in Freespace2\ModName\data\tables instead).  
  
'''NEVER install anything to Freespace2\Data regardless of what the instructions say'''.
+
'''Run the Launcher, click on MOD tab, select the folder that contains all the mod's files (i.e. not ModName/Data, simply ModName) and you're ready to play.'''
  
If you are following this guide there is no reason to install there (with one exception I'll come to later). Installing to that folder means that FS2 retail and multiplayer will load the mod and probably break. The only exception is if you want the mod to work on multiplayer or retail. For instance if you have downloaded the validated multiplayer missions then there is no harm in placing them there as you want retail multiplayer to be able to access them. However you must take great care when doing this. Any problems you experience later could very easily be due to you installing a retail mod and then forgetting you did it.
+
(Launcher MOD tab is really setting the -mod flag, so you get the command line explained in the next section. For more info about how -mod and MOD Tab work, read [[Command-Line_Reference#-mod]]).
Since FS2_Open will run the vast majority of retail mods you're probably better off simply installing the mod for FS2_Open.  
 
  
What you should do is make a folder within your Freespace2 folder. Make sure that this folder has no spaces and no hyphens (In fact FS2_Open doesn't like it if there is a space anywhere in the path so C:\Program Files\Freespace 2\ModName\ is right out). If the mod consists completely of VP files stick them all in there and you're done with this step.  
+
The last step is only required if you want the mod to be able to access the Media VP files and it doesn't already have a [[mod.ini]].
If the mods readme tell you to install to Freespace2\Data make a new folder called Data within the one you just created and then follow the instuctions using this new Data folder as if it were Freespace2\Data (i.e if told to stick a file in Freespace2\Data\Tables you stick it in Freespace2\ModName\Data\Tables).  
+
<br />This is done by creating a new text file called [[mod.ini]] (be careful that the computer doesn't call it mod.ini.txt). Cut and paste this into the file:
  
The last step is only required if you want the mod to be able to access the media VP files. For most FS2 based mods this will be true. This is done by creating a new text file called mod.ini (be careful that the computer doesn't call it mod.ini.txt). Cut and paste this into the file
+
<pre>[multimod]
 +
SecondaryList = mediavps;</pre>
  
[multimod]<BR>
+
:::'''PLEASE NOTE:'''
secondrylist = ,Media_VPs; <BR>
+
::::Older mods will use "secondrylist" and start the mod list with a leading comma. This is no longer necessary (these were workarounds for bugs that have since been fixed), and thus [[deprecation|deprecated]].
  
Place this file in the mods folder. Run the launcher, click on mod, select the new folder and you're ready to play.
+
Place this file in the mod's folder, then run the game as described above.
 +
Most, if not all, mods should already come with a ready-made mod.ini. If they don't, or if you are unsure how to create one, feel free to bug the mod's creator about it.
  
 
== Alternative method / more info ==  
 
== Alternative method / more info ==  
 +
Alternative method by jr2 (if you don't want to use mod.ini)
 +
 +
Just install the MOD as mentioned above, except skip the part about making a mod.ini file. <br>
 +
Then, in the launcher, under the Features tab, enter the following:<br>
 +
:-mod mod1,mod2,mediavps<br>
 +
where <mod1> is the mod you want to play, <mod2> is the mod that the mod you're playing depends on, and <mediavps> is the name of the folder where you've stuck the Media VP files.<br>
 +
 +
===Example 1===
 +
To run Transcend, if I've installed it to C:\Freespace2\transcend,
 +
and if I've installed Media VPs to C:\Freespace2\mediavps, I'd type:
 +
 +
:-mod transcend,mediavps
 +
 +
into the Features tab.
  
Alternative method by jr2 (if you don't want to use mod.ini)
+
===Example 2===
Just install the MOD as mentioned above, except skip the part about making a mod.ini file.
+
To run the Solar Wars Chapter 1 mod for the Inferno Chapter 1 mod, if I've installed Solar Wars Chapter 1 to
Then, in the launcher, under the Features tab, enter the following:
 
-mod mod1,mod2,Media_VPs
 
where <mod1> is the mod you want to play, <mod2> is the mod that the mod you're playing depends on, and <Media_VPs> is the name of the folder where you've stuck the Media VP files.
 
For example:
 
  
a) to run Transcend if I've installed it to \<whatever_directory_tree_freespace_is_in>\Transcend
+
:C:\Freespace2\solar_wars_ch1
and if I've installed Media VPs to \<whatever_directory_tree_freespace_is_in>\Media_VPs , I'd type:
 
-mod Transcend,Media_VPs
 
into the Features tab
 
  
b) to run the Solar Wars Chapter 1 mod for the Inferno Chapter 1 mod if I've installed Solar Wars Ch 1 to \<whatever_directory_tree_freespace_is_in>\Solar_Wars_Ch1
 
 
and if I've installed Inferno Chapter 1 to
 
and if I've installed Inferno Chapter 1 to
\<whatever_directory_tree_freespace_is_in>\INFR1
+
 
 +
:C:\Freespace2\infr1
 +
 
 
and if I've installed the Media VPs to
 
and if I've installed the Media VPs to
\<whatever_directory_tree_freespace_is_in>\Media_VPs
+
 
 +
:C:\Freespace2\mediavps
 +
 
 
I'd type:
 
I'd type:
-mod Solar_Wars_Ch1,INFR1,Media_VPs
 
  
Basically, (remember, -mod mod1,mod2,Media_VPs) FS2 SCP looks for the files it needs in <mod1>, if they are there, then it uses them, if not, it looks in <mod2>, if not there, <Media_VPs>, if not there, then the main FS2 directory.  If there are more than one version of the file it needs, then it will use the one that it finds first, in the order that it looks for them, as seen above.
+
:-mod solar_wars_ch1,infr1,mediavps
 +
 
 +
 
 +
Basically, (remember, -mod mod1,mod2,mediavps) FS2_Open looks for the files it needs in <mod1>, if they are there, then it uses them, if not, it looks in <mod2>, if not there, <mediavps>, if not there, then the main FS2 directory.  If there are more than one version of the file it needs, then it will use the one that it finds first, in the order that it looks for them, as seen above.
 +
 
 +
This also applies to Fred2 Open, as it loads mods with the -mod parameter like FreeSpace2 Open does.
 +
 
 +
Also, you could use the mod.ini method so that mediavps is automatically appended to the list and you'd only have to type <mod1>,<mod2> in.
 +
 
  
Also, you could use the mod.ini method so that Media_VPs is automatically appended to the list and you'd only have to type <mod1>,<mod2> in.
+
[[Category:Source Code Project]]
 +
[[Category:User-made Campaigns|*]]
 +
[[Category:Tutorials|Mods, installing for FS2 Open]]

Revision as of 05:14, 27 January 2015

Important Note

Before 3.7.0, it was recommended to create a new pilot for every campaign that you played. That is, one pilot for the main campaign, one for FSPort, etc. This would in most cases avoid the dreaded pilot file corruption problems that cropped up sometimes. Since FSO version 3.7.0, the pilot file format was completely overhauled and there should no longer be any problems caused by switching mods.

Improvements upon Retail

While installing mods for FreeSpace has never been hugely difficult, FS2_Open has made considerable improvements to the way that they are handled. Under retail, installing more than one mod involved either installing several copies of FS2 or tiresome dragging and renaming of folders and files. Under FS2_Open, less than a minute's work when installing a mod can mean that you can swap between mods with nothing more than a click of a button.

Installing the Media VP files

To truly take advantage of FS2_Open's modding features, you should install the media VP files to a subfolder of your FreeSpace 2 folder. Although you can call this folder anything you like, the assumption that will generally be made is that if you have put them in a folder it will be called mediavps, so it is probably best to stick to that. Now that you have put the media VP files in that folder, you must go to the mod tab on the Launcher and select "mediavps" as your mod when running FS2. If you don't do this, FS2 will run with none of the media VPs' features. It will be like playing retail again.

Using the MediaVPs for user-made mods that make use of retail ships is possible. However, standalone mods specifically require you to NOT use the MediaVPs to avoid file conflicts.

Important note regarding post-MVP 3.6.10

The official installation instructions for MediaVPs 3.6.12 require you to place each official MediaVP release into its own folder, following the naming scheme "mediavps_3612" where "3612" is evidently the version number (since 2014, the version number has been replaced with the year it released, for example "mediavps_2014" where "2014" is the version year). Since mods that come before this paradigm shift presuppose your MediaVPs are in the "mediavps" folder, you have to open the mod.ini that comes with the mod and edit it to parse the appropriate "mediavps_3612" folder instead of "mediavps". See below on how to edit the mod.ini.

Installing a mod

Be very wary of what the readmes that come with mods tell you to do. Many mods were written before FS2_Open had these new features or by people only vaguely aware of what they do. For this reason, always remember this:

Do NOT install anything to Freespace2\data or into the root FreeSpace 2 folder regardless of what the instructions say.

Installing files into Freespace2\data or the root FreeSpace folder is the method used for retail campaigns and very old SCP builds only. This guide is about installing mods for up-to-date FreeSpace Open builds.

If you are following this guide, there is no reason to install files into either of the folders mentioned. Installing a mod to Freespace2\data means that FS2 retail and multiplayer will load the mod and probably break.

What you should do is make a separate folder for every mod within your FreeSpace 2 folder. If the mod consists completely of VP files, stick them all in a folder within the root FreeSpace 2 directory and you're done with this step.

If the mod's readme tells you to install to Freespace2\Data, make a new folder called Data within the one you just created and then follow the instructions using this new Data folder as if it were Freespace2\Data (i.e if the readme file instructs you to put a file in Freespace2\data\tables, put it in Freespace2\ModName\data\tables instead).

Run the Launcher, click on MOD tab, select the folder that contains all the mod's files (i.e. not ModName/Data, simply ModName) and you're ready to play.

(Launcher MOD tab is really setting the -mod flag, so you get the command line explained in the next section. For more info about how -mod and MOD Tab work, read Command-Line_Reference#-mod).

The last step is only required if you want the mod to be able to access the Media VP files and it doesn't already have a mod.ini.
This is done by creating a new text file called mod.ini (be careful that the computer doesn't call it mod.ini.txt). Cut and paste this into the file:

[multimod]
SecondaryList = mediavps;
PLEASE NOTE:
Older mods will use "secondrylist" and start the mod list with a leading comma. This is no longer necessary (these were workarounds for bugs that have since been fixed), and thus deprecated.

Place this file in the mod's folder, then run the game as described above. Most, if not all, mods should already come with a ready-made mod.ini. If they don't, or if you are unsure how to create one, feel free to bug the mod's creator about it.

Alternative method / more info

Alternative method by jr2 (if you don't want to use mod.ini)

Just install the MOD as mentioned above, except skip the part about making a mod.ini file.
Then, in the launcher, under the Features tab, enter the following:

-mod mod1,mod2,mediavps

where <mod1> is the mod you want to play, <mod2> is the mod that the mod you're playing depends on, and <mediavps> is the name of the folder where you've stuck the Media VP files.

Example 1

To run Transcend, if I've installed it to C:\Freespace2\transcend, and if I've installed Media VPs to C:\Freespace2\mediavps, I'd type:

-mod transcend,mediavps

into the Features tab.

Example 2

To run the Solar Wars Chapter 1 mod for the Inferno Chapter 1 mod, if I've installed Solar Wars Chapter 1 to

C:\Freespace2\solar_wars_ch1

and if I've installed Inferno Chapter 1 to

C:\Freespace2\infr1

and if I've installed the Media VPs to

C:\Freespace2\mediavps

I'd type:

-mod solar_wars_ch1,infr1,mediavps


Basically, (remember, -mod mod1,mod2,mediavps) FS2_Open looks for the files it needs in <mod1>, if they are there, then it uses them, if not, it looks in <mod2>, if not there, <mediavps>, if not there, then the main FS2 directory. If there are more than one version of the file it needs, then it will use the one that it finds first, in the order that it looks for them, as seen above.

This also applies to Fred2 Open, as it loads mods with the -mod parameter like FreeSpace2 Open does.

Also, you could use the mod.ini method so that mediavps is automatically appended to the list and you'd only have to type <mod1>,<mod2> in.