Caves of Qud Wiki

Modding:Mod Configuration: Difference between revisions

← Older edit
Further changes
m Rm beta disclaimer
 
(19 intermediate revisions by 4 users not shown)
Line 3: Line 3:
There are a number of configuration files that can be associated with a mod. They are all placed in the root folder of the mod and are all optional.
There are a number of configuration files that can be associated with a mod. They are all placed in the root folder of the mod and are all optional.


=<code>manifest.json</code>=
By convention, all JSON keys will be referred to using the casing used in the game's code. However, the configuration file keys are case-insensitive.
 
=manifest.json=
[[File:ModManagerMock.png|thumb|right|Mod Manager mock]]  
[[File:ModManagerMock.png|thumb|right|Mod Manager mock]]  
The <code>manifest.json</code> 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==
==Structure==
Line 14: Line 16:
! Properties
! Properties
|-
|-
| '''id'''
| '''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 your 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. ||
* Defaults to <code>config.json</code>'s <code>ID</code> field.
* Falls back to [[#config.json|<code>config.json</code>'s]] <code>ID</code> field.
|-
|-
| '''loadorder'''
| '''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> ||
* Defaults to <code>config.json</code>'s <code>LoadOrder</code> field.
* Falls back to [[#config.json|<code>config.json</code>'s]]'s <code>LoadOrder</code> field.
|-
|-
| '''title'''
| '''Title'''
| Title of the mod, displayed in the mod manager. ||
| Title of the mod, displayed in the mod manager. ||
* Accepts [[Modding:Text Color Codes & Object Rendering|color shaders]].
* Accepts [[Modding:Text Color Codes & Object Rendering|color shaders]].
* Defaults to <code>workshop.json</code>'s <code>Title</code> field.
* Falls back to [[#workshop.json|<code>workshop.json</code>'s]] <code>Title</code> field.
|-
|-
| '''description'''
| '''Description'''
| Short description of the mod, displayed in the mod manager. ||
| Short description of the mod, displayed in the mod manager. ||
* Accepts [[Modding:Text Color Codes & Object Rendering|color shaders]].
* Accepts [[Modding:Text Color Codes & Object Rendering|color shaders]].
|-
|-
| '''tags'''
| '''Tags'''
| Comma-delimited list of tags, only for display in the mod manager and has no effect on tags used in the workshop. ||
| Comma-delimited list of tags, only for display in the mod manager and has no effect on tags used in the workshop. ||
* Defaults to <code>workshop.json</code>'s <code>Tags</code> field.
* Falls back to [[#workshop.json|<code>workshop.json</code>'s]] <code>Tags</code> field.
|-
|-
| '''version'''
| '''Version'''
| Mod's version, displayed in the mod manager. ||
| Mod's version, displayed in the mod manager. ||
|-
|-
| '''author'''
| '''Author'''
| Creator(s) of the mod. ||
| Creator(s) of the mod. ||
* Accepts [[Modding:Text Color Codes & Object Rendering|color shaders]].
* Accepts [[Modding:Text Color Codes & Object Rendering|color shaders]].
|-
|-
| '''previewImage'''
| '''PreviewImage'''
| 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.||
| 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.||
* Defaults to <code>workshop.json</code>'s <code>ImagePath</code> field.
* 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. ||
|}


==Example <code>manifest.json</code>==
==Version Ranges==
An example <code>manifest.json</code>, taken from the [[Modding:Tutorial_-_Snapjaw_Mages|snapjaw mages]] tutorial.
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">
<syntaxhighlight lang="json">
{
{
     "id": "Pyovya_SnapjawMage",
     "ID": "Pyovya_SnapjawMage",
     "title": "Snapjaw Mages!",
     "LoadOrder": 1,
     "description": "Adds the new Snapjaw Mage creature to Caves of Qud.",
    "Title": "{{R|Snapjaw}} {{C|Mages}}!",
     "version": "0.1.0",
     "Description": "Adds the new {{Y|snapjaw}} {{R|fire}} {{Y|mage}} and {{Y|snapjaw}} {{C|ice}} {{Y|mage}} creatures to Caves of Qud.",
     "author": "Pyovya",
     "Version": "0.1.0",
     "tags": "Creature",
     "Author": "{{M|Pyovya}}",
     "PreviewImage": "preview.png"
     "Tags": "Creature",
     "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>
</syntaxhighlight>


=<code>workshop.json</code>=
=workshop.json=
The <code>workshop.json</code> file configures a mod's upload to the [https://steamcommunity.com/app/333640/workshop/ Caves of Qud Steam Workshop]. It is usually manipulated through the game's Workshop Uploader.


==Structure==
{| class="wikitable"
|-
! Field
! style="width: 65%" | Description
! Properties
|-
| '''WorkshopId'''
| The mod's unique ID on the workshop. ||
|-
| '''Title'''
| Title of the mod, displayed on the workshop. ||
|-
| '''Description'''
| Description of the mod, displayed on the workshop. ||
* Accepts [https://steamcommunity.com/sharedfiles/filedetails/?id=2807121939 formatting tags].
|-
| '''Tags'''
| Comma-delimited list of tags, displayed on the workshop. ||
* [https://steamcommunity.com/app/333640/workshop/ Pre-defined tags] can be filtered on.
|-
| '''Visibility'''
| Stringed integer, detailing the mod's visibility on the workshop.
* <code>"0"</code>: The mod is private (visible only to the mod's creator).
* <code>"1"</code>: The mod is visible to friends only.
* <code>"2"</code>: The mod is public.
||
|-
| '''ImagePath'''
| Relative path to an image used as an icon for the mod in the workshop, recommended size 512x512.
||
|}
==Example workshop.json==
An example <code>workshop.json</code> for the [[Modding:Tutorial_-_Snapjaw_Mages|snapjaw mages]] tutorial mod.
<syntaxhighlight lang="json">
{
  "WorkshopId": 708258860,
  "Title": "Snapjaw Mages",
  "Description": "[h1]Snapjaw Mages[/h1]\n\nThis mod adds the new [b]Snapjaw Mage[/b] creature to Caves of Qud.",
  "Tags": "Creatures",
  "Visibility": "2",
  "ImagePath": "Preview.png"
}
</syntaxhighlight>
=modconfig.json=
The <code>modconfig.json</code> file configures a mod's properties for all textures located within the mod's folder.
==Structure==
{| class="wikitable"
|-
! Field
! style="width: 65%" | Description
! Properties
|-
| '''ShaderMode'''
| 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.  '''Note''':  This currently only works for textures rendered in the world.  Most UI elements do not support this mode.
||
|-
| '''TextureWidth'''
| The width of the mod's textures, in pixels.
||
|-
| '''TextureHeight'''
| The height of the mod's textures, in pixels.
||
|}
==Example modconfig.json==
An example <code>modconfig.json</code>.
<syntaxhighlight lang="json">
{
  "shaderMode": 0,
  "textureWidth": 16,
  "textureHeight": 24
}
</syntaxhighlight>


=config.json=
The <code>config.json</code> file was obsoleted in version [[Version_history/2020#201.44|2.0.201.44]] and was subsumed by the <code>manifest.json</code> file.


[[Category:Modding]]
[[Category:Modding Resources]]
{{Modding Navbox}}
{{Modding Navbox}}
Retrieved from "https://wiki.cavesofqud.com/wiki/Modding:Mod_Configuration"