About.xml

From RimWorld Wiki
Revision as of 17:35, 29 May 2023 by Aelanna (talk | contribs) (Added note about case sensitivity in package ID, modVersion field)
Jump to navigation Jump to search

< Modding Tutorials

?
Under Review
This tutorial or guide is currently undergoing review and should not be considered ready to use.

About.xml is a required file that identifies your mod to RimWorld.

Setup

Your About.xml file should be placed directly inside your About folder. Note that both the folder and file name are case-sensitive and must be spelled exactly this way; please see the mod folder structure guide for more information. 

Mods
└ MyModFolder
  └ About
    └ About.xml

The contents of About.xml is a standard XML file with ModMetaData as the root tag: 

<?xml version="1.0" encoding="utf-8"?>
<ModMetaData>

  <!-- content goes here -->

</ModMetaData>

Required Tags

The following tags are all required for a functioning mod. Please read the tag descriptions carefully:

XML Description 
<packageId>AuthorName.ModName</packageId>

The internal identifier for your mod, used to identify your mod as a dependency, load order helper, or with MayRequire attributes. packageIds should be alphanumeric with at least one period separating two strings. It is usually recommended that you use YourName.YourModName, YourProjectName.YourModName, YourName.YourSeriesName.YourModName, or something similar.

packageId must be globally unique across all mods. If RimWorld encounters more than one mod with the same packageId, even if they are not in your current mod list, then an error will be thrown and only the first mod will be usable. The only time that using the same packageId is recommended is if you are forking or continuing a mod and want it to act as a drop-in replacement. In such cases, players must unsubscribe from the original mod to be able to use yours.

Note: packageId is case-insensitive as RimWorld will internally convert all IDs to lowercase; capitalization is done for readability, but two IDs that are identical other than case will resolve as identical. 

<name>My Mod Name</name>

The title of your mod. While the name of your mod does not need to be globally unique and most references to mods are now using packageId, PatchOperationFindMod still uses mod names and thus you should avoid changing the name of your mod unless absolutely necessary. 

<author>Author Name, Another Author Name, A Third Author Name</author>
or
<author>
  <li>Author Name</li>
  <li>Another Author Name</li>
  <li>A Third Author Name</li>
</author>

The author of this mod, usually yourself. More than one author can be specified by separating names with commas or by using list nodes. 

<description>This is the description of this mod.</description>

The plain-text description of your mod. This is used as both the content description of your mod in mod managers (including the vanilla mod manager) as well as the initial description of your mod if uploaded to Steam Workshop. In the latter case, you can change your Workshop item description independent of the mod itself, thus it is generally recommended that you keep the description of your mod in About.xml relatively short. 

<supportedVersions>
  <li>1.4</li>
</supportedVersions>

The RimWorld versions that your mod supports. A warning will be given to the player if attempting to load the mod under a version you have not explicitly specified support for, but this does not prevent players from loading the mod if they so choose.

It is strongly recommended that you only specify support for versions that you have explicitly tested compatibility for; RimWorld has changed dramatically between versions in the past and even XML-only mods may not be guaranteed to work without version-specific changes.


Optional Tags

The following tags are optional and should only be used if you need them:

XML Description 
<modVersion>1.0</modVersion>
or
<modVersion IgnoreIfNoMatchingField="True">1.0</modVersion>

A version string for your own personal version tracking.

WARNING: This tag was introduced in RimWorld 1.4 and will generate errors in previous versions unless IgnoreIfNoMatchingField is used. If you intend to support older versions of RimWorld with your mod and you want to use this field, you must add this attribute. 

<url>https://steamcommunity.com/workshop/filedetails/?id=2009463077</url>

A web link that can be displayed with your mod info. This can be any link, though most mods will link to their primary download source, such as a Steam Workshop page, GitHub repository, or Ludeon Forum link.

The example URL is the Steam Workshop page for the latest version of Harmony. 

<descriptionsByVersion>
  <v1.4>A different description.</v1.4>
</descriptionsByVersion>

Used to specify a different mod description for specific versions of RimWorld. This is not used by Steam Workshop. 

<modDependencies>
  <li>
    <packageId>brrainz.harmony</packageId>
    <displayName>Harmony</displayName>
    <steamWorkshopUrl>steam://url/CommunityFilePage/2009463077</steamWorkshopUrl>
  </li>
</modDependencies>

Used to specify dependencies for your mod. Players will be warned if a dependency for your mod is not loaded in their mod list, though players may choose to ignore it.

Note that this is not automatically used by Steam Workshop; if you want players to be notified that they should download a dependency, you must add that via Steam Workshop's "Required Items" feature. 

<modDependenciesByVersion>
  <v1.4>
    <li>
      <packageId>brrainz.harmony</packageId>
      <displayName>Harmony</displayName>
      <steamWorkshopUrl>steam://url/CommunityFilePage/2009463077</steamWorkshopUrl>
    </li>
  </v1.4>
</modDependenciesByVersion>

Used to specify dependencies for your mod that only apply for a specific version. See above for more details. 

<loadBefore>
  <li>CETeam.CombatExtended</li>
</loadBefore>

Used to specify mods that your mod should load before. RimWorld will warn the player if your mod is not in the correct place in their mod list.

Mods specified this way must be referenced by their packageId. 

<loadBeforeByVersion>
  <v1.4>
    <li>CETeam.CombatExtended</li>
  </v1.4>
</loadBeforeByVersion>

Same as loadBefore, but only for the specified RimWorld versions. 

<forceLoadBefore>
  <li>CETeam.CombatExtended</li>
</forceLoadBefore>

Same as loadBefore, but instead of just a warning, RimWorld will not allow your mod to be loaded after the specified mods. Note that external mod managers such as RimPy may not respect this field. 

<loadAfter>
  <li>erdelf.HumanoidAlienRaces</li>
</loadAfter>

Used to specify mods that your mod should load after. RimWorld will warn the player if your mod is not in the correct place in their mod list.

Mods specified this way must be referenced by their packageId. 

<loadAfterByVersion>
  <v1.4>
    <li>erdelf.HumanoidAlienRaces</li>
  </v1.4>
</loadAfterByVersion>

Same as loadAfter, but only for the specified RimWorld versions. 

<forceLoadAfter>
  <li>erdelf.HumanoidAlienRaces</li>
</forceLoadAfter>

Same as loadAfter, but instead of just a warning, RimWorld will not allow your mod to be loaded after the specified mods. Note that external mod managers such as RimPy may not respect this field. 

<incompatibleWith>
  <li>CETeam.CombatExtended</li>
</incompatibleWith>

Used to specify mods that your mod is incompatible with. Players will be warned if the specified mods are loaded at the same time that your mod is.

This should generally only be used to specify mods that are fundamentally incompatible with your mod rather than mods that simply have bugs related to your mod. 

<incompatibleWithByVersion>
  <v1.4>
    <li>CETeam.CombatExtended</li>
  </v1.4>
</incompatibleWithByVersion>

Same as incompatibleWith, but only for the specified versions.

Examples

As About.xml is required for all mods, you can use existing mods as a reference if you need some examples of working About.xml files. The default installation folder for Steam Workshop mods is under C:\Program Files (x86)\Steam\steamapps\workshop\content\294100

Retrieved from "https://rimworldwiki.com/index.php?title=Modding_Tutorials/About.xml&oldid=135029"