Structure and elements

Mod, Properties, Dependencies, References, and ActionCriteria.

Structure of a .modinfo file

Mod

The root element in a .modinfo file is always the <Mod> element. It should have the following attributes:

• id

  • The id is an identifier used to distinguish mods. It must be unique to distinguish it from other mods.

    It’s recommended that the id be composed solely of ASCII characters and be less than 64 characters. It’s also recommended to use solely lower case letters, and to use dashes instead of underscores or spaces.

    It’s also good practice to adopt a developer prefix (an informal identifier for yourself, something like fxs, suk, lime) for all your mods. So instead of giving your mod the id my-cool-mod, you’d give it the id fxs-my-cool-mod to ensure your mod id is completely unique.

• version
  • The version number for the mod.
• xmlns
  • The XML namespace. This should always be set to ModInfo.

Properties

The Properties element contains much of the additional information about the mod. It consists of the following child elements. All these elements are technically optional, but at minimum, you should include Name, Description, and Author.

• Name
  • The name of the mod. If this element is left empty, the mod will not show up in the Add-Ons screen, though the game can still load it.
• Description
  • A brief description of what the mod does. It will be displayed in the Add-Ons screen.
• Authors
  • The name of the author(s).
• AffectsSavedGames

  • Determines whether the mod affects existing saved games.

    Mods with this element set to 1 cannot be removed or added to games that are already in progress. Mods that affect the Gameplay database should have this set to 1.

    Mod with this element set to 0 can be added or removed at any time. This is usually for mods that ONLY affect the game’s UI and/or Localization database.

    Set to 1 or 0. If this element is excluded, it defaults to 1.

• Package
  • This field is not currently used by the game’s UI. It would allow for mods with the same package value to be grouped together.
• PackageSortIndex
  • This field is not currently used by the game’s UI. It would determines the order in which mods are shown in the browser.
• ShowInBrowser
  • Determines whether the mod should be shown on the Add-Ons screen. Set to 1 or 0. If this element is excluded, it defaults to 1.
• EnabledByDefault
  • Determines if the mod is enabled by default if it has not been enabled/disabled in the game previously. Set to 1 or 0. If this element is excluded, it defaults to 1.

Dependencies

The Dependencies element consists of a list of Mod child elements. This mod will have those mods as dependencies. This means those mods will need to be activated for this mod to be activated. Additionally, those mods will be loaded before this mod.

Each child Mod element should have the following attributes:

• id
  • This is the id of the mod that this mod will reference. This should match the mod id in the Mod root element of that mod’s .modinfo file
• title
  • This is the name of the mod that this mod will reference on. This should match the Name in the Properties element of that mod’s .modinfo file

<Dependencies>
    <Mod id="fxs-new-policies" title="LOC_MODULE_ANTIQUITY_POLICIES_NAME"/>
 </Dependencies>

A mod can have as many or as few dependencies as it needs. Additionally, all mods have the following modules as dependencies by default:

• core
• base-standard
• age-antiquity
• age-exploration
• age-modern

References

The References element consists of a list of Mod child elements. This mod will have those mod as references. This means those mods will be loaded before this mod.

Each child Mod element should have the following attributes:

• id
  • This is the id of the mod that this mod will depend on. This should match the mod id in the Mod root element of that mod’s .modinfo file
• title
  • This is the name of the mod that this mod will depend on. This should match the Name in the Properties element of that mod’s .modinfo file

<References>
    <Mod id="friedrich-xerxes-alt" title="LOC_MODULE_FRIEDRICH_XERXES_ALT_NAME"/>
 </References>

ActionCriteria

The ActionCriteria element consists of Criteria child elements.

Criteria are a set of conditions that need to be met for a mod to execute an ActionGroup (see the ActionGroups section of this document).

