bevy_trenchbroom

NOTE: Main branch is not ready for real use yet. Expect (and report!) broken or missing features.

Integration and support for the following workflows:

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

^{Arcane Dimensions - Tears of the False God .bsp loaded and rendered in Bevy}

How to use

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

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

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

fn main() {
    App::new()
        // ...
        // TrenchBroom maps use repeating textures, and currently by default bevy's images don't repeat.
        // Use `repeating_image_sampler` to easily create a sampler for this that is optionally filtered.
        .add_plugins(DefaultPlugins.set(ImagePlugin { default_sampler: repeating_image_sampler(false) }))
        .add_plugins(TrenchBroomPlugin::new(
            TrenchBroomConfig::new("example_game") // <- The name of your game
                // Here you can customize the resulting bevy_trenchbroom and game configuration with a builder syntax
                .special_textures(SpecialTexturesConfig::new()) // <- You'll want to enable this if you're loading BSPs with embedded textures via WADs
                // ...
        ))
        // ...
    ;
}

NOTE: By default, TrenchbroomConfig::auto_remove_textures contains __TB_empty, meaning that when loading .maps, any face without a texture will be automatically ignored, saving processing and render time.

Quake's entity classes and their base classes are treated as an analog to Bevy's components and their required components.

You can define your components like so to turn them into quake classes.

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

// The required worldspawn class makes up the main structural world geometry and settings. Exactly one exists in every map.
#[derive(SolidClass, Component, Reflect, Default)]
#[reflect(Component)]
#[geometry(GeometryProvider::new().convex_collider().smooth_by_default_angle().render().with_lightmaps())]
pub struct Worldspawn {
    pub fog_color: Color,
    pub fog_density: f32,
}

// BaseClass doesn't appear in editor, only giving properties to those which use it as a base class.
#[derive(BaseClass, Component, Reflect, Default)]
#[reflect(Component)]
pub struct SolidShadows {
    /// `ericw-tools` `light`: If 1, this model will cast shadows on other models and itself.
    /// Set to -1 on func_detail/func_group to prevent them from casting shadows.
    /// (Default: 0, no shadows)
    pub _shadow: i8,
}

// SolidClass (also known as brush entities) makes the class contain its own geometry, such as a door or breakable
#[derive(SolidClass, Component, Reflect)]
#[reflect(Component)]
#[require(Visibility)]
// You can also use the #[base()] attribute which will take precedence over the require attribute if you want to require components that don't implement QuakeClass, or don't want to be a required component.
#[base(Visibility, SolidShadows)]
#[geometry(GeometryProvider::new().convex_collider().smooth_by_default_angle().render().with_lightmaps())]
// By default, names are converted into snake_case. Using the classname attribute, you can define the case you want it to be converted to instead.
#[classname(PascalCase)] // Would be FuncWall instead of func_wall
// Or you can just set the classname directly.
#[classname("func_wall")]
pub struct FuncWall;

#[derive(SolidClass, Component, Reflect)]
#[reflect(Component)]
// Don't include a collider for func_illusionary.
#[geometry(GeometryProvider::new().smooth_by_default_angle().render().with_lightmaps())]
pub struct FuncIllusionary;

// A more advanced example

// PointClass doesn't have any geometry built-in -- simply just a point in space.

/// A GLTF model with no physics.
#[derive(PointClass, Component, Reflect)]
// Here you would probably do a #[component(on_add = "<function>")] to spawn the GLTF scene when this component is added.
// Make sure to remember that `on_add` is run both in the scene world stored in the map asset, and main world.
// The utility function `DeferredWorld::is_scene_world` is a handy shorthand to early return if the hook is being run in a scene.
//
// Alternatively, you could create a system with a query `Query<&StaticProp, Without<SceneRoot>>` and spawn it through that.
// NOTE: If your GLTF model is rotated weird, add the TrenchBroomGltfRotationFix component when adding it.
#[reflect(Component)]
#[require(Transform, Visibility)]
// Sets the in-editor model using TrenchBroom's expression language.
#[model({ "path": model, "skin": skin })]
pub struct StaticProp {
    // no_default makes the field have an empty default value in-editor, and will cause an error if not defined.
    #[no_default]
    pub model: String,
    /// Documentation comments on structs and their fields will show up in-editor.
    pub skin: u32,
    pub collision_type: CollisionType,
    pub enable_shadows: bool,
}
// If your struct has fields, you need to implement Default for said fields.
// I recommend using the `smart-default` crate for this.
impl Default for StaticProp {
    fn default() -> Self {
        Self {
            model: default(),
            skin: 0,
            collision_type: CollisionType::Model,
            enable_shadows: true,
        }
    }
}

/// A GLTF model with physics.
#[derive(PointClass, Component, Reflect)]
// Here you'd use #[component(on_add = "<function>")] or a system to add a RigidBody of your preferred physics engine.
#[reflect(Component)]
#[require(StaticProp)]
pub struct PhysicsProp;

// For `choices` fgd properties, you can derive FgdType on a unit enum.
#[derive(Reflect, FgdType)]
pub enum CollisionType {
    /// Uses colliders defined in the model, or none if the model doesn't have any
    Model,
    /// Mesh bounding box collider
    BoundingBox,
    // No collision
    None,
}

Then to access the config from TrenchBroom, at some point in your application, you need to call TrenchBroomConfig::write_folder. Example:

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

// app.add_systems(Startup, write_trenchbroom_config)

fn write_trenchbroom_config(server: Res<TrenchBroomServer>) {
    if let Err(err) = server.config.write_folder("<folder_path>") {
        error!("Could not write TrenchBroom config: {err}");
    }

    // This will write <folder_path>/GameConfig.cfg, and <folder_path>/example_game.fgd
}

This writes it out every time your app starts, but depending on what you want to do, you might want to write it out some other time.

After you write it out, the folder the files need to end up in is your TrenchBroom games configuration folder which you can find the path of here.

Materials and bevy_materialize

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.

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

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 "material" 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 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 StandardMaterial in MaterializePlugin.

Loading maps

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")));
}

Physics/Collisions

bevy_trenchbroom supports bevy_rapier3d and avian3d to easily add colliders when spawning geometry.

First, enable the rapier or avian feature on the crate, then either call convex_collider or trimesh_collider on your class's GeometryProvider to create the respective type of collider(s) with said geometry.

Known Bugs

If you are using GLTF models, you might notice that they are rotated 90 degrees in TrenchBroom, compared to in Bevy. To fix this, add the TrenchBroomGltfRotationFix Component to your entity in its spawner.

Possible future plans

• Entity IO

Supported Bevy && TrenchBroom Versions

Bevy	bevy_trenchbroom	TrenchBroom
0.15	0.6	2024.1
0.14	0.4-0.5	2024.1
0.13	0.1-0.3	2024.1

Note: There's a good chance that it will work for other TrenchBroom versions then the one your version of bevy_trenchbroom is made for.