Plugin API (C++)

The server side of a plugin: how a plugin library is built against the LonelyIce fork of AzerothCore, the entry points it exports, the checks the loader makes and what it does with a plugin, in which order. The loader (PluginMgr, src/server/shared/Plugins of the fork) is part of the core, so everything here applies to the fork's plain worldserver, authserver and dbimport as much as to LonelyIce. The package side (manifest fields, launcher settings, patches, client files, catalogs) is in Plugin format; the fork's own summary is its doc/Plugins.md.

Core build

Plugin libraries need the core built as shared libraries, with a name for its binary interface:

cmake -DWITH_DYNAMIC_LINKING=ON -DAC_PLUGIN_ABI=<name> -DAC_PLUGIN_SOURCE_DIRS=<plugin dir>;<plugin dir> ...

A core built without shared libraries takes the same plugin sources, built into the programs (see Built into the programs).

AddPlugin

A plugin's CMakeLists.txt calls

AddPlugin(<target> SOURCES <files...> [CORE <library>] [LINK <libraries...>] [INCLUDES <dirs...>]
          [RUNTIME_FILES <files...>] [EXPORT_ALL])

The library is named after server.library of the manifest and placed in <AC_PLUGINS_OUTPUT_DIR>/<id>/server/<platform>/. plugin.json, the folders data, sql, conf, lua, client and the files settings.json, icon.png, LICENSE, README.md are copied next to it on every build (folders are replaced, so removed files disappear). Every plugin is compiled with AC_PLUGIN_BUILD defined, for headers that choose between dllexport and dllimport.

Entry points

A plugin library includes PluginApi.h and ends with exactly one entry macro:

#include "PluginApi.h"

void AddTacticsScripts();       // creates the plugin's ScriptObjects, as a module's Add*Scripts() does

AC_PLUGIN(AddTacticsScripts)

Both functions are plain void() functions (PluginFunction). In a shared-library build the macro defines four C functions, exported with __declspec(dllexport) on Windows and default visibility elsewhere:

extern "C" char const* AcorePlugin_Abi();        // AC_PLUGIN_ABI
extern "C" char const* AcorePlugin_Platform();   // AC_PLUGIN_PLATFORM
extern "C" void        AcorePlugin_OnLoad();     // calls onLoad, if any
extern "C" void        AcorePlugin_AddScripts(); // calls addScripts, if any

AC_PLUGIN_PLATFORM is fixed by the compiler's target:

In authserver and dbimport only onLoad runs; they have no scripts. A database backend is a plugin whose onLoad calls RegisterBackendDriver (IDbConnectionBackend.h) and whose manifest lists "apps": [ "worldserver", "authserver", "dbimport" ]; see the fork's doc/Plugins.md.

Loading

The programs call the loader after their main config and the log are loaded, before the module configs and the databases:

The folder is the config option PluginsDir (default plugins, relative to the working directory); LonelyIce sets it through AC_PLUGINS_DIR (Environment variables). PluginMgr::Load:

1. Reads plugin.json of every subfolder, in name order (folders without one are ignored, so plugins/.disabled is never looked into). A plugin not made for this program (server.apps, default ["worldserver"]) is left out without a message. Unknown format, a missing id or version, a manifest that cannot be parsed and an id already used by another folder are logged as errors and skipped.
2. Adds the plugins built into the program that have no folder (with a warning: their configs and SQL are not used).
3. Drops, until nothing changes, plugins whose depends are missing or out of range and plugins whose conflicts name a plugin still in the set.
4. Orders the rest: dependencies first, ties by id.
5. For each plugin in that order: skip it if a dependency failed to load; otherwise open its library (below). A plugin that fails is logged (Plugin <id> <version> not loaded: <reason>) and counts as failed for the plugins after it.
6. For each loaded plugin: register its config (config of the manifest) with the config manager, add its databases folders for auth, characters and world to the updater (state MODULE), log Plugin <id> <version> (<name>), then call its onLoad.

Opening a library:

