The Addon Definition and API Versioning

Updated 21 October, 2026

The Addon Definition and API Versioning

Every Nexus addon describes itself with an AddonDefinition_t, returned from its exported GetAddonDef function. The definition tells Nexus who you are, which version of the API you were built against, how to load and unload you and where to look for updates. This guide explains every field, the rules Nexus enforces, and how API versioning keeps old addons working.

The GetAddonDef export

extern "C" __declspec(dllexport) AddonDefinition_t* GetAddonDef();

Nexus calls this function right after loading your DLL, before anything else. It also calls it for addons that end up disabled, to show them in the addon list, so keep it free of side effects: fill in the struct and return it. Do not call any API functions here, you do not have the API yet.

Nexus copies the definition when it loads your addon, but the function pointers must of course stay valid. Returning a pointer to a static or global struct is the usual approach.

Fields

Field Required Description
Signature Yes Unique 32-bit ID of your addon. Must not be 0. See Signature.
APIVersion Yes The API revision Nexus passes to your load function. Use NEXUS_API_VERSION, or 0 if you do not use the API at all. See API versions.
Name Yes Display name in the addon list.
Version Yes Your addon's version as Major.Minor.Build.Revision. Used to compare against updates, see Versions.
Author Yes Your name or your team's name.
Description Yes A short, one-line description.
Load Yes Called with the API table when the addon is loaded.
Unload Yes, unless hot-loading is disabled Called before the addon is unloaded, also when the game closes.
Flags No Combination of EAddonFlags, see Flags. Use AF_None if none apply.
Provider No Where updates come from, see Update provider.
UpdateLink No Location of updates for the selected provider.

If a required field is missing, Nexus refuses to load the addon and lists the missing fields in its log.

Signature

The signature identifies your addon permanently. Nexus uses it to remember whether your addon is enabled, to match it against the addon library, to route targeted events to it and to detect duplicates: if two loaded files declare the same signature, only the first one is loaded.

  • Pick a random value once, for example 0x1A2B3C4D, and never change it. Changing it makes Nexus treat your addon as a different addon, so users lose its enabled state.
  • Never use 0, and never reuse another addon's signature.
  • If you publish in the Nexus library, register the same signature there. The site rejects signatures that are already taken, so registering early reserves yours. See Packaging and Distributing Nexus Addons.

Older documentation suggested negative numbers for addons that are not hosted on Raidcore. Such signatures still work, but a random value registered in the library is the better choice today, since it is guaranteed to be unique.

Versions

AddonVersion_t holds four 16-bit numbers: Major, Minor, Build and Revision. Nexus compares them in that order. When you publish updates through GitHub releases, the release tag is converted into the same format, so the two have to match:

  • A tag like 1.4.2 or v1.4.2 becomes 1.4.2.0.
  • A tag like 1.4.2.7 or v1.4.2.7 becomes 1.4.2.7.
  • Tags with any other format, for example 1.4.2-beta, are ignored.

Bump the version in GetAddonDef for every release. If the DLL inside a release reports a lower version than the release tag, Nexus keeps downloading the same update.

Flags

Flag Effect
AF_None No special behavior.
AF_IsVolatile Your addon depends on game internals that may break with a game update, such as memory layouts or function signatures. When Nexus detects a new game build, it disables the addon until an update is released for it, and re-enables it automatically afterwards. Users can still enable it manually.
AF_DisableHotloading Your addon cannot be unloaded while the game is running. Disabling, uninstalling and updating take effect on the next start. Unload is still called when the game closes, if you provide it.
AF_LaunchOnly Your addon can only be loaded while the game is starting. Enabling it later takes effect on the next start. Use this if your addon needs to hook something that happens early during startup.

In C++, combine flags with a cast, since the result of | on an enum is an int:

s_AddonDef.Flags = (EAddonFlags)(AF_IsVolatile | AF_DisableHotloading);

Only use these flags when you need them. Hot-loading is one of the main reasons users and developers choose Nexus, and every flag above takes something away from it.

Update provider

Nexus checks for an update each time it loads your addon, including on every game start, using the provider you declare. If it finds a newer version, it downloads it, swaps the files and reloads your addon.

Provider UpdateLink How updates are detected
UP_GitHub The repository URL, for example https://github.com/you/MyAddon Nexus reads the repository's releases, picks the highest version whose tag matches the format above, and downloads the first .dll asset of that release. Pre-releases are only used if the user allows them for your addon. This is the recommended provider.
UP_Direct A direct download URL of the DLL Nexus requests the same URL with .md5 appended, or .md5sum as a fallback, and downloads the DLL if the hash differs from the installed file. Without a hash file, no update is detected.
UP_Self Your own update endpoint Nexus does not check for updates. Your addon checks on its own and calls RequestUpdate with the download URL when it finds one.
UP_Raidcore Not used Reserved for hosting on Raidcore. It does not provide updates at the moment, so use GitHub releases instead.
UP_None Optional No updates. If you set an UpdateLink anyway, Nexus derives the provider from it: links to github.com are treated as GitHub, others as direct downloads.

Releasing through GitHub is covered in detail in Packaging and Distributing Nexus Addons.

API versions

The API table your addon receives is versioned. Every time new functions are added, Nexus introduces a new revision instead of changing an existing one, and it keeps every older revision working. An addon built years ago against revision 1 still receives exactly the table it expects.

This has two consequences:

  • Set APIVersion to NEXUS_API_VERSION from the header you build against. The value and the struct layout in that header always belong together.
  • If you set a version that Nexus does not know, for example because your header is newer than the user's Nexus, the addon is not loaded and the log says so. In practice this only happens briefly after a new revision, since Nexus updates itself on startup.

Set APIVersion to 0 if your addon does not use the API at all. Load then receives a null pointer.

Revision history

Revision Added
1 Rendering, paths, MinHook, logging, events, WndProc, keybinds, DataLink, textures from file, resource and URL, Quick Access shortcuts.
2 Notification-only events, sending window messages to the game only, textures from memory and the GetOrCreate texture functions, Quick Access notifications, localization.
3 Alerts, targeted events and log channels.
4 Keybind handlers that also receive key releases, update requests for self-updating addons, and fonts.
5 Invoking keybinds programmatically, and setting translated strings at runtime.
6 Game keybinds, closing windows with Escape, font resizing and context menus attached to a specific Quick Access shortcut.

The current Nexus.h describes revision 6 only. If you maintain an old addon, upgrade to the current header rather than mixing revisions.