API reference

The API is one C header, core/include/readyup/plugin_api.h. This page describes version 1.6. The header has the exact signatures and a comment on every member. When this page and the header differ, the header is right.

Versions

#define READYUP_PLUGIN_API_VERSION_MAJOR 1
#define READYUP_PLUGIN_API_VERSION_MINOR 2
#define READYUP_PLUGIN_API_VERSION ((MAJOR << 16) | MINOR)

#define RU_API_VERSION_MAJOR(v)  /* v >> 16 */
#define RU_API_VERSION_MINOR(v)  /* v & 0xFFFF */
#define RU_API_HAS(ptr, member)  /* is member inside ptr->struct_size? */

A plugin that requires 1.6 in ru_plugin_info.api_version can call everything. A plugin that requires an older minor must check RU_API_HAS(api, member) before it calls a newer member. The rules are on Threading and ABI.

Exports

A plugin exports exactly these three functions, with READYUP_PLUGIN_EXPORT.

readyup_plugin_info

const ru_plugin_info* readyup_plugin_info(void);

Called right after the library is opened, before anything else. It must not call into the core. Return a pointer to a static struct:

typedef struct ru_plugin_info {
  uint32_t struct_size;  /* sizeof(ru_plugin_info) */
  uint32_t api_version;  /* READYUP_PLUGIN_API_VERSION you need */
  const char* name;      /* file name without ".so", [a-z0-9_-] */
  const char* version;
  const char* author;
  const char* description;
} ru_plugin_info;

The core refuses the plugin if name does not match the file name, if the API major differs, or if the plugin needs a newer minor than the core has.

readyup_plugin_load

int readyup_plugin_load(const ru_api* api, uint32_t core_api_version);

Runs on the game thread. Register your commands, ticks and subscriptions here. Keep the api pointer: it stays valid until unload returns.

Return 0 on success. Any other value aborts the load. The core then removes what you already registered and closes the library.

readyup_plugin_unload

void readyup_plugin_unload(void);

Runs on the game thread, when none of your code is running. Stop and join your threads, and free your memory. The core removes all your registrations afterwards, whether or not you removed them yourself.

ru_api

The core passes this table to readyup_plugin_load. Every function takes api->self as the first argument. The core uses it to know which plugin owns a registration.

Call these functions only from the game thread, unless the table says "any thread". From a callback you always are on the game thread.

1.0: basics

Both command callbacks get an ru_command_ctx:

typedef struct ru_command_ctx {
  uint32_t struct_size;
  uint64_t steamid64;       /* 0 for the console */
  int slot;                 /* player slot, or -1 if unknown */
  int is_console;           /* 1 for the server console / RCON */
  const char* name;         /* sender name, "Console" for the console */
  const char* text;         /* the full trimmed line, e.g. ".hello world" */
  int argc;                 /* argv[0] is the command itself */
  const char* const* argv;
} ru_command_ctx;

Tick callbacks get an ru_tick_info: frame (simulating frames since start), now (monotonic seconds) and, since 1.2, simulating.

1.1: output and players

You own the ru_player struct. Set struct_size before you pass it in. It has slot, steamid64 (0 for bots), team, is_bot, connected, name[128], and since 1.2 userid (the <N> in log lines, which kickid takes).

1.1: engine events and log lines

1.1: schema and entities

1.1: round control, admins, config

1.1: between plugins, and across reloads

1.2

1.3 to 1.6

Each player has one center panel. The core keeps who owns it until that panel's seconds run out. The priorities are RU_HTML_PRIO_INFO (10), RU_HTML_PRIO_HUD (50, what center_html_to_slot and center_html_all use), RU_HTML_PRIO_NOTICE (70, one-off cards), RU_HTML_PRIO_MENU (80, a menu the player opened) and RU_HTML_PRIO_ALERT (90, must be seen now).

Handles

typedef uint64_t ru_handle;  /* 0 = failure */

Each registration returns a handle. It is unique for the life of the server process.

Events

The core turns engine game events and server log lines into one set of lifecycle events. Once its engine event listener is up, events come from the engine. Before that, they come from log lines. source says which. The core picks one source for each fact, so you do not get the same round or player change twice.

Every event also has map, the current map. Unknown numbers are -1 (slot, scores) or 0 (winner).

Enums

typedef enum ru_log_level {
  RU_LOG_INFO = 0, RU_LOG_WARN = 1, RU_LOG_ERROR = 2,
  RU_LOG_DEBUG = 3   /* only with debug=1 */
} ru_log_level;

typedef enum ru_team {
  RU_TEAM_UNASSIGNED = 0, RU_TEAM_SPECTATOR = 1, RU_TEAM_T = 2, RU_TEAM_CT = 3
} ru_team;

enum { RU_CHAT_RAW = 1u << 0 };                         /* chat_all: no prefix */
enum { RU_CMD_HIDE = 1u << 0, RU_CMD_OBSERVE = 1u << 1 }; /* *_command_ex flags */

Interfaces

Plugins publish interfaces with provide_interface, and others find them with get_interface. Each interface is a C struct of function pointers that starts with struct_size. Members are only ever added at the end. Check struct_size before you use a member, and look the interface up again in every callback.

readyup.match.v1

core/include/readyup/match_iface.h. Published by match.so. The core reads it to fill the match part of /status.

Without match.so, /status shows "match_plugin": "none" and update_safe: true.

readyup.fleet.v1

core/include/readyup/fleet_iface.h. Published by fleet.so. The core reads get_status for /status. The match and skins plugins use the rest.

Handlers also get two local messages that never go over the wire: local.connection (the link went up or down) and local.offline_timeout (the offline auto-pause time was reached).

Selftest lines

core/include/readyup/selftest_iface.h. A plugin adds its own lines to ru selftest by publishing readyup.selftest.<its name>:

typedef struct ru_selftest_iface_v1 {
  uint32_t struct_size;
  void (*run)(ru_selftest_add_fn add, void* ctx);
} ru_selftest_iface_v1;

run calls add(ctx, status, name, detail) once per check. status is OK, FAIL, PEND, SKIP, INFO or WARN. run can be called from any thread, even while the plugin unloads. It must be fast, must not block, and must not call any API member except log.