Crate plumesplat

Crate plumesplat 

Source
Expand description

§PlumeSplat

Advanced terrain and mesh splatting for Bevy Engine with support for up to 256 materials in a single draw call.

PlumeSplat extends Bevy’s StandardMaterial with texture array splatting, enabling complex multi-material terrains with full PBR lighting support.

§Features

  • 256 Material Support: Blend up to 256 materials using texture arrays and per-vertex indices
  • Single Draw Call: All materials rendered efficiently in one draw call
  • Full PBR Integration: Extends StandardMaterial for proper lighting, shadows, and reflections
  • Triplanar Mapping: UV-less texturing that works on arbitrary geometry without seams
  • Normal Maps: Per-material normal mapping for detailed surfaces
  • Packed PBR Textures: Support for metallic, roughness, ambient occlusion, and height maps
  • Stochastic Tiling: Eliminates visible texture repetition patterns
  • Height-Based Blending: Natural material transitions based on height maps
  • Builder API: Ergonomic API for creating materials from individual textures

§Quick Start (Builder API - Recommended)

The easiest way to use PlumeSplat is with the builder API:

use bevy::prelude::*;
use plumesplat::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(PlumeSplatPlugin)
        .add_systems(Startup, setup)
        .run();
}

fn setup(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    asset_server: Res<AssetServer>,
) {
    // Define material layers
    let grass = MaterialLayer::new(asset_server.load("grass.png"));
    let dirt = MaterialLayer::new(asset_server.load("dirt.png"));
    let rock = MaterialLayer::new(asset_server.load("rock.png"))
        .with_normal(asset_server.load("rock_normal.png"));

    // Build the pending material
    let pending = SplatMaterialBuilder::new()
        .add_layer(grass)
        .add_layer(dirt)
        .add_layer(rock)
        .with_uv_scale(2.0)
        .build();

    // Spawn with mesh - material auto-creates when textures load
    commands.spawn((
        Mesh3d(meshes.add(Cuboid::default())),
        pending,
    ));
}

§Vertex Attributes

Meshes must include custom vertex attributes specifying material indices and blend weights:

use plumesplat::prelude::*;

// Create per-vertex material data
let vertices = vec![
    MaterialVertex::single(0),           // 100% material 0
    MaterialVertex::blend2(0, 1, 0.5),   // 50% material 0, 50% material 1
    MaterialVertex::blend4([0, 1, 2, 3], [0.4, 0.3, 0.2, 0.1]),
];

// Encode for the GPU
let (indices, weights) = encode_material_data(&vertices);

// Add to your mesh
// mesh.insert_attribute(ATTRIBUTE_MATERIAL_INDICES, indices);
// mesh.insert_attribute(ATTRIBUTE_MATERIAL_WEIGHTS, weights);

§Key Types

Modules§

prelude
Convenient imports for common PlumeSplat types.

Structs§

MaterialLayer
A single material layer defining textures for one terrain type.
MaterialVertex
Per-vertex material data for terrain splatting.
PendingSplatMaterial
Component marking an entity as having a pending splat material.
PlumeSplatExtension
Material extension that adds texture array splatting to StandardMaterial.
PlumeSplatPlugin
Bevy plugin that enables PlumeSplat terrain splatting.
PlumeSplatSettings
Shader uniform settings for PlumeSplat rendering.
SplatMaterialBuilder
Builder for creating PendingSplatMaterial with a fluent API.

Constants§

ATTRIBUTE_MATERIAL_INDICES
Custom vertex attribute storing 4 material indices packed into a u32.
ATTRIBUTE_MATERIAL_WEIGHTS
Custom vertex attribute storing 4 blend weights packed into a u32.

Functions§

encode_material_data
Encodes material data for a slice of vertices into packed u32 vectors.
pack_u8x4
Packs four u8 values into a single u32.
unpack_u8x4
Unpacks a u32 into four u8 values.

Type Aliases§

PlumeSplatMaterial
Type alias for the complete PlumeSplat material.