source: AE/packages/31000GlassBreakingMoves/About this patch.txt@ 965

Glass Breaking Moves
Technical Notes
by Iritscen (March 2014)

Here is some detailed documentation on the patch for anyone who's interested.  If you are not familiar with the terms "patch mod" or "XML patching", first read http://wiki.oni2.net/Making_a_patch_mod.

The way this patch makes glass-breaking work is to add to Oni a particle called "glass_break", logically enough. glass_break performs the action "Glass Charge" for the duration of its lifetime.

Next, the particle is registered for use by a character by editing their ONCC (see Type 1 below). Finally (and this is the complex part), the particle is added to every animation that we desire to break glass. Generally speaking that means all attacks, and blownup and knockdown animations.

Because we need to tread as lightly as possible in adding particles to Oni, the particle needs to be added intelligently. The complexity of the process requires the use of JavaScript through the @CUSTOM_CODE feature in XmlTools.

Below are the five types of JS-driven patches performed by this mod. They are listed by the name-matching pattern used to collect the files to be patched; the count of vanilla files captured by this pattern is also listed. These pattern matches come to a grand total of 711 files. Note, however, that the patch will also apply to any active mods, which may contain additional ONCC and TRAM files.

Type 1:
Pattern: ONCC*
Matches: 123 files
Purpose: Looks for an existing glass_break particle in the ONCP registry, and adds it if not present.

Type 2:
Pattern: TRAM*blownup*, TRAM*tgt*
Matches: 9 + 56 files (65 total)
Purpose: Blownup animations (like knockdowns, below) have no existing Attack data, because falling characters do not strike other characters in vanilla Oni. Therefore, we simply add the glass_break particle to Head and RightFoot, so both ends of the character can break glass if passing through it. The lifetime of the particle is the duration of the animation.
         "tgt" animations are the animations for the target (victim) of a throw. These _do_ have Attack data, generally listing many bones as candidates for colliding with and hurting other characters. We do not want to add glass_break to all these bones, so we use the same patching code as for blownups, adding glass_break to Head and RightFoot.

Type 3:
Pattern: TRAM*knockdown*
Matches: 13 files
Purpose: Like blownups above, knockdown animations have no existing Attack data. We don't want to use the exact code that we used for blownups, though, because the feet are unlikely to strike glass when the character falls down (this animation is also used much more frequently, so it is more important to be sparing with the particle). Therefore, we just add glass_break to Head for the duration of the animation.

Type 4:
Pattern: TRAM*comb*, TRAM*kick*, TRAM*punch*, TRAM*getup_k*, TRAM*getupfront*, TRAM*slide*
Matches: 78 + 166 + 137 + 12 + 17 + 99 files (509 total)
Purpose: The attack animations in Oni are captured by these patterns. Here, we look at what bones are used in the Attack in order to tell which bones might strike glass — but we need to be selective. E.g., Mutant Muro's heavy kick, TRAMMUTCOMkick_heavy (this is the butt slam attack) uses both the left and right thighs, calves, and feet for collision, for a total of six bones. The patch code for Type 4 determines which bones are outermost for each extremity used in the attack; in this case, it will determine that they are LeftFoot and RightFoot. Once the outermost bones are determined, glass_break is added to each of them, for the same duration as the attack's collision, e.g. frames 43-48.
         In order to avoid particle overload, the patch has two safety measures. First, it will not add particles to an animation past a total count of 16 (including dust, contrails, etc.), because >16 particles in a TRAM will crash Oni. Secondly, the patch starts off by removing all existing glass_break particles listed for the animation. In previous versions of the Anniversary Edition, a set of TRAMs was distributed that had been edited by an automated tool to include glass_break. This tool did not hesitate to add glass_break for all attacking bones, and some of these modded TRAMs were used as the basis for new TRAMs made for new characters. Thus, we need to clear any existing glass_break assignments before adding them to the outermost bones as described above.

Type 5:
Pattern: TRAMKONCOMrun_throw_fw
Matches: 1 file
Purpose: This patch runs only for one animation, Konoko's Lariat. It is the only notable throw animation which has an attack component (not to be confused with throw target animations, which all have attack components), therefore no other throws need to be patched. This "throw" allows Konoko to kick nearby enemies while swinging around a victim's neck, so her feet have been assigned as attack bones. For this attack we do not need JavaScript because we know what to expect from this one animation. We simply add glass_break to LeftFoot for frames 29-39, matching the duration of the attack data for her feet.