XmlTools/Full documentation: Difference between revisions

Latest revision as of 12:20, 5 April 2021

This page lists all XmlTools commands with examples. It is the full version of the documentation of XmlTools options found on the main page. The main page also offers a beginner's guide to this program's syntax and links to pages that explain the concepts behind XML modding.

Command-line operations

These are the commands that you can pass to XmlTools when directly calling it from the command line.

--add-values

Description

This operation allows you to add new XML values to an existing XML element that contains a list of values. The values should be space-separated and contained within quotes.

Oni's game data contains various bitsets that are used to indicate the on/off status of attributes that can pertain to that object. For instance, characters in the game can have various flags such as Unkillable turned on for them. In OniSplit's XML output of this data, the flags are given names and listed within quotes as a single string. --add-values and --remove-values were designed to edit these XML representations of bitsets.

Usage: XmlTools --add-values --new-val "new values"

Example

Let's say you want to add the Unkillable and NonCombatant flags to character A_L18.

XmlTools command:

XmlTools --add-values --new-val "Unkillable NonCombatant" --xpath-expression "/Oni/Objects/CHAR[@Id='3926']/OSD/Flags" --files "BINACJBOCharacter.xml"

XML Before

XML After

<Oni>
     <Objects>
           <CHAR Id="3926">
                 <Header>
                 <Flags />
                 <Position>-37.3426628 756 -491.6369</Position>
                 <Rotation>0 221.15564 0</Rotation>
                 </Header>
                 <OSD>
                       <Flags>NotInitiallyPresent</Flags>
                       <Class>TCTF_lite_1</Class>
                       <Name>A_L18</Name>
                       <Weapon>w8_mbo</Weapon>
                 ...
                 </OSD>
           </CHAR>
     ...
     </Objects>
</Oni>

<Oni>
     <Objects>
           <CHAR Id="3926">
                 <Header>
                 <Flags />
                 <Position>-37.3426628 756 -491.6369</Position>
                 <Rotation>0 221.15564 0</Rotation>
                 </Header>
                 <OSD>
                       <Flags>NotInitiallyPresent Unkillable NonCombatant</Flags>
                       <Class>TCTF_lite_1</Class>
                       <Name>A_L18</Name>
                       <Weapon>w8_mbo</Weapon>
                 ...
                 </OSD>
           </CHAR>
     ...
     </Objects>
</Oni>

--remove-values

Description

This operation allows you to remove XML values from an existing XML element that contains a list of values. The values should be space-separated and contained within quotes.

Oni's game data contains various bitsets that are used to indicate the on/off status of attributes that can pertain to that object. For instance, characters in the game can have various flags such as Unkillable turned on for them. In OniSplit's XML output of this data, the flags are given names and listed within quotes as a single string. --add-values and --remove-values were designed to edit these XML representations of bitsets.

Usage: XmlTools --remove-values --current-val "current values to remove"

Example

Let's say you want to remove the UpgradeDifficulty and InfiniteAmmo flags from character D_S82.

XmlTools command:

XmlTools --remove-values --current-val "UpgradeDifficulty InfiniteAmmo" --xpath-expression "/Oni/Objects/CHAR[@Id='7643']/OSD/Flags" --files "BINACJBOCharacter.xml"

XML Before

XML After

<Oni>
     <Objects>
           <CHAR Id="7643">
                 <Header>
                 <Flags />
                 <Position>173.626175 0 36.94594</Position>
                 <Rotation>0 134.847549 0</Rotation>
                 </Header>
                 <OSD>
                       <Flags>NotInitiallyPresent UpgradeDifficulty InfiniteAmmo</Flags>
                       <ClassTCTF_swat_1</Class>
                       <Name>D_S82</Name>
                       <Weapon>w3_phr</Weapon>
                 ...
                 </OSD>
           </CHAR>
     ...
     </Objects>
</Oni>

<Oni>
     <Objects>
           <CHAR Id="7643">
                 <Header>
                 <Flags />
                 <Position>173.626175 0 36.94594</Position>
                 <Rotation>0 134.847549 0</Rotation>
                 </Header>
                 <OSD>
                       <Flags>NotInitiallyPresent</Flags>
                       <ClassTCTF_swat_1</Class>
                       <Name>D_S82</Name>
                       <Weapon>w3_phr</Weapon>
                 ...
                 </OSD>
           </CHAR>
     ...
     </Objects>
</Oni>

--replace-value

Description

This operation allows you to execute a find/replace on existing XML elements, changing one specific value to another.

Usage: XmlTools --replace-value --current-val "currentValue" --new-val "newValue"

Example

Let's say you want to find all the w1_tap weapons currently assigned to characters and change them to w8_mbo.

XmlTools command:

XmlTools --replace-value --current-val "w1_tap" --new-val "w8_mbo" --element-name "Weapon" --parent-element-name "OSD" --files "BINACJBOCharacter.xml"

XML Before

XML After

