XmlTools

WARNING

THIS PAGE IS CURRENTLY BEING UPDATED TO THE NEW VERSION OF XMLTOOLS.

PLEASE WAIT UNTIL IS FINISHED BEFORE USING ITS DOCUMENTATION.

Overview

XmlTools is a command-line modding tool that operates on XML files, including those exported by OniSplit. It supports many operations in XML files and even non implemented operations using custom javascript code.

It is written in C++, works in both Mac OS X and Windows and is very efficient in terms of performance.

The initial version was written to help with the development of the Old China level mod and was also written in C# (previous 2.0) but later it was rewritten to C++ due to performance reasons. It was then developed further for the purposes of the AE so that resources could be patched smartly. To learn about the overall process, read Making a patch mod and AE Framework - XML patching.

XmlTools can be used as a standalone tool or as a base for another tools. It can be issued commands directly on the command-line interface (CLI) or passed a text file on the CLI with a list of commands to perform.

Links

• Download the tool in a standalone form here or download it using the AEI's Tool Manager.
• XmlTools is used along with OniSplit as the backend for the GUI tool Vago.

Features

• Update all values in a set of XML elements (e.g., repositioning an OBAN animation or adjusting the pelvis height of a TRAM).
• Inverts a set of XML elements (e.g., invert an OBAN animation).
• Add new values to a set of XML elements (e.g., add the 'unkillable' flag to some characters in a level).
• Remove values from a set of XML elements (e.g., remove boss shields from characters in a level).
• Replace values in a set XML elements (e.g., increase the health of characters by replacing the old HP value).
• Patch file support that allows the modder to list multiple commands in a file, to all be performed at once.
• Add new XML inside existing nodes (patch only).
• Remove XML nodes (patch only).
• Powerful custom XML editing using JavaScript (e.g., to employ complex logical or mathematical operations) (patch only).

• To select elements to the above operations it can be used the element name, parent element name, attribute name/value and XPath 1.0.

Syntax

You can find out the XmlTools options if you don't provide any or when using --help option. You can get the version with the option "--version". The commands below must be preceded by either XmlTools.exe (Windows) or ./XmlTools (Mac). If XmlTools is not in the current folder, you can provide the full/relative path to it or set the path variable. On the Mac, be sure to use / rather than \ in paths.

The basic syntax is:

Windows	XmlTools.exe --add-values --element-name "Weapon" --new-val "w1_tap" --files "BINACJBOCharacter.xml"
Mac	./XmlTools --add-values --element-name "Weapon" --new-val "w1_tap" --files "BINACJBOCharacter.xml"

Here's how it breaks down:

Invocation	Note that if XmlTools is not in the Command Prompt/Terminal's current directory, you must provide the full path to it or set the path variable.
Operation	The command to perform. Note the commands are prefaced by a --, some commands have a short version which is prefaced by a single - followed by a letter.
Operation Value	This is where you supply the value that this specific command needs. As seen below, --element-name requires the XML element name, so we provide that here. Quotes should be used when the value has spaces or to avoid Unix shell expansion.

Command-line options

You can use any of the following operations bellow with XmlTools. If you don't provide all the required options to an operation XmlTools will notice you.

Operations

-a, --add-values

Add new values to a set of XML elements;

--remove-values

Removes values from a set of XML elements;

--replace-value

Replaces 1 value in a set of XML elements;

--replace-all-values

Replaces all values in a set of XML elements;

-u, --update-elements

Updates all values in a set of XML elements;

-i, --invert-elements

Inverts a set of XML elements.

Operations inputs

-c, --current-val <current-val>

Current value(s) [use space as separator];

-n, --new-val <new-val>

New value(s) [use space as separator];

-d, --diff-old-new-val <diff-old-new-val>

Difference between old and new value;

--positions <positions>

Positions [use space as separator] [0-index based];

-f, --files <files>

XML files to process [wildcards supported];

-p, --patch-files <patch-files>

Patch files to process [wildcards supported];

--force-target-files <force-target-files>

Force the patch-files operation in the specified XML files. [wildcards supported];

-e, --element-name <element-name>

Name of the XML element(s) where processing will occur;

--parent-element-name <parent-element-name>

Name of the XML parent element of <element-name> [used as filter];

--attribute-name <attribute-name>

Attribute name of <element-name> [used as filter];

--attribute-value <attribute-value>

Attribute value of <attribute-name> [used as filter];

-x, --xpath-expression <xpath-expression>

XPath 1.0 expression to select elements where processing will occur;

--no-backups

No backups [faster processing];

--no-verbose

Reduce the number of text messages output [faster processing].

Patch file operations

Patch files are mainly used for two purposes: to create a list of commands within one file that you can pass to XmlTools to execute all at once, and to use JavaScript code to modify the XML.

To make a patch, create a plain-text file that uses the following commands and pass it to XmlTools using the patchfile command documented above. See HERE for instructions on making a patch mod package for the AE and HERE to learn how the AEI handles patch mods.

Arguments in square brackets are optional.

@ADDTO Element <quoted tag name> [ParentElement <quoted tag name>] [File <quoted file name>]

Adds the raw XML that follows to the named array tag.

@ADDTO Element "Particles"
<xml>
   <Particle>
      <Start>0</Start>
      <End>45</End>
      <Bone>Head</Bone>
      <Name>glass_break</Name>
   </Particle>
</xml>

@REMOVE Element <quoted tag name> [ParentElement <quoted tag name>] [File <quoted file name>]

Removes named element from the array tag named by ParentElement.

@COMMAND <command-line string>

Runs any of the commands available under "Command-line operations" above. Use standard command-line syntax described in that section, including -filename.

@COMMAND invert -element:Height -parelement:Heights -filename:test.xml

@CUSTOMCODE [File <quoted file name>]

Executes the JavaScript code inside a <code> tag. You should avoid this method when possible because it is much slower than the native XmlTools commands.

The XML library that you can use in your JavaScript code is called W3C DOM Parser and its documentation is available here. The most important thing to know about the DOM Parser is that the contents of the XML file are saved in the global variable $xmlData. So you will need to access it to edit the XML. Make sure that after the editing process you update $xmlData with the new XML so the file gets correctly edited.

Here is a sample usage for @CUSTOMCODE:

Sample XML file to be patched:

<Oni>
 <Animation>
   <Lookup>
     <Type>KickForward</Type>
     <AimingType>KickForward</AimingType>
     <FromState>RunBackStart</FromState>
     <ToState>Standing</ToState>
     <Varient>Combat</Varient>
     <FirstLevel>4</FirstLevel><!--The JavaScript code below will change this tag's value from 4 to 0-->
     ...
     </Lookup>
  </Animation>
</Oni>

XmlTools patch file contents:

@CUSTOMCODE
<code>
  var parser = new DOMImplementation(); // instantiate the W3C DOM Parser
  var domDoc = parser.loadXML($xmlData); // load the XML into the parser and get the DOMDocument, using $xmlData variable
  var levelNode = domDoc.getDocumentElement().getElementsByTagName("FirstLevel").item(0).firstChild;
  if (levelNode.toString() == "4")
     levelNode.setNodeValue("0"); // change level from 4 to 0
  $xmlData = domDoc.getDocumentElement().getXML(); // update the global variable with the new XML
</code>

Note that if you don't use the optional File <quoted file name> argument, the operation will be applied over all the XML files in the same directory as xmlTools.exe -- unless you used the -forceinfiles argument along with the patchfile command as described in that command's documentation. Note that the File argument allows wildcards ('*', '?').