AE:Plugins

Overview

Plugins are instance files that do not conform to the "level#_Final" naming convention. The "level ID" field at the beginning of every instance in a .dat file stores a hashed difference between "_Final" and the suffix of the plugin. Instance files can only be used by Oni under the name specified at the time of their creation.

The retail versions of Oni do not accept plugins as valid "level files", however, this has been fixed for all major versions of Oni as of May 2008. It is thus possible to generate (with OniSplit) and use (with patched Oni engines) a variety of plugins both for "level 0" and for "chapter" levels. Note, though, that just because a feature is new doesn't mean it's as revolutionary/user-friendly/recommendable as you'd like it to be. There's about the same amount of science to making and using plugins as there is to OBD and BSL.

Below is an overview of the basic functionality of plugins, and a few words of wisdom as for the philosophy.

Oni loads instance files in a certain order. On NTFS partitions of Windows and on Mac OS X that order will be ASCII-based (case-sensitive, "B" before "a", etc). On Windows 98 and such the order is more random and depends on dates of creation. As for what happens to the instances in the files being loaded, there is no such thing as "overriding" - more like the first instance registered with a certain name being the only one accessible by that name. Instances without raw parts typically follow the intuitive rule "plugin loaded first - instance registered first". For things like OBJC, the order is reversed, i.e., in order to "override" a level's OBJC you have make sure that the overriding plugin's name comes after level2_Final or whatever you're "overriding" (so, e.g., level2_OBJC). Finally, some instance types are stored dynamically in an array, so: 1) if you have, e.g., several instance files containing ONCCs, they will all end up in the "shapeshifter" array (first the ones from the first loaded instance file, ordered by name, then the ones from the second instance file, also ordered by name, etc); 2) If two of those instance file have an ONCC with the same name, both of them be loaded, at their respective places in the array: both will be accessible with F8 and by ID, but only the one loaded first will be accessible by name.

Now busting a few opinions about how plugins are much cooler than user-side use of OniSplit, shell scripts and delta patches. Of course the fact that you can "just" put the plugin in your GameDataFolder and play makes it look like it's user-friendlier than OniSplit and somehow "empowers dummies" to access modded content without the need for complicated installation routines (with or without a GUI). However, one thing plugins are definitely not is foolproof. They are not "just files" that you put into your GameDataFolder "and see what happens" (and then whine about crashes). They all have their compatibility issues, that imply thorough testing and public release notes. Both the modder and the user should be just as careful when working with plugins as when rebuilding "_Final" levels. One should also be careful not to expect too much from plugins in the big scheme of things.

To create a plugin version of the Edition, for example, is a naive wish. A key feature of the Edition is the "globalization" of virtually every character, sound and texture in Oni. Distributing such a plugin in ready-to-use form would amount to distributing a large part of Oni's content for free, which is very "legally challenged". Also, the download sizes would reach a few hundred megabytes. Last but not least, such a "global" plugin would be redundant of the un-globalized content in the end user's "chapter levels", so: 1) Oni will take up more space on the user's HDD; 2) Oni will load redundant instances simultaneously (thus, in every level, there would be a range of globalized ONCC from the plugin and then the ONCC originally present in that level), possibly resulting in overflow.

Another issue is that a modder has to provide both a "sep" and a "no-sep" version of every plugin if he wants users of all platforms to enjoy his stuff. Considering all of the above, plugins are not likely to be used on a systematic basis for anything but "100% new" content, and in the scope of projects like the Edition, they hardly make any sense at all, because OniSplit is irreplaceable when it comes to globalization.

Also, plugins suffer from a major limitation on the Mac because of how the engine only allows for 16 instance files to be present in GameDataFolder: that means that if the original 15 .dat files are preserved, only one plugin is allowed at a time (historically, this used to be level0_Tools). In the absence of a fix, an obvious workaround is to group Oni's chapters into "acts", and launch Oni with one "act" at a time.

One thing plugins are useful for is testing new content during development. It takes OniSplit much faster to build a small plugin than a chapter level, let alone level0 with full globalization. Note, however, that while working with "hot" file buffers during a modding session, OniSplit can generate a 500-MB level0_Final.dat in about 30 seconds; rebuilding levels after a long break takes considerably longer.

The only thing you should be careful about when working with such plugins is dependencies. Typically your plugin will be all the smaller as it uses global content, but whoever you give that plugin to should be aware of the globalized resources involved. Otherwise you'll get pointless crash reports all the time just because you assumed people would only use your plugin in tandem with the Edition, etc.

