XML:Basic tutorial

XML tutorial for 2009-7 AE release

What is XML modding?

Binary data becomes converted into more human-readable form which allows easier modding. All supported file types can be seen HERE.

Okay, what do I need?

OniSplit will be your tool. It's part of AE. Installing AE spares you some work because it splits the level achieves right away and globalize some more data. Global data can be used in any level.

AE installed. What now?

OniSplit cannot be opened in a classic way. But you are lucky. Now we have a GUI (graphical user interface) for it.

Mac user will want to get "AETools"

Install instructions are on same page.

Windows user will want to get "OniSplit GUI"

Unpack and put the executables into your "GameDataFolder" inside "edition" folder.

What mod possibilities do I have?

See HERE again. It's an overview what you could do. 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 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.

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.

supported file types

General information. In which level is chapter X stored? See HERE.  : XML documentation available  : XML documentation available but incomplete  : XML documentation not available but that doesn't mean you cannot mod the file type  : XML documentation not needed / uninteresting file type

BINA/OBCJ/CHAR 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 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 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 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 come passes/comes near the door.

BINA/OBCJ/FLAG 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 List of furniture in a specific level. This file type could be extract as XML file but it's obsolete, nothing more than a relict from time of development.

BINA/OBCJ/MELE List of melee profiles for global use. It means how the AI use it's combat moves.

BINA/OBCJ/NEUT 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 List of particle in a specific level. There you can setup their position, script name and scaling.

BINA/OBCJ/PATR 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 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 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 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 List of laser triggers in a specific level. There exist several forms and can trigger not only script functions.

BINA/OBCJ/TURR 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 List of weapons in a specific level which are spawned at level load. Actually only the position of them is set there.

BINA/ONIE 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 3D particle. Particle are used as weapon's damage doer, decals and light effects.

BINA/TMBD 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.

CONS Console. You can write there user's position and facing and also the screen images.

DPge Diary page. You what to write a page for a new level or alternative story then there you go.

FILM Movement record. Usually used for cutscenes. During that time of animation, AIs have no AI. ^_^

HPge Help page. But, ahm, who wants to mod that?

IGHH In-game HUD. That's your health bar, compass, etc..

IPge Item page. If you have created a new item then there you can describe it, give warnings, whatever.

Impt Impact. This file is used to build up the hierarchy of impacts. See ONIE for more information.

Mtrl Material. This file is used to build up the hierarchy of materials. See ONIE for more information.

ONCC 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 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 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 Level descriptor. In other words it is the level name in the save game menu.

ONSK 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 Variant list of characters. It's used for randomize characters' appearance.

ONWC Weapon class. Contains primary and secondary fire mode, more flags, particle, 3D model, and textures.

OBAN Object animation. Also used for cutscene cameras and characters (Elevators: object and character are animated at same time).

OPge Objective page. That's the place where you can write the objective for a new or modified level.

PSpc 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 Part specification list.

PSUI Part Specifications UI (User Interface).

TRAC Animation collection. Every character can move and fight thanks to a collection.

TRAM Animation. Theoretical it's possible to write animations in XML but so far nobody has been crazy enough to do that. The format might change in near future enabling real animation modding. At the moment we use it only for minor tweaks and particle links.

TRGE Laser trigger emitter. This file type holds the 3D model and it's coordinates. Used by TRIG.

TRMA Character's texture map array. Every body part is covered by textures. This file type holds links to those textures.

TXMB Big texture map. Only used for spalsh screens, you know .. these big Intro, WinLevel and LoseLevel images.

TXMP Texture map. Well, this type covers all images in Oni. (TXMB are actually TXMP too.)

TxtC Console text. Each time you access a console you get a text page. That's TxtC.

WMCL Window menu cursor list. Mouse pointer(s).

WMDD Window Menu Dialog Data. It shapes pages like TxtC and WPge. However, new button functions would require engine modding.

WMM Window menu menu.

WPge 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:

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

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

• code folding: don't destroy the structure to compress code. There are tools which can handle large xml files. (e.g. Microsoft Visual ... Express and xcode both for free)

You can fold whole instances and parent tags.

Folded code can be previewed in Microsoft Visual Express applications, although xcode provides an extra scroll popup.

Windows (Visual C++)

Windows

Macintosh (xcode)

way without Windows GUI: window address bar

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 "shift + c" for coping marked text and "shift + v" for pasting text.)

way without Windows GUI: local called CMD

Useful for debugging. Copy the code into an empty text file and save it as whatever.reg, then double click it.

REGEDIT4
[HKEY_CLASSES_ROOT\Directory\shell\cmd]
@="Open Command Window Here"
[HKEY_CLASSES_ROOT\Directory\shell\cmd\command]
@="cmd.exe /k \"cd %L\""
[HKEY_CLASSES_ROOT\Drive\shell\cmd]
@="Open Command Window Here"
[HKEY_CLASSES_ROOT\Drive\shell\cmd\command]
@="cmd.exe /k \"cd %L\""

Now you can goto "Oni/edition" and mark the GameDataFolder, right-click it, a popup menu appears, click "Open Command Window Here".

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.