Documentation/Engine/Mod manager

With the new mod manager we introduce packages. Packages can be:

• zip archives - exactly the same which you used before with the .scs or .zip extension.
• normal directories - where each directory represents separate mod.

We recommend using normal directories for development of the mod and using zip archives for mod release, to make mod size smaller and more handy for end-user (on file vs. directory full of files). Inside the package you can define manifest file containing meta data about the mod. Meta data are used by mod manager to display your mod to the user. You can specify description, icon image and much more.

Using the manifest

To set all meta data information you will need to create "manifest.sii" containing "mod_package" unit definition file in your mod package. Example "manifest.sii" file:

SiiNunit
{
# ".package_name" does not matter as the dot at the beginning of the file means
# that this unit is anonymous. Please keep this form to not make any conflicts
# with other mod packages (name collisions).
mod_package : .package_name
{
        # Package version can be any string with any length.
        package_version: "1.0 Release 3"

        # Display name can be any string with any length.
        display_name: "My mod"

        # Author can be any string with any length.
        author: "My Nick"

        # Categories is an array of strings.
        category[]: "ui"
        category[]: "truck"

        # Icon inside the root directory of the mod.
        icon: "mod_icon.jpg"

        # Description file inside the root directory of the mod.
        description_file: "mod_description.txt"

        # compatible_versions[]: "1.19.*" # Mod is compatible with 1.19.X..
}
}

NOTE: We do not limit attributes by length but some places where those meta data are displayed have limited space. To avoid problems we perform cutting of the values to fit the UI. Cutting will simply cut the string at some point and add ".." at the end of the string to mention that there is more content but it does not fit there.

• package_version
  • Type: string
  • The version of the mod package.
• display_name
  • Type: string
  • Display name of the mod. If none is specified name of the package without extension is used.
• author
  • Type: string
  • Author name.
• category
  • Type: array of strings
  • List of categories. Currently we limit categories up to 2 per mod. If you use more than two only first two will be used. If none is specified mod is assigned to "Others" category. You can use only categories from the set defined in Categories to use</a>
• icon
  • Type: string
  • Name of file inside the root of the mod package directory which contains the icon image. Can be only .jpg file with exact size: 276x162px
• description_file
  • Type: string
  • Name of file inside the root of the mod package directory which contains the description text. Description file has to be simple text file with .txt extension saved in UTF-8 encoding. Content of the description file is shown in mod details window and should include information about usage of your mod, additional credits of included mods etc. For possible text formatting see section Description of your mod
• compatible_versions (Not applicable for Steam Workshop mods)
  • Type: array of strings
  • List of compatible game versions. If the list is present and the game version does not match any version from that list, the user will be unable to use the mod and he will have to wait for author to update it. Shall be used only for mods that are likely to get broken, like a map mods.
    Note: If you want your mod to be compatible with all versions simply skip this parameter. Note also that formatting of the Steam version with "s" suffix (for example: 1.18.1s) does not exist in this versioning so please do not use it.
    Each item from the list supports wildcards formatting shown below:

    compatible_versions[]: "1.19.*"

    This means that the mod is compatible with all "1.19.x" versions, e.g. all patches with number starting with 1.19 are compatible. Examples in the table show compatible game versions for the string "1.19.*":

    Version	Compatible?
    1.18.1	no
    1.19.1	yes
    1.19.1.3	yes
    1.19.4	yes
    1.20.4	no

    You can also specify support for only one revision of the game which is not recommended as we do not change game a lot between minor patches.
    For example:

    compatible_versions[]: "1.19.1"

    This usage is not a good idea as your mod will work only with the 1.19.1 version.
    If we will release some hotfix, your mod will simply be incompatible with it.
    You can also use more than one compatible version definitions, like this:

    compatible_versions[]: "1.19.*"
    compatible_versions[]: "1.20.*"

    This way you support both 1.19 and 1.20 patches.
    REMEMBER! If you specify a very restricted set of versions, users of your mod may wait for you, to release a hot fix for the mod evenversion number and your mod is 100% compatible with the latest release.
  • Mod types and configurations for them:
    • Map mods

      compatible_versions[]: "X.X.*"

      Just check if major game version part matches. We might break map compatibility between major patches (1.17 > 1.18 for example) so you have to re-export your map mod from the map editor again. Between patches (like 1.18.1 > 1.18.2) there is a very small chance that we will introduce some critical change to map formats and thus break compatibility.
    • Tuning parts, trucks, model sets and any other
      The best way is not to use this variable as there is a very small chance that your mod will be broken.

Categories to use

Set of valid categories which you can use as value of "category" array entries:

• truck
• trailer
• interior
• tuning_parts
• ai_traffic
• sound
• paint_job
• cargo_pack
• map
• ui
• weather_setup
• physics
• graphics
• models
• movers
• walkers
• prefabs
• other

Description of your mod

Description text length is not limited. Moreover there is also additional ability to colorize your mod description with BBCode tags.

List of available color tags:

Tag	Result color
[red]	#FF2626
[green]	#75FF00
[blue]	#12ABE5
[normal]	Default font color used in UI
[white]	#FFFFFF
[orange]	#FFAE00

For example:

[red]Hello [green]Wor[orange]ld

Will result in: Hello World

Sample mod

You can download a sample mod with manifest here

Other problems not described here

If you have any problem with adjusting your mod to the new standards, feel free to write on our forum in out mods forum section.