XML:Basic tutorial: Difference between revisions

From OniGalore
Jump to navigation Jump to search
m (wording)
m (better link for supershield details)
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{update}}
{{XML Home}}
==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 testing your mod package, and globalizes more of Oni's data. Global data can be used in any level.


===What is XML, first of all?===
Here's a step-by-step guide to creating a mod through XML modding, using an ONCC modification as an example. It will give you a grasp of the usual tools and workflow. Let's roll!
:[[wikipedia:XML|E'''X'''tensible '''M'''arkup '''L'''anguage]] is a plain-text file format designed to be both human-readable and machine-readable. It stores data in between tags, e.g. <tt><Data>Some data here.</Data></tt>, 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 <tt><?xml version="1.0" encoding="UTF-8" ?></tt>. 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''?===
: '''Open AEInstaller, then Vago'''
: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 at the bottom of the page, but the illustrated guide below shows how to do this more easily with a GUI.
:: Open the AEI and choose the menu item Tools > Vago GUI (first, Vago has to have been installed via Tools > Manage Tools).
:: When Vago is opened for the first time, it will ask you to locate the AE installation on your hard drive.


===Is that the same thing as this XML ''patch'' modding?===
: '''Get Konoko's character file (ONCC) by splitting level0_Final.dat'''
:Not quite; XML patching is based on XML modding, though. 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.
:: In Vago, go to the "Levels" tab.
:: Drag and drop the file level0_Final.dat, found in the directory AE/AEInstaller/vanilla/, into the "Sources" section of the window. Click "Convert".
:: At the top, click on the blue folder icon. The folder with Vago's converted files will appear. Go into Levels/DAT - ONI FILES/level0_Final/.


