ServerPack Format

MCUpdater ServerPacks are a well defined XML format. For those to whom such things have meaning, the full XSD is available at http://files.mcupdater.com/ServerPackv2.xsd. We provide a full featured sample modpack at http://files.mcupdater.com/example/SamplePack.xml. Every MCUpdater installation will attempt to load this pack if it has nothing better to do. For purposes of this document, I will reference sections of the sample pack.

Please be aware that all XML tags and attributes ARE case sensitive. This means that if you are editing your XML by hand and try to define a <SubModule/> it won’t work because MCU is only looking for <Submodule/>s.

ServerPack

All packs should contain at a bare minimum the following:

This is mostly XML boilerplate that shouldn’t interest most users. The most important part is the <ServerPack/>‘s version="3.3" attribute. This tells MCU what sort of pack definition to expect – we’ve changed the format several times over the years and modern MCU builds still support older versions of the XML format. The current version is 3.3 (as of July 2015) and should be used for all packs until a new version replaces it.

Server

Inside the <ServerPack/>, you should then define one or more <Server/> entry – packs without servers are useless and MCU can’t do anything with them. The current sample pack defines the following <Server/>:

The highlited attributes are required:

  • id – A semi-unique internal name that MCU will use to identify the server in the context of the current pack (and any other packs it may import).
  • name – A human-readable display name that will be shown to users.
  • version – The Minecraft version this pack is for.

Additionally, the following attributes are optional but recommended:

  • newsUrl – A URL to the server’s news page (or modlist in the case of the example pack). This is displayed in a browser window to users when they select the server and can be used to tell them about outages, updates, etc…
  • iconUrl – A URL to a small (32×32 recommended) icon displayed in the server list to help users identify the entry quickly.
  • revision – A number or word or other way of identifying your pack’s version. This will be displayed to the user and on the Minecraft main menu and helps when debugging pack problems.
  • mainClass – Used when launching Minecraft. In almost every case, you should set it to net.minecraft.launchwrapper.Launch as in the sample pack.
  • serverAddress – The fully qualified hostname or ip address and port (eg, example.com:25565) of the game server. If this pack doesn’t actually point at a real running game server, you don’t need to specify this.
  • autoConnect (boolean, default: true) – Whether MCU should try to automatically connect to the game server immediately upon Minecraft startup instead of waiting on the main menu.

The following attributes are also supported but can usually be ignored:

  • abstract (boolean, default: false) – Used to tell MCUpdater that this server should not appear in the server list and is meant to be imported by other servers.
  • generateList (boolean, default: true) – Used to tell MCU to add the server to the in-game server list automatically.
  • launcherType – Used to tell MCU whether to start Minecraft using the “new” MC1.6 style launcher or the legacy launcher.
  • libOverrides – For specifying specific library versions to use in cases like MC1.7 where the MC client and server ship differently from Mojang.

Fastpack can automatically populate launcherType and libOverrides for you if necessary.

<Server/>s can then contain two different types of children: <Import/>s and <Module/>s.

Import

MCUpdater serverpacks are modular and can be composed of other packs. This is really helpful when it comes to common or complicated mods – like Forge. In fact, we recommend that all packs use an import when it comes to installing Forge, and we provide a service that handles all of that headache up for you:

The two important parts of an <Import/> tag are its url attribute and the child value.

  • url – The URL to download the pack xml to be imported from.
  • child – The <Server/> id to import.

When you import a <Server/> entry into your own, it will fetch all <Module/>s that the other entry defines as if they were specified in your xml instead of the <Import/> tag.

Module

The meat of any serverpack is a whole mess of <Module/>s. Otherwise you wouldn’t be bothering with all of this. A <Module/> is a file that MCUpdater downloads and installs somewhere in a Minecraft instance folder.

A full <Module/> entry might look something like this:

The entire <Meta/> section is completely optional and exists primarily to make displaying a modlist easier – but that’s a topic for another discussion.

The <Module/> tag’s required attributes are:

  • name – A friendly name to display in the mod list.
  • id – A unique (to this server) identifier used to reference the mod.

Optional attributes:

  • depends – The id of an otherwise optional mod that this mod won’t work without. For multiple dependencies, specify them as a comma-separated list.
  • side (enum, default: BOTH) – Which side (CLIENT, SERVER, or BOTH) should this mod be installed on? Mostly useful in cases where a single serverpack is being used to configure both Minecraft clients and servers.

