Mod.ini

From FreeSpace Wiki
Revision as of 09:44, 4 January 2016 by Yarn (talk | contribs)
Jump to: navigation, search

The mod.ini documentation from wxLauncher's old Google Code wiki (https://code.google.com/p/wxlauncher/wiki/ModIniOptions) is currently being ported to this page. For the old mod.ini page, see here: mod.ini (old)


This page describes all of the mod.ini options available to mod/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)

windowtitle

windowicon

welcometext

modimage255x112

modimage182x80

iconok

iconwarn

iconwarnbig

iconerror

iconinfo

iconinfobig

iconhelp

iconhelpbig

iconideal

newssource

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