How the modding system works (some technical details)

From Halfway
Revision as of 10:45, 14 October 2014 by CoDi (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

How the modding system works (some technical details)

Discovery

The mod system is able to load mods from multiple locations:

  1. As a directory structure in the mods/ folder. The system searches for mods/<folder>/mod-info.json files. The name of <folder> is then used as the (internal) name of the mod.
  2. From ZIP archives in the mods/ folder. The content of each archive found is searched for a <folder>/mod-info.json entry, where <folder> equals the name of the archive. As an example, an archive named myMod.zip is searched for a file myMod/mod-info.json inside.
  3. Steam Workshop files the user subscribed to are downloaded as ZIP archives. They are processed the same way as local archives, just stored at a different location (in the operating system's temp directories).

In summary, it should be easy for mod creators to "transform" a mod from a raw directory structure into an archive mod by simply ZIP'ing the mods/<folder> directory.

Mod names

Mods do have an internal name, and a display name. The name used for display is set by the "display-name" property in mod-info.json. The internal name equals the folder name of the mod, or the file name of the ZIP archive.

Internal names are case insensitive, which means "myMod" and "MYmoD" are equal from the mod system's point of view.

Please don't use spaces and special characters in folder/archive names. The letters A-Z, a-z, 0-9, '_' and '-' are fine.

Versioning

The mod-info.json contains two different version flags. The "display-version" property is just used for display in the game's options menu. The "version" property is used internally as a "revision" number to decide if a version is "more recent".

If the mod system discovers two or more mods of the same (internal) name, the version is used to decide which mod to use. If the versions are equal, the local (raw directory structure) version is preferred. This means that a content creator with his local version, a zipped version, and the version subscribed to on Steam Workshop all at the same version/revision will have his local version - the one he's most likely want to work/test with - supersede all other versions.

Directory structure

Besides the properties in mod-info.json, the mod system just uses the folder structure of a mod to decide which content to add to or replace from the main game. This means that the folder structure must follow the main game's structure in order to have mods work properly.

mod-info.json

{

"display-name" : "That's the name shown in the main and options menus.",

"display-version" : "The version string displayed in the options menu.",


"version" : <the revision number used internally to for versioning>,


"description" : [

"The text shown in the options menu.",

"Only the first two lines will be displayed."

],


"steam-workshop-title" : "The title to be shown in the Steam Workshop.",

"steam-workshop-description" : "The description text to be shown in the Steam Workshop.",


"parent" : null,

"extends-parent" : false,


"dependencies" : [

]

}

Parents and dependencies

It is possible to "chain" mods by setting the "parent" property in mod-info.json. The parent's content is then superseeded by this mod. This can be useful in some cases, e.g. to have one mod offer localisation to another mod. Note: this feature wasn't tested extensively yet, so you might run into technical issues.

The dependencies property hasn't been tested so far and should not be used for now. It was introduced to allow mods to customize the order in which they are processed.