Quake level loading for Bevy!

More specifically, integration and support for the following workflows:

• TrenchBroom -> .map -> Bevy
• TrenchBroom -> .map -> ericw-tools -> .bsp -> Bevy

• Add the bevy_trenchbroom to your project: cargo add bevy_trenchbroom.

• Add TrenchBroomPlugins with a supplied TrenchBroomConfig to your app like so:

use bevy::prelude::*;
use bevy_trenchbroom::prelude::*;

fn main() {
    App::new()
        // ...
        .add_plugins(TrenchBroomPlugins(TrenchBroomConfig::new("your_game_name")))
        // ...
    ;
}

You can configure TrenchBroomConfig through a builder syntax.

Quake's entity classes are treated as an analog to Bevy's components. Here is an example of a simple point class:

use bevy::prelude::*;
use bevy_trenchbroom::prelude::*;

#[point_class]
#[derive(Default)]
struct MyClass {
	property_a: f32,
	property_b: String,
}

Now just run your game once, and it should automatically be available in TrenchBroom!

For more comprehensive documentation on this topic, see the manual.

Now that you have your environment setup, and have assumedly created your map, loading it is pretty easy.

use bevy::prelude::*;
use bevy_trenchbroom::prelude::*;

// app.add_systems(Startup, spawn_test_map)

fn spawn_test_map(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
) {
    commands.spawn(SceneRoot(asset_server.load("maps/test.map#Scene")));
    // Or, if you're using BSPs.
    commands.spawn(SceneRoot(asset_server.load("maps/test.bsp#Scene")));
}

Because Bevy's material system so heavily relies on generics, storing and inserting arbitrary materials at runtime is challenging.

To this end, i've created the bevy_materialize crate, which bevy_trenchbroom uses.

TrenchBroomPlugins Automatically adds MaterializePlugin with the default toml deserializer. If you wish to use a different deserializer, add your own MaterializePlugin before adding TrenchBroomPlugins.

Texture loaders for loose and embedded textures can be changed in TrenchBroomConfig.

The default loader for loose textures first looks for <texture>.<GenericMaterial extension>. <GenericMaterial extension> is also defined in your config, and is "toml" by default.

If the file can't be found, it then tries to load <texture>.<Image extension> into a StandardMaterial as a fallback. <Image extension> can similarly changed in your config. The fallback is very useful because if you have a bunch of simple textures where the material file would look something like

[material]
base_color_texture = "example.png"

it can get a bit repetitive.

You can also configure the rest of the properties of the default material in MaterializePlugin.

bevy_trenchbroom supports BSP loading via the qbsp crate when the bsp feature is activated.

For more information, please see the manual.

bevy_trenchbroom supports avian3d to easily add colliders when spawning geometry.

Other physics engines aren't built-in, but can be integrated by enabling the physics-integration feature, implementing the PhysicsBackend trait, and adding it through TrenchBroomPhysicsPlugin.

To use the Avian integration, enable the avian_f32 feature (or avian_f64 if you use double-precision). Now you can either call convex_collider or trimesh_collider on your class's SceneHooks to create the respective type of collider(s) with said geometry.

TIP: If you want Brush entities to have a collider by default, you can add this to your TrenchBroomConfig:

.default_solid_scene_hooks(|| SceneHooks::new().convex_collider())

For dedicated servers bevy_trenchbroom supports headless mode by turning off its client feature. e.g.

bevy_trenchbroom = { version = "...", default-features = false }

See the Migration Guide when updating between versions!

^{There is a good chance other versions of TrenchBroom and ericw-tools will work, especially close ones, these are just the versions we officially support.}