From 8805cc568f51877578074aa9859637bd560bc145 Mon Sep 17 00:00:00 2001 From: luccie-cmd Date: Wed, 6 Aug 2025 18:42:29 +0200 Subject: Added modding documentation page --- content/docs/modding.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) (limited to 'content/docs/modding.md') diff --git a/content/docs/modding.md b/content/docs/modding.md index 0fe757b..ccc38fd 100644 --- a/content/docs/modding.md +++ b/content/docs/modding.md @@ -1,3 +1,61 @@ # Modding + +A mod is a special plugin that can do things that alter the experience of the game. + +## Making your own + +Any mods that need to be compiled for a 32 bit WASM freestanding environment. + +### Mod exported functions + +A mod **MUST** provide atleast 2 functions: `init` and `deinit` +The signatures are: +- `uint64_t init(uint32_t modID)` +- `uint64_t deinit()` +The return values of `init` and `deinit` are results. Any non zero result will abort `sideros` and have the exit code of the result +This `modID` parameter in `init` is used in some engine functions. (See [engine functions](#engine-functions) for more) + +#### init +The `init` function is the first function called in a mod and is used for setting up variables, initializing a memory manager and defining [systems](#systems). + +#### update +There's no formal definition of an `update` function but you can emulate an update function by hooking on `render` (See [hooking](#hooking) for more info on how to do this) + +#### deinit +The `deinit` function is the last function called in a mod and is used for deleting the defined memory managers and deleting the defined systems + +### Engine functions + +There are a couple of functions you can use. (All of them have to be defined with the IA32 Cdecl + [system-V (Subsection 3.2.3)](https://refspecs.linuxbase.org/elf/x86_64-abi-0.99.pdf) calling convention): +#### Logging +- `void logDebug(const uint8_t* string, uint64_t length)` +- `void logInfo(const uint8_t* string, uint64_t length)` +- `void logWarn(const uint8_t* string, uint64_t length)` +- `void logErr(const uint8_t* string, uint64_t length)` + +The `logDebug` function is only executed if the `sideros` binary **AND** the mod itself are compiled in debug mode. + +Each of these logging functions will print either until a null character has been found, or the length is exhausted. +They will also print a special identifier in front of them with their logging level (So [DEBUG] for logDebug, [INFO] for logInfo, ...) + +#### Hooking functions +- `void hook(uint32_t modID, uint32_t functionID)` + +### Systems + +TODO + +### Hooks + +Hooks are special in a way that they can latch on to a function in the engine and be executed when that function is called. +See [this](#hooking-functions) for function signatures. + +#### Special information +All hooks have a special parameter refered to internally as `deltatime` this is just the time how long it took between the previous call and this call + +## Installing mods + +Installing mods can be done by copying the produced and/or downloaded .wasm file and copying it to the $SIDEROS_PATH/assets/mods directory. +All .wasm files in that directory will be loaded and ran. \ No newline at end of file -- cgit v1.2.3