modding script hooks

To mod authors: Please use the new ::mods_queue function to allow your mods to participate in dynamic ordering. Also, if you compile your own .cnut files, you must exercise care with the command-line arguments. See the documentation for ::mods_hookClass.

This mod implements a few hooks that can be used to implement many types of mods without overwriting script files. It may not be complete, but can be expanded with additional capabilities if and when they're needed. The mod currently exposes the following functionality, as functions that you can call:

INSTALLATION

Just drop the .zip file into your game's data directory. No need to unzip it. NOTE: If you just want to use mods that depend on mod_hooks, you can stop reading here. The rest of this page is only for people who want to develop new mods.

EXAMPLES

For example mods implemented using these hooks, see any of my mods for Battle Brothers.

FUNCTIONS:

::mods_addHook(name, func = null)

Registers a hook that will be called by ::mods_callHook(name). Multiple functions can be registered for the same hook, in which case they'll be called in order. Arguments:

name - The name of the hook, which is arbitrary.

func - The function that will be called when the hook is invoked, or null to simply create the hook without registering a function. The function may take any number of parameters. If the hook function returns a non-null value, that value will be returned from ::mods_callHook and further hook processing will be halted.

::mods_callHook(name, ...)

Invokes hook functions by name. If no hooks have been registered, nothing will happen. If a hook function returns a non-null value, that value will be returned and further hook processing will be halted. If all hook functions return null, the function returns null. Arguments:

name - The name of the hook, which should match that provided to ::mods_addHook.

All additional arguments will be passed to the hook function.

::mods_removeHook(name, func)

Removes a hook that was previously registered. Arguments:

name - The name of the hook, which should match that provided to ::mods_addHook.

func - The function to remove. This must be the exact same function object that was registered.

::mods_hookNewObject(name, func, once = false)

A convenience method for hooking into the instantiation of a new object. Arguments:

name - The name of the object. If the object is implemented in scripts/x/y/z.cnut, the name should be "x/y/z"

func - A function that takes one argument, which is the newly instantiated object. Normally the function should return null, but if it returns a different value that value will be substituted for t