Riivolution does its magic according to XML files found in the folder /riivolution on an SD card or USB drive. The format is very extensive and flexible; many different kind of game modifications can be made this way. This page will attempt to explain how to write powerful XML files. The Riivolution Schema can also be used to verify that your XML is set up properly.

If you're just interested in getting Riivolution running, or want to see an example, look over at the Patch Templates page; this page is meant for power users and people planning on releasing packaged game mods.

The Basics

Riivolution patch XMLs are made up of three parts:

  • The id tag, which specifies which game it should be applied to, if any.
  • The options tag, which organizes patches into an Option-Choice menu system.
  • The patches themselves, which define what files and memory to replace and how.

Terminology

Each element attribute has a type of data that behaves in a certain way.

Integer

An integer type only accepts numbers, which must be in either decimal or hexadecimal form. Numbers will only be recognized as hexadecimal if preceeded by "0x".

Boolean

A boolean type can only be true or false, yes or no.

Hex String

A hex string is a string of hex characters, treated as data. It may or may not be preceeded by "0x", and the number of characters in it must be a multiple of two (it cannot have half a byte).

String

A string is just a string of one or more characters. There's nothing really special about them.

Path

A path is special because they can be either absolute or relative to a root, which defaults to /riivolution. The root can be changed at either the wiidisc or patch level, and whenever a relative path is used, it is combined with the current root.

Parameters

A param isn't an attribute type, but rather, a special node that can be used in many different places. They can be applied at the option, choice, or patch level under options. They assign a value to a name, which can be used for dynamic replacements within paths of patches.

For example, if I set a param to be the following... 

   <param name="slot" value="1" />

Then put this inside an option, any patches used in that option will be able to have their paths affected by it. The format to use in a path is "${name}", so I could set up a patch like so... 

   <file disc="/testfile{$slot}.arc" external="test{$slot}.arc" />

Which would replace {$slot} with "1" when applied. Note that if a param name isn't set, it will be blanked out. So if a different option were to use this file patch, it would try replacing "/testfile.arc" rather than "/testfile1.arc" as it would under the option with the param set.

Default Parameters

Riivolution provides a few built-in params that you can use inside of your XMLs. They describe the disc currently in the drive and are as follows: 

{$__gameid} contains the first three characters of the Game ID. For example, "RSB" for Super Smash Bros. Brawl
{$__region} contains the region character of the Game ID, usually "E", "P", or "J"
{$__maker}  contains the maker code of the Game ID. For example, "01" is Nintendo.

Using these together can be used to get the full Game ID, "RSBE01", like so: 

{$__gameid}{$__region}{$__maker}

The Root

All Riivolution XMLs are encompassed in a root wiidisc node, like so: 

   <wiidisc version="1" root="/riivolution">
       ...
   </wiidisc>

Attributes

  • version - integer - required - Riivolution v1.0 only supports XMLs with a version of 1.
  • root - path - optional - Used as the root for all paths used within this XML.

ID

The id tag is meant to make sure an XML is only applied to the game it was written for. If it is ommitted, the XML will be loaded for any game. There can not be more than one ID tag in one XML.

The id tag can specify the game ID, developer, disc number, version, and region(s). Any combination of these are allowed, and anything ommitted or empty will allow everything through. Here's an example: 

   <id game="SZA" developer="69" disc="0" version="0">
       <region type="P" />
       <region type="E" />
   </id>

The previous example will make sure the XML works for both PAL and NTSC versions of Rock Band 2.

