OniGalore

Introduction to modding: Difference between revisions

Page Discussion

Introduction to modding (view source)

Revision as of 23:58, 3 December 2025

1,964 bytes added ,  Wednesday at 23:58
added Engine terminology link; removed some unneeded WP links that are found on that page now; removed two links to OCF tutorials – one is found on Importing character models, which is already linked here, and the other link has been added to an "integrate" note on Importing character models
m (wording)
(added Engine terminology link; removed some unneeded WP links that are found on that page now; removed two links to OCF tutorials – one is found on Importing character models, which is already linked here, and the other link has been added to an "integrate" note on Importing character models)
 
(42 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{finish}}
{{integrate|The tutorials are called "Creating the Lair" and "Adding character classes".|plural=yes}}
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.
{{TOClimit}}
==What is modding?==
[[Image:No easy button.png|150px|right]]
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 [[wikt:DIY|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".


This page provides an introduction to modding that does not assume that you have much modding experience or knowledge of the Oni engine.
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.
<div class="toclimit-2">
__TOC__
</div>


==Introduction to modding==
* Go to the {{OMD}} to see what kinds of mods are available, or;
[[Image:No_easy_button.png|150px|right]]
* Install the [[Anniversary Edition]] to try out the mods, or;
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 [[wiktionary:DIY|DIY]] personality and a high tolerance for technical details. If this page seems like a chore to read, for instance, then you are definitely not ready for Oni modding :-) We do not yet have any modding solutions with a big red button that says "easy".
* Continue reading to get an overview of the game engine.


Like learning a new language, 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.
==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).


==Introduction to the Oni engine==
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.
Oni runs on a custom engine that Bungie could build for both Windows and the Macintosh (later, PlayStation 2 support was added, however console games are not easily modded, so we do not work with the PS2 version of Oni). At the time development started, Bungie did not yet have a true 3D engine, and Oni's lead coders intended their work to be reused in future Bungie titles, so the engine consists of various "modules" or subsystems. Since Oni was inspired by an [[Anime|animé]] film, some of the subsystems have colorful animé-related names like [[wikipedia:Akira (film)|Akira]] (environment), [[wikipedia:Motoko Kusanagi|Motoko]] (graphics), and [[wikipedia:My Neighbor Totoro|Totoro]] (animation).


Unfortunately, the game was rushed to completion during a change of ownership (see [[Oni]] for the full story), and it was not possible for the developers to release any tools or information to aid the fans in modding. The game data also reflects Oni's rocky development, being assembled somewhat haphazardly, containing unused and duplicate resources, and also missing a number of resources that the engine looks for during gameplay. One good thing that can be said about the engine is that it is solid enough to run smoothly over top of the errors that it regularly encounters in the data. That being said, it's easy to crash the engine when modding, as is the case with all game engines.
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.


Due the lack of modding tools/information at the time of Oni’s release, fans had to explore the wild jungle of raw game data and create modding tools through reverse-engineering. It took over seven years to unlock most of the game's secrets –- and the work is still ongoing (see [[History of Oni modding]]). But to make a long story short, we can now mod almost all types of data effectively, allowing us to create entirely new levels with new characters, new scripts, new voice acting, and new music. Now we're turning our focus to making tools that are user-friendly so artists can work more freely.
* 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.


Altogether, we have identified 124 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.
==How is the game data structured?==
A game can be compared to a theater play: in both cases, you have <u>stages</u>, <u>scripts</u>, <u>actors</u>, and <u>music</u>. 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 [[wp:Artificial intelligence in video games|AI]] '''actors''' along the way. '''Music''' will often play dynamically behind all this, changing along with the flow of events.


==Introduction to the game data==
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.
A game can be compared to a theater play: in both cases, you have ''stages'', ''actors'', ''scripts'', 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 is told what to do through various textual instructions, cutscenes, and/or voice acting (more ''scripts''), and he interacts with [[wiktionary:artificial_intelligence|AI]]-driven ''actors''. ''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, which is not unusual for games, and found in the files inside GameDataFolder\ that end in ".dat", ".raw", and, on Macs, ".sep". The files called level0_Final provide resources for all levels, and when you load a Chapter, the set of files for that level, e.g. level12_Final, provide the level-specific resources for that Chapter. The scripts are stored in separate, plain-text files ending in ".bsl", in the IGMD\ folder inside GameDataFolder\. 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 [[Engine terminology]] and [[Game data terminology]] to learn the community's terms for Oni's engine and data, or;
* Continue reading to learn the general process of modding.


