diff --git a/docs/source/index.rst b/docs/source/index.rst index b1f6b223..23934625 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -96,5 +96,6 @@ Cheatsheet :hidden: :caption: Plugins + /plugins/interfaces/index /plugins/interfacesapi - /plugins/resources \ No newline at end of file + /plugins/resources diff --git a/docs/source/plugins/index.rst b/docs/source/plugins/index.rst new file mode 100644 index 00000000..ba533310 --- /dev/null +++ b/docs/source/plugins/index.rst @@ -0,0 +1,6 @@ +Plugins +======= + +While regular mods are restricted to options provided by the game and Northstar, Plugins have no such limitations. + +Plugins are dynamically linked libraries that get loaded by the Northstar Launcher. As such plugins can do anything the launcher could, like adding new squirrel functions or hooking the game. diff --git a/docs/source/plugins/interfaces/index.rst b/docs/source/plugins/interfaces/index.rst new file mode 100644 index 00000000..feb7a2e3 --- /dev/null +++ b/docs/source/plugins/interfaces/index.rst @@ -0,0 +1,10 @@ +Interfaces +========== + +Interfaces do things + +.. toctree:: + :maxdepth: 2 + + /plugins/interfaces/required_interfaces + /plugins/interfaces/northstar diff --git a/docs/source/plugins/interfaces/northstar.rst b/docs/source/plugins/interfaces/northstar.rst new file mode 100644 index 00000000..a7013ba2 --- /dev/null +++ b/docs/source/plugins/interfaces/northstar.rst @@ -0,0 +1,29 @@ +Northstar Interfaces +==================== + +Interfaces exposed by ``northstar.dll`` + +.. cpp:struct:: NSSys + + Northstar system functionality + + .. cpp:function:: void Log(HMODULE pluginHandle, LogLevel level, const char* msg) + + Log a message into it's sink maintained by the launcher + + .. cpp:function:: void Unload(HMODULE handle) + + Unload a plugin by it's handle + + .. cpp:function:: void Reload(HMODULE handle) + + Reload a plugin by it's handle + +.. cpp:enum:: LogLevel + + .. cpp:enumerator:: INFO + + .. cpp:enumerator:: WARN + + .. cpp:enumerator:: ERR + diff --git a/docs/source/plugins/interfaces/required_interfaces.rst b/docs/source/plugins/interfaces/required_interfaces.rst new file mode 100644 index 00000000..ea899039 --- /dev/null +++ b/docs/source/plugins/interfaces/required_interfaces.rst @@ -0,0 +1,94 @@ +Required Interfaces +=================== + +All plugins are required to expose these interfaces, otherwise they will not get loaded. + +PluginId +-------- + +.. note:: + + The latest version is ``PluginId001`` + +.. cpp:struct:: PluginId + + Query static data about a plugin like it's name + + .. cpp:function:: const char* GetString(PluginString prop) + + .. cpp:function:: int64_t GetField(PluginField prop) + +.. cpp:enum:: PluginString + + Identifier of the string queried by ``GetString``. Enum members are 32 bit large. + + .. cpp:enumerator:: NAME + + Name of the plugin + + .. cpp:enumerator:: LOG_NAME + + Name of the plugin used for logging + +.. cpp:enum:: PluginField + + Identifier of the bitfield queried by ``GetField``. Enum members are 32 bit large. + + .. cpp:enumerator:: CONTEXT + + - ``1`` if the plugin should run on dedicated servers + - ``2`` if the plugin should run when ``client.dll`` is going to get loaded + +PluginCallbacks +--------------- + +.. note:: + + The latest version is ``PluginCallbacks001`` + +.. cpp:struct:: PluginCallbacks + + Callbacks for the launcher + + .. cpp:function:: void Init(HMODULE nsModule, const PluginNorthstarData* initData, bool reloaded) + + Called after the plugin has been loaded and validated. + + .. cpp:function:: void Finalize() + + Called after all plugins have been loaded. + + .. cpp:function:: bool Unload() + + Called just before the plugin library will get unloaded by the launcher's plugin system. + + If ``false`` is returned, the plugin will not be unloaded. + + At the moment plugins that get unloaded are intended for development purposes. Consider always returning ``false`` in distributed builds of your plugin. + + .. cpp:function:: void OnSqvmCreated(CSquirrelVM* sqvm) + + Notifies the plugin of any squirrel virtual machines that got created + + .. cpp:function:: void OnLibraryLoaded(HMODULE module, const char* libraryName) + + Notifies the plugin of any other library loaded by the launcher or any other library. + + .. cpp:function:: RunFrame() + + .. note:: + + Keep this function simple to avoid performance issues + + This function will run every frame of the game. + + If you want to call any squirrel functions, you need to make sure the state of the vm allows it. If you're not in the context of a native closure and want to call a squirrel function, you need to implement a buffer that calls objects in this Callback. + + +.. cpp:struct:: PluginNorthstarData + + Data passed to plugins on initialization + + .. cpp:var:: HMODULE pluginHandle + + The handle of this plugin used for logging