Introduction to modding
This page provides an introduction to modding that does not assume that you have prior modding experience or knowledge of the Oni engine. Links to more technical parts of the wiki are interspersed below or can be accessed directly from the wiki's Main Page.
What is modding?
Modifying, or "modding", a game is generally easier than creating one, because you might only be changing some of the game's existing elements, or creating a limited amount of new data. Nevertheless, modding can be an intimidating field to get into. Our community does not have the polished modding tools of the big engines like Unreal (but we're getting better). You should have a DIY personality and a high tolerance for technical details. We do not yet have any modding solutions with a big red button that says "easy".
Modding your first game is always the hardest, but after that you can more easily pick up new ones. If you take things one step at a time, you can learn a lot from Oni about how to make games in general; in fact, many game developers started out as modders. Additionally, there are lots of different ways for someone to mod; whether your interest is in coding, art, sound, 3D modeling, or general game design, there's something for you to do, and collaborating with others to divide the work according to your abilities can lead to a memorable, rewarding creative experience.
- Go to the Oni Mod Depot to see what kinds of mods are available, or;
- Install the Anniversary Edition to try out the mods, or;
- Continue reading to get an overview of the game engine.
What engine does Oni run on?
Oni runs on a custom engine that could be built for Windows, the Macintosh and the PlayStation 2 (console games are not easily modded, so we don't work with the PS2 version of Oni). The engine consists of various subsystems, some of which have colorful animé-related names like Akira (environment), Motoko (graphics) and Totoro (animation).
Unfortunately, the game was rushed to completion during a change of ownership, and it was not possible for the developers to release any tools or information to aid the fans in modding. Thus, fans had to explore the wild jungle of the raw game data and create modding tools through reverse-engineering. It took over seven years to unlock most of the game's secrets, but we can now mod almost all types of data effectively, allowing us to create entirely new levels and characters.
Altogether, we have identified over 100 types of resources (often called "file types" on this wiki, and "tags" in many other game modding communities) in the game data, however we only directly edit about half of these. It may sound intimidating at first, but depending on the kind of modding you want to do, you might be able to start working with only a little knowledge of the engine.
- Go to Oni for the full story on Oni's development, or;
- Go to History of Oni modding to read about the community's accomplishments up until now, or;
- Continue reading to learn about the game data files.
How is the game data structured?
A game can be compared to a theater play: in both cases, you have stages, scripts, actors, and music. A level is built so that when the player performs certain actions or reaches certain locations on the stage, further events are set in motion according to the script. The player interacts with AI actors along the way. Music will often play dynamically behind all this, changing along with the flow of events.
In Oni's case, the stages, actors and music (and other sounds) are all packed together into files inside GameDataFolder/ that end in ".dat", ".raw", and, on Macs, ".sep". The level0_Final files provide resources for all levels, and when you load a Chapter, an additional set of data files provide the level-specific resources for that Chapter (e.g. level12_Final for Chapter 10). The scripts are stored in separate plain-text files ending in ".bsl" inside GameDataFolder/IGMD/. The player's progress is stored in persist.dat next to the Oni application.
- Go to Oni (folder) for information on each file, or;
- Go to Game data terminology to learn the precise terms for Oni's data, or;
- Continue reading to learn the general process of modding.
What is the workflow for modding?
The general order of events in creating a mod is (1) unpacking the resources you wish to edit, (2) editing them, and (3) re-packing them into Oni's level data. You can rely on the Anniversary Edition Installer to re-pack your data, which means that you just need to know how to create the kind of mod package that the AEI requires. If you are only creating a script mod, then you don't need to unpack any data, but you'll still need to know how to place your script(s) in a mod package.
Data unpacking
The game data cannot be edited easily until our tools convert it into something more modder-friendly. Thus you will usually start by using OniSplit to break level data files (those .dat/.raw(/.sep) files) into their component resources (.oni files), then convert those resources into something editable. The editable format you arrive at will depend on the kind of data you're editing. It might be plain-text, XML, PNG, Collada, WAV, etc. The editors which you'll use on this data will be third-party programs.
Third-party tools
If you are scripting, then you might need nothing more than a text editor. For editing textures, you might only need a free bitmap editor. For creating levels or characters, you'll need a full 3D modeling package. Since Oni doesn't have modern 3D graphics, you won't need to know as much about modeling as with a modern game, and there are free modelers available. Our recommendations for tools will be found under the subsections of "Modding resources" below.
Community tools
Talk about scripting assistants, XmlTools, Vago and other tools we've made, some of which are available from within the AEI.
Mod creation
To see how mods normally look and how they are distributed and installed, you should download the Anniversary Edition and choose to install some mods. You can then look at the packages that have been downloaded to AE/AEInstaller/packages/.
- Go to OniSplit's page to learn how to unpack and reassemble the game data, or;
- Go to XmlTools' page to learn how to smartly alter the game data during mod installation, or;
- Go to Making a mod package to learn how to assemble a mod, or;
- Continue reading to learn about the types of modding you can perform.
Which resources should I be modding?
Oni assembles its game world from the scripts in the IGMD folder, game data in the .dat/.raw(/.sep) files in GameDataFolder, and persist.dat. It's easy to read the BSL scripts since they're plain-text, but how do you find the resource in the game data that you want to edit? Look under "Modding resources" below for a link to the XML database, which explains the function and location of each resource type.
Editing scripts
The easiest kind of modding is scripting. Scripts are written in BSL, the BFW Scripting Language, and stored as plain-text files with the suffix .bsl in sub-folders inside GameDataFolder/IGMD/. Scripts take a lifeless level and spawn characters in it (Konoko and the AI-driven NPCs), give the level a logical flow of events, drive cutscenes, make the AIs play certain roles, and alter the level's appearance.
Scripting is the easiest way to mod because you only have to modify BSL files using a text editor. It's quick and easy to see the results of your work (just reload the level), and you have lots of accessible examples to learn from. That being said, scripts sometimes reference game resources in technical ways, so you will have to learn how certain data types work in order to script effectively.
- Go to the BSL namespace to start learning about scripting, or;
- Continue reading to learn what's involved with editing resources.
Modding resources
Broadly speaking, Oni's resources can be broken down as: environments (architecture, triggers, furniture), characters (class data, instance lists, 3D models), weapons (ditto), text (diary pages, objectives, subtitles), and sound (music, voice-overs, and sound effects). However, new levels do not require all this data to be made from scratch. You might decide to re-use a level or some of its resources, or make a new level populated with existing characters, etc.
- Go to the XML namespace to get a simple introduction to the types of game data and learn the (relatively) user-friendly XML modding technique, or;
- Go to the OBD namespace to learn more technical details about the game data, or;
- Continue reading to start down the path to modding specific kinds of resources.
Environments
Levels are usually built in SketchUp. Blender can be used for levels, objects, characters and animations. Formerly we preferred to do that work in Mod Tool, but the support for Blender is continuing to improve, so that it should completely replace Mod Tool as our modeler of choice around 2022.
- Tutorial: Creating the Lair - A level tutorial
- Tutorial: Authoring custom camera animations
Textures
Modders have their own preference for which bitmap editor to use when editing/creating textures. On one end of the scale are expensive programs such as Photohop, and on the other end are free editors like Gimp and Paint.NET.
Textures have dimensions always of "power of 2": their pixel sizes must be one of those numbers 2, 4, 8, 16, 32, 64, 128, 256, 512. Mac supports a maximum of 1024 pixel per dimension: 1024 x 1024. For PC you can only use images as big as 512 x 512.
A common question is how to create (TXMB) splash screens (level start screens), win level and lose level screens. Those images are made of smaller ones due to Oni's limitation in pixel dimension.
All other images use TXMP as file type. These can can static, animated, transparent or have an reflection map (env map, usually for character armor). Special properties like double sidedness for glass are set up in the level's master xml page.
- Tutorial: Modifying textures (TXMP)
Characters
Characters in Oni are built with a simple 19-part skeleton. This skeleton (TRIA) is usually the same for all humanoid characters and simply tells Oni how the 3D meshes (TRBS) are put together. You cannot really compare this with the modern game industry's use of the term "skeleton". The meshes have individual textures (TXMP) stored in a list (TRMA).
In its entirety, a character is defined by their class file (ONCC) which links also to the animation list (TRAC). The high modularity of character data allows Oni to share many resources between characters (especially animation collections and particles).
- Tutorial: Adding character classes (ONCC)
- Tutorial: Importing character models (TRBS)
- Tutorial: Tweak an individual animation (TRAM)
- Tutorial: Adding spawnable characters to a level (CHAR)
Some cutscenes require the character to use OBANs to overcome obstacles. These OBANs usually have a partner TRAM. The positions from character's animation data have been outsourced to OBAN to avoid effects of gravity. (See Griffin's helicopter scene in last level.)
ONCC
|
+-- TRBS
| |
| +-- TRIA (embedded)
+-- TRMA
| |
| +-- TXMP
+-- TRAC
|
+-- TRAM
Weapons
- Tutorial: Importing weapon models
Text
As long as you don't confuse IDs of instances and stick to the structure, these types shouldn't pose a problem.
Important text-related file type are:
Sound and music
- Instructions on importing sounds and links to conversion tools can be found HERE.
Need some inspiration?
To get ideas, play some existing mods (which you can install with the AE), or look at the pages below.