<Oni>
     <Objects>
           <CHAR Id="7209">
                 <Header>
                 <Flags />
                 <Position>434.9334 756 -231.2183</Position>
                 <Rotation>0 258.058838 0</Rotation>
                 </Header>
                 <OSD>
                       <Flags>NotInitiallyPresent</Flags>
                       <Class>TCTF_lite_1</Class>
                       <Name>l7</Name>
                       <Weapon>w1_tap</Weapon>
                 ...
                 </OSD>
           </CHAR>
     ...
     </Objects>
</Oni>

<Oni>
     <Objects>
           <CHAR Id="7209">
                 <Header>
                 <Flags />
                 <Position>434.9334 756 -231.2183</Position>
                 <Rotation>0 258.058838 0</Rotation>
                 </Header>
                 <OSD>
                       <Flags>NotInitiallyPresent</Flags>
                       <Class>TCTF_lite_1</Class>
                       <Name>l7</Name>
                       <Weapon>w8_mbo</Weapon>
                 ...
                 </OSD>
           </CHAR>
     ...
     </Objects>
</Oni>

--replace-all-values

Description

This operation allows you to replace the values on all matching XML elements regardless of their current value (unlike --replace-value). The new values should be space-separated and contained within quotes.

Usage: XmlTools --replace-all-values --new-val "new values"

Example

Let's say you want to replace all existing character flags with the InfiniteAmmo and NotInitiallyPresent flags.

XmlTools command:

XmlTools --replace-all-values --new-val "NotInitiallyPresent InfiniteAmmo" --element-name "Flags" --parent-element-name "OSD" --files "BINACJBOCharacter.xml"

XML Before

XML After

<Oni>
     <Objects>
           <CHAR Id="7643">
                 <Header>
                 <Flags />
                 <Position>173.626175 0 36.94594</Position>
                 <Rotation>0 134.847549 0</Rotation>
                 </Header>
                 <OSD>
                       <Flags>NoAutoDrop UpgradeDifficulty CanSpawnMultiple</Flags>
                       <ClassTCTF_swat_1</Class>
                       <Name>D_S82</Name>
                       <Weapon>w3_phr</Weapon>
                 ...
                 </OSD>
           </CHAR>
     ...
     </Objects>
</Oni>

<Oni>
     <Objects>
           <CHAR Id="7643">
                 <Header>
                 <Flags />
                 <Position>173.626175 0 36.94594</Position>
                 <Rotation>0 134.847549 0</Rotation>
                 </Header>
                 <OSD>
                       <Flags>NotInitiallyPresent InfiniteAmmo</Flags>
                       <ClassTCTF_swat_1</Class>
                       <Name>D_S82</Name>
                       <Weapon>w3_phr</Weapon>
                 ...
                 </OSD>
           </CHAR>
     ...
     </Objects>
</Oni>

--update-elements

Description

This operation allows you to offset the values in a set of existing XML elements by specified amounts. The value differences must be space-separated and contained within quotes.

Usage: XmlTools --update-elements --diff-old-new-val "differences old-new values"

Examples

Example 1

Let's say you have a level built in a 3D modeling program and you have already set the positions in the BINACBJOCharacter file for all the characters that are to be spawned during the gameplay. However, for some reason you need to change the position of the level in the modeling program, which means that the character spawn locations are now incorrect. --update-elements provides the means for correcting them.

Let's say that you know that the (x, y, z) difference between the old level's position and the new level's position is, in Oni's world units, {130, 80, 0}. Those offsets can be deducted from each spawn location.

XmlTools command:

XmlTools --update-elements --diff-old-new-val "130 80 0" --element-name "Position" --parent-element-name "Header" --files "BINACJBOCharacter.xml"

XML Before

XML After

<Oni>
     <Objects>
           <CHAR Id="3873">
                 <Header>
                 ...
                 <Position>227.145248 756 -403.65567</Position>
                 ...
                 </Header>
                 ...
           </CHAR>
           <CHAR Id="3922">
                 <Header>
                 ...
                 <Position>501.63855 756 223.189484</Position>
                 ...
                 </Header>
                 ...
           </CHAR>
           <CHAR Id="3926">
                 <Header>
                 ...
                 <Position>-37.3426628 756 -491.6369</Position>
                 ...
                 </Header>
                 ...
           </CHAR>
           ...
     ...
     </Objects>
</Oni>

<Oni>
     <Objects>
           <CHAR Id="3873">
                 <Header>
                 ...
                 <Position>97.145248 676 -403.65567</Position>
                 ...
                 </Header>
                 ...
           </CHAR>
           <CHAR Id="3922">
                 <Header>
                 ...
                 <Position>371.63855 676 223.189484</Position>
                 ...
                 </Header>
                 ...
           </CHAR>
           <CHAR Id="3926">
                 <Header>
                 ...
                 <Position>-167.342663 676 -491.6369</Position>
                 ...
                 </Header>
                 ...
           </CHAR>
           ...
     ...
     </Objects>
</Oni>

Example 2

Let's say you want to use the Tanker's forward throw attack with a new character. You know that your new character has a higher pelvis than the Tanker, which means that you need to alter the height values in every frame of the Tanker's TRAM data to match those of your new character.

