XML:Basic tutorial

From OniGalore
Revision as of 18:19, 12 April 2013 by Iritscen (talk | contribs) (rewriting intro to be more intro-y)
Jump to navigation Jump to search


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

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.

What is XML?

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, 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 HERE.

So I just export some data to XML and start editing. Got it.

Not so fast! A lot of the data is not that self-explanatory; 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.

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.
Mac user will want to get "AETools"
Install instructions are on same page.
Windows user will want to get "OniSplit GUI" or Vago GUI
Unpack and put the executables into your "GameDataFolder" inside "edition" folder.

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.

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

supported file types

Question: "I want to modify files in chapter X. But what level archive is that?"

Answer: "Check out this overview."


Documentation status:

Aqua Dot-Green.png : available
Aqua Dot-Yellow.png : incomplete
Aqua Dot-Red.png : not available, but that doesn't mean you cannot mod the file type


BINA

BINA/ONIE Aqua Dot-Yellow.png
ONIE is a list of all impacts effects which can happen in the game. That includes weapon particle, hand-to-hand combat and movements. The impact effects depends on source type and the material which is hit.
BINA/PAR3 Aqua Dot-Yellow.png
3D particle, also known as 3RAP and PART files. Particle are used as weapon's damage doer, decals and light effects.
BINA/SABD Aqua Dot-Yellow.png
Sound Animations Binary Data.
BINA/TMBD Aqua Dot-Green.png
TMBD is a list of all materials in the game which groups texture map under them. That way environment gets materials which are used by ONIE.


OBJC

BINA/OBCJ/CHAR Aqua Dot-Yellow.png
List of characters in a specific level. There you can setup their position, script name, weapon, ammunition, items, team, combat, melee id, etc..
BINA/OBCJ/CONS Aqua Dot-Green.png
List of consoles in a specific level. There you can setup their position, script name (Id), screen images, and script functions. Basically they are used to open doors.
BINA/OBCJ/CMBT Aqua Dot-Yellow.png
List of combat profiles for global use. There you can set AI's conditions for hand-to-hand, weapon combat, and retreat - in dependence of distances and enemy's counterattack.
BINA/OBCJ/DOOR Aqua Dot-Green.png
List of doors in a specific level. There you write conditions when a door opens (or not), and what events are triggered by a character who passes/comes near the door.
BINA/OBCJ/FLAG Aqua Dot-Green.png
List of flags in a specific level. There you can setup their position. They are used by script commands and patrol paths.
BINA/OBCJ/FURN Aqua Dot-Red.png
List of furniture in a specific level. This file type can be useful to import level objects.
BINA/OBCJ/MELE Aqua Dot-Yellow.png
List of melee profiles for global use. It means how the AI use it's combat moves.
BINA/OBCJ/NEUT Aqua Dot-Green.png
List of neutral behaviors in a specific level. Every character has melee, combat and netral behavior Id. It determines whether a non-player character (NPC) talks to you or not, this includes also rewards you could get from such characters.
BINA/OBCJ/PART Aqua Dot-Green.png
List of particle in a specific level. There you can setup their position, script name and scaling.
BINA/OBCJ/PATR Aqua Dot-Green.png
List of patrol paths in a specific level. A patrol path has an Id which is used by CHAR and script command "ai2_dopath".
BINA/OBCJ/PWRU Aqua Dot-Green.png
List of powerups (items, e.g. hyposprays) in a specific level which are spawned at level load. There you can setup their position.
BINA/OBCJ/SNDG Aqua Dot-Yellow.png
List of sound "groups" (spheres) in a specific level. It used to create sound spheres. Come near a machine and you might hear a sound, that's because of SNDG.
BINA/OBCJ/TRGV Aqua Dot-Green.png
List of trigger volumes in a specific level. They are invisible areas which trigger script functions, this depends on character's team Id.
BINA/OBCJ/TRIG Aqua Dot-Green.png
List of laser triggers in a specific level. There exist several forms and can trigger not only script functions.
BINA/OBCJ/TURR Aqua Dot-Green.png
List of turrets in a specific level. Not that their pods are part of the level geometry. Spawn one additional and it might be located somewhere in the air. Basicly you can setup their head's position, the weapon inside the turrent head, and the team Id which is the target.
BINA/OBCJ/WEAP Aqua Dot-Green.png
List of weapons in a specific level which are spawned at level load. Actually only the position of them is set there.


Others

