LibreSplit/docs/plugins.md

# Plugins

* Plugin system is in place, allowing you to add features to LibreSplit.

> [!IMPORTANT]
> Always make sure that you fully trust the plugins you're installing.
> Unknown plugins might contain malicious code and give you lots of headaches.

## How do I install a plugin?

Just drop the plugin (which should have a `.so` extension) in your `$XDG_DATA_HOME/libresplit/plugins/` directory (usually will be `~/.local/share/libresplit/plugins/`) and the plugin will be loaded on LibreSplit's next start.

To remove a plugin, just move it out of the `plugins` directory or delete it.

## Plugin Development

Plugins (so far) are enabled to:

- Register new Lua functions;
- Register handlers to timer events.

### The plugin metadata

Each plugin must have the following metadata to identify itself:

* name
* description
* version
* author

You can just stick them in your plugin code like this:

```c
const char plugin_name[] = "Test Plugin";
const char plugin_description[] = "Does nothing, it just exists";
const char plugin_version[] = "0.1";
const char plugin_author[] = "The LibreSplit Core Team";
```

### Initializing the plugin

Each plugin must have an entry point with the following signature:

```c
int plug_init(PlugAPI* api)
```

You can find `PlugAPI` in the `plugin.h` header file, as the plugin system is now, you'll need it to be able to register hooks and Lua functions.

In the init function you will have to register your hooks and Lua functions.

### Registering a new Lua function

Plugins can register new Lua functions. Such functions need to have a signature similar to this:

```c
int my_awesome_lua_function(lua_State* L)
```

You will need to register the function in the `plug_init` entry point, like follows:

```c
int plug_init(PlugAPI* api){
    api->register_lua_function("lua_function_name", my_awesome_lua_function);
    return 0;
}
```

Where `lua_function_name` is the name that will be used to call the function from inside the Lua Auto Splitter Runtime.

### Registering a new event handler

Plugins can register handlers for timer events. Such functions need to have a signature similar to this:

```c
int my_awesome_handler(const ls_timer* timer)
```

You will need to register the function in the `plug_init` entry point, like follows:

```c
int plug_init(PlugAPI* api){
    api->register_event_hook(EVENT, my_awesome_handler);
    return 0;
}
```

Where `EVENT` can be one of the following:

* `START` - Run on the start of the timer.
* `SPLIT` - Run on each split.
* `STOP` - Runs when the timer is stopped.
* `RESET` - Runs on a timer reset.
* `CANCEL` - Runs when the run is cancelled.
* `SKIP` - Runs every time a split is skipped.
* `UNSPLIT` - Runs every time a split is undone.
* `PAUSE` - Runs when the timer is paused.
* `UNPAUSE` - Runs when the timer is unpaused

### Closing the plugin

Each plugin should have a shutdown function with the following signature:

```c
int plug_shutdown()
```

This will be executed when LibreSplit is exiting, so you should use it to clean up resources and closing everything properly.