XML:Basic tutorial

This page contains information that is out of date. Please update this information to reflect where the community is at today.

XML modding with the Anniversary Edition

First off, we'll assume that you understand the material in the Modding Oni article. This tutorial is written with the Anniversary Edition in mind, because the AE installs the modding tools you need, gives you the framework for testing your mod package, and globalizes more of Oni's data so it can be used in any level.

What is XML, first of all?

EXtensible Markup Language is a plain-text file format designed to be both human-readable and machine-readable. It stores data in-between tags, e.g. Some data here., and these tags can be arranged in a hierarchy to keep things organized. The only technical difference between a normal text file and an XML file is that the file ends in ".xml" instead of ".txt" and that it typically begins with the string <?xml version="1.0" encoding="UTF-8" ?>. While you thus could easily make an XML file by hand in any text editor, there are programs listed below which are better suited for easy XML editing.

Okay, so what is XML modding?

XML modding is the process of using OniSplit to export "binary data" -- raw Oni resource data -- into human-readable XML, which allows much easier modding, then importing that data back into Oni. Media resource types with XML support may extract as a standard format file (e.g. PNG) with an XML file alongside it. The list of file types with XML support can be seen HERE. Below are instructions for doing this manually on the command line as well as an illustrated guide on how to do this more easily with a GUI.

Is XML modding the same thing as this XML patch modding?

Not quite; XML patching is based on XML modding, though. Once you understand everything on this page, read Making a patch mod to learn about patch mods.

So I just export some data to XML and start editing, right?

Not so fast! A lot of the data is too complex to be self-explanatory in the XML format. You need to read the XML File Types page to learn how the game data is interrelated and what it all does.

What tools do I need?

OniSplit will be your main tool. XmlTools is also needed for making XML patch mods. Installing the AE will automatically install these tools, and will update a tool whenever the AE Installer runs and detects a new version of one.

Note that OniSplit cannot be opened by simply double-clicking it; it's a command-line tool. But you are lucky -- we now have a GUI for it: Vago. It's best to install Vago through the AEI Tools menu.

What kinds of mods can I make?

We can now make completely new levels. If you need some ideas, a few can be found on the Modding Brainstorms page.

I want to modify the files in Chapter X. What level file is that?

See the GameDataFolder page.

XML beginner tutorial

Mac:		PC:
converting an ONI file into an XML file
Open Edition's AETools_Data folder and create a new folder named "ONIfiles". Run AETools, choose "Extract" tab. Click on checkbox "Expract as .xml file". Then click on "Extract .oni file(s)" and choose "ONCCk4_L.oni". See "XMLfiles" in "AETools_Data". There you should find "ONCCk4_L.xml".		Open Edition's GameDataFolder and create two new folders named "XML" and "ONI". Run the GUI, choose "ONI - XML" tab and its upper section. Click first browse button and search for "ONCCk4_L.oni" inside the level0_Characters folder. Click second browse button and choose the XML folder as target. Now click on Convert button.
modifing the XML file
Open the extracted file with a simple text editor. Search for "HasSupershield" tag and set its value to "1". Save file.		Open the extracted file with a simple text editor. Search for "HasSupershield" tag and set its value to "1". Save file.
creating the ONI file
Choose "Convert" tab. Now click onto "Select File(s) for Conversion" button and mark "ONCCk4_L.xml". Click "Choose" button. Then click "Select Destination Folder". Search for your ONIfiles folder, mark it, and click "Choose button." Made a mistake when modified the XML file? The terminal window would appear now and telling you the trouble making line. Find the line in you XML file and fix it. Line number isn't always accurate. (It can shift - often by 1.) Then try again creating the file.		Goto "XML -> ONI" section. Click first browse button and search for "ONCCk4_L.xml" inside the XML folder. Click second browse button and choose the ONI folder as target. Now click on Convert button. Try THIS method if no oni file was created. Use then "onisplit -create ONI XML/ONCCk4_L.xml" and look for error messages. Find the line in you XML file and fix it. Line number isn't always accurate. (It can shift - often by 1). Then try again creating the file.
creating and installing a mod package
Choose "Package" tab. The GUI is actually pretty much self-explaining. Fill the editboxes with following: 90000 Test [Test] 1 That's a package to test new mods. YourNameHere Then click "Create package" button and search for your ONIfiles folder. Mark it and click "Choose" button. AEInstaller should automatically open now, select your test package. Hit "Install!" button.		Click on GUI's "AE Package" tab. The GUI is actually pretty much self-explaining. Fill the editboxes with following: 90000 Test [Test] 1 That's a package to test new mods. YourNameHere Browse Edition's GameDataFolder and choose the ONI folder as source folder. Browse Edition's install folder and choose the package folder as target. Open AEInstaller and select your test package. Hit "Install!" button.
testing the modification
Let's test our modification. Therefore we start TCTF HQ redux (pre-last level). The supershield becomes automatically switched on at 51% overpower (301 healh points). "chenille" cheat works too.		Let's test our modification. Therefore we start TCTF HQ redux (pre-last level). The supershield becomes automatically switched on at 51% overpower (301 healh points). "chenille" cheat works too.

Important tips for working with XML files

• Capitalization matters: OniSplit is case-sensitive when it processes the XML.
• Text indentation: most tags have some indentation (tabs). It is not needed by OniSplit but it helps one get an understanding of the hierarchy. Example:

good:

   <Instance id="4" type="IGSA">
       <Strings>
           <Link>#7</Link>
       </Strings>
   </Instance>

bad:

   <Instance id="4" type="IGSA"><Strings><Link>#7</Link></Strings></Instance>

• Code folding: A simple text editor (and good use of the search function) is actually enough to work with Oni's XML. But big files might be easier to handle with what programmers call "code folding". Code folding is found in IDEs like Microsoft Visual Studio (Windows) and Xcode (Mac). Both are free.

This allows you to fold whole instances and parent tags. Folded code can be previewed in Microsoft Visual Studio applications. Xcode provides an extra scroll popup.

Windows

Windows

Macintosh (Xcode)

Extracting XMLs from the Mac command line (the Terminal)

Put the newest OniSplit.exe into the "Oni/GameDataFolder" folder.

Open the Terminal program then "change directory" to the GameDataFolder (Type "cd " then drag the GameDataFolder into the Terminal window, now press the RETURN key)

At this point you can enter the OniSplit commands, such as:

   mono onisplit.exe -extract:xml xml_dir level0_Final/ONCCkonoko*.oni

("ONCCkonoko_generic" will be extracted in new folder "GameDataFolder/xml_dir".)