OBD:Instance file format

Click to return to the main OBD page.

".dat" redirects here; for other files ending in ".dat", see Oni (folder).

You should read the Game data terminology page before this one.

The Raw and separate file formats page should be read after this one.

Files in GameDataFolder/ named "level[0-19]_Final.dat", together with ".raw" and sometimes ".sep" counterparts, contain the game data for Oni. These are called "instance files" internally, but a more common-sense name for them is level data files. The format described below was also used for the tool files which supplied the GUI for the in-game editor, however the retail Oni game application refuses to load tool files; for the story behind the tool files, see level0_Tools.

The level 0 files do not contain resources for a specific level but rather resources (instances) shared across all levels. Level 0 is loaded when the game starts and is never unloaded. All other level files, 1-19, are only loaded when their corresponding level starts and then unloaded when it ends. Oni can only hold two level files in memory concurrently. Thus, resources have to be duplicated on disk whenever a character class, sound effect, etc. occurs in more than one level. For instance, although there are only 2,380 unique sounds in the game, there are 7,386 sounds stored across all level data files.

Backwards and garbage data

As mentioned, the game's developers used the in-game editor to create AIs, particles, etc. in a level. When one of these developers saved his work, the contents of the level, stored in his PC's RAM, were flushed directly to disk. Thus the structure of the .dat/.raw/.sep files reflects the way in which Bungie West chose to store levels in memory. So when we read the data in the files with a hex editor, we can see eccentricities such as blank space (coming from unused fields and byte-alignment padding) and garbage data (such as now-meaningless pointer values). Further gaps, mostly representing orphaned obsolete resources, add up to about 25 MB for the whole game.

Additionally, because the levels were built on Intel-based machines, which use a little-endian architecture, sequences of bytes which represent numbers were written from least-significant to most-significant byte. FourCCs in the data are stored "backwards", such as "13RV" which is meant to be read "VR31", because Bungie defined those four bytes as a 32-bit integer, not a string, causing them to be written to disk in little-endian order.

File limits

• Max level number: 127
• Max number of instance files in GameDataFolder: 512 (Windows), 16 (Windows demo, Mac)
• Max number of simultaneously loaded instance files: 64
• Max number of instances in a file: 131071
• Max length of an instance file name: 31
• Max length of an instance name: 63 (including the 4 character template tag)

Header

Here is a walkthrough of an instance file using the level0_Final.dat in English Windows Oni. Follow along in a hex editor for maximum educational value. Each term will be explained in-depth when we fully consider the related data. First, here is how the file begins:

Offset	Type	Raw Hex	Value	Description
0x00	uint64	1F 27 DC 33 DF BC 03 00	0x0003BCDF33DC271F	Total template checksum (main indicator of engine compatibility): 0x0003BCDF33DC271F (PC v1.0) - templates compatible with Windows retail engine 0x0003BCDF23C13061 (PC v1.1) - templates compatible with Windows demo and Mac engines 0x0003BA70A8DBAE11 (PS2) - templates compatible with PlayStation 2 engine OniSplit's .oni files use PC 1.0 checksum by default and 1.1 checksums when holding data that is stored differently in the 1.1 format (SNDD, TXMP, AGQG, M3GM, IGSt, TSFT/TSGA, TRAM/TREX)
0x08	uint32	31 33 52 56	'13RV'	.dat version (meant to be read as "VR31") OniSplit's .oni files use '23RV' ("VR32") instead
0x0C	uint16	40 00	64	size of this header
0x0E	uint16	14 00	20	size of instance descriptor (32 in Windows alpha 6)
0x10	uint16	10 00	16	size of template descriptor
0x12	uint16	08 00	8	size of name descriptor
0x14	uint32	83 24 00 00	9347	instance descriptor count
0x18	uint32	D4 1B 00 00	7124	name descriptor count
0x1C	uint32	38 00 00 00	56	template descriptor count
0x20	uint32	A0 BC 03 00	0x03BCA0	data block offset
0x24	uint32	A0 35 25 00	2438560	data block size
0x28	uint32	40 F2 28 00	0x28F240	name block offset
0x2C	uint32	04 4F 02 00	151300	name block size
0x30	uint32	99 CF 40 00	(garbage)	used by OniSplit for raw table offset
0x34	uint32	90 4F 63 00	(garbage)	used by OniSplit for raw table size
0x38	uint32	F4 55 5F 00	(garbage)	unused
0x3C	uint32	90 4F 63 00	(garbage)	unused

The file's total template checksum is the sum of all the template checksums (see "Template descriptors" below). Oni looks at this number in order to validate that it can read this version of the game data format. In practical terms, the total checksum value given for Windows above tells us that this level data is in the .dat/.raw file scheme, and the value given for Mac Oni and the Windows demo tells us that the level data uses the .dat/.raw/.sep file scheme.

