XmlTools

This page is unfinished. Can you fill in any missing information? If it is not clear which part of the page is unfinished, ask on the talk page.

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 (Mono required) and Windows (.NET 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.

It can be used as a standalone tool or as a base for another tools.

Links

• Download the tool package here (actual program folder found inside the plain/xxx_only/Tools/ folder).
• XmlTools is used by the AEI to apply XML patches, as explained HERE.
• XmlTools is used along with OniSplit as the backend for the GUI tool Vago.

Features

• Modify a chain of values (for example, to reposition an OBAN animation or adjust pelvis height for a TRAM).
• Invert a chain of values (for example, invert an OBAN animation).
• Add new values to XML elements (for example, add the 'unkillable' flag to some characters in a level).
• Remove values from XML elements (for example, remove boss shields from characters in a level).
• Replace values in XML elements (for example, increase the health of characters by replacing the old HP value).
• Add custom XML to existing files (patch only)
• Remove XML from existing files (patch only)
• Patch file support allows the modder to list multiple commands in a file, on separate lines, to all be performed at once.

Using it

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.

Global arguments

You may use these arguments with each command listed in the next section:

-filename:<XML file>	Specifies file to modify (allows wildcards '*','?') (backup made by default) (when not used will apply the operation over all the xml files in the same directory of xmlTools.exe)	Optional
-element:<XML tag>	Specifies XML tag to look for in the file	Required
-parelement:<XML tag>	Specifies XML tag that contains -element tag to avoid override elements that have the same name but have different parent elements	Optional

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 "Min" elements by it's parent element. So you can use -element:Min -parelement:Pitch to refer to "Min" of "Pitch" element.

-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

Command-line operations

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

Update a XML 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 XML 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 errors numbers and they internal name

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

To create a list of commands within one file that you can pass to XmlTools to execute all at once, 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 for the AE.

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

Adds the raw XML that follows to the named array tag, e.g.:

@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, e.g.:

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

@CUSTOMCODE [File<quoted file name>]

Executes the javascript code inside the code tag, useful for complex XML editing (using loops and conditions for example). You should avoid this method because it is much more slower than the native XmlTools commands, so always which is possible edit your code using XmlTools commands.

The XML library that you can use in javascript code is called W3C DOM Parser and its documentation is available here.

The current file XML is saved at 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.

Usage example:

XML code:

<Oni>
 <Animation>
   <Lookup>
     <Type>KickForward</Type>
     <AimingType>KickForward</AimingType>
     <FromState>RunBackStart</FromState>
     <ToState>Standing</ToState>
     <Varient>Combat</Varient>
     <FirstLevel>4</FirstLevel> 
     ...
     </Lookup>
  </Animation>
</Oni>

Javascript code:

@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 specify the optional [File<quoted file name>] argument the operation will applied over all the XML files in the same directory of xmlTools.exe.

Also this [File<quoted file name>] allows wildcards ('*','?').