Attributes

  • game - string - optional - Up to three characters (or four if you're too lazy to use the region nodes and want to restrict it to one region) to match the disc's Game ID. Usually starts with a 'R' or 'S'.
  • developer - string - optional - Two characters used to identify the makers of the game.
  • disc - integer - optional - One byte specifying the disc number of the game. This is usually 0, but may be 1 for the second disc of a multi-disc game - like Tales of Symphonia - and so on.
  • version - integer - optional - Another byte specifying the disc version. This is again usually 0, but may be increased for game reprints.

Options

All sections of an XML must be encompassed by options tags: 

   <options>
       ...
   </options>

There are no attributes that can be used here.

Macros

Macros can be used to clone an option multiple times, while giving it a different name and set of params for each clone. 

   <macro id="optionid" name="New Option Name">
       <param name="paramname" value="value" />
   </macro>

Attributes

  • id - string - required - The id of the option to clone.
  • name - string - required - The new name to set to the cloned option.
  • The macro node can contain numerous param nodes. Without them it's not very useful.

Sections

A section represents a page in the GUI, though they can be split up into multiple pages if they contain too many options. They contain options, and have no attribute but a name: 

   <section name="Levels">
       ...
   </section>

Attributes

  • name - string - required - The name of the section as it should show up in the program.

Options

An option represents something modifiable in the program. It contains choices, and only one can be active at any given time. It can hold params, and also can always be set to disabled. 

   <option id="optionid" name="My Option" default="1">
       ...
   </option>

Attributes

  • id - string - optional - Used for both allowing an option to be macroed, as well as combining options from two different XMLs (they must be under the same section name as well).
  • name - string - required - The name of the option to be shown in the program.
  • default - integer - optional - The index of the default choice to be selected when the program first starts. Once the user has saved their settings (launched a game), this is ignored and the last-used choice is set.
    The index is 1-based, because setting it to 0 is disabled (this is the default when it's not specified).

Choices

A choice represents one choice within an option. It can also hold params, and references patches to be applied; these patch subnodes can also have params applied to them. 

   <choice name="Choice Name">
       <patch id="patchid" />
       <patch id="anotherpatch />
   </choice>

Attributes

  • name - string - required - This is the name of the choice as it appears in the program.
  • patch : id - string - required - The ID of the patch to enable when this choice is selected. This refers to the patches defined in the next section.

Patches

A patch is a set of commands that Riivolution will execute when the proper choice is selected. It can contain file, folder, and memory patches, and follows this format... 

   <patch id="patchid" root="/path">
       ...
   </patch>

Attributes

  • id - string - required - This is the id that a choice will reference in order to enable the patch.
  • root - path - optional - This can set the root path for all items in this patch.

File Patch

A file patch will replace the contents of one file on disc with one from an external device. 

   <file disc="/filename.arc" external="filename.arc" resize="true" create="false" offset="0x10" length="0x100" />

Attributes

  • disc - disc path - required - The file on disc to replace. This can be rooted as a full disc path or just a filename to search for.
  • external - path - required - The file on SD/USB to replace the disc file with.
  • resize - boolean - optional - Defaults to true, specifies whether to resize the disc file to the external file.
  • create - boolean - optional - Defaults to false, specifies whether to add the file on the disc if it does not exist.
  • offset - integer - optional - The offset into the disc file to start replacing; defaults to 0 (beginning of the file).
  • length - integer - optional - The length specifies how much to patch the file. If not specified, or set to 0, it will default to the size of the external file.

Folder Patch

A folder patch replaces a number of files from an external device onto the disc. 

   <folder disc="/filename.arc" external="filename.arc" resize="true" create="false" recursive="true" length="0x1000" />

Attributes

  • disc - disc path - optional - The folder on disc to replace. This can be empty or omitted in order to just do a filename search without a specific folder.
  • external - path - required - The folder on SD/USB to replace the disc files with.
  • resize - boolean - optional - Defaults to true, specifies whether to resize the disc files to the ones found in the external folder.
  • create - boolean - optional - Defaults to false, specifies whether to add any files and folders (if recursive == true) to the disc folder if they're not found.
  • recursive - boolean - optional - Defaults to true and tells Riivolution whether to go looking in subfolders for other files to replace.
    This option only works when the disc path is rooted and set to a folder.
  • length - integer - optional - The length specifies how much to patch each file in the folder. It can be used to expand files in a folder for testing purposed. If not specified, or set to 0, it will default to the size of each external file.

Savegame Patch

A savegame patch will redirect a game's savegame to the external path specified. It can be used to store a save on SD/USB/Wifi without corrupting a player's original save when playing a game hack with different stages. Check out the Savegame Template for a universal savegame XML. 

   <savegame external="/riivolution/save" clone="true" />

Attributes

  • external - path - required - The folder on SD/USB to store the game's savefile inside. It will be created if it does not exist.
  • clone - boolean - optional - Defaults to true, specifies whether to copy the Wii's current savegame to the external folder before starting the game. When set to true, this is only done when the external folder is empty, so only on first startup or if it's been deleted. When set to false, it begin an entirely new save if the external folder is empty.

Memory Patch

There are a few different kinds of memory patches, and they all deal with patching the Wii's memory right before a game loads. They can be used to apply various different ASM hacks to games.

NOTE: The valuefile attribute is a path, and params can be used in it as of Riivolution v1.04.

The default memory patch looks like the following, and is used to write values to a set address... 

   <memory offset="0x80001000" value="0F73AB3D" original="1337BAAD" />
   <memory offset="0x80001000" valuefile="/file.bin" />
Attributes
  • offset - integer - required - The offset in memory at which to write and/or verify.
  • value - hex string - required - The value to write to memory at. Must be a string of hex characters, and its length must be a multiple of two.
  • valuefile - path - required - An alternative to value is to specify a file path to read the value from instead. Either valuefile or value must be specified, and the whole file will be used.
  • original - hex string - optional - If original is specified, but does not match the memory at that address, value will not be written to memory.

Ocarina Patch

An Ocarina Patch will look in the dol for the value specified, and then find the next occurring blr and replace it with a branch to offset. 

   <memory offset="0x80001800" value="0F73AB3D" ocarina="true" />
Attributes
  • offset - integer - required - The offset is the offset in memory of the location to branch to.
  • value - hex string - required - The value pattern to search the game binary for.
  • ocarina - boolean - required - Must be true for this form to work.

Search Patch

A memory search patch can be used to replace a pattern in the main executable dynamically. 

   <memory original="1337BAAD" value="831378F2" align="4" search="true" />
Attributes
  • original - hex string - required - The original pattern to search the game binary for.
  • value - hex string - required - The value to replace the original pattern with. Must be the same length.
  • valuefile - path - required - An alternative to value is to specify a file path to read the value from instead. Either valuefile or value must be specified, and the whole file will be used.
  • align - integer - optional - The byte alignment to search with. Defaults to 1, but often should be higher in order to save time when searching.
  • search - boolean - required - Must be true for this form to work.