Examples

The plugins provided below are for testing purposes only. Apart from "Babel", virtually no plugins should be distributed in the long run, especially those with original game content. Most of the plugins will be generated user-side with xdelta and OniSplit.

level 0 modules

The content of level 0 can easily be split into modules like level0_Characters, level0_Music, level0_Speech, level0_Weapons, level0_Levels, etc. The modules are much smaller than a single level0_Final, so they are faster to navigate and to mod. However, when defining such a partition, it's important to come up with a sensible layout early on: this, and the Mac limitation, makes it tricky to design an "official" set of modules to be used by the Edition.

Babel

http://geyser.oni2.net/edition/plugins/level0_Babel.zip

Description

Includes a plugin for the PC version. Adds russian versions of menu items, subtitles, text consoles, diary/objective pages and item/weapon descriptions.

Limitation

Requires an engine fix (available for PC in the latest Daodan, pending for the Mac) that increases the buffer size for font textures. Without the fix, the original level0_Final will fail to load completely, and out-of-game UI will be screwed up. Things that don't quite work are diary pages and level-specific item descriptions.

BGI

http://geyser.oni2.net/edition/plugins/level0_BGI.zip <- UPDATED 02:52, 28 August 2008 (CEST)

Description

Includes a plugin for both PC and Mac. Adds a set of BGI troopers and executives with various fighting styles and a set of new weapons (ballistics only, nothing fancy). Does not replace any existing ONCC or ONWC.

Limitation

Only works correctly for a retail version of Oni, with globalized TRAC and TRMA. Otherwise, misses TXMPSUPER_REFLECT (Mukade's env-map texture) and/or various TRAC, some of them not available in the demo. Missing TRAC cause memory corruption.

HD Griffin

http://geyser.oni2.net/edition/plugins/level0_Characters.zip

Description

Includes a plugin for both PC and Mac. Replaces the BlackOps Griffin. The new Griffin has a tentative HD head (4 times as many faces) and fights like a Tanker (more so if you update the MELE link in CHAR).

Limitation

Works correctly for a retail version with globalized TRAC and TRMA. Otherwise, misses TRACTanker_animations and BlackOps Griffin's TRMA. Missing TRAC cause memory corruption.

Shinatama Too

http://geyser.oni2.net/edition/plugins/level0_Shin2.zip

Description

Includes a plugin for both PC and Mac. Adds new character: a Shinatama who fights like Konoko and no longer hovers above the ground (the TRBS was scaled up and compensated with a body factor in the ONCC). The textures have been color-swapped (meant as placeholders for a more original combat outfit).

Limitation

Works for any version, with or withour the Edition. Indeed, Konoko's TRAC is global and everything else (TRBS, TRMA, TXMP) is included in the plugin.

Level 2 CHAR

http://geyser.oni2.net/edition/plugins/level2_OBJC.zip

Description

Includes a plugin for both PC and Mac. Slightly modifies the CHAR for CHAPTER 02 . ENGINES OF EVIL: Barabas takes part in the initial ambush, and Muro appears later on.

Limitation

Works with any version of Oni, as long as Chapter 2 is available.

Dashing

http://geyser.oni2.net/edition/plugins/level0_Animations.zip

Description

Includes a plugin for both PC and Mac. Makes all males, Ninja and Furies able to dash. Preserves running animations for Konoko. Provides TRAMai_kon_animations to be used by Evil Konoko, female civilians, etc.

Limitations

Works best with globalized TRAM. Otherwise, Elites, Ninjas and Furies won't be able to fight. This is typically a thing that will not stay a plugin forever, and is provided purely for testing purposes.

Camera

http://geyser.oni2.net/edition/plugins/level0_Camera.zip

Description

Includes a plugin for PC retail only (make_corpse doesn't work for OMNI or PC demo; and if you have a Mac beta, plugin-loading hasn't been fixed for you anyway). Provides a character class for authoring custom camera animations, complete with a set of animations and an aiming screen. Supposed to be used in conjunction with the manual camera and make_corpse: position camera, make corpse, copy pelvis matrix from corpse to OBAN.

Limitations

None. Works with or without edition/globalization. Without make_corpse it is of little use though, except as an experimental hovering turret... just export/import if you're interested in toying with that.