Making a patch mod: Difference between revisions

From OniGalore
Jump to navigation Jump to search
(→‎Overview: hopefully a better intro)
m (link fix)
 
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
==Overview==
This page explains how to use the patch feature available to [[AE]] mod packages. Before reading this page, you should make sure you grasp the [[Introduction to modding|basics of modding Oni]], the process of [[XML|XML modding]], and [[Making a mod package|how to make a mod package]].
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 [[Anniversary Edition/Framework|HERE]].
__NOTOC__
 
==Introduction==
==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!
'''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.
'''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.
'''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 resource conflicts, there are no actual conflicts in how the mods wish to alter Oni's data because each mod affects a different part of the animation data in resources such as TRAMKONOKOknockdown1. Therefore, if they are created as patch mods, all three mods can be installed at once.


==Creation process==
==Creation process==
Line 17: Line 16:


===Syntax===
===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 [[XmlTools#Patch_file_operations|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.
.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 [[XmlTools#Patch_file_operations|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===
===Sample patch===
A simple example of a patch mod is the AE core mod "Unlock All Moves". There are [[Quotes/Moves#Unlockable_moves|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 [[OniSplit#XML|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:
A simple example of a patch mod is the AE core mod "[http://mods.oni2.net/node/266 Unlock All Moves]". There are [[Quotes/Moves#Unlockable_moves|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 [[TRAM]]s. 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 [[OniSplit#XML|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
@XML_TOOLS Version "2.0"
  @COMMAND Options "--replace-all-values --element-name 'FirstLevel' --new-val '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.
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 [[Anniversary Edition/Framework|HERE]].


[[Category:Modding tutorials]]
[[Category:Modding tutorials]]

Latest revision as of 19:16, 9 November 2023

This page explains how to use the patch feature available to AE mod packages. Before reading this page, you should make sure you grasp the basics of modding Oni, the process of XML modding, and how to make a mod package.

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 resource conflicts, there are no actual conflicts in how the mods wish to alter Oni's data because each mod affects a different part of the animation data in resources such as TRAMKONOKOknockdown1. Therefore, if they are created as patch mods, all three mods can 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.