Let's say that we know the difference between the pelvis height of the Tanker and your character is -0.7970685 (that is, the values that we are about to alter are this much less than what they should be). This number will be added to each value in the named XML elements.

XmlTools command:

XmlTools --update-elements --diff-old-new-val "-0.7970685" --element-name "Height" --parent-element-name "Heights" --files "TRAMTANCOMthrow_fw.xml"

XML Before

XML After

<Oni>
     <Animation>
           ...
           <Heights>
                 <Height>9.12794</Height>
                 <Height>9.25521</Height>
                 <Height>9.401095</Height>
                 <Height>9.556288</Height>
                 <Height>9.711483</Height>
                 <Height>9.857368</Height>
                 <Height>9.984637</Height>
                 <Height>10.0839806</Height>
                 ...
           <Heights>
           ...
     </Animation>
</Oni>

<Oni>
     <Animation>
           ...
           <Heights>
                 <Height>9.9250085</Height>
                 <Height>10.0522785</Height>
                 <Height>10.1981635</Height>
                 <Height>10.3533565</Height>
                 <Height>10.5085515</Height>
                 <Height>10.6544365</Height>
                 <Height>10.7817055</Height>
                 <Height>10.8810491</Height>
                 ...
           <Heights>
           ...
     </Animation>
</Oni>

--invert-elements

Description

This operation allows you to invert a set of values in XML elements, for example, reversing the motion of an animation by flipping its frame values from 1, 2, 3 to 3, 2, 1.

Usage: XmlTools --invert-elements

Example

Let's say you want to invert the helicopter animation from Oni's final level. You'll notice that the helicopter comes up from below to land on the satellite dish platform, and then it goes down again. If we invert the helicopter animation, it will come down from above, and then go back up again (which is exactly what was done in the Old China mod).

For simplicity we will only edit one part of the helicopter animation: 'heli_interior09' and its Translation (position) element. Please note that to correctly invert the animation, you will need to invert the Rotation element too.

XmlTools command:

XmlTools --invert-elements --element-name "Translation" --files "OBANheli_interior09.xml"

XML Before

XML After

<Oni>
     <OBAN id="0">
           ...
                 <OBANKeyFrame>
                       ...
                       <Translation>-184.349075 1312.973 -3162.01733</Translation>
                       ...
                 </OBANKeyFrame>
                 <OBANKeyFrame>
                       ...
                       <Translation>-184.330032 1336.40686 -3162.01978</Translation>
                       ...
                 </OBANKeyFrame>
                 ...
                 <OBANKeyFrame>
                       ...
                       <Translation>-185.234482 1465.60852 -3060.43579</Translation>
                       ...
                 </OBANKeyFrame>
                 <OBANKeyFrame>
                       ...
                       <Translation>-185.233032 1465.56641 -3060.47461</Translation>
                       ...
                 </OBANKeyFrame>
           ...
     </OBAN>
</Oni>

<Oni>
     <OBAN id="0">
           ...
                 <OBANKeyFrame>
                       ...
                       <Translation>-185.233032 1465.56641 -3060.47461</Translation>
                       ...
                 </OBANKeyFrame>
                 <OBANKeyFrame>
                       ...
                       <Translation>-185.234482 1465.60852 -3060.43579</Translation>
                       ...
                 </OBANKeyFrame>
                 ...
                 <OBANKeyFrame>
                       ...
                       <Translation>-184.330032 1336.40686 -3162.01978</Translation>
                       ...
                 </OBANKeyFrame>
                 <OBANKeyFrame>
                       ...
                       <Translation>-184.349075 1312.973 -3162.01733</Translation>
                       ...
                 </OBANKeyFrame>
           ...
     </OBAN>
</Oni>

Patch file operations

XmlTools has a special set of commands that can be listed within a plain-text file to be executed all at once. These commands were designed for use with the AE Installer and revolve around making larger or more complex changes to the data that can only be easily conveyed to XmlTools in a text file. Since one of the following commands allows you to use any of the operations listed in the "Command-line operations" section, all the above functionality is accessible here too. See the main page for the syntax of supplying a patch file to XmlTools.

@XML_TOOLS

Description

This operation allows you to specify options related to running XmlTools. Currently the only option available is "Version", which allows you to supply the minimum version of XmlTools that is required to apply the patch file.

Usage: @XML_TOOLS Version "XmlToolsVersion"

Example

Let's say your patch is only compatible with XmlTools 2.0.

XmlTools patch command:

@XML_TOOLS Version "2.0"

Note that "2.0" means that it is also compatible with XmlTools 2.0a, 2.0b, etc.

@ADD_INSIDE_NODES

Description

This operation allows you to insert a block of new XML into existing XML nodes. The XML to be inserted must be wrapped in <xml>...</xml> tags as seen below.

Usage:

@ADD_INSIDE_NODES

<xml>

XML to insert

</xml>

Example

Let's say you want to add a new glass particle to the SWAT Griffin ONCC.

XmlTools patch command:

