#About C in a mod
A mod's code is LumaScript, and it can also include C or C++ files. Use C when you already have C code, such as a library or a port of an existing mod, or when you want the game's function hooks at their lowest level.
LumaLink compiles your C into the same library as the mod's LumaScript, for every platform the mod lists. Nothing is interpreted while the game runs.
A mod can't be C alone. It needs at least one .lum file, which starts the C code. For more information on LumaScript, see About LumaScript.
#Prerequisites
- LumaLink and an installed Nebula. For more information, see Installing LumaLink.
- A mod folder with a
codeentry in itsluma.json. For more information, see Creating a mod.
You don't need a compiler of your own. LumaLink brings the compilers for every platform.
#Adding C files
Put .c, .cpp and .h files in the mod's source folder, beside its .lum files:
double-bits/
luma.json
source/
main.lum
bits.c
bits.hlumalink build compiles every C and C++ file in source and its folders. Include a header by its path from source.
#Calling C from LumaScript
Declare the C function in a header:
C #include <stdbool.h> bool bits_on(void);In LumaScript, read the header with
use c, and declare the function withextern c fn:LumaScript use c "bits.h" extern c fn bits_on() -> bool on start { if not bits_on() { log "double-bits: the game has no addStockedStarPiece to hook" } }
The LumaScript declaration must match the C one. These types cross between the two:
| LumaScript | C |
|---|---|
i8 to i64, u8 to u64 |
int8_t to int64_t, uint8_t to uint64_t |
f32, f64 |
float, double |
bool |
bool |
vec2, vec3, vec4, mat34, color |
Structs of floats, in that order |
A struct marked c struct |
The same struct, in C layout |
text, bytes |
A pointer and a length, valid until the call returns |
ref<C> |
A handle. Get the object with lumart_ref_get, on the game thread. |
Lists, maps and other containers don't cross. Pass them one item at a time, or as bytes.
#Calling LumaScript from C
Mark a LumaScript function export c fn:
var times: i32 = 2
export c fn bits_times() -> i32 {
return times
}LumaLink writes a header with every exported function, lm_exports.h. Include it in your C:
#include "lm_exports.h"
int n = bits_times();Only your mod's own C sees an exported function. The game and other mods can't call it.
#Using the game from C
Two headers give your C the game:
luma.h, which comes with Nebula: finding the game's functions, hooking them, reading fields, services, memory and the mod log.lumart.h, which comes with LumaLink:luma_rt_coreis the game's table of functions, andluma_rt_selfis your mod.
#include "luma.h"
#include "lumart.h"
luma_rt_core->log(luma_rt_self, "double-bits: on");Memory from luma_rt_core->alloc(luma_rt_self, size, align) is counted on the Mods page and freed when the mod stops. Give it back sooner with luma_rt_core->free.
#Services
Each service has a header of its own, such as luma_audio.h for audio. Ask for the service's table by its name and version:
#include "luma_audio.h"
void bits_ding(void) {
const LumaAudioService* audio = (const LumaAudioService*)luma_rt_core->service(
luma_rt_self, LUMA_AUDIO_NAME, LUMA_AUDIO_MAJOR, LUMA_AUDIO_MINOR);
LumaHandle voice;
if (audio != 0) {
audio->play(luma_rt_self, "Ding", 0, 0, 0, &voice);
}
}service returns null when the game has no such service, or the player didn't grant the permission it needs. The service works as it does from LumaScript. For more information, see Services.
#Hooking a game function
A hook is your function, run when the game calls one of its own. This example doubles every star bit Mario collects:
#include "luma.h"
#include "lumart.h"
#include "lm_exports.h"
#include "bits.h"
/* Runs before the game adds star bits, and multiplies how many. */
static int32_t more_bits(LumaCall* call, void* user) {
(void)user;
int* count = (int*)call->args[1];
*count *= bits_times();
return 0; /* 0: the game's own function runs next, with the new count */
}
bool bits_on(void) {
const LumaFunction* add = luma_rt_core->function("GameDataFunction::addStockedStarPiece", "void(int)");
return add != 0 && luma_rt_core->hook(luma_rt_self, add, LUMA_BEFORE, more_bits, 0) == 0;
}function(name, signature)finds the game's function by its name, and its signature as the game's source writes it. It returns null when the game has none.hook(mod, function, kind, hook, user)adds your hook.useris passed back to your hook each time.- The hook gets the call:
call->args[0]is the object (this), or null for a function without one.call->args[1]and on point at the arguments, so a hook can change them. For a reference parameter, it points at the object itself.call->resultpoints at the result.
A hook runs at one of four times:
| Kind | When it runs |
|---|---|
LUMA_BEFORE |
Before the function. Return 0 to let it run, or non-zero to skip it. Write call->result before skipping. |
LUMA_AFTER |
After the function. It can change the result. |
LUMA_WRAP |
Around the function. Call luma_rt_core->proceed(call) where the function should run. |
LUMA_REPLACE |
Instead of the function. Only one mod can replace a function. |
hook returns:
| Value | Meaning |
|---|---|
| 0 | Added. |
| -1 | Refused. A constructor or destructor takes LUMA_BEFORE and LUMA_AFTER only, and a function whose result has no default can't be skipped. |
| -2 | Another mod replaces this function already. |
| -3 | Not called on the game thread. Add hooks from on start or another event. |
luma_rt_core->unhook, with the same values, takes a hook out. All of a mod's hooks go when the mod stops.
A hook runs on whichever thread calls the function. luma_rt_core->game_thread() returns 1 on the game thread.
To find a function's name and signature, look in the game description. For more information, see The game description.
In LumaScript, before, after and wrap hook the game's functions with less code. Use C hooks when the rest of the work is in C.
#Building and checking
lumalink build double-bits
lumalink check double-bitsbuild compiles the C and LumaScript for every platform in luma.json, and prints each library it makes. A C error is printed as the compiler gives it, with the file and line.
check also checks the game names your LumaScript uses. It can't see inside your C, so a name your C looks up with function is found only when the game runs. Always handle the null case, as the example does.
#Troubleshooting
| Message | What to do |
|---|---|
| ... has no LumaScript: no source/**/*.lum | Add a .lum file that calls your C. |
| The compiler's own error, with a file and line | Fix the C. |
| A type that can't cross | Use a type from the table in Calling C from LumaScript. |
While the game runs, a fault in your C stops the mod, and the Mods page and the mod log say where. For more information, see When a mod fails.