AISA
AI spawn array. AISA is still used for a few cutscene characters, even though BINA/CJBO/CHAR has made it redundant.
AKEV Aqua Dot-Yellow.png
Akira Environment. It's the 3D level model. You can take a look into it but it's not recommended to tweak this by hand. Instead edit the AKEV as dae file in a 3D editor like Mod Tool.
CONS Aqua Dot-Red.png
Console class.
DPge Aqua Dot-Green.png
Diary page. You what to write a page for a new level or alternative story then there you go.
DOOR Aqua Dot-Red.png
Door class.
FILM Aqua Dot-Green.png
Movement record. Usually used for cutscenes. During that time of animation, AIs have no AI. ^_^
HPge Aqua Dot-Green.png
Help page.
IGHH Aqua Dot-Green.png
In-game HUD. That's your health bar, compass, etc..
IPge Aqua Dot-Green.png
Item page. If you have created a new item then there you can describe it, give warnings, whatever.
Impt Aqua Dot-Green.png
Impact. This file is used to build up the hierarchy of impacts. See BINA/ONIE for more information.
M3GM Aqua Dot-Red.png
Geometry. Some of these 3D objects are used by OBANs and PAR3 files.
Mtrl Aqua Dot-Green.png
Material. This file is used to build up the hierarchy of materials. See BINA/ONIE for more information.
OBAN Aqua Dot-Green.png
Object Animation. Yes, used by objects but also for moving characters and cutsceen cams.
OFGA Aqua Dot-Yellow.png
Object Furniture Geometry Array. Used to import objects with no functions. (Door, consoles, etc. becomes imported by their object collections. See ONLV for more information.)
ONCC Aqua Dot-Yellow.png
Character class. It contains weapon skills, behavior Ids, view radius, jump power, sounds, 3D model (TRBS), animation collection (TRAC), textures (TRMA), and much more.
The XML file contains also the character's body part material (CBPM), body part impacts (CBPI), and particles for animations (ONCP and ONIA).
ONCV Aqua Dot-Green.png
Character variant. 1) It's used to build up the hierarchy of randomness pools. Some characters with different appearance can form a pool for randomness. A flag in CHAR determinze if a character use one of these pools. 2) It can be also used to upgrade characters on difficult level hard - enabled by a flag in CHAR.
ONGS Aqua Dot-Green.png
Game settings. There you can modify the values of the health bar, hypospray strength, game difficult setting, at what distance item glow is displayed, and autoprompts (text message when picking up a new kind of item).
ONLD Aqua Dot-Yellow.png
Level descriptor. In other words it is the level name in the save game menu.
ONLV Aqua Dot-Yellow.png
Oni Game Level. Holds among other things: BSL folder name (<Name>), AKEV (Akira Environment) link, ONSK (Oni sky) link, and a link to AISA (AI Character Setup Array which is a bit obsolent because of CHAR).
ONSK Aqua Dot-Green.png
Sky. It's designed as a box so you will need five images: for top, north, east, south and west. The bottom has no image.
ONVL Aqua Dot-Green.png
Variant list of characters. It's used for randomize characters' appearance.
ONWC Aqua Dot-Green.png
Weapon class. Contains primary and secondary fire mode, more flags, particle, 3D model, and textures.
OPge Aqua Dot-Green.png
Objective page. That's the place where you can write the objective for a new or modified level.
OSBD Aqua Dot-Yellow.png
Oni Sound Binary Data. They determine how (SNDD) sound files get played.
StNA Aqua Dot-Green.png
StNA files are obsolete. However, on its name page are collections of flags used by TRAM.
PSpc Aqua Dot-Green.png
Part specification. Oni can decorate a page (OPge, TxtC, maybe other too) with images from one source. You write coordinates there which means these parts.
PSpL Aqua Dot-Red.png
Part specification list.
PSUI Aqua Dot-Red.png
Part Specifications UI (User Interface).
SUBT Aqua Dot-Green.png
Subtitle Array. Those SUBT files can't be extracted as xml but txt. SUBT has a link so you are simply aware of it.
TRAC Aqua Dot-Green.png
Animation collection. Every character can move and fight thanks to a collection.
TRAM Aqua Dot-Yellow.png
Animation. You can create new animations with Mod Tool. But for setting Oni-specific flags, links to particle and so on you need to edit the xml file afterwards or you create precursor xml before.
TRAS Aqua Dot-Red.png
Totoro Aiming Screen. Used for make characters aim with weapons.
TRBS Aqua Dot-Green.png
Totoro Body Set, in other words the 3d model of a character. ONCC (character class) files links to TRBS. The 3d data itself will be exported/imported as dae files.
TRGE Aqua Dot-Green.png
Laser trigger emitter class. This file type holds the 3D model and it's coordinates. Used by TRIG.
TRIG
Laser trigger class.
TRMA Aqua Dot-Green.png
Character's texture map array. Every body part is covered by textures. This file type holds links to those textures.
TRSC Aqua Dot-Red.png
Totoro Aiming Screen Collection. Used for make characters aim with weapons.
TXMB Aqua Dot-Green.png
Big texture map. Only used for spalsh screens, you know .. these big Intro, WinLevel and LoseLevel images.
TXMP Aqua Dot-Green.png
Texture map. Well, this type covers all images in Oni. (TXMB use multiple TXMPs to create a big texture.)
TxtC Aqua Dot-Green.png
Console text. Each time you access a console you get a text page. That's TxtC.
WMCL Aqua Dot-Red.png
Window menu cursor list. Mouse pointer(s).
WMDD Aqua Dot-Green.png
Window Menu Dialog Data. It shapes pages like TxtC and WPge. However, new button functions would require engine modding.
WMM Aqua Dot-Red.png
Window menu menu.
WPge Aqua Dot-Green.png
Weapon page. That's the place where you can write descriptions page about a specific weapon.


working with XML files: good to know

  • 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 being aware of the search function) is actually enough to work with Oni's xml. Anyway, big files might be easier to handle with code folding. So, if you like code folding, you maybe try Microsoft Visual ... Express (PC) or Xcode (Mac). Both are for free.
You can fold whole instances and parent tags.
Folded code can be previewed in Microsoft Visual Express 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 Windows GUI: window address bar

window_address_bar_preview.png

Put the newest OniSplit.exe into the "edition\GameDataFolder" folder and use the window's address bar (that's where you can see the directory in full length).

Delete that address, type (for example) the code below, and hit enter.

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

The star is good for mess extraction/creation and good for shorten long unique file names. ("ONCCkonoko_generic" will be extracted in new folder "edition\GameDataFolder\xml_dir".)


It's also a good idea to keep the code in a temporary opened text file. There you can easily modify the code for other files and doesn't need you to type it from beginning into the address bar. (Be aware of Windows' short cut "CTRL + C" for coping marked text and "CTRL + V" for pasting text.)

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.