#quake #bsp #map #child-process #gamedev #temp-dir #aas

quake-bspc

Asynchronous wrapper for running the Quake BSP compiler 'bspc' as a child process

6 releases

0.1.5 Nov 24, 2022
0.1.4 Nov 22, 2022

#768 in Game dev

MIT/Apache

125KB
489 lines

Contains (ELF exe/lib, 240KB) test_resources/bspci386

quake-bspc

License Latest Version Documentation

This library provides a simple interface around the bspc Quake compiler 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)

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

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(
    "./path/to/bspc.exe",
    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 would usually be the case in async Rust), 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(
    "./path/to/bspc.exe",
    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);
    }
}

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~152MB
~2.5M SLoC