Making a patch mod

From OniGalore
Revision as of 22:21, 14 June 2015 by Iritscen (talk | contribs) (reader should obviously know how to XML mod first)
Jump to navigation Jump to search
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.

Overview

A patch mod, or XML patch mod, is a solution to the problem of mods which affect overlapping game data files. It used to be the case that these mods would overwrite each other even if they were making separate changes to the same files, simply because mod installation required whole files to be supplied by each mod. In the same way that OniSplit improved the modding process by splitting the levels into .oni files that could be replaced individually, now patch modding extends our control over the data even further, allowing us to modify only specific parts 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 mods which modify data like character classes and animation properties (but not media like textures and sounds). 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 @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.