Skip to content

Commit 8f05a24

Browse files
ChristopherJTrentChristopherJTrent
authored
Merge pull request #6 from jsantorek/main
quickstart snippet fixes and style improvements
2 parents 2b1aab5 + f460949 commit 8f05a24

1 file changed

Lines changed: 54 additions & 44 deletions

File tree

‎pages/guides/Addon Quickstart.md‎

Lines changed: 54 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,74 @@
11
\page addon-quickstart Addon Quickstart
2-
This is a full guide on how to get started with the AddonHost and implement your own addon. This guide will remain build-system agnostic and avoid compiler extensions where possible.
2+
This is a complete guide on how to get started with the AddonHost and implement your own addon. It is build-system agnostic and avoids compiler-specific extensions where possible.
33

44
\note
5-
This guide will be using the C++ programming language. Creation of addons in languages other than C++ are outside the scope of this guide.
6-
If you want to program in another language, check out the [community bindings](@ref bindings)
5+
This guide uses the C++ programming language. Creating addons in languages other than C++ is outside the scope of this guide.
6+
If you want to program in another language, check out the [community bindings](@ref bindings).
77

8-
If all you need is an example, see [The Compass Addon](https://github.com/RaidcoreGG/GW2-Compass) (Built with Visual Studio)
9-
Alternately, see [NexPad](https://github.com/ChristopherJTrent/NexPad) for a GNU make + GCC example using Msys2
8+
If all you need is an example, numerous Nexus addons are open source, notably:
9+
1. [The Compass Addon](https://github.com/RaidcoreGG/GW2-Compass), which includes Visual Studio project files
10+
2. [NexPad](https://github.com/ChristopherJTrent/NexPad), a GNU Make + GCC example using MSYS2
11+
3. [TrueWorldCompletion](https://github.com/jsantorek/GW2-TrueWorldCompletion), which uses CMake and Clang (with Docker and Conan as options)
1012

11-
Each addon loaded by nexus is required to export a function matching the signature `AddonDefinition_t* GetAddonDef()`. See [AddonDefinition_t](@ref AddonDefinition_t) for the full struct definition
13+
Each addon loaded by Nexus is required to export a function matching the signature `AddonDefinition_t* GetAddonDef()`. See [AddonDefinition_t](@ref AddonDefinition_t) for the full struct definition.
1214

13-
Example implementation of GetAddonDef
15+
### Example implementation of `GetAddonDef`
1416
```cpp
17+
#include <Nexus.h>
18+
1519
AddonDefinition_t AddonDef{};
1620

17-
void AddonLoad(AddonAPI_t*) {} //add a body as needed.
18-
void AddonUnload() {} //add a body as needed.
21+
void AddonLoad(AddonAPI_t*) {} // Add a body as needed.
22+
void AddonUnload() {} // Add a body as needed.
1923

20-
extern "C" __declspec(dllexport) AddonDefinition_t GetAddonDef()
24+
extern "C" __declspec(dllexport) AddonDefinition_t* GetAddonDef()
2125
{
22-
AddonDef.Signature = -1; //This must be positive and unused if your addon is available on nexus and negative otherwise.
23-
AddonDef.APIVersion = NEXUS_API_VERSION; //this is defined in nexus.h, and contains the current latest version of nexus.
24-
AddonDef.Name = "Example Addon";
25-
AddonDef.Version.Major = 1; //Treat AddonDef.Version as a SemVer compatible version number.
26-
AddonDef.Version.Minor = 0;
27-
AddonDef.Version.Build = 0;
28-
AddonDef.Version.Revision = 1;
29-
AddonDef.Author = "Raidcore";
30-
AddonDef.Description = "Example Addon for Documentation";
31-
AddonDef.Load = *AddonLoad;
32-
AddonDef.Unload = *AddonUnload;
33-
34-
//Optional:
35-
AddonDef.Provider = EUpdateProvider::UP_None; //See EUpdateProvider in nexus.h
36-
AddonDef.UpdateLink = "https://github.com/RaidcoreGG/GW2-Example-Addon" // this link doesn't actually exist.
26+
AddonDef.Signature = -1; // Must be positive and unused if hosted on Nexus; negative otherwise.
27+
AddonDef.APIVersion = NEXUS_API_VERSION; // Defined in Nexus.h; the latest supported API version.
28+
AddonDef.Name = "Example Addon";
29+
AddonDef.Version.Major = 1; // Treat AddonDef.Version as a SemVer-compatible version.
30+
AddonDef.Version.Minor = 0;
31+
AddonDef.Version.Build = 0;
32+
AddonDef.Version.Revision = 1;
33+
AddonDef.Author = "Raidcore";
34+
AddonDef.Description = "Example Addon for Documentation";
35+
AddonDef.Load = &AddonLoad;
36+
AddonDef.Unload = &AddonUnload;
37+
38+
// Optional:
39+
AddonDef.Provider = EUpdateProvider::EUpdateProvider_None; // See EUpdateProvider in Nexus.h
40+
AddonDef.UpdateLink = "https://github.com/RaidcoreGG/GW2-Example-Addon"; // This link doesn't actually exist.
41+
42+
return &AddonDef;
3743
}
3844
```
39-
Fields not explicitly marked as optional are required.
40-
`Load()` will be called when your addon is loaded, and should initialize anything your addon needs. The `AddonAPI_t*` it receives will contain a version of the nexus API matching the one specified in `AddonDef.APIVersion`. See [AddonAPI_t](@ref AddonAPI_t) for the current version of that API.
41-
`Unload()` will be called when the game shuts down, when your addon is updated, and when it is unloaded. If your addon should not be able to be unloaded at runtime, set `AddonDef.Flags` to `EAddonFlags::DisableHotloading`.
45+
Fields not explicitly marked as optional are required.
46+
47+
`Load()` will be called when your addon is loaded and should initialize anything the addon needs. The `AddonAPI*` parameter will contain a version of the Nexus API matching the one specified in `AddonDef.APIVersion`. See [AddonAPI_t](@ref AddonAPI_t) for the current API definition.
4248
43-
### Addon Signatures
44-
If your addon is hosted on Raidcore, this should be the unique ID of your addon.
45-
If your addon is *not* hosted on Raidcore, it should be any negative integer.
49+
`Unload()` will be called when the game shuts down, when your addon is updated, or when it is manually unloaded. If your addon must not be unloaded at runtime, set `AddonDef.Flags` to `EAddonFlags::DisableHotloading`.
50+
51+
### Addon Signatures
52+
If your addon is hosted on Raidcore, this should be the unique ID of your addon.
53+
If your addon is *not* hosted on Raidcore, it should be any negative integer.
4654
4755
\note
48-
Do not set it to 0, and do not use the signature of another addon.
56+
Do not set the signature to 0, and do not use the signature of another addon.
4957
5058
### API Versions
51-
If you don't use any of Nexus's functions, set APIVersion to 0.
52-
If APIVersion is a non-zero value, it must be a current or previous `NEXUS_API_VERSION`.
59+
If you do not use any Nexus API functions, set APIVersion to 0.
60+
If APIVersion is non-zero, it must be a current or previous `NEXUS_API_VERSION`.
5361
5462
\warning
55-
Your addon will not load if you set APIVersion to an invalid value.
63+
Your addon will not load if APIVersion is set to an invalid value.
5664
5765
## The Addon API reference
58-
It is recommended to store the reference to the addon API in a shared place, so you can include it in any files that need it. An example of how to do this is shown below.
66+
It is recommended to store the addon API reference in a shared location so it can be accessed from any file that needs it. An example is shown below.
5967
6068
### `Shared.h`
6169
```cpp
6270
#pragma once
63-
#include "nexus.h"
71+
#include "Nexus.h"
6472
//#include "imgui.h"
6573
6674
extern AddonAPI_t* Addon_API;
@@ -78,18 +86,20 @@ AddonAPI_t Addon_API;
7886
void AddonLoad(AddonAPI_t* API) {
7987
Addon_API = API;
8088

81-
//Uncomment the next two lines if you are using imgui, and have included it in shared.h
89+
// Uncomment the next two lines if you are using ImGui and have included it in Shared.h
8290
//ImGui::SetCurrentContext((ImGuiContext*)Addon_API->ImguiContext);
8391
//ImGui::SetAllocatorFunctions((void* (*)(size_t, void*))Addon_API->ImguiMalloc, (void(*)(void*, void*))Addon_API->ImguiFree);
8492
}
93+
8594
void AddonUnload() {}
8695

87-
extern "C" __declspec(dllexport) AddonDefinition_t GetAddonDef() {
88-
//... Omitted for brevity, see above for full contents.
96+
extern "C" __declspec(dllexport) AddonDefinition_t* GetAddonDef() {
97+
// ... Omitted for brevity, see above for full example.
8998
}
9099
```
91-
92100
## About unloading
93-
When `AddonDefinition_t::Unload()` is called, you should free any resources you have allocated. E.G. Keybinds.
94-
Nexus will do its best to clean up after you should you forget, but no guarantee is made that it will do so perfectly.
95-
To prevent memory leaks, clean up after yourself.
101+
When `AddonDefinition_t::Unload()` is called, you should free any resources you have allocated (e.g. keybinds).
102+
103+
Nexus will attempt to clean up resources if you forget, but no guarantee is made that cleanup will be complete or correct.
104+
105+
To prevent memory leaks and other issues, always clean up after yourself.

0 commit comments

Comments
 (0)