XML:Basic tutorial: Difference between revisions

From OniGalore
Jump to navigation Jump to search
m (trying out level 3 headers for FAQ, it worked well for my polylectiloquy; touching up code folding tips (I kind of like this part, honestly, let's keep it))
(→‎XML tutorial for Anniversary Edition: general touch-up, mentioning patch mods and removing AETools)
Line 1: Line 1:
{{update}}
{{update}}
==XML tutorial for Anniversary Edition==
==XML tutorial for Anniversary Edition==
This tutorial is written with the [[Anniversary Edition]] in mind, because it installs the modding tools you need, gives you the framework for making a mod package, and globalizes more data. Global data can be used in any level.
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 making a mod package, and globalizes more data. Global data can be used in any level.


===What is XML, first of all?===
===What is XML, first of all?===
Line 7: Line 7:


===Okay, so what is XML modding?===
===Okay, so what is XML modding?===
:In the old days, most of Oni's resources had to be edited by [[wikipedia:Hex editor|hex editor]]. Then [[User:Neo|Neo]], a fan and hacker, introduced XML exporting. This turns "binary data" -- raw Oni resource data -- into human-readable XML which allows much easier modding. You can then import your edited XML back into Oni's resource format with a simple command. The list of file types with XML support can be seen [[XML:File_types|HERE]].
:In the old days, most of Oni's resources had to be edited by [[wikipedia:Hex editor|hex editor]]. Then [[User:Neo|Neo]], writer of OniSplit, introduced XML exporting. This turns "binary data" -- raw Oni resource data -- into human-readable XML which allows much easier modding. You can then import your edited XML file back into Oni's resource format with a simple command. The list of file types with XML support can be seen [[XML:File_types|HERE]]. The instructions for doing this manually on the command line are found [[OniSplit#XML|HERE]], but there's a nice illustrated guide to doing this without the use of the command line below. Note: "XML modding" is not "XML patch modding". Once you understand everything on this page, read [[Making a patch mod|THIS]] page to learn how (and why) you can make a patch mod.


===So I just export some data to XML and start editing?===
===So I just export some data to XML and start editing?===
:Not so fast! A lot of the data is not that self-explanatory even as XML; it simply can't be, when the game engine is so complex. That's what the XML namespace on this wiki is for: documenting the game data tag by tag according to what you'll be seeing in the XML files, but just as importantly, explaining ''what all that data does''. That's important, because the wiki's original game data documentation in the [[OBD]] namespace was written for hackers and is lacking in plain-English explanation.
:Not so fast! A lot of the data is not that self-explanatory even as XML; it simply can't be, when the game engine is so complex. That's what the XML namespace on this wiki is for: documenting the game data tag by tag according to what you'll be seeing in the XML files, but just as importantly, explaining ''what all that data does''. That's important, because the wiki's original game data documentation in the [[OBD]] namespace was written for hackers and is lacking in plain-English explanations.


===Okay, what do I need to get started?===
===Okay, what do I need to get started?===
: [[OniSplit]] will be your main tool. [[xmlTools]] is also needed for making XML patch mods. Installing the [[AE]] is the recommended way to get these tools and a helpful framework installed.
: [[OniSplit]] will be your main tool. [[XmlTools]] is also needed for making XML patch mods. Installing the [[AE]] is the recommended way to get these tools and a helpful framework installed.


===I've got the AE installed. What now?===
===I've got the AE installed. What now?===
: OniSplit cannot be opened by simply double-clicking it; it's a command-line tool. But you are lucky -- we now have a [[wikipedia:GUI|GUI]] for it.
: OniSplit cannot be opened by simply double-clicking it; it's a command-line tool. But you are lucky -- we now have a [[wikipedia:GUI|GUI]] for it: [[Vago (tool)|Vago]]. It's best to install Vago through the [[AEI#Tools|AEI]].
:: Mac user will want to get '''"[[AE:Anniversary_Edition_Tools|AETools]]"'''
::: Install instructions are on same page.
:: Windows user will want to get '''"[http://oni.bungie.org/community/forum/viewtopic.php?id=692 OniSplit GUI]"''' or '''[http://oni.bungie.org/community/forum/viewtopic.php?id=2385 Vago GUI]'''
::: Unpack and put the executables into your "GameDataFolder" inside "edition" folder.


===What kinds of mods can I make?===
===What kinds of mods can I make?===

Revision as of 15:51, 14 April 2013


Aged parchment-60px.jpg

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

XML tutorial for 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 making a mod package, and globalizes more data. Global data 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 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?

In the old days, most of Oni's resources had to be edited by hex editor. Then Neo, writer of OniSplit, introduced XML exporting. This turns "binary data" -- raw Oni resource data -- into human-readable XML which allows much easier modding. You can then import your edited XML file back into Oni's resource format with a simple command. The list of file types with XML support can be seen HERE. The instructions for doing this manually on the command line are found HERE, but there's a nice illustrated guide to doing this without the use of the command line below. Note: "XML modding" is not "XML patch modding". Once you understand everything on this page, read THIS page to learn how (and why) you can make a patch mod.

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

Not so fast! A lot of the data is not that self-explanatory even as XML; it simply can't be, when the game engine is so complex. That's what the XML namespace on this wiki is for: documenting the game data tag by tag according to what you'll be seeing in the XML files, but just as importantly, explaining what all that data does. That's important, because the wiki's original game data documentation in the OBD namespace was written for hackers and is lacking in plain-English explanations.

Okay, what do I need to get started?

OniSplit will be your main tool. XmlTools is also needed for making XML patch mods. Installing the AE is the recommended way to get these tools and a helpful framework installed.

I've got the AE installed. What now?

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.

What kinds of mods can I make?

See HERE again. It's an overview of the kinds of resources that allow XML editing. But note that some types can be more difficult to mod than other.
If you need some ideas look at this page: modding brainstorms.
If you want to contribute AE: bug-fixes and feature requests.
Check also the AE's current To-Do page and maybe there are fields that need a modder.

Hmm, I want to modify the files in Chapter X. But what level file is that?

Check out this overview of Oni's game files.

Is there an easy exercise to get me started?

Just see at the following table. Read left side if you use a Macintosh PC, read right side if you use a Windows PC.
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".

XML_tutorial_mac_1C_TN.png 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.

XML_tutorial_1C_TN.png
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. XML_tutorial_mac_2C_TN.png Open the extracted file with a simple text editor. Search for "HasSupershield" tag and set its value to "1". Save file. XML_tutorial_2B_TN.png
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.

XML_tutorial_mac_3C_TN.png

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.

XML_tutorial_3C_TN.png

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.

XML_tutorial_mac_4C_TN.png



XML_tutorial_mac_5C_TN.png

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.

XML_tutorial_4C_TN.png


XML_tutorial_6B_TN.png

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. XML_tutorial_img6_TN.png 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.
XML_tutorial_img6_TN.png

Important tips for working with XML files

  • capitalization rules (use of capital and small initial letters): You need to care about it because also Onisplit does.
  • text position in a line: most tags have some distance towards line begin. It is not needed but preserve the overview.
  • structure: some tags have children. Destroying the structure doesn't affect the reconversion but it is not good for the overview. 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.
collapse_code_preview.png
Windows

hover_an_instance_preview.png
Windows

code_folding_preview.png
Macintosh (xcode)

way without Mac GUI: 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".)


XML advanced tutorial

Read on HERE.