V1 API-Schnittstelle#

Auf dieser Seite werden alle SDK-Anforderungen und -Funktionen ausführlich beschrieben. Ein vollständiges Beispiel-Plugin finden Sie hier.

Funktionen#

Logging-Schnittstelle
GSC-Funktions- und Methodenregistrierung
Registrierung von Clientbefehlen
Ereignis-Rückrufe
Thread-Planer

Eingangsstelle#

Der wichtigste Teil Ihres Plugins ist die Einrichtung des Einstiegspunkts. Ohne eine korrekte Implementierung kann Ihr Plugin nicht geladen werden. Der folgende Codeausschnitt kann als Mindestbeispiel für die Einrichtung des Einstiegspunkts verwendet werden.

#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;
}

Das plugin_name(), on_startup() und on_shutdown() -Methoden müssen implementiert werden, damit Ihr Plugin von Plutonium als gültig angesehen wird.

on_startup: Wird ausgeführt, nachdem alle Plutonium-Patches angewendet wurden, bevor WinMain des Spiels aufgerufen wird
on_shutdown: Wird ausgeführt, wenn das Plugin entladen wird

Das on_initialize -Funktion wird als Einstiegspunkt zu Ihrem Plugin verwendet. Mit dieser Funktion erkennt Plutonium die Implementierung des Plugin-SDK. Ihre Implementierung muss genau dieser Signatur folgen.

Die Plugin-Schnittstelle verfügt auch über eine optionale is_game_supported() Methode. Standardmäßig versuchen alle von Plutonium unterstützten Spiele, das Plugin zu laden. Sie können diese Methode verwenden, um zu entscheiden, ob Ihr Plugin geladen werden soll oder nicht, wenn es nur einen Titel unterstützt.

Protokollierung#

Die Protokollierungsschnittstelle wird verwendet, um Nachrichten zurück in das Plutonium-Konsolenfenster zu drucken.

void on_startup(plutonium::sdk::iinterface* interface_ptr, plutonium::sdk::game game) override
{
    interface_ptr->logging()->info("Plugin Starting Up!");
}

Info: Druckt die Informationsnachricht ohne Farbgebung
Warnen: Gibt Warnmeldungen mit gelbem Text aus
Fehler: Gibt eine Fehlermeldung mit rotem Text aus

GSC#

Die GSC-Schnittstelle wird verwendet, um benutzerdefinierte Methoden und Funktionen auf der GSC-VM zu registrieren. Diese Methoden können dann einfach von einem GSC-Skript aufgerufen werden, das auf dem Server geladen ist.

VERZICHTSERKLÄRUNG: Wenn es auf IW5 verwendet wird, führt das Entladen des Plugins wahrscheinlich zum Absturz des Spiels. Das Entladen wird auf T4, T5 und T6 mit benutzerdefinierten GSC-Funktionen unterstützt.

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-Verwendung:

init()
{
    testFunction();

    level thread onPlayerConnect();
}

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

        player testMethod();
    }
}

Befehle#

Die Client-Befehlsschnittstelle wird verwendet, um einen benutzerdefinierten Handler für einen bestimmten Befehl zu registrieren, der von einem Client an den Server gesendet wird.

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);
}

Rückrufe#

Die Callbacks-Schnittstelle ermöglicht es Ihrem Plugin, benachrichtigt zu werden, wenn generische Spielereignisse auftreten. Diese Ereignisse können dann verwendet werden, um benutzerdefinierte Logik hinzuzufügen, die zu einem bestimmten Zeitpunkt ausgeführt werden muss.

on_dvar_init() - Das dvar-System des Spiels ist initialisiert und bereit, dvars zu registrieren.
on_after_dvar_init() - Die meisten Spiel-dvars wurden registriert und die Haupt-Thread-Schleife beginnt gleich
on_game_init(int levelTime, int restart) - Der Spielserver wird initialisiert
- levelTime - Zeitspanne, die der Server bereits ausgeführt wurde
- restart - Gibt an, ob diese Initialisierung das Ergebnis eines Neustarts des Servers ist (d. h. map_restart)
on_game_shutdown(int freeScripts) - Der Spielserver wird heruntergefahren
- freeScripts - Gibt an, ob die Spielskripte freigegeben werden (d.h. keine map_restart)
on_player_pre_connect(int clientNum) - Ein Client verbindet sich zum ersten Mal mit dem Server
on_player_connect(int clientNum) - Ein Client stellt eine Verbindung zum Server her
- Dieses Ereignis wird ausgelöst, wenn ein Client nach einer map_restart die Verbindung wiederherstellt!
on_player_disconnect(int clientNum) - Ein Client trennt die Verbindung zum Server.
on_scripts_load() - Der Server beginnt mit dem Laden von GSC-Skripten
on_scripts_execute() - Der Server beginnt mit der Ausführung von GSC-Skripten

Scheduler#

Die Scheduler-Schnittstelle ermöglicht es Ihrem Plugin, Code zu planen, der zu einem bestimmten Zeitpunkt in einem bestimmten Spielthread ausgeführt werden soll.

Fäden:

main - Der Hauptthread der ausführbaren Datei des Spiels. Dieser Thread ist immer aktiv
game - Der Spiel-/Server-Thread. Dieser Thread wird nur ausgeführt, wenn gerade eine Karte geladen ist und abgespielt wird

Sendepläne:

on_frame - Dieser Callback wird für jeden Frame des ausgewählten Threads ausgeführt.
once - Dieser Callback wird einmal im nächsten Frame des ausgewählten Threads ausgeführt.
delay - Dieser Callback wird nach einer bestimmten Anzahl von Millisekunden auf dem ausgewählten Thread ausgeführt
every - Dieser Callback wird nach einer bestimmten Anzahl von Millisekunden auf dem ausgewählten Thread ausgeführt und neu geplant, um basierend auf der Auswertung des Callbacks erneut ausgeführt zu werden.

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);
}