Getting Started with Nexus Addon Development

Updated 21 October, 2026

Getting Started with Nexus Addon Development

This guide takes you from an empty folder to a Nexus addon that loads in the game, draws a window and reloads in seconds while you work on it. It uses C++ and Visual Studio, because Nexus and Dear ImGui are written in C++, but nothing here depends on a specific IDE or build system. If you prefer another language, see Developing Nexus Addons in Other Languages.

What a Nexus addon is

A Nexus addon is a 64-bit Windows DLL that exports a single function, GetAddonDef. Nexus calls it to read the addon's name, version and entry points, then calls the addon's Load function with a table of API functions. Everything else, from drawing windows to registering keybinds, goes through that table.

Because Nexus owns the loading process, it can unload and reload your addon while the game is running. That makes for a fast development loop, and it is why cleaning up after yourself matters, see Understanding the Nexus Addon Lifecycle.

What you need

  • A C++ compiler that can build 64-bit Windows DLLs. Visual Studio 2022 with the Desktop development with C++ workload is the most common choice. Clang and MinGW also work.
  • The Nexus API header, Nexus.h, from the RCGG-lib-nexus-api repository. Many projects add it as a Git submodule.
  • Dear ImGui 1.80, if your addon draws an interface. It has to be exactly this version, see Rendering and Dear ImGui Integration.
  • Guild Wars 2 with Nexus installed.

If you learn best from complete projects, several open source addons are good references, for example Commander's Toolkit by Raidcore.

Setting up the project

  1. Create a new, empty C++ project and set its configuration type to Dynamic Library (.dll). Build for the x64 platform only. Guild Wars 2 is a 64-bit game and cannot load 32-bit DLLs.
  2. Use C++17 or newer.
  3. Add Nexus.h and the ImGui 1.80 sources (imgui.cpp, imgui_draw.cpp, imgui_tables.cpp, imgui_widgets.cpp and their headers) to the project. You do not need ImGui's platform or renderer backends, Nexus takes care of those.
  4. Consider linking the C++ runtime statically (/MT for release builds). Your users then do not need a matching Visual C++ Redistributable installed.
  5. Name the output after your addon, for example MyAddon.dll.

Your first addon

The following file is a complete addon. It writes to the Nexus log when it loads and draws a small window.

#include 

#include "Nexus.h"
#include "imgui.h"

static AddonAPI_t* s_API = nullptr;

void AddonLoad(AddonAPI_t* aApi);
void AddonUnload();
void AddonRender();

extern "C" __declspec(dllexport) AddonDefinition_t* GetAddonDef()
{
	static AddonDefinition_t s_AddonDef{};
	s_AddonDef.Signature        = 0x1A2B3C4D; /* Pick your own, see below. */
	s_AddonDef.APIVersion       = NEXUS_API_VERSION;
	s_AddonDef.Name             = "My Addon";
	s_AddonDef.Version.Major    = 1;
	s_AddonDef.Version.Minor    = 0;
	s_AddonDef.Version.Build    = 0;
	s_AddonDef.Version.Revision = 0;
	s_AddonDef.Author           = "Your Name";
	s_AddonDef.Description      = "My first Nexus addon.";
	s_AddonDef.Load             = AddonLoad;
	s_AddonDef.Unload           = AddonUnload;
	s_AddonDef.Flags            = AF_None;
	return &s_AddonDef;
}

void AddonLoad(AddonAPI_t* aApi)
{
	s_API = aApi;

	/* Use the ImGui context and allocator of Nexus. */
	ImGui::SetCurrentContext((ImGuiContext*)s_API->ImguiContext);
	ImGui::SetAllocatorFunctions(
		(void* (*)(size_t, void*))s_API->ImguiMalloc,
		(void (*)(void*, void*))s_API->ImguiFree
	);

	s_API->GUI_Register(RT_Render, AddonRender);
	s_API->Log(LOGL_INFO, "MyAddon", "Hello from My Addon!");
}

void AddonUnload()
{
	s_API->GUI_Deregister(AddonRender);
	s_API = nullptr;
}

void AddonRender()
{
	if (ImGui::Begin("My Addon"))
	{
		ImGui::Text("Hello, Tyria!");
	}
	ImGui::End();
}

A few things to note:

  • GetAddonDef must be exported with C linkage under exactly that name, which is what extern "C" __declspec(dllexport) does. The definition it returns has to stay valid while the addon is loaded, so it is static. All of its fields are explained in The Addon Definition and API Versioning.
  • AddonLoad receives the API table. Keep the pointer, you need it everywhere.
  • Everything registered in AddonLoad is deregistered in AddonUnload.

Choosing a signature

The Signature is your addon's permanent, unique ID. Nexus uses it to recognise your addon across updates, to store its settings and to tell addons apart. Choose a random 32-bit value, written as eight hexadecimal digits, for example 0x1A2B3C4D. Do not use 0, and never copy another addon's signature, since Nexus refuses to load two addons with the same signature.

If you plan to publish your addon in the Nexus library, start its project on raidcore.gg early with the same signature. That reserves it, and the site will tell you if someone else already uses it.

Running your addon

  1. Build the project.
  2. Copy MyAddon.dll into the addons folder in your game folder.
  3. In the game, open the Nexus menu with Ctrl+O and go to Addons. Your addon is listed, but new addons start disabled. Click Load.
  4. The window appears, and the Log page shows your message.

From now on, Nexus remembers that your addon is enabled and loads it on every start.

Reloading without restarting the game

While your addon is loaded, Windows locks MyAddon.dll, so you cannot overwrite it. Instead, copy the new build next to it as MyAddon.dll.update. Nexus watches the addons folder, notices the file, unloads your addon, swaps the files and loads the new version, usually within a second.

In Visual Studio, you can automate this with a post-build event under Project Properties, Build Events, Post-Build Event:

copy /Y "$(TargetPath)" "C:\Program Files\Guild Wars 2\addons\$(TargetFileName).update"

Adjust the path to your game folder. Now every build appears in the game a moment later. See Testing and Debugging Nexus Addons for attaching a debugger and other tips.

Using the API across files

Once your addon grows beyond one file, store the API pointer in a shared place:

/* Shared.h */
#pragma once
#include "Nexus.h"

extern AddonAPI_t* APIDefs;
/* Shared.cpp */
#include "Shared.h"

AddonAPI_t* APIDefs = nullptr;

Then assign APIDefs = aApi; in your load function and include Shared.h wherever you need it.

Next steps