logo
Expand description

LiveSplit Wrapper

A safe wrapper library for writing LiveSplit One autosplitters

build status docs license

LiveSplit One uses dynamically loaded WASM modules for plugins, which means they have to communicate over a C api. This crate contains ergonomic wrappers and helpers to write those plugins in safe rust. At the moment only autosplitters are supported, but there will eventually be support for more general plugins.

Implementing an autosplitter

To write an autosplitter you need to implement the Splitter trait and invoke the register_autosplitter! macro on your splitter.

Here’s a full (nonsensical) example. Build this with --target wasm32-unknown-unknown and it can be loaded by frontends such as livesplit-one-desktop or obs-livesplit:

use livesplit_wrapper::{Splitter, Process, TimerState, HostFunctions};

#[derive(Default)]
struct MySplitter {
    process: Option<Process>,
}

livesplit_wrapper::register_autosplitter!(MySplitter);
impl Splitter for MySplitter {
    fn new() -> Self {
        let mut s = MySplitter::default();
        s.process = s.attach("CoolGame.exe");
        if s.process.is_none() {
            log::warn!("failed to connect to process, is the game running?");
        }
        s.set_tick_rate(120.0);
        s.set_variable("items collected", "0");
        s
    }

    fn update(&mut self) {
        if let Some(p) = &self.process {
            match (self.state(), p.read::<i16>(0xD1DAC71C)) {
                (TimerState::Paused, Ok(314)) => self.unpause(),
                (TimerState::Running, Ok(42)) => self.pause(),
                _ => {}
            }
        }
    }
}

For a real-world example, check out this Celeste autosplitter.

Macros

Wires up the necessary c interface for a type that implements Splitter.

Structs

This logger gets initialized automatically when you register an autosplitter and emits logs to LiveSplit’s autosplitter runtime.
A thread-safe cell which can be written to only once.
A handle representing an attached process that can be used to read its memory.

Enums

Currently the only possible error is a failed memory read on the attached process.
The possible states of the timer.

Traits

The autosplitter’s interface for interacting with the LiveSpilit timer.
Marker trait for “plain old data”.
The main autosplitter trait.

Type Definitions

An address in the attached processes memory.
The result of an attempt to read process memory.