lexzor/amxmodx-discord-api
An AMX Mod X module which expose some of D++ functionalities in Pawn to interact with Discord API for bots
Discord API into Pawn
A library for AMX Mod X that provides some of the Discord API functionality to AMXX plugins.
It uses D++ (DPP) as the underlying C++ library to interface with Discord API, exposing convenient natives that plugin developers can call directly from their AMX Mod X scripts.
Important
This module is still in BETA, so crashes may occur due to the module itself or AMX Mod X plugins you create.
If you find any error please open an issue or a PR.
Usage
Before installing the module, you have to know it may not work on outdated operating system because the project uses C++20. If you use Pterodactyl Panel to run your server in a Docker container, you may want to update the docker image to ghcr.io/parkervcp/steamcmd:debian.
Discord Bot Configuration
First you have to create a bot in Discord Developer portal and copy it's token.
Discord bots use intents to specify which events they receive. This module uses the Message Content Intent by default for message events. You must enable this intent in the Discord Developer Portal.
It is also recommended to enable all other intents from the portal to ensure the bot works correctly.
Installation
- Download last stable release.
- Copy
discordapi_amxx_i386.soto/cstrike/addons/amxmodx/modules. - Enable module in
/cstrike/addons/amxmodx/configs/modules.iniby typing a new linediscordapi. - Restart server and type in server console
amxx modulesto check if it was loaded properly.
AMX Mod X Scripting
All natives and forwards can be found in include folder.
Plugin examples can be found in scripting folder.
1. General Informations
Almost all natives and forwards include a parameter called identifier, which must be unique. This is necessary because the module needs to know which bot the changes should apply to or which bot is emitting an event. It can also be used to split bot functionality across multiple plugins.The identifier is not validated by the module, so using duplicate identifiers can result in changes being applied to the wrong bot or events being captured incorrectly.
2. Discord API Requests
Some natives send requests over HTTPS or WebSocket protocols to the Discord API, and the response cannot be returned in the same server frame. All asynchronous logic is mostly handled by the DPP library and the module itself, but if an error occurs, it will be printed in the console. For example, the native StartBot will return an error if the bot does not exist. However, if the bot fails to connect to the Discord API, an error will be printed later in the console when a response is received.3. Interactions
A topic that should be mentioned is interactions. Some forwards may be marked with Interaction. In these cases, you can use the SendReply native. For example, if you use it in the OnChannelMessageCreated forward, the bot will reply directly to the user’s message with the message you send.4. Discord API Events
Events are sent through forwards, and their data is provided in JSON format. To avoid runtime stack error in plugins due to AMX Mod X limitation, some event data may be minimized. You can find the JSON data format in the include files, inside each native or forward’s body details.5. Debugging
You can set the log level to VERBOSE in the bot options (which can be changed at any time during the bot’s lifecycle). Note that the VERBOSE log level can be overwhelming, as it displays almost all HTTPS or WebSocket data received from the Discord API, but it may be useful when manipulating bot options (for example, global or guild slash commands) to catch errors. To debug events without VERBOSE log level, you can use the PRINTS_EVENT_DATA option in the Options array with SetBotOptions (see discordapi.inc) to output the full JSON data received from the Discord API. Note that the printed values do not exactly represent the data passed to AMX Mod X forwards due to plugin limitations. If you consider there is not enough data to develop your plugin, you can anytime open an issue or a PR.Contribution
Before diving into the build steps, it’s important to understand that the project is compiled inside a Docker container running a specific Unix-like distribution. This approach was adopted because Half-Life 1 game servers are hosted on a wide variety of operating systems. Currently, testing has only been performed on Hostsrc.io Counter-Strike 1.6 game servers running in a Debian 12 Docker container.
The project uses D++ (DPP) as the underlying C++ library, which requires at least C++17. This project itself is compiled with C++20. D++ relies on additional libraries such as ZLib, OpenSSL, and cURL, which are compiled and statically linked into the project to avoid issues with missing APIs on different operating systems.
Important
All build steps are intended for Windows users, as they use PowerShell scripts; however, they can be easily converted to Bash scripts.
Build steps
1. Docker Setup
First, you need to build the Docker container that will be used to compile both project and libraries. Currently only Debian12 is supported.1. Open Windows Powershell Terminal.
2. Navigate to amxmodx-discord-api\docker-images\debian12.
3. Run build_container.ps1.
After this step, the Docker container should be installed on your computer.
2. Build Libraries
As mentioned earlier, the project statically links libraries so that the AMXX module does not depend on OS-installed libraries at runtime. This step only needs to be done once per Docker container.1. Open Windows Powershell Terminal.
2. Navigate to amxmodx-discord-api\docker-images\debian12.
3. Run build_libs.ps1.
After completion, all required libraries will be copied to the amxmodx-discord-api\vendor\bin directory.
3. Build Project
Finally, build the project itself:1. Open Windows Powershell Terminal.
2. Navigate to amxmodx-discord-api\docker-images\debian12.
3. Run build_project.ps1.