@ADD_INSIDE_NODES ElementName "Particles" ParentElementName "ONCP" Files "ONCCgriffin_swat.xml"
<xml>
    <ONCPParticle>
         <Name>glass_break</Name>
         <Type>glass_break</Type>
         <BodyPart>None</BodyPart>
    </ONCPParticle>
</xml>

XML Before

XML After

<Oni>
     ...
     <ONCP id="3">
           <Particles>
                 ...
                 <ONCPParticle>
                     <Name>glow</Name>
                     <Type>h2h_griglow_e01</Type>
                     <BodyPart>None</BodyPart>
                 </ONCPParticle>
           <Particles>
     ...
     </ONCP>
</Oni>

<Oni>
     ...
     <ONCP id="3">
           <Particles>
                 ...
                 <ONCPParticle>
                     <Name>glow</Name>
                     <Type>h2h_griglow_e01</Type>
                     <BodyPart>None</BodyPart>
                 </ONCPParticle>
                 <ONCPParticle>
                     <Name>glass_break</Name>
                     <Type>glass_break</Type>
                     <BodyPart>None</BodyPart>
                 </ONCPParticle>
           <Particles>
     ...
     </ONCP>
</Oni>

@REMOVE_NODES

Description

This operation allows you to remove existing XML nodes.

Usage: @REMOVE_NODES

Example

Let's say you want to remove the glass particle from the SWAT Griffin ONCC.

XmlTools patch command:

@REMOVE_NODES XPathExpression "/Oni/ONCP/Particles/ONCPParticle[@Name = 'glass_break']" Files "ONCCgriffin_swat.xml"

XML Before

XML After

<Oni>
     ...
     <ONCP id="3">
           <Particles>
                 ...
                 <ONCPParticle>
                     <Name>glow</Name>
                     <Type>h2h_griglow_e01</Type>
                     <BodyPart>None</BodyPart>
                 </ONCPParticle>
                 <ONCPParticle>
                     <Name>glass_break</Name>
                     <Type>glass_break</Type>
                     <BodyPart>None</BodyPart>
                 </ONCPParticle>
           <Particles>
     ...
     </ONCP>
</Oni>

<Oni>
     ...
     <ONCP id="3">
           <Particles>
                 ...
                 <ONCPParticle>
                     <Name>glow</Name>
                     <Type>h2h_griglow_e01</Type>
                     <BodyPart>None</BodyPart>
                 </ONCPParticle>
           <Particles>
     ...
     </ONCP>
</Oni>

@COMMAND

Description

This operation allows you to use any of the command-line operations in a patch file.

Usage: @COMMAND Options "Command line operation"

Note: For command-line input operations which use quotes ("..."), replace the double quotes with single quotes ('...'). If any XPath expression also includes single quotes, you can double them (''...'') to allow XmlTools to process the command.

Example

Let's say you want to perform the same operation as in the --add-values example: adding the Unkillable and NonCombatant flags to character A_L18.

XmlTools patch command:

@COMMAND Options "--add-values --new-val 'Unkillable NonCombatant' --xpath-expression '/Oni/Objects/CHAR[@Id=''3926'']/OSD/Flags' --files 'BINACJBOCharacter.xml'"

Note that in the XPath expression we replace each single quote by two single quotes, allowing XmlTools to differentiate from the single quotes used around command line options).

The resulting XML file is exactly the same as in the --add-values example.

@CUSTOM_CODE

Description

This operation allows you to use JavaScript to edit XML. You can use this for complex logic and mathematical tasks which aren't supported by XmlTools' basic operations. You should only use this option as a last resort if you are using it for a patch mod, because it is MUCH slower than all the other native options. Try to optimize your code as much as possible, as the complexity of the code has a large effect on the overall speed of XmlTools in running JavaScript.

Usage:

@CUSTOM_CODE

<code>

JavaScript for XML editing

</code>

You can exit prematurely from the JavaScript code using the return keyword. It is also possible to output JavaScript variables to the console using the "echo" function: echo(var);. This function allows you to debug the code that you develop.

The $xmlData global variable contains the contents of the XML file on disk. After you modify the XML, update this variable again with the new XML in order for XmlTools to update the file on disk, otherwise your changes will not take effect.

