mod_info.lua documentation

Mods

All mods must be in subdirectories somewhere under /mods (Unless they are special, frontend mods, see description of mountpoints). Each mod has a mod_info.lua file which contains various bits of info:

name = "Happy mod"                          # Name to use for this mod
version = 123                               # Version number to use for this mod
copyright = "Copyright © 2006, Someone"     # Optional copyright info
description = "A long description of happy mod and why it will make you happy"
author = "Joe"                              # Optional author info
url = "http://www.gaspoweredgames.com"      # Optional URL to anywhere author likes

source = "https://github.com/FAForever/fa.git@master"
    Optional (But recommended) URL that points to a URL where the latest version
    of the mod is available. The @ segment in the URI reflects the ref to use.
    If omitted, will default to the default branch of the remote repository.

    The schemes: "https://" and "git+https://" are the only currently supported schemes
    currently.

uid = B019FBEE-E411-11DB-AFAE-13D355D89593 
    Uniquely identify this mod. This defaults to the mods name, but that's
    not a very safe way to keep mods differentiated. I'd recommend using a GUID
    or Guaranteed Unique ID. Also, every new version of a mod should get a new
    GUID so that mods which rely on the old version can select it appropriately.
    This following webpages allow you to generate a guaranteed unique ID on line (as of 4/6/07)
    http://www.somacon.com/p113.php
    http://www.famkruithof.net/uuid/uuidgen

selectable = true
    Flag for whether to list this mod in the mod manager window, where the
    player can select it. Examples where you would set it to false are:

    1.  A mod containing just custom maps, along with textures and props used
        on those maps. The mod will be automatically enabled when one of its
        maps is used.

    2.  A mod supplying textures and props for use by other mods. Those mods
        indicate that they require this one, and it is automatically enabled
        when they are.

enabled = true
    Setting enabled to false causes a mod to never be loaded. Provides
    an easy way to disable a mod during development. The default is true.

exclusive = false
    A simple form of preventing conflicting mods. Only one 'exclusive' mod
    can be active at a time. The default is false. Note that this precludes
    the use of requires/conflicts

ui_only = false
    Set true to indicate that this mod only affects the user interface. If
    this flag is false (the default), all players in a multiplayer game must
    have it in order for anyone to use it. If true, one player can have it
    active independently of the other players. (Games on GPGNet may restrict
    this further.)

    TODO: If ui_only is set true, the mod's files should not even be accessible
    from within the sim, but we need the VFS stuff implemented properly first.

icon = "mod_icon.dds"
    Name of icon to use for this mod in the mod selection window. The default is
    mod_icon.dds in the same directory as the mod_info.lua file.

requires = {
    # Optionally indicates that this mod only works if another mod is also present.
    # It might be nice if you add a comment after each uid to denote the name of the mod
    # so mere mortals can maintain your list :)
    "fec58b30-0036-4b9e-9995-fe2d6fe4c6e9",     -- Chris' Whacky Mod
    "18e391bc-67aa-49fb-8a5f-34efec2d1c2c",     -- Jeffs Cool Mod
    "61d2cb50-08ac-46ba-b261-3c3e3372aef0",     -- Teds Dumb Mod
}

conflicts = {
    Indicate any other mods that this mod is known to conflict with; the game
    will refuse to enable both of them at the same time.
    Same format as 'requires'.
}

before = {
    List of other mod names. If this mod happens to be active at the same time
    as any of the named other mods, it will be applied before them.
    Same format as 'requires'.
}

after = {
    List of other mod names. If this mod happens to be active at the same time
    as any of the named other mods, it will be applied after them. If you do
    not supply an 'after' list, the 'requires' list will be used in its place.
    Same format as 'requires'.
}

requiresNames = {
    # an optional table which will map the required uids to friendly names so the user of the mod can determine what they are missing
    ["fec58b30-0036-4b9e-9995-fe2d6fe4c6e9"] = "Chris' Whacky Mod v123",
    ["18e391bc-67aa-49fb-8a5f-34efec2d1c2c"] = "Jeff's Cool Mod",
    ["61d2cb50-08ac-46ba-b261-3c3e3372aef0"] = "Ted's Dumb Mod",
}