• a plugin built into the program uses its registered entry points, no library and no ABI check;
• a plugin without server.library (data or client only) has nothing to open and loads;
• core.abi of the manifest must equal the core's AC_PLUGIN_ABI;
• a core without shared libraries refuses plugin libraries;
• the file server/<platform>/<library> must exist (name.dll, libname.so, libname.dylib);
• Windows: LoadLibraryEx with LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR | LOAD_LIBRARY_SEARCH_DEFAULT_DIRS, so the DLLs next to the plugin library are found; Linux and macOS: dlopen with RTLD_NOW | RTLD_GLOBAL, so a plugin's symbols are visible to the plugins loaded after it;
• AcorePlugin_Abi and AcorePlugin_Platform must be exported, with AcorePlugin_OnLoad or AcorePlugin_AddScripts, and must return the core's ABI and platform.

Then the program loads the module configs: for each plugin with a config, first the .conf.dist from the plugin folder, then, if it exists, modules/<name>.conf, whose values override it key by key. That modules folder is the one beside the main config file the program loaded (-c; LonelyIce passes its absolute path), on every system; only when there is no such folder does the core use modules of its default config directory (configs/ of the working directory on Windows, the build's CONF_DIR elsewhere, ConfigMgr::GetModulesConfigPath()). The static modules' configs are looked up in the same folder. reload config reads all of them again. Options in the .conf that the .dist does not declare are reported as unknown. worldserver and LonelyIce --server register the plugins' scripts in the modules script loader, after the static modules (sPluginMgr->AddScripts()), and add every loaded plugin's id to the enabled-modules list. Libraries stay loaded until the process exits; there is no unloading or reloading.

PluginMgr

PluginMgr.h (library shared), reached as sPluginMgr:

PluginInfo:

Ranges for Satisfies (and depends) mean what they mean in npm's semver: comparators separated by spaces and/or commas, all of which must hold (>=1.0.0 <2.0.0 or >=1.0.0,<2.0.0). ^1.2.3 is >=1.2.3 <2.0.0, ^0.2.3 is >=0.2.3 <0.3.0, ^0.0.3 is >=0.0.3 <0.0.4; ~1.2.3 and ~1.2 stay below 1.3.0, ~1 below 2.0.0; a partial version covers what it leaves out (1.2, 1.2.x: >=1.2.0 <1.3.0; <=1.2: <1.3.0; >1.2: >=1.3.0); * matches anything. The table is in Package manager. A range that cannot be read (||, hyphen ranges, pre-release versions, unknown operators) never matches; the core's Acore::VersionRange::IsValid(range, &badTerm) (VersionRange.h) tells whether a range can be read and where it cannot, and the loader skips a plugin whose depends has such a range.

Plugin code

• Configuration: sConfigMgr->GetOption<T>("Key", default), as in a module; the options come from the plugin's .conf.dist and .conf, and AC_<KEY> environment variables override them.
• Databases: only through the core's interfaces: WorldDatabase, CharacterDatabase, LoginDatabase, prepared statements, transactions, and ModuleDatabasePool for a database the plugin owns. The loader registers update folders for auth, characters and world only; a plugin-owned database (an object in databases) is opened, created and updated by the plugin itself (playerbots: ModuleDBUpdater in its DatabaseScript). SQL files follow Plugin format, section 5.
• Other plugins: declare them in depends (they load first) and link against their libraries with LINK; check an optional one with sPluginMgr->IsLoaded("<id>").
• Named ids given out for the plugin's patches are read from the world table plugin_ids (Plugin format, section 7).

Built into the programs

With a core built without shared libraries, AddPlugin builds the plugin as an object library linked into each program of server.apps (worldserver when missing), copies its RUNTIME_FILES next to the programs and still lays out the plugin folder, without a library. It defines AC_PLUGIN_STATIC and AC_PLUGIN_ID (the manifest's id), and the entry macro then registers the entry points under that id before main runs, instead of exporting them:

void RegisterStaticPlugin(char const* id, PluginFunction onLoad, PluginFunction addScripts);

(through a StaticPluginRegistrar object). The loader uses these entry points for the plugin folder of the same id, so configs, SQL, dependencies and load order work as for a library; a built-in plugin whose folder is missing is loaded anyway, without its configs and SQL.