Making a patch mod

Overview

A patch mod, or XML patch mod, is a solution to the problem of conflicting mod packages. The AE releases prior to Seven dealt with this conflict for certain mods by pre-modding certain base .oni files, forcing the player to have them installed. However, like OniSplit allowed us to create optional mods for level files by splitting the levels into modular .oni files that could be replaced, so patch modding extends our control over the data even further, allowing us to modify specific properties of .oni files. It does this by providing the AEI with just the changes that should be made to an XML export of a resource, which are then applied using XmlTools. This provides a way to stack any mods which modify data like ONCCs and TRAMs (but not media resources like TXMPs and SNDDs). The full process for how the AEI handles patch mods is described HERE.

Purpose of patch modding

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 a patch mod instead. 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.

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 @ADDTO and @REMOVE commands and the ability to use XmlTools' normal command-line operations with @COMMAND, 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:

@COMMAND replaceall -element:FirstLevel -value:0

The AEI will then process this file by looking up the TRAM whose name matches the .oni-patch file (TRAMKONCOMcomb_k_k_k), exporting it as XML, running XmlTools to apply the patch, then re-importing the XML as an .oni file and combining it with all other selected mods into the new level data for Oni to use. The modder does not have to worry about whether there is a modded form of this TRAM in some active mod 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.