Anniversary Edition/Framework

The Anniversary Edition Seven introduced a revised framework which installs into the directory Oni/AE/, separate from any previous Editions, which installed into Oni/Edition/. Following is a technical description of how mods are installed, from start to finish. To learn how to make your own mod in the package format used by the AE Installer, see Making a mod package. To understand the material below, you should first be familiar with Oni's data files on a general level, so OBD is recommended reading.

Initialization

When first running the Installer, the user is required to initialize the AE. This is a one-time process that uses OniSplit to break the .dat/.raw(/.sep) files in Oni's GDF into their constituent resources, yielding thousands of .oni files. These files are stored in temporary folders, one for each level.

Next, the Installer performs what is called globalization. When developing Oni, in order to save memory, BWest put in each level's data files only the characters, textures, sounds, etc. that were needed. Since we have far more RAM these days, we can make this data available in all levels in order to allow more versatile modding. To do this, the Installer moves many of the .onis from each specific level's folder into level 0's folder, discarding duplicates in the process (since many of the same resources were duplicated throughout the original levels' data).

There is a major exception to this globalization, however. Each level's AKEV and all child resources (e.g. all environmental textures), as well as the level's title, fail and win screens, and LSI, are left in that level's folder. If the textures were globalized and a modder intended to replace a texture on just one level, it would show up in all levels, which might not be the desired effect. So, what data is globalized? Primarily, all characters, their animations (even the ones for specific cutscenes), all sounds, and any textures that are not connected to AKEVs (e.g., unused textures). All particles are already globalized in vanilla Oni, and these remain globalized in the AE.

Finally, the Installer builds new .dat/.raw(/.sep) files for each level from those re-shuffled folders of .oni files, saving them in AE/AEInstaller/vanilla/. Note that no data has been altered yet, just the resources reorganized.

Installation

After this, the user can choose some mods to install. When the Install button is clicked, the Installer (AEI) performs the following actions:

1. Look at which levels will be altered by comparing the current selection of mods to the set of previously installed mods, and delete those levels' .dat/.raw(/.sep) files from AE's GDF.

2. Collect .oni files that will be patched by an XML patch mod by calling OniSplit with -export: switch. The .oni files are stored in a system temporary directory, so they will be automatically deleted by the OS later.

The Installer first looks for any patches (.oni-patch files) among the user's chosen mods. An .oni-patch is named according to the resource it modifies, e.g. TRAMKONCOMbk_fw_kick.oni-patch, and placed in a folder with a level's name, such as level2_Final/, in order to indicate which level it patches (just like the .oni files in mod packages).

Because patches are intended to take precedence over any regular mods, the Installer checks whether any selected mods have a .oni file, meant for the same level, which matches the .oni-patch's name. If so, it converts the mod's .oni file to XML; otherwise it extracts the resource by that name from the vanilla .dat of the appropriate level (stored in AE/AEInstaller/vanilla/). If more than one mod has a matching .oni, the highest-numbered mod's .oni is used.

3. Convert .oni files from step 2 to XML by calling OniSplit with -extract:xml switch. The XML files will be deleted after installation is done.

4. Process XML patches by calling XmlTools to operate on XML files from step 3.

The AEI makes a single temporary patch file which lists inside of it a series of commands to XmlTools to perform the instructions in each individual .oni-patch file. This "master patch" is made for performance reasons and should not affect the modder who creates .oni-patches. Read the documentation for XmlTools to understand how the patch files are actually processed, and read Making a patch mod to learn how to make an XML patch mod.

5. Convert patched XML files from step 4 back to .oni files by calling OniSplit with -create switch.

The newly-made .oni files, with the patches applied, overwrite the .oni files in the directory in which they were placed in step 2.

6. Build new level files by calling OniSplit with "pack -out" switch.

For each level, the AEI passes OniSplit the location of the vanilla AE .dat (in AE/AEInstaller/vanilla/) plus a list of directories that contain .oni files meant for that level in ascending order by mod number, so that higher-numbered mods override lower ones*. The last directory in the list is the temporary directory containing the patched .oni files from step 5, so that the patched files override any other versions of those resources. The final .dat/.raw(/.sep) files have now been created in the AE's GDF.

*Note that this is on a file-by-file basis. So a package numbered 11111 will only override package 11110 wherever their files conflict, when they are both installed. Thus a package numbered 11111 could be used intentionally to override only certain files in 11110, e.g., to improve or fix them. On the other hand, a partial override by a higher package might be an undesirable interaction. It's the responsibility of the modders to be aware when there's an unwanted interaction and to mark their mod as being incompatible with the other one using the Incompatibility flag described in Making a mod package.

7. BSL files are treated similarly to .oni files. Mods with bsl/ folders are considered in ascending order and the highest-numbered mod that affects a given level has its BSL files copied to the AE IGMD folder. The special case with BSL is the "addon" feature. When a mod's Mod_Info.cfg uses the "HasBSL->Addon" flag, those mods' BSL files are considered after the highest-numbered regular BSL mod (or vanilla BSL, in the absence of any mod) is installed for each level. The addon BSL files are copied into the desired level folders, overwriting whatever file by the same name already exists there.

Secret feature: If a modder is experimenting with his own script in a given level's BSL folder, he can place an ignore.txt file in that folder (no contents necessary) in order to prevent the AEI from wiping out the BSL in that folder in case a mod tries to affect it.

8. Plain files (files in a mod's plain/ directory) are copied into the directory specified within the platform folders within the plain/ folder. E.g., if the mod contains the directory plain/common/Tools/, then the files in that directory will be copied into a Tools folder in the AE/ directory.

9. If the user's AEI preferences call for it, the intro and/or outro videos are copied from the vanilla Oni GDF to the AE GDF.

10. Any new levels that were added by mods to the game are unlocked by editing persist.dat so that they are accessible from the Load Game dialog.