V1 API Interface#

This pages goes into detail on all the SDK requirements and features that are provided. A full example plugin can be found here.

Features#

Entry Point#

The most important part of your plugin is setting up the entry point. Without a correct implementation, your plugin will fail to load. The following snippet of code can be used as a minimum example for setting up the entry point.

#include "plutonium-sdk/plutonium_sdk.hpp"

std::unique_ptr<plutonium::sdk::plugin> plugin_;
class plugin_impl : public plutonium::sdk::plugin
{
public:
    const char* plugin_name() override
    {
        return "Plutonium SDK Example";
    }

    void on_startup(plutonium::sdk::iinterface* interface_ptr, plutonium::sdk::game game) override
    {
        // startup code
    }

    void on_shutdown() override
    {
        // shutdown code
    }
};

PLUTONIUM_API plutonium::sdk::plugin* on_initialize()
{
    return (plugin_ = std::make_unique<plugin_impl>()).get();
}

BOOL APIENTRY DllMain(HMODULE, DWORD, LPVOID)
{
    return TRUE;
}

The plugin_name(), on_startup() and on_shutdown() methods are required to be implemented for your plugin to be considered valid by Plutonium.

  • on_startup: Executed after all the Plutonium patches are applied, before the game's WinMain is called
  • on_shutdown: Executed when the plugin is unloaded

The on_initialize function is used as the entry point to your plugin. This function is how Plutonium discovers the plugin SDK implementation. Your implementation must follow this exact signature.

The plugin interface also has an optional is_game_supported() method. By default, all Plutonium supported games will try and load the plugin. You can use this method to choose whether or not to load your plugin if it only supports one title.

Logging#

The logging interface is used to print messages back to the Plutonium console window.

void on_startup(plutonium::sdk::iinterface* interface_ptr, plutonium::sdk::game game) override
{
    interface_ptr->logging()->info("Plugin Starting Up!");
}
  • info: prints information message with no coloring
  • warn: prints warning messages with yellow text
  • error: prints error message with red text

GSC#

The GSC interface is used to register custom method and function builtins to the GSC VM. These methods can then be easily called from a GSC script loaded on the server.

DISCLAIMER: If used on IW5, unloading your plugin will likely cause the game to crash. Unloading is supported on T4, T5 and T6 with custom GSC builtins.

void test_method_builtin(plutonium::sdk::types::entref entity)
{

}

void test_function_builtin()
{

}

void on_startup(plutonium::sdk::iinterface* interface_ptr, plutonium::sdk::game game) override
{
    interface_ptr->gsc()->register_function("testFunction", test_function_builtin);
    interface_ptr->gsc()->register_method("testMethod", test_method_builtin);
}

GSC Usage:

init()
{
    testFunction();

    level thread onPlayerConnect();
}

onPlayerConnect()
{
    for(;;)
    {
        level waittill( "connected", player );

        player testMethod();
    }
}

Commands#

The Client Command interface is used to register a custom handler for a specific command sent by a client to the server.

void client_command_function_test(int client_num)
{

}

void on_startup(plutonium::sdk::iinterface* interface_ptr, plutonium::sdk::game game) override
{
    interface_ptr->client_command()->register_client_command("testClientCommand", client_command_function_test);
}

Callbacks#

The callbacks interface allows your plugin to be notified when generic game events occur. These events can then be used to add custom logic that needs to be executed at a specific time.

  • on_dvar_init() - The game's dvar system is initialized and ready to register dvars
  • on_after_dvar_init() - Most game dvars have been registered and the main thread loop is about to begin
  • on_game_init(int levelTime, int restart) - The game server is being initialized
    • levelTime - Amount of time the server has been running
    • restart - Indicates if this initialization is a result of the server restarting (i.e. map_restart)
  • on_game_shutdown(int freeScripts) - The game server is shutting down
    • freeScripts - Indiciates if the game scripts will be free'd (i.e. not a map_restart)
  • on_player_pre_connect(int clientNum) - A client is connecting to the server for the first time
  • on_player_connect(int clientNum) - A client is connecting to the server
    • This event is raised when a client reconnects after a map_restart!
  • on_player_disconnect(int clientNum) - A client is disconnecting from the server
  • on_scripts_load() - The server is beginning to load GSC scripts
  • on_scripts_execute() - The server is beginning to execute GSC scripts

Scheduler#

The scheduler interface allows your plugin to schedule code to be executed on a specific game thread at a specific time.

Threads:

  • main - The main thread of the game's executable. This thread is always active
  • game - The game/server thread. This thread is only executing when a map is currently loaded and playing

Schedules:

  • on_frame - This callback will be executed on every frame of the chosen thread.
  • once - This callback will be executed once on the next frame of the chosen thread.
  • delay - This callback will be executed on the chosen thread after a specified number of milliseconds
  • every - This callback will be executed on the chosed thread after a specified number of milliseconds and rescheduled to be executed again based on the evaluation of the callback.
scheduler::evaluation callback()
{
    // code
    return scheduler::reschedule;
}

void on_startup(plutonium::sdk::iinterface* interface_ptr, plutonium::sdk::game game) override
{
    // execute a callback on the game thread every 1000ms
    interface_ptr->scheduler()->every(callback, 1000, scheduler::thread::game);
}
Edit this page