*See [[Oni (folder)]] for information on each file, or;
==What is the workflow for modding?==
*Continue reading to learn about the types of modding you can perform.
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 as Oni level data. You can rely on the Anniversary Edition Installer to re-pack your data; you simply create the mod package in the format 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.


==Introduction to types of modding==
===Data unpacking===
===Scripting===
The game data cannot be edited easily until our tools convert it into something more modder-friendly. You will usually start by using OniSplit to break level data files (those .dat/.raw(/.sep) files) into their component resources, which are saved as .oni files. Then you will need to 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 suited for each file format.
The easiest kind of modding is scripting. Scripts are written in the BungieFrameWork Scripting Language and stored as plain-text files with the suffix .bsl. Scripts take a lifeless level and spawn characters in it (the AI-driven NPCs and Konoko), 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 can work with existing game data, and 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 (14 levels' worth!). That being said, scripts constantly reference game resources in sometimes technical ways, so you will have to learn how certain data types work in order to script effectively.
===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/texturing as you would with a modern game, and there are free modelers available. Our recommendations for tools will be found under the subsections of "Modding resources" below.


*Go to the [[BSL]] namespace to start learning about scripting.
===Community tools===
Besides OniSplit, two of the key fan-made tools are Vago and XmlTools. Vago is a GUI for OniSplit which is much more user-friendly than using OniSplit on the command line. [[XmlTools]] is a technical tool that few modders need to use, but it allows the creation of patches (partial changes to a single resource which can stack on top of each other). Both tools can be installed from within the AE Installer. Once installed, they are found in AE/Tools/ alongside OniSplit.


===Binary modding===
===Mod creation===
This is where those 88 data types come into play that we mentioned earlier. Broadly speaking, the kinds of data we're talking about are: '''level geometry''' (architecture, triggers, and furniture), '''characters''' (class data, models), '''text''' (diary, objectives, subtitles, etc.), 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.
To see how mods normally look and how they're distributed and installed, you should download the [[Anniversary Edition]] and install some mods. You can then look at the packages that have been downloaded to AE/AEInstaller/packages/.


The game data is called "binary data" because it's made of raw 0s and 1s in a proprietary format until our tools convert it into something more modder-friendly. The basic process of modding game data involves breaking the level data (a .dat file supplemented by a .raw file, and on the Mac a .sep file as well) into its component resources (.oni files), then converting those resources into something editable. The editable format depends on the kind of data you're editing. It might be plain-text, XML, PNG, Collada, WAV, etc.
* Go to [[OniSplit]]'s page to learn how to unpack and reassemble the game data, or;
* Go to [[Vago]]'s page to learn how to use this OniSplit GUI, 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.


Thus, besides our community modding tools, the program(s) you need in order to mod will vary according to your modding task; you might need nothing more than a text editor, you might need a free bitmap editor, or you might need a full 3D modeling package. Thankfully, since Oni is graphically primitive, you won't need to know as much about modeling as with a modern game, and there are free modelers available (but not as good as the commercial ones). In any case, make sure you download the [[Anniversary Edition]], which provides a modding framework and installs modding tools.
==Which resources should I be modding?==
Oni assembles its game world from the scripts in the IGMD folder, the 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.


*Go to the [[XML]] namespace to get a friendly introduction to the types of game data and learn the (relatively) user-friendly XML modding technique, or;
===Editing scripts===
*Go to the [[OBD]] namespace to start learning about the binary data on the byte-by-byte level, or;
The easiest kind of modding is scripting. Scripts are written in a unique language called BSL 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, give it a logical flow of events, drive the cutscenes, make the AIs perform certain roles, and alter the level's appearance.
*Continue reading to learn a little more about specific types of binary modding so you know what you're getting yourself into.


====Character models====
Scripting is the easiest way to mod because you can 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.
Characters in Oni are built with a simple 19-part skeleton. ''Talk about ONCCs and related data here. Mention [[Mod Tool]], [[User:Iritscen/BlenderTutorial|Blender]]''.


* tutorial: [[Importing_character_models|Importing character models (TRBS)]]
* Go to the [[BSL]] namespace to start learning about scripting, or;
* tutorial: [[Adding_spawnable_characters|Adding spawnable characters to a level (CHAR)]]
* Continue reading to learn what's involved with editing binary resources.
* tutorial: [[Adding_character_classes|Adding character classes (ONCC)]]


====Character animations====
===Modding resources===
{| border=0 cellspacing=20 cellpadding=0 style="float:right"
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.
| [http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XSI_modding/RAICOMthrow_fw_kick.png http://i305.photobucket.com/albums/nn207/unknownfuture/Oni_Galore_Images/XSI_modding/RAICOMthrow_fw_kick_TN.png]
''An "appetizer screenshot".''
|}
''Talk about OBANs and TRAMs here. Mention Mod Tool''.


** tutorial: [[OBD_talk:TRAM|Tweak animation (TRAM)]]
* 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.


: You need to add some stuff to that file to make it actually work as an animation. In particular the animation type, from/to states and varient needs to be set.  
====Environments====
: For all I know this works with animations exported from Oni and modified in Softimage. If you come up with a completly new animation it should work as long as the skeleton is similar to the one used in Oni.
Levels are usually built in [[SketchUp tutorials and tips|SketchUp]]. The open-source 3D modeler [[Blender]] can be used for levels, objects, characters and animations. Formerly we preferred to do that work in the discontinued [[Mod Tool]], but the community's support for Blender has continued to improve and it is now our modeler of choice.
 
* Tutorial: [[Creating a level]]
* Tutorial: [[Authoring custom camera animations]]


====Textures====
====Textures====
''Mention [http://www.gimp.org/ Gimp], Paint.NET''.
Modders have their own preferred bitmap editors for changing/creating textures. On one end of the scale are expensive programs such as Photoshop, and on the other end are free editors like [https://www.gimp.org/ Gimp] and [https://www.getpaint.net/ Paint.NET].
 
Textures always have dimensions of "power of 2": typically 32, 64, 128 or 256 pixels on a side. [[FERAL|Mac Oni]] supports a maximum of 1024x1024 textures. Windows Oni (with [[Daodan DLL|fan patch]]) supports textures up to 512x512.
 
These textures can be static, animated, transparent or have a reflection map (usually used for armor). Splashscreens (chapter start screens), win-level and lose-level screens are actually composite images made up of smaller textures due to Oni's limitation in texture size.


* tutorial: [[AE:Modifying textures|Modifying textures (TXMP)]]
* Tutorial: [[Modifying textures]]
 
====Characters====
[[Image:Female stun.jpg|right|300px]]
Characters in Oni are built with a 19-part skeleton. This skeleton is the same for all humanoid characters and simply tells Oni how the individual parts with their own geometry and textures are assembled. You cannot really compare this with the modern game industry's use of the term "skeleton".
 
A character's attributes are defined by their character class file which links also to the animation list that defines their moveset. The high modularity of character data allows Oni to share many resources between characters (especially animation collections and particles).
 
* Tutorial: [[Importing character models]]
* Tutorial: [[OBD talk:TRAM|Tweaking an individual animation]]
* Tutorial: [[XML:Adding spawnable characters|Adding spawnable characters to a level]]


====Weapons====
====Weapons====
* tutorial: [[Importing_weapon_models]]
* Tutorial: [[Importing weapon models]]
 
====Levels====
''Talk about AKEVs and related data here. Mention Mod Tool, [[SketchUp_tutorials_and_tips|SketchUp]]''.


* tutorial: [[AE:Authoring_custom_camera_animations]]
====Text====
The text-based resource types are fairly easy to edit as long as you don't get confused by the IDs which they use to link to each other. The main textual resources are the pages you can view in the [[Data Comlink]] and the consoles you read in-game. The textual resource types are listed here: {{SectionLink|OBD:File types/Interface|List}}.


====Sound and Music====
====Sound and music====
* Instructions on importing sounds and links to conversion tools can be found [[XML:SNDD|HERE]].
Instructions on importing sounds, and links to conversion tools, can be found [[XML:SNDD|HERE]].


==Need some inspiration?==
==Need some inspiration?==
Retrieved from "https://wiki.oni2.net/Special:MobileDiff/23646...46056"