89 lines
3.4 KiB
Text
89 lines
3.4 KiB
Text
= Darktide Plugin Template
|
|
:idprefix:
|
|
:idseparator:
|
|
:toc: macro
|
|
:toclevels: 1
|
|
:!toc-title:
|
|
:caution-caption: :fire:
|
|
:important-caption: :exclamtion:
|
|
:note-caption: :paperclip:
|
|
:tip-caption: :bulb:
|
|
:warning-caption: :warning:
|
|
|
|
A template for building an engine plugin for Warhammer 40,000 Darktide.
|
|
|
|
== Getting started
|
|
|
|
In `src/lib.rs`, change `PLUGIN_NAME` and `MODULE_NAME` to unique values matching your plugin.
|
|
Then head to `src/plugin.rs`, where `Plugin.setup_game`, `Plugin.update_game` and
|
|
`Plugin.shutdown_game` are your entry points that the engine will call. Start your plugin
|
|
implementation here.
|
|
|
|
`src/stingray_sdk.rs` provides mappings for the engine's API. A few functions are already
|
|
implemented to serve as an example. You can implement more based on what you need (see
|
|
`LuaApi` in `src/plugin_api.h` for what's available).
|
|
If you do implement more mappings, please contribute them upstream to this template, so that
|
|
others can benefit from them as well.
|
|
|
|
Your primary interface with the game's Lua code should be `LuaApi.add_module_function`. This creates
|
|
functions callable from Lua, such as `DTPluginTemplate.do_something` in `src/plugin.rs`.
|
|
|
|
=== Things to keep in mind
|
|
|
|
* Printing in Rust code will not show up in the game's log. You must use `plugin.log` (`LoggingApi`).
|
|
* Panics in Rust will lead to a game crash. Using `Result` is good hygiene anyways.
|
|
|
|
=== Advanced
|
|
|
|
`PluginApi` contains more functions than just the three currently mapped in `Plugin`.
|
|
If you need any of those, you will have to implement their mapping both in `Plugin` and in
|
|
`src/lib.rs` like to the existing ones.
|
|
|
|
The engine also provides additional API structs beyond `LoggingApi` and `LuaApi`. A full list can be
|
|
found at https://github.com/AutodeskGames/stingray-plugin/blob/master/stingray_sdk/engine_plugin_api/plugin_api.h[AutodeskGames/stingray-plugin].
|
|
You will need to copy the definitions from there to `src/plugin_api.h`. They will likely also need
|
|
adjustments, as Darktide's engine has long since diverted from Autodesk's version.
|
|
|
|
== Building
|
|
|
|
> Only cross-compiling on a Linux build machine has been tested so far.
|
|
> Native build on Windows likely only need the basic setup for Rust, though.
|
|
|
|
The engine requires DLLs to have a name suffix of `_pluginw64_release.dll`. The rest before that
|
|
can be an arbitrary file name. The DLL then needs to be copied to `binaries/plugins` in the game's
|
|
installation directory.
|
|
|
|
=== Docker
|
|
|
|
The easiest way is using the provided `Dockerfile`. While it does run a Linux image, it sets up
|
|
everything needed for compiling Windows DLLs, so it will work the same regardless of the host OS.
|
|
|
|
[source,shell]
|
|
----
|
|
docker build -t my-project .
|
|
docker run --rm -t -v ./:/src/plugin my-project cargo build --release
|
|
----
|
|
|
|
(substitute `my-project` for a fitting name)
|
|
|
|
This `Dockerfile` should be suitable for CI as well.
|
|
|
|
=== Manual (Linux)
|
|
|
|
==== Prerequisites
|
|
|
|
* A reasonably recent version of LLVM, lld & Clang
|
|
** A symlink `clang-cl` -> `clang` in `PATH`
|
|
* cURL
|
|
* Wine
|
|
* Rust toolchain, MSVC target and `rust-src`:
|
|
** `rustup target add x86_64-pc-windows-msvc`
|
|
** `rustup component add rust-src`
|
|
|
|
==== Build
|
|
|
|
Set up https://github.com/Jake-Shadle/xwin[Jake-Shadle/xwin]. That repository contains a Docker file
|
|
that can serve as an example. So does the `Dockerfile` here.
|
|
|
|
This includes the setup of Wine and the environmental variables to have Cargo use the Windows
|
|
libraries and tools through Wine.
|