Game data terminology

A brief introduction to game data-related terms that you will need to know when learning to mod. Also see Engine terminology to learn more about the engine itself.

Binary data

A collective term for all of the game data that Oni runs on. It is mostly distributed among the level data files; though some additional data is found in persist.dat, the term "binary data" tends to refer only to the level data files. Not to be confused with "binary", which refers to a compiled application.

Level data files

The data for each level is found in a pair of files in Windows retail Oni's GameDataFolder ending in ".dat" and ".raw". On Macs and in the Windows demo, a file type ending in ".sep" is also used. OniX also expects .dat/.raw/.sep files, so the app's installer converts the user's game data to the .dat/.raw/.sep format.

Instance file

Any .dat file in GameDataFolder. Instance files are the main type of level data file, in the sense that Oni reads the instance file first when loading a level, and this file serves as an index that allows it to find resources which are packed into the other types of level data files.

.dat file

".dat" is a generic suffix originally used by Oni for all kinds of data, with file names such as level0_Final.dat, persist.dat, and developer-related files such as saved_film*.dat, level_*_corpse.dat, etc. The proper, specific name for the .dat files containing level data is "instance file". That being said, ".dat" has only been used by the community historically to refer to instance files, so you can reasonably assume that's what is meant when you see the suffix by itself. On occasion, ".dat" also refers to the complete set of level data files, .dat/.raw[/.sep].

Instance, resource, file

The use of these terms can be confusing. An instance is often called a file on this wiki, but an instance is not the same as an instance file ending in .dat. An instance is an individual resource such as a texture. They are sometimes called files because they are distinct pieces of data stored and cataloged in a "file system" composed of a set of .dat/.raw[/.sep] files. In at least some cases they were indeed actual, separate files on the developer's computer before being packed into the level data files.

When OniSplit is used to split level data files into individual files for each resource, in effect it is creating thousands of "single-instance instance files" ending in .oni, at which point "instance", "resource", "file", and "instance file" become basically synonymous.

Raw file, .raw

During development, the raw file was eventually created as a companion to the instance file. The kinds of resources stored in these files are generally those with larger amounts of data, like textures and sounds. Raw files have no file header and are simple blobs of data; this is because the instance file serves as the table of contents for them. The only structural rules about raw files are that (1) all data parts are stored 32 byte-aligned and (2) the first 32 bytes of the file are always zero. When a level is loaded into memory, the offsets given for raw data in various resources are converted to pointers to the actual data in memory. Details about the layout and usage of raw/separate files can be found HERE.

Raw files are found in all versions of Oni, unlike separate files.

Separate file, .sep

Further into development, as the Mac version of Oni was finalized, the separate file was created as an additional companion to the instance and raw file. Because the Windows demo was released after the creation of .sep files for Mac Oni, separate files are found in the Windows demo's GameDataFolder as well. And as mentioned earlier, when using OniX, Windows retail installations will also be converted to use .sep files because that is the level file format that the current engine expects.

The above statements about the structure of the raw file apply to the separate file as well. When separate files are present, raw files are much smaller because several resource types have their data stored in the separate file instead. See HERE for details, including why separate files were created.

Template, file type, tag

A template represents a type of resource identified by a four-character code (e.g. "SUBT" for subtitle files); this kind of identifier is generically called a "tag", so modding communities often use the term "tag" to refer to a resource type as a whole. However, just as instances are often called files on this wiki, templates are often called file types here. All templates are listed on the File types page.

.oni

Generated by OniSplit, these files are structurally similar to .dat files except that they only contain a single instance, or one parent instance and various supporting instances if the supporting instances could be considered components of the parent instance; for instance an exported M3GM (a 3D model) will contain all of its 3D data even though this data is held in many small instances of several other templates such as PNTA and VCRA. And unlike how .dat files offload some data to .raw and .sep files, in a .oni file any of the data that might have been contained by the .raw/.sep files is simply appended at the end of the .oni file.