Modding:Mod Configuration: Difference between revisions

(17 intermediate revisions by 4 users not shown)

Line 7:

=manifest.json=

[[File:ModManagerMock.png|thumb|right|Mod Manager mock]]

The <code>manifest.json</code> file is primarily used for display in the game's Mod Manager.

The <code>manifest.json</code> file is primarily used for display in the game's Mod Manager, but can also control how the mod is loaded.

==Structure==

Line 17:

|-

| '''ID'''

| ~~Internal ID~~ of the mod, ~~primarily~~ used ~~for generating files such~~ as ~~<code>modcheck-[id].json</code> when~~ the mod ~~is approved~~. Try to restrict the ID to alphanumeric characters, as ~~different operating systems will refuse certain characters~~ for ~~their file names~~. ||

| Primary identifier of the mod, this is used as the mod's key in the mod manager and to resolve it as a dependency of another mod. Try to restrict the ID to alphanumeric characters, as it is also used as a symbol for preprocessor directives when compiling. ||

* Falls back to [[#config.json|<code>config.json</code>'s]] <code>ID</code> field.

|-

| '''LoadOrder'''

| Whole number indicating the mod's load priority in ascending order: smaller values load before larger ones. E.g. a mod with a loadorder of <code>-1</code> loads before one with <code>1</code>. ||

| Whole number indicating the mod's load priority in ascending order: smaller values load before larger ones. E.g. a mod with a loadorder of <code>-1</code> loads before one with <code>1</code>. Obsolete in favor of <code>Dependencies</code> with build 210. ||

* Falls back to [[#config.json|<code>config.json</code>'s]]'s <code>LoadOrder</code> field.

|-

Line 40:

| Mod's version, displayed in the mod manager. ||

|-

| '''~~Authors~~'''

| '''Author'''

| Creator(s) of the mod. ||

* Accepts [[Modding:Text Color Codes & Object Rendering|color shaders]].

Line 47:

| Relative path to an image used as an icon for the mod in the manager, recommended size 512x512. The largest Caves of Qud displays on default scale is 128x128, but if also used as the steam workshop preview image, that can display at up to 435x435 on the "Most Popular Items" front page.||

* Falls back to [[#workshop.json|<code>workshop.json</code>'s]] <code>ImagePath</code> field.

|-

| '''Dependencies'''

| ID-Version pair collection of mods that are required to load before this one. New in build 210.||

* Accepts [[Modding:Mod Configuration#Version Ranges|version ranges]].

|-

| '''Dependency'''

| Shorthand to declare a single mod dependency of any version, mutually exclusive with <code>Dependencies</code> field. New in build 210.||

|-

| '''LoadBefore'''

| A single or array of mod IDs that this mod should attempt to load earlier than. New in build 210.||

|-

| '''LoadAfter'''

| A single or array of mod IDs that this mod should attempt to load later than. New in build 210.||

|-

| '''Directories'''

| Array of directory objects that can be loaded conditionally depending on game version or other mods in the load order. Refer to [[Modding:Mod Configuration#Directory Structure|directory structure]] for directory properties. New in build 210.||

* Falls back to loading the root directory if undefined.

|}

==Directory Structure==

Each entry in the <code>Directories</code> array will be evaluated and loaded if optional conditions such as version and dependency match.

If no conditions are specified the directory and its paths will always be loaded.

Directories can be used to include separate content/scripts for different game versions, or optional addons to other mods.

If none are explicitly defined the mod's root directory will be loaded.

{| class="wikitable"

|-

! Field

! style="width: 65%" | Description

! Properties

|-

| '''Paths'''

| Array of paths to load, relative to the mod's root directory. Any leading or trailing separators are optional. Each path is deduplicated and only loaded once, even if a parent or sub directory is defined at any point. Be mindful of the fact that paths are case-sensitive on some operating systems. ||

* Prohibited from escaping the mod directory.

* Recursive.

|-

| '''Path'''

| Shorthand to declare a single path, mutually exclusive with <code>Paths</code> field. ||

|-

| '''Version'''

| A version range that is required to match the game's <code>XRLGame.MarketingVersion</code>. This is the bright number in the bottom right of the main menu.||

* Accepts [[Modding:Mod Configuration#Version Ranges|version ranges]].

* Defaults to <code>*</code>.

|-

| '''Build'''

| A version range that is required to match the game's <code>XRLGame.CoreVersion</code>. This is the dark number prefixed with 'build' in the bottom right of the main menu.||

* Accepts [[Modding:Mod Configuration#Version Ranges|version ranges]].

* Defaults to <code>*</code>.

|-

| '''Dependencies'''

| ID-Version pair collection of mods that are required for this directory to be loaded. These are treated as optional dependencies and do influence the load order, but won't prevent the mod from loading overall. ||

* Accepts [[Modding:Mod Configuration#Version Ranges|version ranges]].

|-

| '''Dependency'''

| Shorthand to declare a single mod dependency of any version, mutually exclusive with <code>Dependencies</code> field.||

|-

| '''Options'''

| A single or array of [[Modding:Options|options]] <code>Requires</code> strings that must be true. Note that the XML file containing the referenced options is required to have <code>Option</code> somewhere in its file name. This is a quirk caused by populating the option defaults prior to directory initialization. ||

|}

==Version Ranges==

To match a game or mod's version you'll define a range of acceptable values using a simple and familiar syntax.

Any number left undefined will behave as if substituted with <code>*</code>.

* <code><nowiki>*</nowiki></code>: Matches any version number and will thus always proceed.

* <code>1.0.*</code>: Matches a version greater or equal to <code>1.0.0</code>, but less than <code>1.1.0</code>.

* <code>2.0.208 - 3.0.0</code>: Matches a version greater or equal to <code>2.0.208</code>, and less or equal to <code>3.0.0</code> (i.e. an inclusive closed interval).

* <code>2.0.209.52 - *</code>: Matches a version greater or equal to <code>2.0.209.52</code>.

* <code><nowiki>>3.5</nowiki></code>: Matches a version greater or equal to <code>3.6.0</code>.

* <code><nowiki>>=2 <5</nowiki></code>: Matches a version greater or equal to <code>2.0.0</code>, but less than <code>5.0.0</code>.

* <code><nowiki>^0.5.2 || 7.2.1</nowiki></code>: Matches a version greater or equal to <code>0.5.2</code>, but less than <code>0.6.0</code>. Or a version equal to <code>7.2.1</code>.

==Example manifest.json==

An example <code>manifest.json</code>, taken from the [[Modding:Tutorial_-_Snapjaw_Mages|snapjaw mages]] tutorial and modified to demonstrate more of the file's options.

{

"id": "Pyovya_SnapjawMage",

"ID": "Pyovya_SnapjawMage",

"~~loadOrder~~": 1,

"LoadOrder": 1,

"~~title~~": "{{R|Snapjaw}} {{C|Mages}}!",

"Title": "{{R|Snapjaw}} {{C|Mages}}!",

"~~description~~": "Adds the new {{Y|snapjaw}} {{R|fire}} {{Y|mage}} and {{Y|snapjaw}} {{C|ice}} {{Y|mage}} creatures to Caves of Qud.",

"Description": "Adds the new {{Y|snapjaw}} {{R|fire}} {{Y|mage}} and {{Y|snapjaw}} {{C|ice}} {{Y|mage}} creatures to Caves of Qud.",

"~~version~~": "0.1.0",

"Version": "0.1.0",

"~~author~~": "{{M|Pyovya}}",

"Author": "{{M|Pyovya}}",

"~~tags~~": "Creature",

"Tags": "Creature",

"~~previewImage~~": "preview.png"

"PreviewImage": "preview.png",

"LoadBefore": "SightlessFray",

"LoadAfter": [ "Tamago_PlatypusCommune", "ChromeGarlands" ],

"Dependencies": {

"Pyovya_SaltOrphan": "1.0.0 - *"

},

"Directories": [

{

"Paths": [ "/Common/", "/Assets/Textures/" ]

},

{

"Path": "/Old/",

"Build": "<2.0.209.43"

},

{

"Paths": [ "/NewCS/", "/NewXML/" ],

"Build": ">=2.0.209.43"

},

{

"Path": "/GooeyAddon/",

"Version": ">=1.0.0",

"Options": [ "OptionSnapjawMage_AddGooeyIck == Yes", "OptionSound != No" ],

"Dependencies": {

"Momo_CyberneticGenders": "^2.*",

"IckySounds": ">=999.7.1.X"

}

},

{

"Path": "/SaltAddon/",

"Option": "OptionSnapjawMage_AddRiotSalt == Yes",

"Dependency": "Yarif_RiotCooking"

}

]

}

</syntaxhighlight>

Line 126:

Line 228:

| An integer representing the mod's textures' shader mode.

* <code>0</code>: The [[Modding:Tiles#Tile_Format|default]] texture shader.

* <code>1</code>: The [[Modding:Tiles#True_Color_tiles|true color]] texture shader.

* <code>1</code>: The [[Modding:Tiles#True_Color_tiles|true color]] texture shader. '''Note''': This currently only works for textures rendered in the world. Most UI elements do not support this mode.

||

|-

@@ Line 7: / Line 7: @@
 =manifest.json=
 [[File:ModManagerMock.png|thumb|right|Mod Manager mock]]
-The <code>manifest.json</code> file is primarily used for display in the game's Mod Manager.
+The <code>manifest.json</code> file is primarily used for display in the game's Mod Manager, but can also control how the mod is loaded.
 ==Structure==
@@ Line 17: / Line 17: @@
 |-
 | '''ID'''
-| Internal ID of the mod, primarily used for generating files such as <code>modcheck-[id].json</code> when the mod is approved.<br/>Try to restrict the ID to alphanumeric characters, as different operating systems will refuse certain characters for their file names. ||
+| Primary identifier of the mod, this is used as the mod's key in the mod manager and to resolve it as a dependency of another mod.<br/>Try to restrict the ID to alphanumeric characters, as it is also used as a symbol for preprocessor directives when compiling. ||
 * Falls back to [[#config.json|<code>config.json</code>'s]] <code>ID</code> field.
 |-
 | '''LoadOrder'''
-| Whole number indicating the mod's load priority in ascending order: smaller values load before larger ones.<br/>E.g. a mod with a loadorder of <code>-1</code> loads before one with <code>1</code>. ||
+| Whole number indicating the mod's load priority in ascending order: smaller values load before larger ones.<br/>E.g. a mod with a loadorder of <code>-1</code> loads before one with <code>1</code>.<br/><b>Obsolete in favor of <code>Dependencies</code> with build 210.</b> ||
 * Falls back to [[#config.json|<code>config.json</code>'s]]'s <code>LoadOrder</code> field.
 |-
@@ Line 40: / Line 40: @@
 | Mod's version, displayed in the mod manager. ||
 |-
-| '''Authors'''
+| '''Author'''
 | Creator(s) of the mod. ||
 * Accepts [[Modding:Text Color Codes & Object Rendering|color shaders]].
@@ Line 47: / Line 47: @@
 | Relative path to an image used as an icon for the mod in the manager, recommended size 512x512.<br/>The largest Caves of Qud displays on default scale is 128x128, but if also used as the steam workshop preview image, that can display at up to 435x435 on the "Most Popular Items" front page.||
 * Falls back to [[#workshop.json|<code>workshop.json</code>'s]] <code>ImagePath</code> field.
+|-
+| '''Dependencies'''
+| ID-Version pair collection of mods that are required to load before this one.<br/><b>New in build 210.</b>||
+* Accepts [[Modding:Mod Configuration#Version Ranges|version ranges]].
+|-
+| '''Dependency'''
+| Shorthand to declare a single mod dependency of any version, mutually exclusive with <code>Dependencies</code> field.<br/><b>New in build 210.</b>||
+|-
+| '''LoadBefore'''
+| A single or array of mod IDs that this mod should attempt to load earlier than.<br/><b>New in build 210.</b>||
+|-
+| '''LoadAfter'''
+| A single or array of mod IDs that this mod should attempt to load later than.<br/><b>New in build 210.</b>||
+|-
+| '''Directories'''
+| Array of directory objects that can be loaded conditionally depending on game version or other mods in the load order.<br/>Refer to [[Modding:Mod Configuration#Directory Structure|directory structure]] for directory properties.<br/><b>New in build 210.</b>||
+* Falls back to loading the root directory if undefined.
 |}
+==Directory Structure==
+Each entry in the <code>Directories</code> array will be evaluated and loaded if optional conditions such as version and dependency match.<br/>
+If no conditions are specified the directory and its paths will always be loaded.<br/>
+Directories can be used to include separate content/scripts for different game versions, or optional addons to other mods.<br/>
+If none are explicitly defined the mod's root directory will be loaded.
+{| class="wikitable"
+|-
+! Field
+! style="width: 65%" | Description
+! Properties
+|-
+| '''Paths'''
+| Array of paths to load, relative to the mod's root directory. Any leading or trailing separators are optional.<br/>Each path is deduplicated and only loaded once, even if a parent or sub directory is defined at any point.<br/>Be mindful of the fact that paths are <b>case-sensitive</b> on some operating systems. ||
+* Prohibited from escaping the mod directory.
+* Recursive.
+|-
+| '''Path'''
+| Shorthand to declare a single path, mutually exclusive with <code>Paths</code> field. ||
+|-
+| '''Version'''
+| A version range that is required to match the game's <code>XRLGame.MarketingVersion</code>.<br/>This is the bright number in the bottom right of the main menu.||
+* Accepts [[Modding:Mod Configuration#Version Ranges|version ranges]].
+* Defaults to <code>*</code>.
+|-
+| '''Build'''
+| A version range that is required to match the game's <code>XRLGame.CoreVersion</code>.<br/> This is the dark number prefixed with 'build' in the bottom right of the main menu.||
+* Accepts [[Modding:Mod Configuration#Version Ranges|version ranges]].
+* Defaults to <code>*</code>.
+|-
+| '''Dependencies'''
+| ID-Version pair collection of mods that are required for this directory to be loaded.<br/>These are treated as optional dependencies and do influence the load order, but won't prevent the mod from loading overall. ||
+* Accepts [[Modding:Mod Configuration#Version Ranges|version ranges]].
+|-
+| '''Dependency'''
+| Shorthand to declare a single mod dependency of any version, mutually exclusive with <code>Dependencies</code> field.||
+|-
+| '''Options'''
+| A single or array of [[Modding:Options|options]] <code>Requires</code> strings that must be true.<br/>Note that the XML file containing the referenced options is required to have <code>Option</code> somewhere in its file name.<br/>This is a quirk caused by populating the option defaults prior to directory initialization. ||
+|}
+==Version Ranges==
+To match a game or mod's version you'll define a range of acceptable values using a simple and familiar syntax.<br/>
+Any number left undefined will behave as if substituted with <code>*</code>.
+* <code><nowiki>*</nowiki></code>: Matches any version number and will thus always proceed.
+* <code>1.0.*</code>: Matches a version greater or equal to <code>1.0.0</code>, but less than <code>1.1.0</code>.
+* <code>2.0.208 - 3.0.0</code>: Matches a version greater or equal to <code>2.0.208</code>, and less or equal to <code>3.0.0</code> (i.e. an inclusive closed interval).
+* <code>2.0.209.52 - *</code>: Matches a version greater or equal to <code>2.0.209.52</code>.
+* <code><nowiki>>3.5</nowiki></code>: Matches a version greater or equal to <code>3.6.0</code>.
+* <code><nowiki>>=2 <5</nowiki></code>: Matches a version greater or equal to <code>2.0.0</code>, but less than <code>5.0.0</code>.
+* <code><nowiki>^0.5.2 || 7.2.1</nowiki></code>: Matches a version greater or equal to <code>0.5.2</code>, but less than <code>0.6.0</code>. <b>Or</b> a version equal to <code>7.2.1</code>.
 ==Example manifest.json==
 An example <code>manifest.json</code>, taken from the [[Modding:Tutorial_-_Snapjaw_Mages|snapjaw mages]] tutorial and modified to demonstrate more of the file's options.
 <syntaxhighlight lang="json">
 {
-     "id": "Pyovya_SnapjawMage",
+     "ID": "Pyovya_SnapjawMage",
-     "loadOrder": 1,
+     "LoadOrder": 1,
-     "title": "{{R|Snapjaw}} {{C|Mages}}!",
+     "Title": "{{R|Snapjaw}} {{C|Mages}}!",
-     "description": "Adds the new {{Y|snapjaw}} {{R|fire}} {{Y|mage}} and {{Y|snapjaw}} {{C|ice}} {{Y|mage}} creatures to Caves of Qud.",
+     "Description": "Adds the new {{Y|snapjaw}} {{R|fire}} {{Y|mage}} and {{Y|snapjaw}} {{C|ice}} {{Y|mage}} creatures to Caves of Qud.",
-     "version": "0.1.0",
+     "Version": "0.1.0",
-     "author": "{{M|Pyovya}}",
+     "Author": "{{M|Pyovya}}",
-     "tags": "Creature",
+     "Tags": "Creature",
-     "previewImage": "preview.png"
+     "PreviewImage": "preview.png",
+    "LoadBefore": "SightlessFray",
+    "LoadAfter": [ "Tamago_PlatypusCommune", "ChromeGarlands" ],
+    "Dependencies": {
+        "Pyovya_SaltOrphan": "1.0.0 - *"
+    },
+    "Directories": [
+        {
+            "Paths": [ "/Common/", "/Assets/Textures/" ]
+        },
+        {
+            "Path": "/Old/",
+            "Build": "<2.0.209.43"
+        },
+        {
+            "Paths": [ "/NewCS/", "/NewXML/" ],
+            "Build": ">=2.0.209.43"
+        },
+        {
+            "Path": "/GooeyAddon/",
+            "Version": ">=1.0.0",
+            "Options": [ "OptionSnapjawMage_AddGooeyIck == Yes", "OptionSound != No" ],
+            "Dependencies": {
+                "Momo_CyberneticGenders": "^2.*",
+                "IckySounds": ">=999.7.1.X"
+            }
+        },
+        {
+            "Path": "/SaltAddon/",
+            "Option": "OptionSnapjawMage_AddRiotSalt == Yes",
+            "Dependency": "Yarif_RiotCooking"
+        }
+    ]
 }
 </syntaxhighlight>
@@ Line 126: / Line 228: @@
 | An integer representing the mod's textures' shader mode.
 * <code>0</code>: The [[Modding:Tiles#Tile_Format|default]] texture shader.
-* <code>1</code>: The [[Modding:Tiles#True_Color_tiles|true color]] texture shader.
+* <code>1</code>: The [[Modding:Tiles#True_Color_tiles|true color]] texture shader.  '''Note''':  This currently only works for textures rendered in the world.  Most UI elements do not support this mode.
 ||
 |-