The version of the instance file is the format version. Reading it backwards, as discussed under the "Backwards and garbage data" section, we get "VR31" (which probably means "version 3.1" because the engine subsystem that reads template data was in its third iteration when the game shipped). This is the format version of all instance files in all releases of Oni.

The descriptor sizes are the sizes of the instance, template, and name descriptors which are coming up in this file (see breakdowns in later sections). For instance, each instance descriptor will be 0x14, or 20 bytes, in length.

The descriptor counts are the sizes of arrays which are coming up in this file: the instance, name and template descriptors. For instance, the size of the instance descriptor array will be 0x2483, or 9,347 items, in length.

Next we are told the addresses and sizes of the data and name tables in the instance file. The name block simply follows the data block, as you'll see if you add the data block offset plus the data block size, so the name block offset is technically redundant. The name block offset plus the name block size equals the total size of the file since it's the last segment of the file.

After the name block's size comes four "int"s of garbage; this is padding in order to align the start of the next segment of the file on a 32-byte boundary. The first two 32-bit fields in this space are, however, used in .oni files generated by OniSplit.

That concludes the header of the instance file. Immediately after this header we find the instance descriptors array.

Instance descriptors

The instance descriptor array tells Oni where to find the data and the name of every instance (resource) indexed by the .dat file. The descriptors start at 0x40 in the .dat file, but below is a descriptor found at 0x017B50 in the file which makes a better example. In the table below, we use offsets relative to the start of this descriptor. We also show the alternate structure in the Windows alpha 6, the oldest known version of Oni and the only one with an observed difference in the instance descriptor format.

Offset	Type	Raw Hex	Value	Description (retail)
0x00	tag	54 42 55 53	'SUBT'	template tag
0x04	int32	C8 30 22 00	0x2230C8	data offset (relative to data block)
0x08	int32	01 CB 00 00	0xCB01	name offset (relative to name block)
0x0C	int32	C0 09 00 00	2496	data size
0x10	int32	00 00 30 00	0x300000	flags

Windows alpha 6

Offset	Type	Raw Hex	Value	Description (alpha 6)
0x00	int64	68 6C 04 00	0x46C68	template checksum
0x08	tag	54 42 55 53	'SUBT'	template tag
0x0C	int32	E8 37 18 00	0x1837E8	data offset (relative to data block)
0x10	int32	4E C5 00 00	0xC54E	name offset (relative to name block)
0x14	int32	20 08 00 00	2080	data size
0x18	int32	00 00 30 00	0x300000	flags
0x1C	int32	EA 5F A6 39	08252000 08:00:42 AM	creation date (seconds since 1/1/1900)

The retail version of this instance descriptor tells us that a resource of type SUBT (a subtitle file for Oni; there are only two of these, one containing all speech subtitles, and one for help messages) has data that can be found 0x2230C8 bytes into the data block, which we learned from the file header starts at 0x03BCA0. Its name can be found 0xCB01 bytes into the name block that starts, according to the file header, at 0x28F240.

The data's size is given as 0x09C0, or 2,496 bytes, but it's important to clarify that this is the total size of the data counting from the resource header to the next 32-byte boundary after the end of this instance's actual data; in other words it is the true total of the space occupied on disk by this instance. This is interesting because the data offset leads you to the start of the instance-specific data which begins 8 bytes after the resource header, so if you erroneously add the data size to the data offset to find the end of the instance data then you will find yourself 8 bytes into the next instance.

Before we proceed, let's expand upon the flags field.

Flags - data usage

0x01 00 00 00 - unnamed

0x02 00 00 00 - empty

0x04 00 00 00 - never used; intended to mark instance as pointing to duplicate data rather than its own data

0x08 00 00 00 - instance's data is being used by duplicate instances as a source

Flags - Tool mode

The first two of the following bits occur throughout the original .dat files. However all of these bits are ignored by the engine when loading data because they only have relevance at runtime when Oni is in Tool mode:

0x00 00 10 00 - touched (unsaved data)

0x00 00 20 00 - "in batch file"

0x00 00 40 00 - delete upon next save

The flags "unnamed" and "empty" require special explanation.

Unnamed and empty resources

You'll notice that the level file header lists fewer names (7,124) than instances (9,347). That's because there are 3 types of instance:

