XmlTools/Full documentation

Overview

This page describes all XmlTools options with examples. It is needed to avoid too much content in the XmlTools main page.

Command-line operations

--add-values

Description

This operation allows you to add new XML values to existing XML elements. The values should be space separated and contained within quotes.

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

Example

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

XmlTools command:

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

XML Original	XML After Command
<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 existing XML elements. The values to remove should be space separated and contained within quotes.

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

Example

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

XmlTools command:

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

XML Original	XML After Command
<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 replace 1 XML value from existing XML elements.

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

Example

Let's say you want to swap all the w1_tap weapons from characters 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 Original	XML After Command
<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 all the XML values from existing XML elements. 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 the flags in all characters by 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 Original	XML After Command
<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 update all values in a set of existing XML elements. The values 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 on Google Sketchup. Inside the level you have positioned all the characters that are spawn during the gameplay. However for some reason you need to change the position of the level and the character accordingly. You can move the level inside the level editor, while the positions of the character can be updated using XmlTools.

You know the difference between the old level position and the new level position is 130 in X, 80 in Y and 0 in Z.

XmlTools command:

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

XML Original	XML After Command
<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 tanker forward throw to a new character. You know that your new character has higher pelvis than the tanker, so you need to update all the heights of tanker animation to match those of your new character.

We also know that difference between tanker animation (old value) and your character's (new value) is -0.7970685.

XmlTools command:

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

XML Original	XML After Command
<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 XML elements.

Usage: XmlTools --invert-elements

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 from down to above to reach the compound higher spot then it goes down again. If we invert the helicopter animation it will come from above to down and then to above again (which what was did in 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 invert correctly the animation you will need to invert Rotation element too.

XmlTools command:

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

XML Original

XML After Command

<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

@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.

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 by "2.0" it 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 <xml> and </xml> tags as seen bellow.

Usage:

@ADD_INSIDE_NODES

<xml>

XML to insert

</xml>

Example

Let's say your want do 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 Original	XML After Command
<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 to remove existing XML nodes.

Usage: @REMOVE_NODES

Example

Let's say your want do 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 Original	XML After Command
<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 your want to perform the same operation in --add-values example. This operation adds the Unkillable and the NonCombatant flag to A_L18 character.

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 (allows XmlTools differentiate from the other single quotes around command line options).

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

@CUSTOM_CODE

Description

This operation allows you to use JavaScript to edit XML. You should use this option only as last resort, because it is MUCH slower than all the other native options.

You can use this for complex logics and mathematical operations.

Usage:

@CUSTOM_CODE

<code>

JavaScript for XML editing

</code>

You can return prematurely from the JavaScript code using the return keyword. It is also possible 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 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.

XmlTools uses the JSXML XML Tools JavaScript libraries to allow you to edit XML. You can read it documentation in its website or [ here].