Crate asr

Helper crate to write auto splitters for LiveSplit One’s auto splitting runtime.

There are two ways of defining an auto splitter.

Defining an update function

You can define an update function that will be called every frame. This is the simplest way to define an auto splitter. The function must have the following signature:

#[no_mangle]
pub extern "C" fn update() {}

The advantage of this approach is that you have full control over what happens on every tick of the runtime. However, it’s much harder to keep state around as you need to store all state in global variables as you need to return out of the function on every tick.

Example

#[no_mangle]
pub extern "C" fn update() {
    if let Some(process) = Process::attach("explorer.exe") {
        asr::print_message("Hello World!");
        if let Ok(address) = process.get_module_address("explorer.exe") {
            if let Ok(value) = process.read::<u32>(address) {
                if value > 0 {
                    asr::timer::start();
                }
            }
        }
    }
}

Defining an asynchronous main function

You can use the async_main macro to define an asynchronous main function.

Similar to using an update function, it is important to constantly yield back to the runtime to communicate that the auto splitter is still alive. All asynchronous code that you await automatically yields back to the runtime. However, if you want to write synchronous code, such as the main loop handling of a process on every tick, you can use the next_tick function to yield back to the runtime and continue on the next tick.

The main low level abstraction is the retry function, which wraps any code that you want to retry until it succeeds, yielding back to the runtime between each try.

So if you wanted to attach to a Process you could for example write:

let process = retry(|| Process::attach("MyGame.exe")).await;

This will try to attach to the process every tick until it succeeds. This specific example is exactly how the Process::wait_attach method is implemented. So if you wanted to attach to any of multiple processes, you could for example write:

let process = retry(|| {
   ["a.exe", "b.exe"].into_iter().find_map(Process::attach)
}).await;

Example

Here is a full example of how an auto splitter could look like using the async_main macro:

Usage on stable Rust:

async_main!(stable);

Usage on nightly Rust:

#![feature(type_alias_impl_trait, const_async_blocks)]

async_main!(nightly);

The asynchronous main function itself:

async fn main() {
    // TODO: Set up some general state and settings.
    loop {
        let process = Process::wait_attach("explorer.exe").await;
        process.until_closes(async {
            // TODO: Load some initial information from the process.
            loop {
                // TODO: Do something on every tick.
               next_tick().await;
            }
        }).await;
    }
}

Re-exports

• pub use arrayvec;
• pub use time;
• pub use itoa;
  itoa
• pub use ryu;
  ryu

Modules

• deep_pointer
  Support for storing pointer paths for easy dereferencing inside the autosplitter logic.
• emulator
  Support for attaching to various emulators.
• file_format
  Support for parsing various file formats.
• future
  Futures support for writing auto splitters with asynchronous code.
• game_engine
  Support for attaching to various game engines.
• settings
  Support for interacting with the settings of the auto splitter.
• signaturesignature
  Support for finding patterns in a process’s memory.
• string
  Support for string types that can be read from a process’s memory.
• sync
  Useful synchronization primitives.
• time_util
  This module provides utilities for creating durations.
• timer
  This module provides functions for interacting with the timer.
• watcher
  Support for watching values and tracking changes between them.

Macros

• async_main
  Defines that the auto splitter is using an asynchronous main function instead of the normal poll based update function. It is important to frequently yield back to the runtime to communicate that the auto splitter is still alive. If the function ends, the auto splitter will stop executing code.
• panic_handler
  Defines a panic handler for the auto splitter that aborts execution. By default it will only print the panic message in debug builds. A stack based buffer of 1024 bytes is used by default. If the message is too long, it will be truncated. All of this can be configured.

Structs

• Address
  A general purpose address.
• Address16
  A 16-bit address that can be read from a process’s memory.
• Address32
  A 32-bit address that can be read from a process’s memory.
• Address64
  A 64-bit address that can be read from a process’s memory.
• Error
  An error returned by a runtime function.
• MemoryRange
  A memory range of a process. All information is queried lazily.
• MemoryRangeFlags
  Describes various flags of a memory range.
• Process
  A process that the auto splitter is attached to.
• ProcessId
  A process id is a unique identifier for a process. It is not guaranteed to be the same across multiple runs of the same process. It is only guaranteed to be unique for the duration of the process. This matches the operating system’s definition of a process id.

Enums

• Endian
  The endianness of a value.
• PointerSize
  Pointer size represents the width (in bytes) of memory addresses used in a certain process.

Traits

• FromEndian
  A trait for converting from big or little endian.

Functions

• get_arch
  Queries the architecture that the runtime is running on. Due to emulation this may not be the same as the architecture that an individual process is targeting. For example 64-bit operating systems usually can run 32-bit processes. Also modern operating systems running on aarch64 often have backwards compatibility with x86_64 processes.
• get_os
  Queries the name of the operating system that the runtime is running on. Due to emulation this may not be the same as the operating system that an individual process is targeting.
• print_limited
  Prints a log message for debugging purposes by formatting the given message into a stack allocated buffer with the given capacity. This is useful for printing dynamic messages without needing an allocator. However the message may be truncated if it is too long.
• print_message
  Prints a log message for debugging purposes.
• set_tick_rate
  Sets the tick rate of the runtime. This influences how many times per second the update function is called. The default tick rate is 120 ticks per second.

Derive Macros

• FromEndianderive
  Generates an implementation of the FromEndian trait for a struct. This allows converting values from a given endianness to the host’s endianness.