Making a patch mod

Before reading this page, you should make sure you grasp the basics of modding Oni, and the process of XML modding. It will also help to read Making a mod package first.

Introduction

Problem: You want to mod a certain resource, but you know that the resource is already getting replaced by another mod. That mod might come after yours numerically, thus erasing any change your mod makes if a player installs both mods. It seems that your only option is to mark your mod as incompatible with the other one, so the player has to choose which one to install. But wait!

Solution: If you aren't altering the exact same part of a certain resource as another mod, you can use an XML patch mod instead ("patch mod", for short). A patch mod allows you to only alter the part of the resource that you need to; thus, patches can "stack" onto each other, so that any number of mods can affect the same resource without overriding each other. Note that XML patch mods only work on data that can be exported by OniSplit in the XML format, such as character classes and animation properties, but not media like textures and sounds.

Example: Consider the mods Glass Breaking Moves, Domino Knockdowns, and Disarm Revamp. Glass Breaking Moves adds a glass-breaking property to attacks and falling-body animations so they will shatter glass if they connect with a window. Domino Knockdowns adds a damaging stun or stagger property to an animation so that a falling character can hurt a character they collide with. Disarm Revamp removes the DropWeapon flag from knockdown animations so that characters can hold onto their gun more easily, and shoot at the enemy while laying on the ground. These mods have a potential three-way conflict; for instance, they all desire to affect TRAMKONOKOknockdown1. However, although they have file conflicts, there are no actual conflicts in how the mods wish to alter Oni's data. A patch mod will allow all three mods to be installed at once.

Creation process

Hierarchy

When assembling your mod package, you place .oni-patch files in a "patches/" directory instead of an "oni/" directory (see Making a mod package for a full sample hierarchy). Patches can thus co-exist with other types of files in a package; so you could mod some of Oni's data using complete .oni replacement files and mod only the potentially conflicting data with .oni-patches. While it's true that you could make many mods into patch mods, be aware that there is a performance hit when using patches, so it's probably better to stick to using .oni files until you expect or know of a conflict with another mod.

Naming

To make a patch mod, you create a plain-text file with the name of the .oni file you wish to mod, and the suffix ".oni-patch". To affect multiple files that share a common string in their name, you use a '-' as a wildcard. For example, a patch file with the name "TRAM-knockdown.oni-patch" will affect all resources in Oni named "TRAM[something]knockdown".

Syntax

.oni-patches are essentially XmlTools files, which is to say that they use a syntax that only XmlTools understands. You should take the time to read about it HERE now. Between the commands @ADD_INSIDE_NODES, @REMOVE_NODES, @COMMAND (XmlTools' normal command-line operations) and @CUSTOM_CODE (custom JavaScript editing code) you have a fair amount of power over the .oni in XML form.

Sample patch

A simple example of a patch mod is the AE core mod "Unlock All Moves". There are nine moves in Oni that Konoko learns as the game progresses. A veteran player is used to having those moves, so the AE unlocks them all from the start. To figure out how to unlock a move, you would start by reading about TRAMs. You would see a note about a flag for a "first level where the animation is available". On the XML:TRAM page, or by looking at XML-exported TRAMs, you would observe that the XML tag is "FirstLevel". Thus, you create a text file with the name of each move to unlock, for instance TRAMKONCOMcomb_k_k_k.oni-patch, with the contents:

@XML_TOOLS Version "2.0"

@COMMAND Options "--replace-all-values --element-name 'FirstLevel' --new-val '0'"

The AEI will then process this file by retrieving the .oni file whose name matches the .oni-patch file (TRAMKONCOMcomb_k_k_k), exporting it as XML, running XmlTools to apply the patch, then converting the XML file back to an .oni file and combining it with all other selected mods into the new level data in the GDF. The modder does not have to worry about whether there is a modded form of the .oni file he is patching in some mod the player has installed because the AEI will use the .oni from the highest-numbered mod as the base for the patch. The AEI will use the vanilla resource from Oni if there are no modded versions of the .oni among the player's active mods. The full process for how the AEI handles patch mods is described HERE.