===So I just export some data to XML and start editing, right?===
: '''Convert the .oni to XML'''
: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.
:: In the level0_Final/ folder, there will be a lot of files. You want ONCCk4_L.oni. This is the name of the file for the version of Konoko that appears in Chapter 13, as [[Konoko's outfits|documented here]].
:: Go to Vago's "XML" tab and drag-and-drop ONCCk4_L.oni into the "Sources" section. Click "Convert".


===What tools do I need?===
: '''Edit the XML'''
:[[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.
:: Click the blue folder icon again and go into "XML/ONI - XML". There should be a file called ONCCk4_L.xml now.
:: Open that file with a plain-text editor (in Windows, you should use Notepad, and TextEdit will work on the Mac).
:: Search for the <HasSupershield> tag and change its value from 0 to '''1'''.
:: Save the file and close it.


===I've got the AE installed. What now?===
: '''Convert the XML back to a .oni'''
: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 Tools menu]].
:: Go to Vago's "XML" tab. In the "From:" popup menu, choose "XML", and the "To:" popup menu should have "ONI" supplied automatically by Vago.
:: Drag-and-drop your XML file into the "Sources" section. Click "Convert".
:: Click the blue folder icon again and go into "XML/XML - ONI".
:: Create a new folder on your hard drive, preferably outside of the VagoWorkspace folder, called "level0_Final", and put your new ONCCk4_L.oni file into it.


===What kinds of mods can I make?===
[[Image:HasSupershield_1.png|thumb|200px|right|For more information on the supershield flag, see [[Supershield]].]]
:See [[XML:File_types|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 others.
: '''Get the file back into Oni'''
:If you need some ideas look at this page: '''[[Modding_brainstorms|modding brainstorms]]'''.
:: The best way to test your mod is to make an [[Making_a_mod_package|AE package]]. Vago can help you do this: choose the menu item Tools > AEI Mod Package Wizard.
:: Fill in all the mandatory fields. Set the Type to "Character". When choosing a package number, follow the suggested numbering range that is auto-filled in Package Number, and click "Check" to see if it has already been used by another package. Hit "Continue" once you have decided on a package number.
:: Leave the optional fields blank. Hit "Continue".
:: Drag-and-drop your level0_Final folder into the "Common" section. Hit "Done".  


===Hmm, I want to modify the files in Chapter ''X''. But what level file is that?===
: '''Test your mod'''
:Check out [[GDF|this overview]] of Oni's game files.
:: Copy your package folder into AE/AEInstaller/packages/ in your Oni installation.
 
:: Open the AEI, locate your mod by looking under the "-Local-" category or by typing its name into the Filter, and install it.
===Is there an easy exercise to get started?===
:: Load Oni's level "TCTF Regional HQ (redux)" (the next-to-last level).
:We're glad you asked:
:: If you raise your health above 150% (301 HP), the supershield will switch on and you will be untouchable. The "chenille" cheat is a handy alternative to finding some hypos, and it will permanently turn on the supershield.
 
{| class="wikitable" width="100%"
!colspan=2|Mac:
!colspan=2|PC:
|-
!colspan=4|converting an ONI file into an XML file
|-
 
 
|valign="top"|Open Edition's AETools_Data folder and create a new folder named "ONIfiles".
 
 
Run AETools, choose "Extract" tab.<br>Click on checkbox "Expract as .xml file".<br>Then click on "Extract .oni file(s)" and choose "ONCCk4_L.oni".<br>See "XMLfiles" in "AETools_Data". There you should find "ONCCk4_L.xml".
|valign="top"|[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_mac_1C.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_mac_1C_TN.png]
|valign="top"|Open Edition's GameDataFolder and create two new folders named "XML" and "ONI".
 
 
Run the GUI, choose "ONI - XML" tab and its upper section.<br>Click first browse button and search for "ONCCk4_L.oni" inside the level0_Characters folder.<br>Click second browse button and choose the XML folder as target.<br>Now click on Convert button.
|valign="top"|[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_1C.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_1C_TN.png]
|-
!colspan=4|modifing the XML file
|-
|valign="top"|Open the extracted file with a simple text editor. Search for "HasSupershield" tag and set its value to "1". Save file.
|valign="top"|[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_mac_2C.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_mac_2C_TN.png]
|valign="top"|Open the extracted file with a simple text editor. Search for "HasSupershield" tag and set its value to "1". Save file.
|valign="top"|[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_2B.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_2B_TN.png]
|-
!colspan=4|creating the ONI file
|-
|valign="top"|Choose "Convert" tab.<br>Now click onto "Select File(s) for Conversion" button and mark "ONCCk4_L.xml". Click "Choose" button.<br>Then click "Select Destination Folder". Search for your ONIfiles folder, mark it, and click "Choose button."
 
 
<font color="#888888">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.</font>
|valign="top"|
[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_mac_3C.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_mac_3C_TN.png]
|valign="top"|Goto "XML -> ONI" section.<br>Click first browse button and search for "ONCCk4_L.xml" inside the XML folder.<br>Click second browse button and choose the ONI folder as target.<br>Now click on Convert button.
 
 
<font color="#888888">Try [[#way_without_Windows_GUI:_local_called_CMD|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.</font>
|valign="top"|
[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_3C.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_3C_TN.png]
 
|-
!colspan=4|creating and installing a mod package
|-
|valign="top"|
Choose "Package" tab.
The GUI is actually pretty much self-explaining.<br>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.
|valign="top"|
[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_mac_4C.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_mac_4C_TN.png]
 
 
 
 
[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_mac_5C.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_mac_5C_TN.png]
|valign="top"|
Click on GUI's "AE Package" tab.<br>The GUI is actually pretty much self-explaining.<br>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.
|valign="top"|
[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_4C.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_4C_TN.png]
 
 
[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_6B.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_6B_TN.png]
|-
!colspan=4|testing the modification
|-
|valign="top"|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.'''
|[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_img6.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_img6_TN.png]
|valign="top"|Let's test our modification. Therefore we start TCTF HQ redux (pre-last level).<br>The supershield becomes automatically switched on at '''51% overpower''' (301 healh points). '''"chenille" cheat works too.'''
|[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_img6.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/XML_tutorial_img6_TN.png]
|}
 
==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 [[wikipedia:IDE|IDEs]] like [http://www.microsoft.com/express/download/ Microsoft Visual Studio] (Windows) and [http://developer.apple.com/technology/Xcode.html 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.
 
{|
|[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/collapse_code.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/collapse_code_preview.png]<br>Windows
|
[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/hover_an_instance.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/hover_an_instance_preview.png]<br>Windows
|
[http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/code_folding.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XML_modding/code_folding_preview.png]<br>Macintosh (Xcode)
|}
 
==Extracting XMLs from the Mac command line (the Terminal)==
Put the '''[[OniSplit|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==
The XML basic tutorial deals with XML <=> .oni conversion and how to get the data into the game.
 
The XML advanced tutorial shows that resource can depend on each other and that they work together with BSL.
 
Read on [[XML:Advanced_tutorial|HERE]].
 
 
==XML expert tutorial==
The XML expert tutorial is about possibilities...
 
The more you know in general the more creative you can be.
 
Some resources are not always found to be connected (e.g. CHAR and CONS) but can be made to work together.
 
Read on [[XML:Expert_tutorial|HERE]].
<!-- setting up alarm consoles should be a good candidate for this
alternative choices for such tutorial: TRAM usage of charactes, ONIE
 
alarm consoles, reading material:
http://wiki.oni2.net/AI#Pursuit_of_enemy_alias_.22I_will_find_you....22
http://wiki.oni2.net/AI#Alarm_behavior_-_.22She.27s_everywhere.21.22
-->


[[Category:Modding tutorials]]
[[Category:Modding tutorials]]

Latest revision as of 15:56, 9 May 2024

Click to return to the main XML page.

Here's a step-by-step guide to creating a mod through XML modding, using an ONCC modification as an example. It will give you a grasp of the usual tools and workflow. Let's roll!

Open AEInstaller, then Vago
Open the AEI and choose the menu item Tools > Vago GUI (first, Vago has to have been installed via Tools > Manage Tools).
When Vago is opened for the first time, it will ask you to locate the AE installation on your hard drive.
Get Konoko's character file (ONCC) by splitting level0_Final.dat
In Vago, go to the "Levels" tab.
Drag and drop the file level0_Final.dat, found in the directory AE/AEInstaller/vanilla/, into the "Sources" section of the window. Click "Convert".
At the top, click on the blue folder icon. The folder with Vago's converted files will appear. Go into Levels/DAT - ONI FILES/level0_Final/.
Convert the .oni to XML
In the level0_Final/ folder, there will be a lot of files. You want ONCCk4_L.oni. This is the name of the file for the version of Konoko that appears in Chapter 13, as documented here.
Go to Vago's "XML" tab and drag-and-drop ONCCk4_L.oni into the "Sources" section. Click "Convert".
Edit the XML
Click the blue folder icon again and go into "XML/ONI - XML". There should be a file called ONCCk4_L.xml now.
Open that file with a plain-text editor (in Windows, you should use Notepad, and TextEdit will work on the Mac).
Search for the <HasSupershield> tag and change its value from 0 to 1.
Save the file and close it.
Convert the XML back to a .oni
Go to Vago's "XML" tab. In the "From:" popup menu, choose "XML", and the "To:" popup menu should have "ONI" supplied automatically by Vago.
Drag-and-drop your XML file into the "Sources" section. Click "Convert".
Click the blue folder icon again and go into "XML/XML - ONI".
Create a new folder on your hard drive, preferably outside of the VagoWorkspace folder, called "level0_Final", and put your new ONCCk4_L.oni file into it.
For more information on the supershield flag, see Supershield.
Get the file back into Oni
The best way to test your mod is to make an AE package. Vago can help you do this: choose the menu item Tools > AEI Mod Package Wizard.
Fill in all the mandatory fields. Set the Type to "Character". When choosing a package number, follow the suggested numbering range that is auto-filled in Package Number, and click "Check" to see if it has already been used by another package. Hit "Continue" once you have decided on a package number.
Leave the optional fields blank. Hit "Continue".
Drag-and-drop your level0_Final folder into the "Common" section. Hit "Done".
Test your mod
Copy your package folder into AE/AEInstaller/packages/ in your Oni installation.
Open the AEI, locate your mod by looking under the "-Local-" category or by typing its name into the Filter, and install it.
Load Oni's level "TCTF Regional HQ (redux)" (the next-to-last level).
If you raise your health above 150% (301 HP), the supershield will switch on and you will be untouchable. The "chenille" cheat is a handy alternative to finding some hypos, and it will permanently turn on the supershield.
Retrieved from "https://wiki.oni2.net/w/index.php?title=XML:Basic_tutorial&oldid=42710"