mountpoints = {
    A table of subdirectories in the mod to map to the VFS, e.g.:
    ENV = "/env"
    means to map "mod-dir/ENV" to the virtual path "/env", potentially shadowing everything
    that is normally in that directory.

    Having this key implies 'selectable' = false. It defaults to:
    
    {'.'='/mods/mod_name/'}.
}

Fields 'id' and 'location' also get filled in during initialization, to the full path to the mod_info file and the directory containing it.

Adding extra maps

Any extra maps in a mod will automatically show up on the available maps list on the single- and multi-player skirmish screen, as long as they have an appropriate Configuration set up.

If you select a map from a mod for play, that mod (and any other mods it depends on) will automatically be active for that session. This allows you to define custom units or props just for a particular set of maps.

Adding custom units

If an active mod has any .bp files defining units, they will be automatically included during blueprint loading.

If a mod contains a blueprint matching the ID of an existing unit (e.g. uel0001) then the mod's blueprint will replace the original. If the "Merge=true" flag is set in the mod blueprint, it will be merged with the original can can override some fields while leaving others intact.

Balance changes

There are two ways to make large-scale balance changes.

First, you can define one or more .bp files with "Merge=true", that override particular fields for many units. This is how the campaign balance mod works.

Second, you can define a function , which is called on each blueprint as it is loaded. This function can then manipulate the blueprint in arbitrary ways.

First, a mod can simply add a new blueprint file that defines a new blueprint.

Second, a mod can contain a blueprint with the same ID as an existing blueprint. In this case it will completely override the original blueprint. Note that in order to replace an original non-unit blueprint, the mod must set the "BlueprintId" field to name the blueprint to be replaced. Otherwise the BlueprintId is defaulted off the source file name. (Units don't have this problem because the BlueprintId is shortened and doesn't include the original path).

Finally, a mod can define a ModBlueprints() function which manipulates the original_blueprints table in arbitrary ways. [How/when exactly is this done?]

Custom skins

A mod can add a ??? file to indicate that it contains a custom skin. The skin will automatically be made available on the list of available skins. TODO: need help from CBlackwell to work out and document custom skin system.

Other changes

A mod can contain a 'shadow' folder, which contains files matching the names and directory structure of the game's top-level folder. These files will REPLACE the game's files on all lookups. You can use this mechanism to replace entire textures, audio files, scripts, blueprints, or any other game data. Note that when a game file is shadowed, the original file becomes completely inaccessible. This is ok for textures and such but usually not what you want for scripts.

A mod can also contain a 'hook' folder, which contains files named the same way, matching the structure of the game's main data folder. After any script file is loaded, we check in the active mods to see if they define a hook of the same name; if so, we run the hook in the same environment as the original script. This allows hooks to tweak or replace individual functions, classes, or other data while still using the original code.

Mod ordering

It often matters in what order mods take effect. For example, perhaps two mods both adjust the tuning of some units, and they have a few in common. The mod that is applied last will take precedence.

By default, mods are applied in simple alphabetical order. However, you can get more control by listing other mods in the 'before' and 'after' sections.

If two mods specify an inconsistent ordering (e.g. they both ask to be before the other), SC will choose an arbitrary ordering and log a warning, but both mods will still be active.

Mod initialization issues

There are three general sorts of mods:
    Front end mods    [mountpoints flag set]
    Ingame UI mods    [ui_only flag set]
    Game mods         [all others]

The mod manager (whether run from the front end or from the lobby) loads this module
to get a list of all mods in the system, so the user can select and deselect mods.
Those changes are stored in the player's preferences.

When launching a game, the lobby scripts call this module to get the list of active
Game mods to pass into the simulation (in gameinfo.Options.Mods). The simulation just
uses whatever list it was given.

The ingame UI calls this module to get a list of ingame UI mods to apply directly from
preferences.