<Module/>s don’t technically have any required children, but without any children, they don’t do much. For a typical mod, the children highlighted in the example are recommended:

  • <URL/> – The URL to download the mod from. It is possible to specify multiple URL’s by providing multiple tags, each with a different priority attribute. The lowest priority (0) is tried first.
  • <Required/> (boolean, default: true) – Whether the user should be able to disable this mod or not. For optional mods, it is possible to set whether the mod should be enabled by default or not by specifying an isDefault attribute.
  • <ModType/> – Tells MCU how to treat the mod. This is a fairly complex type that I will explain further below.
  • <MD5/> – The MD5 checksum of the download. Used to determine if a mod needs to be downloaded or not. If a download does not match the specified MD5, it won’t be used or cached. If no MD5 is provided, then the mod will be downloaded every time the player updates the pack.

Other:

  • <LoadPrefix/> – A prefix to be used when naming the file.  This is generally only used if the pack has issues with mods loading in a certain order.
  • <ModPath/> – A filename to install the module to after downloading it. This is important for mods that have to go in weird download directories like “mods/1.7.10” or that otherwise require specific filenames for one reason or another. If no modpath is specified, MCU will automatically name the download based on the mod’s id and type.
  • <Size/> – The anticipated filesize in bytes of the download. This is purely cosmetic and is used by the GUI to provide users with a better download progress indicator.
  • <Submodule/> – Sometimes you want to organize your mods together in groups. More on this below.
  • <ConfigFile/> – Raw data files that are downloaded along with the module. This is a complex type explained below.

ModType

The <ModType/> tag tells MCU how to install a mod once it has been downloaded. This is a required tag. There are currently 8 different valid types, but for modern packs, you usually only need to consider these first three:

  • Regular – A regular mod, this is a jar/zip file that is placed in the /mods folder once it is downloaded. The vast majority of mods are of this type. When in doubt, go with this.
  • Extract – A zip file that will dump its contents into the /mods folder. This is useful for providing many little files (like configs) at once without having to specify entries for each file individually.
    • If you specify the optional attribute inRoot=’true’, then it will decompress the zip into the pack’s base directory.
  • Litemod – A liteloader mod, this goes in the /mods folder with a .litemod extension. There is nothing special about this handler, it is just a convenience alias that saves you from having to rename the mod separately.

For a discussion on when to use Extract and examples of how to do so, see the blog post that Al hasn’t yet written on the subject 😉

The other valid mod types are:

  • Coremod – An old style mod that belongs in the /coremods folder. This is another convenience alias to save the hassle of renaming. Note that this is only for legacy environments – modern ‘coremods’ should just be installed as Regular.
  • Jar – An old style (or just weird) mod that still needs to be installed directly in the minecraft jar file.
  • Library – A library file that goes into the /libs folder and is added to the java classpath at launch. This is usually for things that need to load themselves (like mod loaders).
  • Override – An existing mod with the same id defined earlier in the pack will be updated with any tags provided in this entry.
  • Removal – An existing mod with the same id defined earlier in the pack will be removed. This is useful when you are Importing another pack and don’t want to include everything it provides.

For an example of interesting things you can do with overrides, check out SMB’s blog post on incremental updates.

Submodule

With very few exceptions, a submodule is defined identically to a module. The big differences are that:

  1. Submods can’t be made optional.
    and
  2. Submods should not contain other submods or config files.

Every other attribute and tag used to define a module can be used quite happily in submodules. This is particularly nice when dealing with mods that ship in multiple jars. In those cases, I recommend creating a <Module/> entry for the core/base component of the mod and defining all of the other addons as <Submodule/>s.

Submods are installed if their parent mod is installed, and aren’t installed if the parent mod is not installed. If you want to pack additional submods and configs together, just put them under the parent mod – nesting more than one level deep gets hairy.

If you need any further organization, consider breaking things apart into multiple <Server/> entries and importing them as necessary.

ConfigFile

Config files are any additional payload that should be delivered along with a mod’s download. A mod can ship as many config files as you want, but if you find yourself defining too many of these for any given mod, you may want to zip things up and package them as a zipped “<Submodule/>” instead.

Configs are simpler than submods and have fewer options:

  • <URL/> – The URL to download the config file from.
  • <Path/> – The path to save the file at (relative to the instance base ala config/examplemod.cfg).
  • <NoOverwrite/> (boolean, default: false) – Whether or not this config should be preserved if an older version exists already.
  • <MD5/> – The MD5 checksum of the config file.

<NoOverwrite/> is useful for providing default keybindings and other client-side config files that a player may want to tune themselves without worrying about clobbering them when the pack updates.