Extensions

Extensions

Extensions are "plug-and-play" components that expand or customize the game.

Common

Layout

The files in an extension are as follows:

• /definition.yml

  Required file containing the definition of the extension: its name, version, author, dependencies

  Example:

name: your-extension-name
author: "Your name"
version: 1.0.0 # semver version
dependencies:
  frontend: ^1.0.0 # which frontend is required
  framework: ^3.0.6 # which framework is required
  rebalancer: ^1.0.6 # which dependency and version is required
type: plugin # either "module" or "plugin"
display-name: "Your extension display name"
meta: # meta attribute specifying this file's format
  version: 1.0.0

• /options.yml

  Optional configuration options for your extension, default values and UI display information is defined here.

• /config.yml

  Optional configuration demands placed on dependencies.

• /locale/en.yml

  Files containing locale information for translating UI options for users.

• /locale/description-en.md

  File containing the information to be displayed when a user clicks on your extension in the GUI.

• init.lua

  Optional lua file containing, when present, at least the following:

  return {
    enable = function(self, config) end,
    disable = function(self, config) end,
  }

The function enable is called when the main process is starting. This function generally speaking runs available lua functions, either provided by other extensions or provided by the framework itself.

/*/

Any (sub)folders are allowed

Plugins

/resources/

Plugins can have a resources folder containing AI, maps, graphics, sound files, etcetera.

Modules

Special permissions

Modules are the only type of extension that can modify game code. Therefore, they have access to the functions specified in core.lua, these are available when init.lua is executed.

/*.dll

Because of this reason, modules can contain DLL files that help out with executing code (highly performant code).

Note that the enable function in init.lua should be responsible for setting up the link between the game and such a DLL.

The easiest way to achieve this is to have a luaopen_dllname C function in the DLL that returns pointers to the DLL's functions. From the lua side, the pointers to these functions can then be used to set up hooks, detours, etc.

The DLL thus depends on at least one library: the same lua version as the modding framework. And the DLL can depend on the ucp.dll itself for quick access to some functionalities.