1. Felix Krull
  2. dx-Plugins

Overview

A simple Plugin Infrastructure for Deus Ex
https://bitbucket.org/fk/dx-plugins
==========================================
For my SavegameCompression package for Deus Ex [compression], I needed a mechanism to run some code when the game launches. And since I couldn't find a way to do that without either changing DeusEx.ini or rebuilding DeusEx.u or other evil-replacing means, I figured I could at least make it generic enough so that other hypothetical projects could be loaded without having to change any of these files; this package is the result.


Compiling
=========
Compiling goes just like with any other UnrealScript package: Add "EditPackages=Plugins" to the "[Editor.EditorEngine]" in DeusEx.ini and do "ucc make". Then, also in DeusEx.ini, find the line "DefaultGame=DeusEx.DeusExGameInfo" and change it so that it reads "DefaultGame=Plugins.DeusExPluginLoader". For HDTP Release 1, do that in HDTP.ini as well.


Advanced Configuration
======================
By default, i.e. after the installation steps above, all plugins in your DeusEx\System directory will be loaded by default (granted, probably not a lot). However, there are a few additional configuration options that you can use to fine-tune the behaviour. All of these need to be put into a section "[Plugins.PluginManager]" in your DeusEx.ini.

- bPluginsEnabled: bool, default: true
Set to false to disable plugin loading entirely so that no plugins at all will be loaded.

- bAllowPluginsByDefault: bool, default: true
Determines the default behaviour for unknown plugins, i.e. those that are not explicitly allowed or disallowed. If set to true, any plugin that is explicitly forbidden (see DisallowedPlugins) will be loaded; if set to false, any plugin that is not explicitly allowed (see AllowedPlugins) will not be loaded.

- AllowedPlugins: string, default: ""
Add the (fully qualified) class name of a plugin class to explicitly allow it. Has no effect if bAllowPluginsByDefault is true.

- DisallowedPlugins: string, default: ""
Add the (fully qualified) class name of a plugin class to explicitly disallow it. Has no effect if bAllowPluginsByDefault is false.

If you want to specify several plugin names for AllowedPlugins or DisallowedPlugins, I'd suggest you just put them one after the other separated by spaces. It's a bit stupid, but that's Old UnrealScript for you. If you really want to know the exact format, read the source at your own responsibility.


For Developers
==============
To create a plugin:
1. Create a subclass of ``Plugins.Plugin`` (in UnrealScript, that is). Implement the method ``Load`` to do your evil bidding. Have it return ``true`` if you think your plugin loaded successfully, ``false`` otherwise. While this return value is currently rather inconsequential, it will at least produce a nice log entry. Take a look at Classes\ExamplePlugin.uc in the source distribution for, well, an example.
2. Write a .int file describing your plugin. Again, ExamplePlugin.int is your best friend here. Change the ``Name`` parameter to the fully qualified name of your plugin class and adjust ``Description`` to your needs (note that the description isn't actually used anywhere).

The actual loading of plugins is implemented in Classes\PluginManager.uc. It collects all plugins that it can find, creates an instance of their plugin class and calls its ``Load`` method. There's some magic in place to make sure each plugin is only initialized once per game start; specifically, ``Load`` will generally be called when entering the main menu.

To actually call the loading mechanism, a modified subclass of ``DeusExGameInfo`` class is used, ``DeusExPluginLoader``. The upshot is that you'll need a dedicated plugin loader class for each mod (that uses its own ``GameInfo`` class, which is most of them). See also [tnmloader] for a plugin loader for The Nameless Mod [tnm].


Legal stuff
===========
Copyright (c) 2012 Felix Krull <f_krull@gmx.de>
All rights reserved.
This software is distributed under the terms of the 2-clause BSD license. The full license text can be found in the file License.txt. In short, you can distribute copies and derived works so long as you include the copyright notice and the disclaimer.


Links
=====
[compression] https://bitbucket.org/fk/dx-savegamecompression
[tnmloader] https://bitbucket.org/fk/dx-tnmpluginloader
[tnm] http://thenamelessmod.com