XmlTools

Overview

XmlTools is a command-line modding tool that operates on XML files, especially those exported by OniSplit. It was developed in C# and works in both Mac OS X (Latest Mono required) and Windows (.NET 3.5 required).

The initial version was written to help with the development of the Old China level mod. 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 Anniversary Edition/Framework#XML patching.

XmlTools can be used as a standalone tool or as a base for another tool. 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

• Modify a chain of values by supplying a new starting point for the chain (sample use: repositioning an OBAN animation or adjusting the pelvis height of a TRAM).
• Invert a chain of values (sample use: inverting an OBAN animation).
• Add new values into XML elements (sample use: adding an item to a space-separated list, i.e. adding to some characters in a level).
• Remove values from XML elements (sample use: removing boss shields from characters in a level).
• Replace values in XML elements (sample use: increasing the health of characters by replacing the old HP value).
• Add/remove XML elements (sample use: adding particles to an attack).
• Powerful custom XML editing using JavaScript (sample use: any time you need to insert XML dynamically based on what you find in the XML file, or employ logical or mathematical operations).
• Patch file support allows the modder to list multiple commands in a file, on separate lines, to all be performed at once.

Syntax

The following actions are listed when calling XmlTools with no options passed in. You can get the version with the argument "version". The commands below must be preceded by either xmlTools.exe (Windows) or mono xmlTools.exe (Mac). If xmlTools.exe 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 following instructions are for Windows by default.

The basic syntax is:

Windows	xmlTools.exe addvalue -value:"DropWeapon" -element:Flags -filename:TRAMSTRCOMhit_fallen1.xml
Mac	mono xmlTools.exe addvalue -value:"DropWeapon" -element:Flags -filename:TRAMSTRCOMhit_fallen1.xml

Here's how it breaks down:

Invocation	Windows can refer to the program directly, but Macs use Mono to run the .NET app; note also that if xmlTools.exe 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 that commands are not prefaced by a -, whereas the arguments supplied after the commands are.
Operation-specific argument(s)	This is where you supply the arguments that this specific command needs. As seen below, addvalue requires the value to add to a space-separated list, so we provide that here. Note the use of quotes as specified in the command's documentation below.
Global argument(s)	Make sure you specify the full path to the file if the file is not in the current directory. No quotes are used for these commands unless you need to pass a file name path with spaces in it.

Global command-line arguments

You may use these arguments with each command listed in the "Command-line operations" section below. Note that the -element is required in all CLI commands, otherwise you can't tell XmlTools what to modify.

(Optional)	-nobackups	XmlTools will not create a backup file (speeds up operations).
(Optional)	-debug	Not used yet. It will be probably used to output some debugging information in the future.
(Optional)	-filename:<XML file>	Specifies file to modify (allows wildcards '*','?') (backup made by default) (when not used, XmlTools will apply the operation over all the XML files in the same directory as xmlTools.exe).
(Required)	-element:<XML tag>	Specifies XML tag to look for in the file.
(Optional)	-parelement:<XML tag>	Specifies XML tag that contains -element tag to pick between elements that have the same name but have different parent elements.

-parelement

Let's say that an XML file has two tags with the same name, e.g.:

<xml>
    <Volume>
         <Min>1</Min>
         <Max>1</Max>
    </Volume>
    <Pitch>
         <Min>1</Min>
         <Max>1</Max>
    </Pitch>
<xml>

In the above code you can differentiate the two "Min" elements by their parent elements. So you can use -element:Min -parelement:Pitch to refer to the "Min" element under "Pitch".

Command-line operations

Arguments in square brackets are optional.

updatechainvalues -newvalue:<quoted string> [-valpositions:<quoted string>] [-valrelation:<quoted string>]

Update a value chain, starting at the -newvalue;

-valpositions (optional) is zero-indexed and can be a single value or a space-separated list, e.g. -valpositions=0 1 4;

-valrelation (optional) means ???.

invert

Inverts a value chain

addvalue -value:<quoted string>

Adds value or space-separated list of values into an element.

removevalue -value:<quoted string>

Removes value or space-separated list of values from an element.

replacevalue -oldvalue:<string> -newvalue:<string>

Replaces specified old value, if found, with new value.

replaceall -value:<string> [-valpositions:<quoted string>]

Replaces value in element with new value, no matter its previous value.

showerrtypes

Show error numbers and their internal names.

patchfile [-forceinfiles:<file names>]

Changes -filename argument to refer to a patch file and applies this patch to the specified files using the [File<quoted file name>] argument,

or to named files with -forceinfiles argument (allows wildcards '*','?'); see below for patch commands.

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. The File argument allows wildcards ('*', '?').