Each criteria must have an id property. The id must be unique on a per mod basis. So a single mod should not have multiple criteria with the same id; but it may have an id that matches a criteria in another mod without conflict.

    <ActionCriteria>
        <Criteria id="antiquity-age-current">
            <AgeInUse>AGE_ANTIQUITY</AgeInUse>
        </Criteria>
        <Criteria id="not-antiquity-age">
            <AgeInUse inverse="1">AGE_ANTIQUITY</AgeInUse>
        </Criteria>
        <Criteria id="always">
            <AlwaysMet></AlwaysMet>
        </Criteria>
        <Criteria id="mod-active" any="true">
            <ModInUse>shawnee-tecumseh`</ModInUse>
            <ModInUse>fxs-norman-rework</ModInUse>
            <ModInUse>leu-more-llamas</ModInUse>
        </Criteria>
    </ActionCriteria>

By default, all conditions in a Criteria element must be met for an Action with that criteria to activate. You can add an any="true" property to the criteria and it will instead be met if any of the conditions are met.

There are several types of conditions/criterion you can use:

AlwaysMet

As the name states, this criterion is always met. ActionGroups that you always want active, should be assigned a Criteria with this criterion.

NeverMet

As the name states, this criterion is never met.

AgeInUse

This criterion is met when the game age matches the provided age. This should be one of AGE_ANTIQUITY, AGE_EXPLORATION, AGE_MODERN. Mods may add new Ages that can be used here as well.

AgeWasUsed

This criterion checks whether the provided age was previously played. It does not account for the current age. So if the provided value is AGE_EXPLORATION and you are currently playing in the Exploration Age, the criterion will not be met.

Additionally, Advanced Starts do not count towards this criterion. An Exploration Era Advanced Start will NOT trigger an AgeWasUsed condition set to AGE_ANTIQUITY.

AgeEverInUse

A combination of AgeInUse and AgeWasUsed. Checks whether the provided Age matches either the current Age, or a previously played Age.

ConfigurationValueMatches

Checks if a game configuration parameter matches the provided values. This criterion needs three separate values:

• Group, this should match the ConfigurationGroup of the desired parameter.
• ConfigurationId, this should match the ConfigurationKey of the desired parameter.
• Value, this should match the value you want to check for.

You can reference the Parameters table in the frontend/shell database for valid configuration values.

For example, a criterion that checks if the game is set to standard speed would look like this.

    <ConfigurationValueMatches>
        <Group>Game</Group>
        <ConfigurationId>SpeedType</ConfigurationId>
        <Value>GAMESPEED_STANDARD</Value>
    </ConfigurationValueMatches>

ConfigurationValueContains

Almost identical to ConfigurationValueMatches, but it instead takes a comma delimited list for the Value field. The criterion is met if the parameter matches any of the provided values

For example, a criterion that checks if the game is set to Governor or Viceroy difficulty would look like this.

    <ConfigurationValueContains>
        <Group>Game</Group>
        <ConfigurationId>Handicap</ConfigurationId>
        <Value>DIFFICULTY_PRINCE,DIFFICULTY_KING</Value>
    </ConfigurationValueContains>

MapInUse

Checks whether the current map type matches the provided value. The value provided should be match the File column of the Maps table in the frontend database.

        <Criteria id="continents-plus">
            <MapInUse>{base-standard}maps/continents-plus.js</MapInUse>
        </Criteria>

RuleSetInUse

Checks if the given ruleset is in use. By default the only ruleset available is RULESET_STANDARD, but more may be added by mods or DLC. You can reference the Rulesets table in the frontend/shell database for valid rulesets.

GameModeInUse

Checks whether the game mode matches the provided value. The value MUST be one of WorldBuilder, SinglePlayer, HotSeat, or MultiPlayer

LeaderPlayabe

Checks whether provided leader is a valid configuration option (can you set up a game with this leader as a player?)

CivilizationPlayable

Checks whether provided civilization is a valid configuration option (can you set up a game with this civilization as a player?).

This is affected by Game Age, CIVILIZATION_HAN would not be a valid option in an Exploration Age game.

ModInUse

This criterion is met when a mod with an id matching the provided value is active. The meaning of ‘mod’ here is broad. This can be user created mods, or official Firaxis DLC such as shawnee-tecumseh.

it can optionally also take a Version property. In which case it will check to see if the mod version MATCHES EXACTLY before being met. It must be exact. Version 1 will not match version 1.0.

    <ActionCriteria>
        <Criteria id="babylon-mod-active">
            <ModInUse>
                <Version>2.0</Version>
                <Value>suk-abyssinia-civilization</Value>
            </ModInUse>
        </Criteria>
    </ActionCriteria>

Continue to: .modinfo — ActionGroups and actions