Crate bspc

This library wraps around the bspc Quake utility tool to make it easier to use it from Rust. It does so by spawning a child process and asynchronously waiting for its output.

Some features include:

• setting up a temporary directory to store input/output files in
• parsing output logs to look for errors/warnings
• streaming the output logs in real-time (via OptionsBuilder::log_stream)

Links

The BSPC tool itself is not included with the library. Instead, it needs to already exist in the filesystem before the library is used.

• Old binary downloads for v1.2: link
• Source: bnoordhuis/bspc
• Fork with more recent commits: TTimo/bspc

Example

Basic example showing the conversion of a Quake BSP file to a MAP file:

use bspc::{Command, Options};
use tokio_util::sync::CancellationToken;

let bsp_contents = b"...";
let result = bspc::convert(
    "./test_resources/bspci386",
    Command::BspToMap(bsp_contents),
    Options::builder()
        .verbose(true)
        .build(),
)
.await;
match result {
    Ok(output) => {
        assert_eq!(output.files.len(), 1);
        println!("{}", output.files[0].name);
        println!("{}", String::from_utf8_lossy(&output.files[0].contents));
    }
    Err(err) => {
        println!("Conversion failed: {}", err);
    }
}

Example with cancellation

The following snippet demonstrates how to cancel the conversion (in this case, using a timeout) via the cancellation token. Note that the cancellation is not done simply by dropping the future (as is normally done), since we want to ensure that the child process is killed and the temporary directory deleted before the future completes.

use bspc::{Command, Options, ConversionError};
use tokio_util::sync::CancellationToken;

let bsp_contents = b"...";
let cancel_token = CancellationToken::new();
let cancel_task = {
    let cancel_token = cancel_token.clone();
    tokio::spawn(async move {
        tokio::time::sleep(std::time::Duration::from_secs(10)).await;
        cancel_token.cancel();
    })
};
let result = bspc::convert(
    "./test_resources/bspci386",
    Command::BspToMap(bsp_contents),
    Options::builder()
        .verbose(true)
        .cancellation_token(cancel_token)
        .build(),
)
.await;
match result {
    Ok(output) => {
        assert_eq!(output.files.len(), 1);
        println!("{}", output.files[0].name);
        println!("{}", String::from_utf8_lossy(&output.files[0].contents));
    }
    Err(ConversionError::Cancelled) => {
        println!("Conversion timed out after 10 seconds");
    }
    Err(err) => {
        println!("Conversion failed: {}", err);
    }
}

Modules

logs

Structs

Options

Options for the conversion process.

OptionsBuilder

Builder for Options.

Output

Full output of the child process, including the exit code, log, and any output files.

OutputFile

A single output file produced by the BSPC process.

Enums

Command

The subcommand to pass to the BSPC executable.

ConversionError

Error type returned by convert.

Functions

convert

Runs the BSPC executable with the given arguments, converting a single file to a different format, returning the complete output of the process (all output files, logs, and exit code).

Type Aliases

CommandArgumentBuilder

Callback used by Command::Other.