XmlTools uses the JSXML XML Tools (http://www.petetracey.com/jsxml/index.html, dead link) JavaScript libraries to allow you to operate upon the XML. You can read its documentation on its website (http://www.petetracey.com/jsxml/documentation.html, dead link) or here.

Example

Let's say you want to double the ammo clips and energy cells to all characters that are on the TCTF team.

XmlTools patch command:

@CUSTOM_CODE Files "BINACJBOCharacter.xml"
<code>
      var myBuilder = new JSXMLBuilder();
      myBuilder.load($xmlData); // Load the XML of the file for editing using the global variable
      
      var elements = myBuilder.elements[0];
      
      var charactersNode = elements.childElement("Objects");
      
      var currAmmoElement, currCellsElement;
      				
      // Loop over all characters
      for (var i=0; (charactersNode.childElement(i)); i++){ // The condition checks if the 'i'th element exists (!= undefined)
      	
             var currChar=charactersNode.childElement(i);
             
             // Check if team is TCTF
             if(currChar.childElement("OSD").childElement("Team").text=="TCTF"){
                    	
                    // Get ammo and cell 'Use' XML elements
                    currAmmoElement=currChar.childElement("OSD").childElement("Inventory").childElement("Ammo").childElement("Use");
                    currCellsElement=currChar.childElement("OSD").childElement("Inventory").childElement("EnergyCell").childElement("Use");
                    
                    // Double the current amount of ammo and cells that the character can use
                    currAmmoElement.text=parseInt(currAmmoElement.text)*2;
                    currCellsElement.text=parseInt(currCellsElement.text)*2;
             }
      }

      $xmlData=myBuilder.generateXML(); // Update the global variable with the new XML to save changes
</code>

XML Before

XML After

<Oni>
     <Objects>
           ...
           <CHAR Id="3926">
                 ...
                 <OSD>
                       ...
                       <Name>A_L18</Name>
                       <Weapon>w8_mbo</Weapon>
                       <Inventory>
                             <Ammo>
                                   <Use>2</Use>
                                   ...
                             </Ammo>
                             <EnergyCell>
                                   <Use>0</Use>
                                   ...
                             </EnergyCell>
                       </Inventory>
                       <Team>TCTF</Team>
                 ...
                 </OSD>
           </CHAR>
           <CHAR Id="7684">
                 ...
                 <OSD>
                       ...
                       <Name>D_Sbo93</Name>
                       <Weapon>w1_tap</Weapon>
                       <Inventory>
                             <Ammo>
                                   <Use>3</Use>
                                   ...
                             </Ammo>
                             <EnergyCell>
                                   <Use>1</Use>
                                   ...
                             </EnergyCell>
                       </Inventory>
                       <Team>TCTF</Team>
                 ...
                 </OSD>
           </CHAR>
           <CHAR Id="7606">
                 ...
                 <OSD>
                       ...
                       <Name>D_N76</Name>
                       <Weapon />
                       <Inventory>
                             <Ammo>
                                   <Use>0</Use>
                                   ...
                             </Ammo>
                             <EnergyCell>
                                   <Use>2</Use>
                                   ...
                             </EnergyCell>
                       </Inventory>
                       <Team>Neutral</Team>
                 ...
                 </OSD>
           </CHAR>
           ...
     ...
     </Objects>
</Oni>

<Oni>
     <Objects>
           ...
           <CHAR Id="3926">
                 ...
                 <OSD>
                       ...
                       <Name>A_L18</Name>
                       <Weapon>w8_mbo</Weapon>
                       <Inventory>
                             <Ammo>
                                   <Use>4</Use>
                                   ...
                             </Ammo>
                             <EnergyCell>
                                   <Use>0</Use>
                                   ...
                             </EnergyCell>
                       </Inventory>
                       <Team>TCTF</Team>
                 ...
                 </OSD>
           </CHAR>
           <CHAR Id="7684">
                 ...
                 <OSD>
                       ...
                       <Name>D_Sbo93</Name>
                       <Weapon>w1_tap</Weapon>
                       <Inventory>
                             <Ammo>
                                   <Use>6</Use>
                                   ...
                             </Ammo>
                             <EnergyCell>
                                   <Use>2</Use>
                                   ...
                             </EnergyCell>
                       </Inventory>
                       <Team>TCTF</Team>
                 ...
                 </OSD>
           </CHAR>
           <CHAR Id="7606">
                 ...
                 <OSD>
                       ...
                       <Name>D_N76</Name>
                       <Weapon />
                       <Inventory>
                             <Ammo>
                                   <Use>0</Use>
                                   ...
                             </Ammo>
                             <EnergyCell>
                                   <Use>2</Use>
                                   ...
                             </EnergyCell>
                       </Inventory>
                       <Team>Neutral</Team>
                 ...
                 </OSD>
           </CHAR>
           ...
     ...
     </Objects>
</Oni>

@@ Line 1: / Line 1: @@
-This page lists all XmlTools commands with examples. It is the full version of the summary of XmlTools options found on the [[XmlTools|main page]]. The main page also offers a beginner's guide to this program's syntax and links to pages that explain the concepts behind XML modding.
+This page lists all XmlTools commands with examples. It is the full version of the documentation of XmlTools options found on the [[XmlTools|main page]]. The main page also offers a beginner's guide to this program's syntax and links to pages that explain the concepts behind XML modding.
 {{TOClimit|3}}
@@ Line 10: / Line 10: @@
 This operation allows you to add new XML values to an existing XML element that contains a list of values. The values should be space-separated and contained within quotes.
-Oni's game data contains various bitsets that are used to indicate the on/off status of attributes that can pertain to that object. For instance, characters in the game can have various flags such as Unkillable turned on for them. In OniSplit's XML output of this data, the flags are given names and listed within quotes as a single string. --add-values and --remove-values were designed to edit these XML representations of bitsets.
+Oni's game data contains various bitsets that are used to indicate the on/off status of attributes that can pertain to that object. For instance, characters in the game can have various flags such as Unkillable turned on for them. In OniSplit's XML output of this data, the flags are given names and listed within quotes as a single string. '''--add-values''' and '''--remove-values''' were designed to edit these XML representations of bitsets.
 Usage:
@@ Line 16: / Line 16: @@
 ====Example====
-Let's say you want to add the Unkillable and the NonCombatant flag to the character A_L18.
+Let's say you want to add the Unkillable and NonCombatant flags to character A_L18.
@@ Line 72: / Line 72: @@
 This operation allows you to remove XML values from an existing XML element that contains a list of values. The values should be space-separated and contained within quotes.
-Oni's game data contains various bitsets that are used to indicate the on/off status of attributes that can pertain to that object. For instance, characters in the game can have various flags such as Unkillable turned on for them. In OniSplit's XML output of this data, the flags are given names and listed within quotes as a single string. --add-values and --remove-values were designed to edit these XML representations of bitsets.
+Oni's game data contains various bitsets that are used to indicate the on/off status of attributes that can pertain to that object. For instance, characters in the game can have various flags such as Unkillable turned on for them. In OniSplit's XML output of this data, the flags are given names and listed within quotes as a single string. '''--add-values''' and '''--remove-values''' were designed to edit these XML representations of bitsets.
 <tt>Usage: XmlTools --remove-values --current-val "current values to remove"</tt>
@@ Line 255: / Line 255: @@
 ====Examples====
 =====Example 1=====
-Let's say you have a level built in a 3D modeling program and you have already set the positions in the BINACBJOCharacter file for all the characters that are to be spawned during the gameplay. However, for some reason you need to change the position of the level in the modeling program, which means that the character spawn locations are now incorrect. --update-elements provides the way to correct them.
+Let's say you have a level built in a 3D modeling program and you have already set the positions in the BINACBJOCharacter file for all the characters that are to be spawned during the gameplay. However, for some reason you need to change the position of the level in the modeling program, which means that the character spawn locations are now incorrect. '''--update-elements''' provides the means for correcting them.
-Let's say that you know that the difference between the old level's position and the new level's position is, in Oni's world units, {130, 80, 0} (in x, y, z order).
+Let's say that you know that the (x, y, z) difference between the old level's position and the new level's position is, in Oni's world units, {130, 80, 0}. Those offsets can be deducted from each spawn location.
 '''XmlTools command:'''
@@ Line 389: / Line 389: @@
 ====Example====
-Let's say you want to invert the helicopter animation from Oni's final level. If you notice, in that level the helicopter comes up from below to land on the satellite dish platform, and then it goes down again. If we invert the helicopter animation, it will come down from above, and then go back up again (which is exactly what was done in the Old China mod).
+Let's say you want to invert the helicopter animation from Oni's final level. You'll notice that the helicopter comes up from below to land on the satellite dish platform, and then it goes down again. If we invert the helicopter animation, it will come down from above, and then go back up again (which is exactly what was done in the Old China mod).
 For simplicity we will only edit one part of the helicopter animation: 'heli_interior09' and its Translation (position) element. Please note that to correctly invert the animation, you will need to invert the Rotation element too.
@@ Line 459: / Line 459: @@
 ==Patch file operations==
-XmlTools has a special set of commands that can be listed within a plain-text file to be executed all at once. One of these commands allows you to use any of the above command-line operations, and another command allows you to use JavaScript to modify the XML (for especially complex situations).
+XmlTools has a special set of commands that can be listed within a plain-text file to be executed all at once. These commands were designed for use with the AE Installer and revolve around making larger or more complex changes to the data that can only be easily conveyed to XmlTools in a text file. Since one of the following commands allows you to use any of the operations listed in the "Command-line operations" section, all the above functionality is accessible here too. See the [[XmlTools|main page]] for the syntax of supplying a patch file to XmlTools.
 ===@XML_TOOLS===
 ====Description====
-This operation allows to specify options related with the XmlTools program. Currently only allows to specify the minimum XmlTools version necessary to apply the patch file.
+This operation allows you to specify options related to running XmlTools. Currently the only option available is "Version", which allows you to supply the minimum version of XmlTools that is required to apply the patch file.
 Usage:
@@ Line 474: / Line 474: @@
 <pre>@XML_TOOLS Version "2.0"</pre>
-Note that by "2.0" it means that it is also compatible with XmlTools 2.0a, 2.0b etc.
+Note that "2.0" means that it is also compatible with XmlTools 2.0a, 2.0b, etc.
 ===@ADD_INSIDE_NODES===
 ====Description====
-This operation allows to insert new XML inside existing XML nodes. The XML to insert must be contained between <tt><xml></tt> and <tt></xml></tt> tags as seen bellow.
+This operation allows you to insert a block of new XML into existing XML nodes. The XML to be inserted must be wrapped in <tt><xml></tt>...<tt></xml></tt> tags as seen below.
 Usage:
@@ Line 491: / Line 491: @@
 ====Example====
-Let's say your want do add a new glass particle to the SWAT Griffin ONCC.
+Let's say you want to add a new glass particle to the SWAT Griffin ONCC.
 '''XmlTools patch command:'''
@@ Line 504: / Line 504: @@
 {| style="margin: 1em auto 1em auto;" <!-- Centers table -->
-! style="width: 50%;" | XML Original
+! style="width: 50%;" | XML Before
-! style="width: 50%;" | XML After Command
+! style="width: 50%;" | XML After
 |-
 |
@@ Line 546: / Line 546: @@
 ===@REMOVE_NODES===
 ====Description====
-This operation allows to remove existing XML nodes.
+This operation allows you to remove existing XML nodes.
 Usage:
@@ Line 552: / Line 552: @@
 ====Example====
-Let's say your want do remove the glass particle from the SWAT Griffin ONCC.
+Let's say you want to remove the glass particle from the SWAT Griffin ONCC.
 '''XmlTools patch command:'''
-  @REMOVE_NODES XPathExpression "/Oni/ONCP/Particles/ONCPParticle[Name = 'glass_break']" Files "ONCCgriffin_swat.xml"
+  @REMOVE_NODES XPathExpression "/Oni/ONCP/Particles/ONCPParticle[@Name = 'glass_break']" Files "ONCCgriffin_swat.xml"
 {| style="margin: 1em auto 1em auto;" <!-- Centers table -->
-! style="width: 50%;" | XML Original
+! style="width: 50%;" | XML Before
-! style="width: 50%;" | XML After Command
+! style="width: 50%;" | XML After
 |-
 |
@@ Line 600: / Line 600: @@
 ===@COMMAND===
 ====Description====
-This operation allows you to use any of the [[XmlTools#Command-line_operations|command line operations]] in a patch file.
+This operation allows you to use any of the [[XmlTools#Command-line_operations|command-line operations]] in a patch file.
 Usage:
 <tt>@COMMAND Options "Command line operation"</tt>
-Note: For command line input operations which use quotes ("") replace the double quotes with single quotes (<nowiki>''</nowiki>). If any XPath expression also includes single quotes you can double them to allow XmlTools to process the command.
+Note: For command-line input operations which use quotes ("..."), replace the double quotes with single quotes (<nowiki>'...'</nowiki>). If any XPath expression also includes single quotes, you can double them (<nowiki>''...''</nowiki>) to allow XmlTools to process the command.
 ====Example====
-Let's say your want to perform the same operation in [[#Example|--add-values example]]. This operation adds the Unkillable and the NonCombatant flag to A_L18 character.
+Let's say you want to perform the same operation as in the [[#Example|--add-values example]]: adding the Unkillable and NonCombatant flags to character A_L18.
 '''XmlTools patch command:'''
   @COMMAND Options "--add-values --new-val 'Unkillable NonCombatant' --xpath-expression '/Oni/Objects/CHAR[@Id=<nowiki>''3926''</nowiki>]/OSD/Flags' --files 'BINACJBOCharacter.xml'"
-Note that in the XPath expression we replace each single quote by two single quotes (allows XmlTools differentiate from the other single quotes around command line options).
+Note that in the XPath expression we replace each single quote by two single quotes, allowing XmlTools to differentiate from the single quotes used around command line options).
-The resulting XML file is exactly the same of [[#Example|--add-values example]].
+The resulting XML file is exactly the same as in the [[#Example|--add-values example]].
 ===@CUSTOM_CODE===
 ====Description====
-This operation allows you to use [[wikipedia:JavaScript|JavaScript]] to edit XML.
+This operation allows you to use [[wikipedia:JavaScript|JavaScript]] to edit XML. You can use this for complex logic and mathematical tasks which aren't supported by XmlTools' basic operations. <u>You should only use this option as a '''last resort'''</u> if you are using it for a [[Making a patch mod|patch mod]], because it is '''MUCH slower''' than all the other native options. Try to <u>optimize your code as much as possible</u>, as the complexity of the code has a large effect on the overall speed of XmlTools in running JavaScript.
-You can use this for complex logics and mathematical operations which aren't supported in other native operations.
-<u>You should only use this option as '''last resort'''</u> if you are using it for [[Anniversary_Edition/Framework#XML_patching|AE Patches]], because it is '''MUCH slower''' than all the other native options. Try <u>maintain your code as optimized as possible</u>, as the user code also highly affects the XmlTools performance while applying the patch.
 Usage:
@@ Line 635: / Line 631: @@
 <tt><nowiki></code></nowiki></tt>
-You can exit prematurely from the JavaScript code using the <tt>return</tt> keyword. It is also possible output JavaScript variables to the console using the echo function: <tt>echo(var);</tt>. This function allows you to debug the code that you develop.
+You can exit prematurely from the JavaScript code using the <tt>return</tt> keyword. It is also possible to output JavaScript variables to the console using the "echo" function: <tt>echo(var);</tt>. This function allows you to debug the code that you develop.
-The <tt>$xmlData</tt> global variable contains the XML of the current file. After you modify the XML, update this variable again with the new XML in order to XmlTools update correctly the file.
+The <tt>$xmlData</tt> global variable contains the contents of the XML file on disk. After you modify the XML, update this variable again with the new XML in order for XmlTools to update the file on disk, otherwise your changes will not take effect.
-XmlTools uses the [http://www.petetracey.com/jsxml/index.html JSXML XML Tools] JavaScript libraries to allow you to edit the XML. You can read it documentation in its [http://www.petetracey.com/jsxml/documentation.html website] or [http://script10k.oni2.net/documentation/xmltools/jsxml-documentation.htm here].
+XmlTools uses the JSXML XML Tools (<nowiki>http://www.petetracey.com/jsxml/index.html</nowiki>, dead link) JavaScript libraries to allow you to operate upon the XML. You can read its documentation on its website (<nowiki>http://www.petetracey.com/jsxml/documentation.html</nowiki>, dead link) or [http://script10k.oni2.net/documentation/xmltools/jsxml-documentation.htm here].
 ====Example====
-Let's say your want to add one additional ammo and cell to all characters that are from TCTF team.
+Let's say you want to double the ammo clips and energy cells to all characters that are on the TCTF team.
 '''XmlTools patch command:'''
@@ Line 657: / Line 653: @@
         <span style="color:green">// Loop over all characters</span>
-        for (var i=0; (charactersNode.childElement(i)); i++){ <span style="color:green">// the condition checks if the ith element exists (!= undefined)</span>
+        for (var i=0; (charactersNode.childElement(i)); i++){ <span style="color:green">// The condition checks if the 'i'th element exists (!= undefined)</span>
                var currChar=charactersNode.childElement(i);
-               <span style="color:green">// Check if it is TCTF</span>
+               <span style="color:green">// Check if team is TCTF</span>
                if(currChar.childElement("OSD").childElement("Team").text=="TCTF"){
@@ Line 668: / Line 664: @@
                       currCellsElement=currChar.childElement("OSD").childElement("Inventory").childElement("EnergyCell").childElement("Use");
-                      <span style="color:green">// Add +1 to the current amount of ammo and cells to use</span>
+                      <span style="color:green">// Double the current amount of ammo and cells that the character can use</span>
-                      currAmmoElement.text=parseInt(currAmmoElement.text)+1;
+                      currAmmoElement.text=parseInt(currAmmoElement.text)*2;
-                      currCellsElement.text=parseInt(currCellsElement.text)+1;
+                      currCellsElement.text=parseInt(currCellsElement.text)*2;
                }
         }
-        $xmlData=myBuilder.generateXML(); <span style="color:green">// update the global variable with the new XML</span>
+        $xmlData=myBuilder.generateXML(); <span style="color:green">// Update the global variable with the new XML to save changes</span>
   <nowiki></code></nowiki>
 {| style="margin: 1em auto 1em auto;" <!-- Centers table -->
-! style="width: 50%;" | XML Original
+! style="width: 50%;" | XML Before
-! style="width: 50%;" | XML After Command
+! style="width: 50%;" | XML After
 |-
 |
@@ Line 693: / Line 689: @@
                          <Inventory>
                                <Ammo>
-                                     <Use><span style="color:blue">'''0'''</span></Use>
+                                     <Use><span style="color:blue">'''2'''</span></Use>
                                      ...
                                </Ammo>
@@ Line 737: / Line 733: @@
                                </Ammo>
                                <EnergyCell>
-                                     <Use>'''0'''</Use>
+                                     <Use>'''2'''</Use>
                                      ...
                                </EnergyCell>
@@ Line 761: / Line 757: @@
                          <Inventory>
                                <Ammo>
-                                     <Use><span style="color:red">'''1'''</span></Use>
+                                     <Use><span style="color:red">'''4'''</span></Use>
                                      ...
                                </Ammo>
                                <EnergyCell>
-                                     <Use><span style="color:red">'''1'''</span></Use>
+                                     <Use><span style="color:red">'''0'''</span></Use>
                                      ...
                                </EnergyCell>
@@ Line 781: / Line 777: @@
                          <Inventory>
                                <Ammo>
-                                     <Use><span style="color:red">'''4'''</span></Use>
+                                     <Use><span style="color:red">'''6'''</span></Use>
                                      ...
                                </Ammo>
@@ Line 805: / Line 801: @@
                                </Ammo>
                                <EnergyCell>
-                                     <Use>'''0'''</Use>
+                                     <Use>'''2'''</Use>
                                      ...
                                </EnergyCell>

XmlTools/Full documentation: Difference between revisions

Latest revision as of 12:20, 5 April 2021

Command-line operations

--add-values

Description

Example

--remove-values

Description

Example

--replace-value

Description

Example

--replace-all-values

Description

Example

--update-elements

Description

Examples

Example 1

Example 2

--invert-elements

Description

Example

Patch file operations

@XML_TOOLS

Description

Example

@ADD_INSIDE_NODES

Description

Example

@REMOVE_NODES

Description

Example

@COMMAND

Description

Example

@CUSTOM_CODE

Description

Example

Navigation menu

Search