Mod.ini

(Copied from the mod.ini documentation on wxLauncher's old Google Code wiki (https://code.google.com/p/wxlauncher/wiki/ModIniOptions) with modifications)

This page describes all of the mod.ini options available to mod/total conversion (TC) authors. Most options are available to both mods and TCs, with the exception that the skin feature is available to TCs only.

Introduction

First, take a look at the complete mod.ini sample to get a sense of the new mod.ini format's capabilities.

About the old format, there are two important points:

• ALL of the mod.ini settings are OPTIONAL. The only requirement is that the mod.ini file must be present, even if it is blank.
• This format is 100% compatible with the old mod.ini format. Therefore, you can use your existing mod without any changes, as long as the mod has a mod.ini file in its mod folder.

General notes

There are several details that should be considered when creating a mod.ini:

• Resource files specified in the mod.ini do not have to be placed in the same folder as the mod.ini itself. They can be in a subfolder instead. Thus you can have a "resources" subfolder in your mod and place all the files there so that they don't clutter your main folder. Separate folders must be specified in the mod.ini using a forward slash (/), as in resources/my_image.png.
• You can add comments to your file by starting lines with a # character. Those lines will be ignored by the launcher when it reads your mod.ini.
• No labels should be left without a value. In other words, all lines in the mod.ini that are not comments or section headers (such as [launcher]) should follow the format label = value.
• Edit your file with a syntax-highlighting capable text editor, such as Notepad++ (Windows), TextWrangler or Aquamacs (OS X), or Scintilla or Gvim/Vim (Linux).

Common sense (aka TLDR)

As noted before, all of the options in the mod.ini are optional. However, as a courtesy for the players, you should include at the very least:

• Mod name (modname)
• Your name (author)
• Mod description (infotext)
• If your mod depends on any mods, list those (secondarylist)

To make things easy, you can copy this basic mod.ini file, fill it in, and include it with your mod. It asks for exactly these pieces of information.

Sections

This guide follows the mod.ini sections in the order they appear in the sample mod.ini. To make the examples fit better, long lines are abbreviated using ellipses (...).

As stated in the sample mod.ini, this example deals with a fictional mod named "The Descent" for The Babylon Project.

[launcher]

[launcher]
modname        = The Descent
image255x112   = skin/logo.png
image182x80    = skin/logo_small.png
infotext       = The aging behemoth was floating in silence ... towards Earth.
author         = kkmic
notes          = You'll need the zathras mod to play this
warn           = 1
website        = http://www.thedescentmod.com
forum          = http://www.forum.thedescentmod.com
bugs           = http://www.bugs.thedescentmod.com
support        = http://www.support.thedescentmod.com

This section is an expanded version of the old mod.ini. It allows you to define basic details about your mod.

modname

Your "fancy" mod name. There is no length limit, although you should keep it below 50 characters, including spaces. This is the name that will appear in the launcher to identify your mod to the player.

image255x112

The image that defines your mod. Must be 255x112 pixels. Although you can use any of BMP, PNG, or GIF formats, you should use BMP if you want to keep your mod compatible with the Windows launcher. If you don't specify an image, the current skin's modimage255x112 will be used instead.

image182x80

The image that is shown on the mod list. Use it if you don't like the way the launcher shrinks your big image or if you want to emphasize some detail from it. Try not to confuse the user with two totally different images, though.

infotext

Introductory text for your mod. Summary. Teaser. Use your imagination.

Note: All of the text must be written on a single line in the mod.ini file. However, if you want to have a line break in the text (that is, text on a new line) write "\n" (without the quotes) -- see the sample for an example. Also note that the Windows launcher does not support this and will just print the "\n" as they are.

author

Your name. Or your team's name. People who play your mod should know whose hard work gives them joy. Or an agonizing death. Depending on your modding skills.

notes

Notes regarding your mod. Technical details. Acknowledgements. You name them. Again, must be one line. See infotext for details.

warn

Give this a value of 1 (a one, not a lowercase L) if your notes are of critical importance to the player.

The effect: a warning sign appears besides your mod once selected and also in the mod detail window beside the note itself.

website

Your mod's mighty homepage.

forum

A link to a dedicated forum/forum section for your mod. If not specified, the Missions and Campaigns forum is used.

bugs

This is where the players should report bugs in your mod. Might be a dedicated bug tracker or a simple forum/forum section.

support

A link to the forum/forum section for support of your mod.

[resolution]

[resolution]
minhorizontalres = 1024
minverticalres   = 768

This section allows you to specify a minimum resolution for your mod. All resolutions smaller than the one you specify will not appear in the Basic Settings page's "Resolution" drop down box. This section is useful in cases such as when your mod doesn't have low-res interface art.

Caution: Be extra-careful with typos when using this section. If you accidentally specify a super-high resolution (say, 1024x7680), then players will be unable to play your mod.

minhorizontalres

The minimum horizontal resolution supported by your mod. Default value is 640.

minverticalres

The minimum vertical resolution supported by your mod. Default value is 480.

[multimod]

[multimod]
primarylist  = ;
secondarylist = zathras;

This section lists additional mods that need to be loaded for your mod to work properly.

primarylist/secondarylist

Contains mods listed by their folder name.

The mods listed in these values will be added to the -mod command line option for the FS2 Open engine and FRED2 Open editor.

To construct the -mod option, the the current mod's folder name is appended to the mods in the primary mod list, which then has the secondary mod list appended to it, resulting in primarylist, folder name, secondarylist.

Note: secondrylist can be used in place of secondarylist because of a bug in the original Windows launcher. However, it is deprecated and should not be used. It is provided for compatibility purposes only.

[recommendedlighting]

[recommendedlighting]
name = Descent recommended
flagset = -ambient_factor 75 ... -ogl_spec 60

This section allows you to provide a recommended selection of lighting settings for the player. This will replace the "Baseline recommended" entry in the lighting presets GUI. These settings are not graphics settings. They are just the knobs for adjusting the level of ambient light, how shiny ships are, and the like.

name

The name that wxLauncher will use to label these settings in the GUI. Limited to 32 characters.

flagset

The flags to be set.

[skin] (TCs only)

[skin]
windowtitle = Astrid CIC
windowicon = skin/astrid.png 
banner = skin/welcome_page_banner.png
welcometext = <p><b>Welcome to wxLauncher ... </p>
modimage255x112 = skin/modimage.png 
modimage182x80 = skin/modimage_small.png
iconok = skin/icon_ok.png
iconwarn = skin/icon_warn.png
iconwarnbig = skin/icon_warn_big.png
iconerror = skin/icon_error.png
iconinfo = skin/icon_info.png
iconinfobig = skin/icon_info_big.png
iconhelp = skin/icon_help.png
iconhelpbig = skin/icon_help_big.png
iconideal = skin/icon_ideal.png
newssource = hlp

The skin section is where you can change the launcher's appearance. You can alter several visual elements (window title bar text, window icon, etc) without having to distribute a custom-built launcher. You can also choose to specify only part of the skin. Any parts that you don't specify will be provided by the default launcher skin. Only TCs can skin the launcher.

windowtitle

The text in the title bar of the launcher window. Use only letters and numbers if possible. There is no official character limit, but keep the text to a reasonable size. Since this is a window title bar, all formatting will be ignored.

windowicon

Launcher's window icon. Must be in Windows icon (ICO) format. Note: Skinning the window icon is currently not supported on OS X.

banner

The welcome page banner. Must be in PNG format. Recommended size is 600x150, with maximum width of 630 pixels and required height of 150 pixels. Will be centered in the welcome page.

welcometext

The text found on the welcome page. Can contain basic HTML tags (such as <b><br><ul<<p><a><ol><u><i><emphasis><strong>) -- see the wxWidgets wiki for a complete list.

modimage255x112

The image that is shown in the mod info dialog when a particular mod doesn't have an image defined. Must have the same resolution as the ordinary mod image (255x112).

modimage182x80

The image that is shown in the mod list when a particular mod doesn't have an image defined. Must have the same resolution as the mod list-sized image (182x80). If this image is not provided, it will be generated automatically by scaling down the modimage255x112 image, if it is provided.

iconok

Icon used in the status bar to indicate that a operation (like news retrieval) succeeded. Must be in PNG format. Must be 24x24 pixels in size.

iconwarn

Icon used in the status bar to indicate that a non-critical operation (like news retrieval) failed. Must be in PNG format. Must be 24x24 pixels in size.

iconwarnbig

Icon used in the modinfo window to indicate that the note specified by the mod author is important and must be read. Must be in PNG format. Must be 64x64 pixels in size.

iconerror

Icon used in the status bar to indicate that a critical operation (like launching the game) failed. Must be in PNG format. Must be 24x24 pixels in size.

iconinfo

Icon used in the status bar to indicate various miscellaneous details. Must be in PNG format. Must be 24x24 pixels in size.

iconinfobig

Icon used in the mods page to bring attention to information there. Must be in PNG format. Must be 64x64 pixels in size.

iconhelp

Icon used when asking the player for network access for retrieving the news. Must be in PNG format. Must be 32x32 pixels in size.

iconhelpbig

Icon used when asking the player for network access for retrieving the news. Must be in PNG format. Must be 64x64 pixels in size.

iconideal

Icon that is currently not used but may eventually be used to mark recommended flags. Must be in PNG format. Must be 24x24 pixels in size.

newssource

The name of the source that wxLauncher should get its news from. Current supported values are hlp and diaspora, with unrecognized values resulting in the default value hlp being selected. More values will be added as more TCs ship with wxLauncher.

Samples

Basic mod.ini sample

# Just replace the text in <> with information about your mod
# and then put the file in your mod folder.
# For more things you can do with a mod.ini file, see
# <http://www.hard-light.net/wiki/index.php/Mod.ini>

[launcher]
modname  = <NameOfYourMod>
infotext = <Describe your mod. You can use \n to add line breaks.>
author   = <YourName>

# If your mod requires other mods to run, include this section,
# otherwise remove it.
[multimod]
secondarylist = <ModDependency1>,<ModDependency2>,<etc.>

Complete mod.ini sample

# This is a fully-fledged mod.ini sample using ALL of the options
# available to mod/TC authors. Please visit the mod.ini wiki page
# to learn about what different options do:
# <http://www.hard-light.net/wiki/index.php/Mod.ini>
# 
# This sample was created for a fictional mod named "The Descent"
# for the Babylon Project total conversion.

[launcher]
modname        = The Descent
image255x112   = skin/logo.png
image182x80    = skin/logo_small.png
infotext       = The aging behemoth was floating in silence among the stars. An eternity has passed, and the Astrid was still sleeping in the coldness of space. Without warning, her forward thrusters fired with an eerie glow, sending vibrations throughout the ship. Metal screamed in protest, as more thrusters fired, shaking the solar dust of the hull. \n\nThen it was silence again. \n\nNothing appeared to have changed, yet slowly but surely, the destroyer had begun its descent towards Earth.
author         = kkmic
notes          = You will need the zathras mod to play this
warn           = 1
website        = http://www.thedescentmod.com
forum          = http://www.forum.thedescentmod.com
bugs           = http://www.bugs.thedescentmod.com
support        = http://www.support.thedescentmod.com

[resolution]
minhorizontalres = 1024
minverticalres   = 768

[recommendedlighting]
name    = Descent recommended
flagset = -ambient_factor 90 -spec_exp 0.7 -spec_tube 1.0 -spec_point 0.7 -spec_static 1.0 -ogl_spec 15 -bloom_intensity 20

[multimod]
primarylist  = ;
secondarylist = zathras;

[skin]
windowtitle = Astrid CIC
windowicon = skin/astrid.png 
banner = skin/welcome_page_banner.png
welcometext = <p><center><b><font size='3'>Welcome to wxLauncher, your one-stop-shop for Freespace 2 and related content</font></b><br><br>If you're new to the Freespace 2 universe, you might want to check out these links first:<br> = <a href='http://www.hard-light.net/wiki/index.php/Main_Page'>FS2 Wiki</a>  = <a href='http://www.hard-light.net/forums/'>FS2 Forum</a> = <a href='http://en.wikipedia.org/wiki/FreeSpace_2'>Wikipedia FS2 page</a> = <a href='http://scp.indiegames.us/mantis/main_page.php'> Reporting bugs</a> =<br><br>Also, don't  forget the help file, there is a nice 'Getting Started' tutorial there.<br></center></p>
modimage255x112 = skin/modimage.png 
modimage182x80 = skin/modimage_small.png
iconok = skin/icon_ok.png
iconwarn = skin/icon_warn.png
iconwarnbig = skin/icon_warn_big.png
iconerror = skin/icon_error.png
iconinfo = skin/icon_info.png
iconinfobig = skin/icon_info_big.png
iconhelp = skin/icon_help.png
iconhelpbig = skin/icon_help_big.png
iconideal = skin/icon_ideal.png
newssource = hlp

KnossosNET Support

Knossos.NET can load mod.ini files if the mod.json is not present in the folder, the keys that KnossosNET can use are these ones:

[launcher]
modname (defaults to folder name if not present)
image255x112
image182x80 (used if image255x112 is not present)
infotext
forum
notes

[multimod]
primarylist
secondarylist
secondrylist

Line terminators (;) arent needed, and will be ignored if they are present.

There is limited support for primarylist, secondarylist... Only mediavps, fsport and fsport-mediavps will be detected on those lists, and if they do they are added to the mod dependency list set to always use the newerest version. Nevertheless, custom dependencies can be used in launcher to add/remove them or set a version. A FSO dependency set to the never version will also be added.

New section and values

All the new values are added to a new section for easy reference, their function is similar or identical to the json equivalents.

[mod]
id
version
type
parent
tile
banner
dependencylist
cmdline

id

Defines the mod unique id, defaults to folder name if not set

version

Mod semantic version, defaults to 1.0.0-<foldername> if not set

type

Mod type: tc or mod (default: mod)

parent

Only used if type = mod, defaults to parent folder name if not set

tile

The 150x225 tile image, image255x112 or image182x80 is used if not present

banner

1070x300 banner image, image255x112 or image182x80 is used if not present

dependencylist

This is a mod.ini format of setting mod dependencies, primarylist/secondary used if not set. It is a list of modid|version (optional) separated by comas. If version is not defined the newerest version is used. Example:

dependencylist = MVPS|3.6.12,FSO|23.2.0-RC1,CP_m

This adds mediavps version 3.6.12, FSO version 32.2.0-RC1 and CP_m with the newerest version to the mod dependency list.

cmdline

a optional mod cmdline to pass to fso

Complete KnossosNET mod.ini Example

Compatible with old launchers and KnossosNET

[launcher]
modname      = Shadow Genesis;
image255x112 = ShadowGenesis.bmp;
image182x80  = ShadowGenesisSmall.bmp;
infotext     = It is the year 2390. Lieutenant Nathan Miles begins duty in the 6th Terran Fleet, commonly know as the Wolf's Fleet. This fleet, having mostly autonomical command structure, is responsible for safety of strategic Alliance systems - the Wolf's Group, intensively colonized sector where multiple Ancient ruins have been found. Human- and Vasudankind are protected by their powerful navy, but despite that, times are not easy. Mysterious terrorist organization called Cerberus Legacy is rapidly spreading its influence in the GTVA, and their leaders are preparing an intrigue that may lead the Wolf's Group on the brink of destruction...;
forum        = http://www.freespace.pl/forum/viewtopic.php?t=5534;
notes        = This is a legacy mod;

[multimod]
primarylist  = ;
secondrylist = Shadow Genesis,mediavps_3612;

[mod]
id             = sg_legacy
version        = 1.0.0-Legacy
type	       = mod
parent	       = FS2
tile           = kn_tile.png
banner         = kn_banner.png
dependencylist = MVPS|3.6.12,FSO|23.2.0-RC1,CP_m
cmdline        = -fps -light 0.8 -ambient 0.9

See also

Old mod.ini documentation