• Unnamed and not empty - they are only referenced by other instances in the same file, generally as child data (e.g., 3D geometry elements like ABNA are "contained" by AKEV, a level's environment).

  In vanilla Oni .dats there are some rare occurrences of unnamed non-empty orphan instances (e.g., TRCM). These are a form of garbage and are discarded by OniSplit when unpacking a level.

• Named and not empty - they can be referenced by other instances in any file and the engine can use their name or template tag to find them.
• Named and empty - "empty" instances are used in level-specific instance files (i.e. not in level0_Final.dat) to associate an instance ID with a name. For every empty resource, there's another one with a matching name in level0_Final.dat that has data in it. The empty resource in the instance file is (usually) looked up by ID, then the engine searches all the loaded files for a non-empty instance with the same name, causing it to find the actual file in the global data in level0_Final.dat.

Peeking ahead at instance name

Before we talk about the name block in depth, we can peek ahead at the name of this resource using the offset we've just been given. Let's add the offset 0xCB01 to 0x28F240, the file header's address for the name block. This gives us the address 0x29BD41. There we find the string "SUBTsubtitles".

Peeking ahead at instance data

The actual subtitle data should be found by adding the offset 0x2230C8 to 0x03BCA0, the file header's address for the data block, to get 0x25ED68. We're going to leave the full details of the data block for later, but below is the data you should actually see for the English Oni SUBT file at this address. You have to consult the SUBT page to know how to read this data.

Offset	Type	Raw Hex	Value	Description
0x08	char[16]	AD DE	dead	unused
0x18	offset	80 44 44 01	0x01444480	raw file data address
0x1C	int32	61 02 00 00	609	array size

After padding of 16 unused bytes, we find that, instead of data, there's an address of the actual data: it's in the level's raw file. Open level0_Final.raw and jump to address 0x01444480, and you should see "01_01_01 Griffin: Give me another reading.", and the rest of some very familiar dialogue continuing from there.

The array size of 609 tells the part of the engine that reads SUBT data to expect a chunk of 609 subtitled lines of dialogue.

Name descriptors

The name descriptor array starts immediately after the instance descriptors array. To find the end of the instance descriptors, we can simply take the size of an instance descriptor, 20 bytes, and multiply it by the number of instance descriptors in the file header. In this case, that means 20 * 9347 = 186940, or 0x02DA3C. Adding that to 0x40 (the start of the instance descriptors) takes us to address 0x02DA7C. Voila, the start of the name descriptors.

The name descriptor array stores the numbers of all named instances in the alphabetical order by said names, which are found in the name block but also pointed to by these entries. This array is used by the engine to look up instances by name; it's also used to find instances by template (scanning just the tag at the start of each name). The purpose of this array being alphabetized was to allow the engine to do a binary search to find instances by name more quickly, but the retail engine no longer attempts a binary search and merely iterates over the array from start to end.

Offset	Type	Raw Hex	Value	Description
0x00	int32	15 16 00 00	5653	instance descriptor index
0x04	int32	60 2C 1C 0E	(garbage)	runtime: pointer to instance name

The index number here is referring to the instance's position in the instance descriptor array. This number is also used by the data block to identify each instance, thus it is found in two places in the data explicitly and one place implicitly.

Since the addresses of the names in memory cannot be known until the file is loaded into RAM, a space of 32 bits is reserved for each pointer at runtime.

Template descriptors

Likewise, the template descriptor array starts directly after the name descriptors. Since name descriptors are 8 bytes, 8 * 7124 (taken from the header) = 56992, or 0xDEA0, and adding that to the name descriptor array's start address (0x02DA7C) gives us 0x03B91C as the start of the template descriptors.

The template descriptor array contains information about all templates (that is, resource types, aka tags), used in the file (56 in this case, as we learned from the file header). Any resource occurring in this instance file has to have its type listed here. Here is the template descriptor at 0x3B9FC:

Offset	Type	Raw Hex	Value	Description
0x00	int64	3C B9 A6 71 08 00 00 00	0x871A6B93C	template checksum
0x08	tag	45 47 52 54	'EGRT'	template tag
0x0C	int32	01 00 00 00	1	unused: number of resources in file that use this template

The template checksum is used to prevent loading of instance files that are not compatible with the current engine version. The tag is the same kind of number-written-as-backwards-ASCII that we discussed in the "Backwards and garbage data" section; in this case, 'EGRT' means TRGE. The field for the number of resources using this template is unused. The number should be correct for each template, but Oni never uses it for anything.

You might wonder how Oni knows how to read each type of data, such as a SUBT or an ABNA. The simple answer is that this information is hard-coded into Oni. In fact, the information on each instance type, as stored in Oni's code, is actually the real "template". The file data merely gives the tag and checksum that identify the template in use so that Oni knows how to read the following data fields. These hardcoded templates also tell Oni which parts of the file data are reserved for pointers.

That's because an instance may have pointers to other related instances, but pointers are only valid in memory; they cannot be stored meaningfully on disk. They must be set at runtime when the level data is loaded into memory and an address in RAM has been assigned. Thus one type of data field in Oni's templates is a "raw data" pointer; on Macs and the Windows demo, there is an additional "separate data" pointer. These pointers are 32 bits in length, as one must expect since Oni was compiled for 32-bit PCs.

Incidentally, the templates in Oni's code have not just the familiar four-character tags attached to them, but also a descriptive string, e.g. "BSP Tree Node Array". These strings were typed into the source code where each template structure was defined, and eventually extracted from the binary by modders. This is the source of the names on OBD:File types.

Data block

The data block occupies the majority of the file and stores all the instance data (though this data sometimes points to the location of more data in a raw/separate file). We peeked at this table before when we looked at the instance descriptor for SUBTsubtitles. The table's starting point is found at the offset given in the header, in this case 0x03BCA0, saving us the trouble of adding up the size of the four preceding segments of the file and then aligning to the next 32-byte boundary.

The reason we'd need to align to 32 bytes is that the start of each instance's record (the instance ID) is always 32 byte-aligned. Thus, even though the template descriptors ended at 0x03BC9C, there are four empty bytes here so that the data block can begin at 0x03BCA0, which divides evenly by 32. This alignment rule also means that the instance-specific data will always start at an offset like 0x0008, 0x0028, 0x0148, etc.

The instance ID and file ID are not actually part of the instance data but are considered to be the resource header. The engine always keeps pointers to the start of the type-specific data itself; we saw this before when we jumped to 0x25ED68 and saw the data for the SUBT rather than the header for this data. The instance ID and file ID are accessed using negative offsets when needed (usually to find the name or template tag of an instance, given a pointer to it).

Offset	Type	Raw Hex	Value	Description
0x00	res_id	01 0B 04 00	1035	instance descriptor index
0x04	lev_id	01 00 00 06	3	level number
0x08	...	...	...	type-specific data...

This example is taken from level 3 so that the file ID is more instructive. In the OBD documentation, these fields are called res_id and lev_id as seen above.

The instance's ID is stored as "(instance descriptor index << 8) | 1". Thus the 1,035th entry in the instance descriptor index will be encoded as 0x40B00. The '1' allows the engine to know which IDs have already been converted to pointers (an instance pointer will always be 8-byte aligned, so it will never have the zero bit already set). These pointer flags were retained when the file was written to disk but are meaningless now. At level-load time the flags are cleared and then set again when Oni allocates memory for each instance. The purpose of left-shifting the index number is simply to leave the lowest byte open for the pointer flag.

The file ID is computed from the number found in the name of the instance file: "(level number << 25) | 1". Thus instances found in level3_Final.dat will have the file ID encoded as 0x6000001. Again, the '1' is used by the engine to know which file IDs have been converted to pointers at runtime, but on disk this is a relic which has no meaning to us. The reason for left-shifting the level number might have originally been to store it alongside the instance ID and the pointer flag in a single int32, but they are separate numbers now, perhaps so that both IDs can have their own pointer flag.

After the header, the size of each instance's data is of a somewhat arbitrary length depending on the template this instance falls under. As mentioned under "Instance descriptors", the data size given by the descriptor includes the 8-byte resource header and the padding at the end of the data to align the next instance on 32 bytes.

Looking backward from data to instance

By the way, if you pick a random place in the data block to look at with a hex editor, how do you know which resource you're looking at? You would look for the highest data offset in the instance descriptor array that is less than your position in the file. Let's say that the string at 0x3BD40 caught our eye: "powerup_ammo". Subtracting the start of the data block, 0x3BCA0, gives us 0xA0 as the position of this string. Now looking back at the instance descriptor array, the instances' data offsets occur every 20 bytes and come directly after the tags. We can see that the first data offset is 0x8 and the next one is 0xF68, thus our offset into the data block of 0xA0 means we are looking at the instance which starts at 0x8. It's the very first instance listed at the start of the instance descriptor array:

Offset	Type	Raw Hex	Value	Description
0x00	tag	53 47 4E 4F	'ONGS'	template tag
0x04	int32	08 00 00 00	0x08	data offset (relative to data block)
0x08	int32	00 00 00 00	0x00	name offset (relative to name block)
0x0C	int32	60 0F 00 00	3936	data size
0x10	int32	00 00 00 00	0	flags

So this tells us that the first data in the data block belongs to the solitary ONGS resource, and that it extends for 3,936 bytes. Since its name offset is 0x0, it's the first string in the name block, which we can see below is SUBTsubtitles.

Name block

This final segment of the file stores all the instance names as C-style ASCII strings (terminated by a zero byte). We peeked at this before when we looked at the instance descriptor for SUBTsubtitles. The start of this table is 32-byte aligned but after that the strings are simply packed end to end, separated only by their null terminator. As with the data block, the name block's starting point is given in the header, in this case 0x28F240.

Offset	Type	Raw Hex	Value	Description
0x00	string	53 55 ... 00	"SUBTsubtitles"	name string (zero-terminated)

These names can be up to 63 characters long, counting the tag. The instance file concludes with the end of the name block.