bevy_symbios_texture

Procedural, tileable texture generation for Bevy.

Generates albedo, normal, roughness (ORM), and optional emissive maps entirely on the CPU — no asset files required. Generation is multi-core (rows are produced in parallel) and seamlessly tileable for all surface textures via toroidal 4-D noise mapping. Alpha-masked card textures (leaf, twig, window, stained glass, iron grille, chain-link, log-end) produce per-pixel transparency and do not tile. Atlas-capable card generators — particle sprites (soft disc, spark, snowflake, puff, ring, petal, shard, flame, flower) and foliage billboards (leaf sprite, grass tuft, frond, reed, needle, broadleaf) — bake alpha-silhouette sheets where every atlas cell is a per-cell-seeded variant of the same config.

Quick start

Synchronous (blocking)

Suitable for startup systems or contexts where a small generation time is acceptable.

use bevy::prelude::*;
use bevy_symbios_texture::{
    bark::{BarkConfig, BarkGenerator},
    generator::{TextureGenerator, map_to_images},
};

fn setup(mut commands: Commands, mut images: ResMut<Assets<Image>>) {
    let map = BarkGenerator::new(BarkConfig::default())
        .generate(512, 512)
        .expect("valid dimensions");

    let handles = map_to_images(map, &mut images);

    commands.spawn(Sprite {
        image: handles.albedo,
        ..default()
    });
}

Asynchronous (non-blocking, recommended)

Offloads pixel math to a private, bounded rayon thread pool (default 4 concurrent tasks; configurable via AsyncTextureConfig::pool_threads) so the main thread is never stalled. On WASM, falls back to Bevy's AsyncComputeTaskPool.

Within each texture, rows are generated in parallel: async tasks work-steal across the private pool (so pool_threads remains the CPU cap), while direct synchronous generate() calls parallelise on the caller's rayon pool — usually the global one, using every core. Output is byte-identical to serial generation.

If rayon::ThreadPoolBuilder::build() fails at first init (out-of-memory, OS thread limit, sandboxed environments) the library logs a warning and falls back to running each generator inline on the calling thread. Texture generation still works — slower and blocking the spawning thread — instead of panicking.

use bevy::prelude::*;
use bevy_symbios_texture::{
    AsyncTextureConfig, SymbiosTexturePlugin,
    async_gen::{PendingTexture, TextureReady},
    bark::BarkConfig,
};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        // Default pool: 4 concurrent tasks.
        .add_plugins(SymbiosTexturePlugin::default())
        // Or explicitly: 0 = auto (available_parallelism() / 2),
        // any positive value = exact thread count.
        // .add_plugins(SymbiosTexturePlugin {
        //     config: AsyncTextureConfig { pool_threads: 0 },
        // })
        .add_systems(Startup, spawn_task)
        .add_systems(Update, on_ready)
        .run();
}

fn spawn_task(mut commands: Commands) {
    commands.spawn(PendingTexture::bark(BarkConfig::default(), 1024, 1024));
}

fn on_ready(
    mut commands: Commands,
    ready: Query<(Entity, &TextureReady)>,
) {
    for (entity, tex) in &ready {
        commands.entity(entity).despawn();
        // tex.0.albedo / tex.0.normal / tex.0.roughness are Handle<Image>
    }
}

Dropping a PendingTexture entity before generation completes sets a cancellation flag; tasks that have not yet started exit without doing any work.

One-shot procedural materials

build_procedural_material_async collapses the StandardMaterial-allocate + PendingTexture-spawn + post-completion-patch dance into a single call. Define a MaterialSettings (PBR fields + a TextureConfig enum that selects the generator), call the helper, and use the returned handle immediately:

use bevy_symbios_texture::{
    MaterialSettings, TextureConfig, build_procedural_material_async,
    brick::BrickConfig,
};

fn spawn_brick_wall(
    mut commands: Commands,
    mut materials: ResMut<Assets<StandardMaterial>>,
    mut images: ResMut<Assets<Image>>,
    mut meshes: ResMut<Assets<Mesh>>,
) {
    let settings = MaterialSettings {
        base_color: [0.65, 0.30, 0.20],
        roughness: 0.85,
        texture: TextureConfig::Brick(BrickConfig::default()),
        ..MaterialSettings::default()
    };
    let material = build_procedural_material_async(
        &mut commands, &mut materials, &mut images, /*cache=*/ None,
        &settings, 512, 512,
    );
    commands.spawn((Mesh3d(meshes.add(Cuboid::default())), MeshMaterial3d(material)));
}

Texture cache

To avoid regenerating the same (generator, config, size) tuple across spawns, insert a TextureCache resource:

use bevy_symbios_texture::{DEFAULT_MEMORY_CACHE_ENTRIES, TextureCache};

app.insert_resource(TextureCache::memory(DEFAULT_MEMORY_CACHE_ENTRIES));
// or, for cross-process persistence:
// app.insert_resource(TextureCache::file("./.texture-cache", manifest_version)?);

Cache hits return previously-uploaded Handle<Image> clones synchronously and skip the rayon dispatch entirely. Cache keys derive from a fingerprint of the config struct, so any field change automatically invalidates the prior entry. manifest_version is mixed into every FileStore on-disk key, so bumping it rotates the persisted cache without deleting the directory — use it when generator internals change without a config-field change.

The library ships two built-in stores — MemoryStore (bounded, FIFO eviction, default) and FileStore (binary blobs on disk) — and exposes the TextureCacheStore trait for custom backends. FileStore persists the raw pixel blobs as generation completes and re-uploads them (regenerating mipmaps) on the first hit after a restart, so warm caches survive across processes.

For diagnostics, TextureCache::entry_count() reports how many entries the backing store currently holds in memory — Some(len) for MemoryStore, None for FileStore, whose entries live on disk. Because the cache retains Handle<Image> clones, its entry count is often the missing term when attributing image-asset growth in a running application.

Animated parameter curves

Time-varying weathering, age, and seasonal change are first-class via the AnimatedProceduralMaterial component plus a small set of ParameterCurve impls (Linear, EaseInOut, Stepped, ScriptedFn). Attach the component to a material entity and the tick_animated_procedural_materials system regenerates the texture whenever the curve's output changes:

use bevy_symbios_texture::{
    AnimatedProceduralMaterial, Linear, ParameterCurve, TextureConfig,
    metal::MetalConfig,
};

let rust = Linear { from: 0.0_f64, to: 1.0, duration: 10.0 };
let base = MetalConfig::default();
let animator = AnimatedProceduralMaterial::new(material, 512, 512, move |t| {
    TextureConfig::Metal(MetalConfig {
        rust_level: rust.eval(t),
        ..base.clone()
    })
})
.with_min_regen_interval(0.25); // throttle regeneration to 4 Hz

Two thresholds gate regeneration: a wall-clock cooldown (min_regen_interval, default 0.25 s) and fingerprint equality. Stepped or plateaued curves cost essentially nothing once the value stops changing.

For sub-second smoothness across the steady-state pixels, drive a fragment-shader uniform on the material — generator output is RGBA8 and is the wrong knob for sub-frame interpolation.

Compute-shader fast path

A wgpu compute-shader port of the hottest generators (FBM-based bark, brick, marble) is on the roadmap but not implemented. The remaining work — porting toroidal noise to WGSL with bit-equivalent CPU/GPU output, dispatch + readback plumbing, a feature flag that swaps in the GPU path when available, and a benchmark suite — is multi-week and was deliberately deferred so this release could ship the asynchronous + cached + animated path on a known-good CPU baseline.

If you need realtime texture editing at 60 FPS today, the alternatives are:

• Rely on the row-parallel CPU path: on a modern many-core desktop the heaviest generator (bark) renders a 512² map in ~20 ms, so interactive editing at moderate resolutions is already feasible without the GPU port.
• Bake the texture once via the regular CPU path and animate a material uniform (rust mask weight, colour blend, etc.) in the fragment shader.
• Use AnimatedProceduralMaterial with a coarse min_regen_interval and accept the staircase update cadence.

Generators

Surface textures (tileable)

All tileable generators produce three seamlessly-repeating maps:

Upload with map_to_images to get repeat-wrapping samplers. When a generator produces an emissive map the polling systems assign it to StandardMaterial::emissive_texture; Bevy multiplies it by the material's emissive colour factor, which the material flow auto-defaults to white when MaterialSettings::emission_color / emission_strength are left unset, so the glow shows out of the box. Set them only to tint or brighten beyond the map's encoded values.

Bark

Domain-warped FBM noise with an anisotropic Worley plate layer for rhytidome furrows, producing fibrous, streaked bark grain.

use bevy_symbios_texture::bark::BarkConfig;

let config = BarkConfig {
    seed: 42,
    scale: 2.0,             // spatial frequency of the pattern
    octaves: 6,             // FBM detail levels (base layer)
    warp_octaves: 3,        // FBM detail for the warp layers (3 is plenty)
    warp_u: 0.15,           // lateral warp strength
    warp_v: 0.55,           // vertical (fibre) warp strength
    color_light: [0.45, 0.28, 0.14],  // ridge colour, linear RGB
    color_dark:  [0.09, 0.05, 0.03],  // groove colour, linear RGB
    normal_strength: 3.0,
    furrow_multiplier: 0.78, // blend weight of the Worley plate layer [0, 1]
    furrow_scale_u: 2.0,     // horizontal cell frequency (higher = narrower plates)
    furrow_scale_v: 0.48,    // vertical cell frequency (lower = longer plates)
    furrow_shape: 2.0,       // plate height power (<1 widens plateau, sharpens cracks)
};

Rock

Ridged multifractal noise for cracked, faceted stone.

use bevy_symbios_texture::rock::RockConfig;

let config = RockConfig {
    seed: 7,
    scale: 3.0,
    octaves: 8,
    attenuation: 2.0,    // ridge sharpness (higher = sharper)
    color_light: [0.37, 0.42, 0.36],
    color_dark:  [0.22, 0.20, 0.18],
    normal_strength: 4.0,
};

Ground

Blended dual-scale FBM for organic soil / dirt surfaces.

use bevy_symbios_texture::ground::GroundConfig;

let config = GroundConfig {
    seed: 13,
    macro_scale: 2.0,    // large soil-patch scale
    macro_octaves: 5,
    micro_scale: 8.0,    // fine grain scale
    micro_octaves: 4,
    micro_weight: 0.35,  // 0.0 = all macro, 1.0 = all micro
    color_dry:   [0.52, 0.40, 0.26],
    color_moist: [0.28, 0.20, 0.12],
    normal_strength: 2.0,
};

Brick

Grid-based SDF with per-cell colour hashing and configurable mortar/bonding pattern.

use bevy_symbios_texture::brick::BrickConfig;

let config = BrickConfig {
    seed: 42,
    scale: 4.0,          // number of brick rows across the tile
    row_offset: 0.5,     // 0.0 = stack bond, 0.5 = running bond, 0.333 = third bond
    aspect_ratio: 2.0,   // brick width-to-height ratio
    mortar_size: 0.05,   // mortar gap as a fraction of cell height [0, 0.4]
    bevel: 0.5,          // corner bevel radius as a fraction of mortar_size [0, 1]
    cell_variance: 0.15, // per-brick colour jitter [0, 1]
    roughness: 0.5,      // surface pitting noise intensity [0, 1]
    color_brick:  [0.56, 0.28, 0.18],
    color_mortar: [0.76, 0.73, 0.67],
    normal_strength: 4.0,
};

Plank

Anisotropic grain FBM with domain warp, Worley knots, and horizontal joint gaps. Each plank row has an independent de-correlated grain phase.

use bevy_symbios_texture::plank::PlankConfig;

let config = PlankConfig {
    seed: 42,
    plank_count: 5.0,     // number of planks visible vertically
    grain_scale: 12.0,    // controls how fine the grain lines are
    joint_width: 0.06,    // gap between planks as a fraction of plank height [0, 0.3]
    stagger: 0.5,         // horizontal stagger of end-joints [0, 1]
    knot_density: 0.25,   // fraction of cells that contain a Worley knot [0, 1]
    grain_warp: 0.35,     // domain-warp strength that bends grain lines [0, 1]
    color_wood_light: [0.72, 0.52, 0.30],
    color_wood_dark:  [0.42, 0.26, 0.12],
    normal_strength: 2.5,
};

Concrete

Smooth FBM surface relief with optional horizontal formwork-panel seams and scattered air-pocket pits.

use bevy_symbios_texture::concrete::ConcreteConfig;

let config = ConcreteConfig {
    seed: 17,
    scale: 5.0,
    octaves: 5,
    roughness: 0.45,          // overall bump amplitude [0, 1]
    formwork_lines: 4.0,      // number of horizontal panel seams [0 = none]
    formwork_depth: 0.12,     // groove depth of seams [0, 1]
    pit_density: 0.08,        // air-pocket density [0, 0.5]
    color_base: [0.55, 0.54, 0.52],
    color_pit:  [0.35, 0.34, 0.33],
    normal_strength: 2.5,
};

Metal

Brushed metal (anisotropic FBM scratches), standing-seam roof panels, hand-hammered dimples, or diamond tread plate — all with optional rust-patch weathering. For Hammered and DiamondPlate, scale sets the dimple / stud count across the tile.

use bevy_symbios_texture::metal::{MetalConfig, MetalStyle};

let config = MetalConfig {
    seed: 31,
    style: MetalStyle::Brushed, // or StandingSeam, Hammered, DiamondPlate
    scale: 6.0,
    seam_count: 6.0,      // StandingSeam: number of ridges across the tile
    seam_sharpness: 2.5,  // StandingSeam: 0.5 = sinusoidal, 4.0 = sharp
    brush_stretch: 8.0,   // Brushed: anisotropy (higher = longer horizontal scratches)
    roughness: 0.25,      // micro-roughness amplitude [0, 1]
    metallic: 0.85,       // metallic value for clean areas [0, 1]
    rust_level: 0.15,     // rust-patch coverage [0 = none, 1 = heavy]
    color_metal: [0.42, 0.44, 0.47],
    color_rust:  [0.42, 0.24, 0.12],
    normal_strength: 3.0,
};

Shingle

Overlapping roof shingles or tiles with configurable profile shape, moss growth, and staggered bonding.

use bevy_symbios_texture::shingle::ShingleConfig;

let config = ShingleConfig {
    seed: 42,
    scale: 5.0,           // number of shingle rows across the tile
    shape_profile: 0.5,   // 0.0 = square/flat, 1.0 = scalloped (half-circle cut)
    overlap: 0.45,        // fraction of each shingle hidden under the row above [0, 0.8]
    stagger: 0.5,         // horizontal stagger of alternate rows [0, 1]
    moss_level: 0.18,     // moss/algae growth on the lower exposed edge [0, 1]
    color_tile:  [0.40, 0.25, 0.18],
    color_grout: [0.18, 0.14, 0.12],
    normal_strength: 5.0,
};

Pavers

Square or flat-top hexagonal paving stones with grout joints, per-stone colour variance, and a rounded-box SDF bevel.

use bevy_symbios_texture::pavers::{PaversConfig, PaversLayout};

let config = PaversConfig {
    seed: 23,
    scale: 5.0,           // roughly the number of pavers across the tile
    aspect_ratio: 1.0,    // width-to-height ratio for Square layout (ignored for Hexagonal)
    grout_width: 0.08,    // grout gap as a fraction of stone size [0, 0.4]
    bevel: 0.5,           // corner bevel radius as a fraction of grout half-width [0, 1]
    cell_variance: 0.10,  // per-paver colour jitter [0, 1]
    roughness: 0.30,      // surface FBM micro-detail amplitude [0, 1]
    color_stone: [0.48, 0.44, 0.40],
    color_grout: [0.28, 0.27, 0.26],
    layout: PaversLayout::Square, // or PaversLayout::Hexagonal
    normal_strength: 3.5,
};

Stucco

High-frequency FBM bumps over a flat matte base — typical of sand-float or pebble-dash exterior render. Entirely matte with zero metallic response.

use bevy_symbios_texture::stucco::StuccoConfig;

let config = StuccoConfig {
    seed: 13,
    scale: 8.0,       // bump density (higher = finer texture)
    octaves: 6,
    roughness: 0.35,  // bump amplitude / surface relief depth [0, 1]
    color_base:   [0.92, 0.89, 0.84],
    color_shadow: [0.72, 0.70, 0.66],
    normal_strength: 2.0,
};

Ashlar

Irregular cut-stone masonry with per-block colour variance, chisel-edge darkening, and configurable mortar joints.

use bevy_symbios_texture::ashlar::AshlarConfig;

let config = AshlarConfig {
    seed: 13,
    rows: 4,              // number of stone courses (rows) [2, 8]
    cols: 4,              // base blocks per course [2, 6]; each row may vary ±1
    mortar_size: 0.04,    // mortar gap as a fraction of average cell size [0, 0.15]
    bevel: 0.4,           // corner bevel as fraction of mortar_size [0, 1]
    cell_variance: 0.18,  // per-block colour jitter [0, 1]
    chisel_depth: 0.4,    // darkening near each block border [0, 1]
    roughness: 0.45,      // FBM face micro-detail amplitude [0, 1]
    color_stone: [0.52, 0.50, 0.47],
    color_mortar: [0.72, 0.70, 0.65],
    normal_strength: 4.5,
};

Cobblestone

Voronoi cell decomposition producing domed, irregularly shaped stones separated by mud/dirt gaps.

use bevy_symbios_texture::cobblestone::CobblestoneConfig;

let config = CobblestoneConfig {
    seed: 7,
    scale: 6.0,           // approximate number of stones across the tile [3, 12]
    gap_width: 0.12,      // mud gap threshold as fraction of stone spacing [0.02, 0.25]
    cell_variance: 0.20,  // per-stone colour jitter [0, 1]
    roundness: 1.2,       // dome profile power [0.5, 2.0]; higher = flatter tops
    color_stone: [0.46, 0.43, 0.40],
    color_mud: [0.22, 0.18, 0.14],
    normal_strength: 5.0,
};

Marble

Domain-warped FBM noise passed through a sinusoidal vein function for polished marble or granite with thin dark veins on a light background.

use bevy_symbios_texture::marble::MarbleConfig;

let config = MarbleConfig {
    seed: 55,
    scale: 3.0,            // overall pattern scale [1, 8]
    octaves: 5,            // FBM octaves for the base layer [3, 8]
    warp_octaves: 3,       // FBM octaves for the warp layers [1, 6]
    warp_strength: 0.6,    // how much the veins meander [0, 1.5]
    vein_frequency: 3.0,   // period of sin() on warped FBM [1, 8]
    vein_sharpness: 2.0,   // exponent narrowing the veins [0.5, 6]
    roughness: 0.08,       // surface roughness [0, 0.3]; low for polished marble
    color_base: [0.92, 0.90, 0.87],
    color_vein: [0.42, 0.38, 0.34],
    normal_strength: 1.5,
};

Thatch

Dense fibrous roofing material with anisotropic straw fibres, lateral domain-warp wiggle, and layered bundle overlap shadows.

use bevy_symbios_texture::thatch::ThatchConfig;

let config = ThatchConfig {
    seed: 19,
    density: 12.0,         // fibre frequency along U [4, 24]
    anisotropy: 8.0,       // V frequency = density / anisotropy [4, 16]
    warp_strength: 0.15,   // lateral domain-warp wiggle [0, 0.5]
    layer_count: 8.0,      // straw-bundle overlap layers along V [4, 16]
    layer_shadow: 0.55,    // shadow depth at bundle bottom [0, 1]
    color_straw: [0.62, 0.54, 0.28],
    color_shadow: [0.22, 0.17, 0.09],
    normal_strength: 3.5,
};

Corrugated

Corrugated metal sheets with sine-wave ridges and valley-concentrated rust weathering.

use bevy_symbios_texture::corrugated::CorrugatedConfig;

let config = CorrugatedConfig {
    seed: 31,
    ridges: 8.0,           // number of corrugation ridges across U [3, 20]
    ridge_depth: 1.0,      // ridge profile amplitude [0.5, 2.0]
    roughness: 0.35,       // base surface roughness [0, 1]
    rust_level: 0.25,      // rust accumulation in valleys [0, 1]
    metallic: 0.85,        // metallic value [0, 1]
    color_metal: [0.72, 0.74, 0.76],
    color_rust: [0.55, 0.30, 0.12],
    normal_strength: 4.0,
};

Asphalt

Three-band toroidal FBM (macro staining, micro roughness, aggregate flecks) for tarmac / asphalt with exposed stone chips.

use bevy_symbios_texture::asphalt::AsphaltConfig;

let config = AsphaltConfig {
    seed: 88,
    scale: 4.0,              // base noise scale [2, 12]
    aggregate_density: 0.22, // exposed stone chip density [0.05, 0.4]
    aggregate_scale: 16.0,   // fleck noise frequency [8, 32]
    roughness: 0.90,         // overall surface roughness [0.7, 1.0]
    stain_level: 0.25,       // macro stain / oil variation [0, 1]
    color_base: [0.06, 0.06, 0.07],
    color_aggregate: [0.35, 0.33, 0.30],
    normal_strength: 2.5,
};

Sand

Wind-rippled sand: a directional sine ridge field phase-warped by FBM so crests meander and merge, plus grain micro-relief and thresholded bright flecks (exposed sparkling grains read as local smooth spots in the ORM).

use bevy_symbios_texture::sand::SandConfig;

let config = SandConfig {
    seed: 91,
    ripple_count: 10.0,    // crests across the tile [4, 24]
    ripple_warp: 0.6,      // crest meander strength [0, 1.5]
    grain_density: 0.12,   // bright-fleck density [0, 0.5]
    grain_scale: 24.0,     // grain noise frequency [8, 48]
    color_crest: [0.86, 0.74, 0.52],
    color_trough: [0.62, 0.50, 0.34],
    normal_strength: 2.5,
};

Snow

Wind-drifted snow: soft FBM relief with a cool shadow tint in the troughs and thresholded sparkle flecks — crystals that brighten the albedo and drop ORM roughness to near zero for specular glints.

use bevy_symbios_texture::snow::SnowConfig;

let config = SnowConfig {
    seed: 73,
    drift_scale: 2.5,      // drift relief scale [1, 6]
    drift_octaves: 4,      // FBM octaves [2, 6]
    sparkle_density: 0.08, // glinting-crystal density [0, 0.5]
    crust_roughness: 0.85, // base crust roughness [0.5, 1]
    color_snow: [0.93, 0.95, 0.99],
    color_shadow: [0.62, 0.70, 0.86],  // cool trough tint
    normal_strength: 1.8,
};

Ice

Polished lake ice: a near-mirror pale-blue base crossed by thin recessed crack veins (sinusoidal bands over FBM contours), with frost patches that whiten the colour and raise roughness toward matte.

use bevy_symbios_texture::ice::IceConfig;

let config = IceConfig {
    seed: 117,
    scale: 3.0,            // pattern scale [1, 8]
    crack_density: 4.0,    // vein frequency [1, 8]
    vein_sharpness: 7.0,   // crack narrowing exponent [2, 12]
    frost_level: 0.25,     // matte frost coverage [0, 1]
    color_ice: [0.72, 0.84, 0.94],
    color_crack: [0.30, 0.44, 0.62],
    normal_strength: 1.5,
};

Moss

A dense velvety moss carpet: broad FBM cushion hummocks overlaid with a fine filament-tip stipple, plus scattered patches bleached toward a dry straw tone. Shaded crevices read deep green while the cushion crowns catch a bright yellow-green.

use bevy_symbios_texture::moss::MossConfig;

let config = MossConfig {
    seed: 21,
    cushion_scale: 5.0,     // hummock scale (lower = broader mounds)
    cushion_octaves: 4,
    filament_scale: 34.0,   // filament-tip stipple frequency (higher = finer)
    filament_octaves: 3,
    filament_weight: 0.45,  // stipple blend weight [0, 1]
    color_deep: [0.03, 0.09, 0.03],  // shaded crevice colour
    color_tip: [0.26, 0.44, 0.10],   // cushion-crown colour
    color_dry: [0.38, 0.34, 0.14],   // bleached straw tone
    dry_patches: 0.25,      // share of the carpet bleached dry [0, 1]
    dry_scale: 2.5,         // dry-patch scale (lower = larger patches)
    cushion_depth: 0.6,     // mound vs stipple share of the height field [0, 1]
    normal_strength: 2.4,
};

Lichen

Crustose lichen colonies over bare rock: a thresholded FBM patch field with pale growing margins, a granular interior, and two species tints (sage grey-green and rusty orange) selected by a slower field, so a rock face shows several colonies rather than one flat wash. Uncolonised texels keep the rock substrate colour.

use bevy_symbios_texture::lichen::LichenConfig;

let config = LichenConfig {
    seed: 7,
    patch_scale: 3.0,       // colony field scale (lower = broader colonies)
    patch_octaves: 2,       // more octaves = more raggedly-lobed outlines
    coverage: 0.45,         // colonised fraction [0, 1]; 0 = bare rock
    rim_width: 0.06,        // pale growing-margin width [0, 0.4]; 0 = none
    species_scale: 1.8,     // species mix (lower = larger single-species areas)
    color_rock: [0.13, 0.13, 0.12],      // bare substrate
    color_lichen_a: [0.14, 0.17, 0.10],  // sage grey-green species
    color_lichen_b: [0.26, 0.13, 0.04],  // rusty orange species
    color_rim: [0.38, 0.40, 0.32],
    grain_scale: 40.0,      // interior grain frequency (higher = finer)
    grain_strength: 0.18,   // interior grain strength [0, 1]
    relief: 0.5,            // how proud the crust stands of the rock [0, 1]
    normal_strength: 1.8,
};

Cactus Skin

A tileable succulent hide: vertical accordion ribs, a periodic lattice of felted areoles seated on the rib crests, and pale spines radiating from each areole. Ribs and areoles are integer-periodic, so the tile wraps seamlessly around an L-system cactus stem.

use bevy_symbios_texture::cactus::CactusSkinConfig;

let config = CactusSkinConfig {
    seed: 0,
    rib_count: 8,           // vertical ribs around the tile [3, 40]
    areole_rows: 9,         // areole rows up the tile [2, 40]
    rib_depth: 0.85,        // accordion-pleat relief [0, 1]
    rib_sharpness: 0.85,    // crest sharpness [0.3, 3]
    color_skin: [0.22, 0.42, 0.27],    // waxy ridge colour
    color_valley: [0.07, 0.17, 0.11],  // shaded pleat colour
    color_areole: [0.55, 0.50, 0.40],  // felt cushions
    color_spine: [0.86, 0.82, 0.66],
    areole_size: 0.022,     // felt radius in UV units [0.005, 0.08]
    spine_reach: 3.2,       // spine length as multiple of areole_size [1, 6]
    spine_count: 8,         // spines per areole [0, 24]
    waxiness: 0.55,         // gloss (higher = lower roughness) [0, 1]
    normal_strength: 1.4,
};

Wainscoting

Wood-panel wainscoting with recessed panel faces, rail/stile framing, and anisotropic grain FBM with domain warp.

use bevy_symbios_texture::wainscoting::WainscotingConfig;

let config = WainscotingConfig {
    seed: 37,
    panels_x: 1,           // horizontal panel divisions [1, 4]
    panels_y: 2,           // vertical panel divisions [1, 4]
    frame_width: 0.20,     // rail/stile width as fraction of cell [0.05, 0.35]
    panel_inset: 0.06,     // panel recess depth [0, 0.15]
    grain_scale: 10.0,     // wood grain spatial frequency [4, 24]
    grain_warp: 0.30,      // grain domain-warp strength [0, 0.8]
    color_wood_light: [0.65, 0.44, 0.20],
    color_wood_dark: [0.28, 0.16, 0.07],
    normal_strength: 4.0,
};

Fabric

Plain-weave cloth: perpendicular warp/weft threads as half-cylinder profiles, over/under crossing relief, fibre fuzz, and yarn-mottle tinting. Match the two colours for solid cloth or contrast them for two-tone weaves.

use bevy_symbios_texture::fabric::FabricConfig;

let config = FabricConfig {
    seed: 29,
    thread_count: 24.0,    // threads per tile edge [8, 64]
    thread_width: 0.85,    // thread width as cell fraction [0.3, 0.98]
    weave_contrast: 0.6,   // over/under relief depth [0, 1]
    fuzz: 0.35,            // fibre fuzz strength [0, 1]
    color_warp: [0.55, 0.36, 0.24],  // vertical threads
    color_weft: [0.62, 0.44, 0.30],  // horizontal threads
    normal_strength: 3.0,
};

Encaustic

Decorative ceramic tiles with glazed surfaces in configurable geometric patterns (checkerboard, octagon, diamond).

use bevy_symbios_texture::encaustic::{EncausticConfig, EncausticPattern};

let config = EncausticConfig {
    seed: 47,
    scale: 5.0,            // tile cells across the texture [2, 10]
    pattern: EncausticPattern::Octagon, // or Checkerboard, Diamond
    grout_width: 0.06,     // grout line width as fraction of cell [0.02, 0.15]
    glaze_roughness: 0.04, // glaze surface waviness [0, 0.1]
    color_a: [0.72, 0.38, 0.22],  // primary tile colour
    color_b: [0.22, 0.35, 0.65],  // secondary tile colour
    color_grout: [0.82, 0.80, 0.75],
    normal_strength: 3.0,
};

Cracked earth

Dried mud plates with curled rims, separated by cracks of constant width — the cheaper F2 − F1 mask widens with the cell, giving large plates canyons and small ones hairlines.

use bevy_symbios_texture::cracked_earth::CrackedEarthConfig;

let config = CrackedEarthConfig {
    seed: 11,
    scale: 7.0,            // plates across the tile [2, 20]
    jitter: 0.85,          // plate irregularity [0, 1]
    crack_width: 0.010,    // crack width in UV units (fraction of the tile)
    crack_depth: 0.55,     // how far cracks cut into the height field
    curl: 0.22,            // how far plate rims lift as they dry
    curl_reach: 0.035,     // how far back from a crack the curl reaches (UV)
    plate_variance: 0.10,  // per-plate tint spread [0, 1]
    grain_scale: 26.0,
    grain_strength: 0.12,
    color_plate: [0.44, 0.33, 0.22],
    color_crack: [0.13, 0.09, 0.06],
    normal_strength: 3.0,
};

Gravel

Packed graded aggregate over dust. Each stone is sized against the distance to its neighbour rather than a fixed radius, so it fills its own cell; the metric decides whether stones read as water-rounded shingle or crushed rock.

use bevy_symbios_texture::gravel::GravelConfig;
use bevy_symbios_texture::noise::CellMetric;

let config = GravelConfig {
    seed: 23,
    scale: 20.0,           // stones across the tile (≈20 roadbase, ≈8 ballast)
    metric: CellMetric::Euclidean, // or Manhattan / Chebyshev for angular stone
    jitter: 0.9,
    roundness: 1.6,        // dome profile exponent
    size_variance: 0.45,   // grading spread [0, 1]
    cell_variance: 0.13,   // per-stone tint spread [0, 1]
    fines_level: 0.55,     // dust filling the gaps [0, 1]
    grain_scale: 60.0,
    color_stone: [0.40, 0.38, 0.35],
    color_dark: [0.17, 0.16, 0.15],
    color_fines: [0.26, 0.24, 0.21],
    normal_strength: 2.5,
};

Forest floor

Fallen leaf litter over humus. Leaves are stamped as discrete objects and layered with a per-leaf depth so they interleave — noise-based "litter" has no edges you can follow around a single leaf.

use bevy_symbios_texture::forest_floor::ForestFloorConfig;

let config = ForestFloorConfig {
    seed: 31,
    litter_scale: 7.0,     // leaves across the coarsest layer
    layers: 3,             // stacked litter layers [1, 4]
    coverage: 0.85,        // fraction of cells carrying a leaf [0, 1]
    leaf_length: 1.15,     // multiple of the lattice cell
    leaf_width: 0.5,       // multiple of the leaf length
    leaf_thickness: 0.35,
    midrib: 0.22,          // darkening of the leaf spine [0, 1]
    humus_scale: 14.0,
    color_humus: [0.09, 0.07, 0.05],
    color_leaf: [0.46, 0.31, 0.12],
    color_leaf_old: [0.22, 0.16, 0.09],
    normal_strength: 2.2,
};

Enamel

A smooth fired glaze, optionally crazed. Its character is the absence of directional structure, which is what a brushed-metal finish cannot fake.

use bevy_symbios_texture::enamel::EnamelConfig;

let config = EnamelConfig {
    seed: 17,
    color: [0.62, 0.20, 0.16],       // fired glaze
    color_body: [0.80, 0.78, 0.74],  // unglazed body, seen through the craze
    gloss_roughness: 0.18,           // above ~0.4 reads as matt paint
    metallic: 0.0,
    crackle: 0.0,                    // 0 leaves the coat perfectly clear
    crackle_scale: 26.0,
    crackle_width: 0.0025,           // UV units, so the web stays hairline
    orange_peel: 0.11,
    orange_peel_scale: 34.0,
    ..Default::default()             // `weathering`, `normal_strength`
};

Obsidian

Near-black polished glass carrying warped flow banding. Keep band_warp well under half a turn: past that the bend exceeds half a band period and the bands fold back through one another instead of flowing.

use bevy_symbios_texture::obsidian::ObsidianConfig;

let config = ObsidianConfig {
    seed: 29,
    color: [0.035, 0.032, 0.045],
    color_sheen: [0.16, 0.15, 0.22],
    band_cycles_u: 5.0,    // whole cycles; the field only tiles at integers
    band_cycles_v: 2.0,
    band_warp: 0.26,       // turns of phase — keep well under 0.5
    band_warp_scale: 1.6,
    band_sharpness: 0.35,
    band_contrast: 0.8,
    gloss_roughness: 0.12,
    metallic: 0.6,
    relief: 0.05,          // polished glass is nearly flat
    ..Default::default()
};

Chitin

Carapace plating. Built on a soft minimum so plates swell into one another rather than meeting at the crease a hard minimum gives; the suture is then drawn back in deliberately.

use bevy_symbios_texture::chitin::ChitinConfig;

let config = ChitinConfig {
    seed: 37,
    scale: 6.0,            // plates across the tile
    jitter: 0.75,
    softness: 24.0,        // low merges plates, high approaches cut stone
    plate_fill: 0.9,       // how far a plate swells toward its neighbour
    plate_relief: 0.55,
    seam_width: 0.006,     // UV units
    seam_depth: 0.75,
    iridescence: 0.22,     // per-plate sheen, applied as a multiplier
    color: [0.20, 0.34, 0.20],
    color_deep: [0.05, 0.09, 0.07],
    gloss_roughness: 0.28,
    metallic: 0.45,
    pit_scale: 40.0,
    ..Default::default()
};

Solar panel

Photovoltaic wafers behind glass. The wiring is laid in cell-local space so it runs continuously across cells while the silicon does not — that continuity is what reads as a panel rather than a tiled floor.

use bevy_symbios_texture::solar_panel::SolarPanelConfig;

let config = SolarPanelConfig {
    seed: 41,
    cells_x: 4.0,
    cells_y: 4.0,
    cell_gap: 0.06,        // fraction of a cell
    corner_cut: 0.14,      // wafers are cut from a round ingot
    busbars: 3.0,
    busbar_width: 0.014,   // coverage is width × count — keep both small
    fingers: 18.0,
    finger_width: 0.003,
    color_cell: [0.020, 0.030, 0.075],
    color_backing: [0.72, 0.72, 0.70],
    color_wire: [0.62, 0.63, 0.65],
    cell_variance: 0.18,   // multiplicative, so near-black silicon stays dark
    crystal_mottle: 0.30,
    crystal_scale: 22.0,
    glass_roughness: 0.10,
    ..Default::default()
};

Parquet

Short boards laid in a repeating figure. Herringbone is not a grid of blocks: a cell's board direction falls out of (i − j) mod 2·aspect, and because that key shifts along both axes the runs interlock into the zig-zag.

use bevy_symbios_texture::parquet::{ParquetConfig, ParquetLayout};

let config = ParquetConfig {
    seed: 43,
    layout: ParquetLayout::Herringbone, // or Basket, Brick
    scale: 8.0,            // board slots across the tile
    aspect: 4.0,           // board length as a multiple of its width
    joint_width: 0.05,
    joint_depth: 0.5,
    grain_lines: 7.0,
    grain_contrast: 0.35,
    grain_warp: 0.22,
    board_variance: 0.13,
    color_wood: [0.36, 0.20, 0.09],
    color_grain: [0.19, 0.10, 0.04],
    color_joint: [0.07, 0.04, 0.02],
    gloss_roughness: 0.32,
    ..Default::default()
};

Truchet

Hashed quarter-arcs that meet at every tile edge whichever way the neighbour fell, so a grid of coin flips reads as one routed network. The emissive channel is only collected when emissive_intensity is above zero.

use bevy_symbios_texture::truchet::TruchetConfig;

let config = TruchetConfig {
    seed: 47,
    scale: 6.0,            // tiles across the panel
    trace_width: 0.09,     // fraction of a tile
    trace_relief: 0.6,
    density: 0.85,         // below 1 the network breaks into runs and stubs
    color_panel: [0.035, 0.055, 0.050],
    color_trace: [0.16, 0.42, 0.34],
    color_glow: [0.10, 0.85, 0.60],
    emissive_intensity: 1.0, // 0 skips the emissive buffer entirely
    panel_roughness: 0.72,
    trace_roughness: 0.30,
    trace_metallic: 0.65,
    mottle_scale: 18.0,
    ..Default::default()
};

Weathering (shared)

Every generator depicting a built or dressed surface carries an optional weathering block that ages it after generation: ashlar, asphalt, brick, chitin, cobblestone, concrete, corrugated, enamel, encaustic, fabric, marble, metal, obsidian, parquet, pavers, rock, shingle, solar panel, stucco, thatch, truchet and wainscoting.

Natural surfaces are deliberately excluded — sand, snow, moss, bark and their kin already read as weathered, and a second ageing pass over them fights the generator rather than helping it. plank is the one gap: it still hand-rolls its pixel loop instead of using the surface driver, so it cannot be handed a config yet. Every layer defaults to an amount of zero, so an untouched block leaves the material exactly as the generator drew it and costs nothing to bake.

Layers are applied in the order material actually ages: edge wear rubs raised arrises back to the substrate, corrosion creeps out of crevices (adding its own crust relief), grime settles into recesses, and runoff streaks draw down from ledges.

use bevy_symbios_texture::rock::RockConfig;
use bevy_symbios_texture::weathering::{Streaks, WeatheringConfig};

let config = RockConfig {
    weathering: WeatheringConfig {
        seed: 4,
        streaks: Streaks {
            amount: 0.9,
            density: 0.5,  // fraction of candidate ledges that actually run
            length: 0.35,  // fraction of the tile height, so it survives a
                           // change of bake resolution
            ..Default::default()
        },
        ..Default::default()
    },
    ..Default::default()
};

Alpha-masked cards

Card generators produce an RGBA8 texture where albedo.alpha encodes the silhouette (0 = fully transparent, 255 = fully opaque). Upload with map_to_images_card so the sampler does not tile and the alpha silhouette does not bleed at edges.

Leaf

A discrete leaf silhouette with procedural venation: midrib, secondary veins, a Perlin venule (tertiary vein) network, Worley capillaries, and optional lobed margins.

use bevy_symbios_texture::leaf::LeafConfig;

let config = LeafConfig {
    seed: 0,
    color_base: [0.12, 0.19, 0.11],  // interior colour, linear RGB
    color_edge: [0.35, 0.28, 0.05],  // edge / autumn tinge
    serration_strength: 0.12,         // tooth depth [0, ~0.35]
    vein_angle: 2.5,                  // secondary vein acuteness
    micro_detail: 0.3,                // Worley capillary blend weight
    normal_strength: 1.0,
    lobe_count: 4.0,                  // 0 = smooth; >0 = lobed margins
    lobe_depth: 0.23,
    lobe_sharpness: 1.0,
    petiole_length: 0.12,             // fraction of V reserved for the stalk
    petiole_width: 0.022,
    midrib_width: 0.12,
    vein_count: 6.0,
    venule_strength: 0.50,
};

LeafSampler can also be used directly for per-pixel evaluation without going through the full generator (e.g., inside a twig compositor):

use bevy_symbios_texture::leaf::{LeafConfig, LeafSampler};

let sampler = LeafSampler::new(LeafConfig::default());
if let Some(sample) = sampler.sample(0.5, 0.4) {
    // sample.height, sample.color, sample.roughness
}

Twig

A composite foliage card: a tapered, organically curved stem carrying multiple leaf cards. Supports two phyllotaxis modes:

• Monopodial (sympodial: false) — opposite leaf pairs on a straight axis with a terminal leaf at the apex.
• Sympodial (sympodial: true) — alternate leaves on a zigzag axis, with a terminal leaf at the apex.

use std::f64::consts::FRAC_PI_2;
use bevy_symbios_texture::twig::TwigConfig;
use bevy_symbios_texture::leaf::LeafConfig;

let config = TwigConfig {
    leaf: LeafConfig::default(),
    stem_color: [0.18, 0.08, 0.06],
    stem_half_width: 0.021,
    leaf_pairs: 4,
    leaf_angle: FRAC_PI_2 - 0.35,  // ~70° from stem axis
    leaf_scale: 0.38,
    stem_curve: 0.015,
    sympodial: true,
};

Window

An SDF-based window card with configurable frame, mullions/muntins, and per-pane glass. The alpha channel is transparent outside the frame and semi-transparent over glass panes.

use bevy_symbios_texture::window::WindowConfig;

let config = WindowConfig {
    seed: 42,
    frame_width: 0.08,       // frame width as a fraction of the card [0, 0.4]
    panes_x: 2,              // number of panes horizontally
    panes_y: 3,              // number of panes vertically
    mullion_thickness: 0.025, // mullion/muntin thickness as a fraction of the glass area
    corner_radius: 0.02,     // inner glass-opening corner rounding [0, 0.4]
    glass_opacity: 0.30,     // glass alpha [0 = clear, 1 = frosted/opaque]
    grime_level: 0.15,       // grime/dirt noise on glass [0, 1]
    color_frame: [0.85, 0.82, 0.78],
    normal_strength: 3.0,
};

Stained Glass

Voronoi-based stained-glass panel with lead came borders and semi-transparent coloured glass panes. Glass alpha is 180 (semi-transparent); lead is 255 (fully opaque).

use bevy_symbios_texture::stained_glass::StainedGlassConfig;

let config = StainedGlassConfig {
    seed: 63,
    cell_count: 12,        // approximate number of glass cells [5, 25]
    lead_width: 0.05,      // lead came width as fraction of cell spacing [0.02, 0.12]
    saturation: 0.85,      // glass colour saturation [0.5, 1.0]
    glass_roughness: 0.06, // glass surface waviness [0, 0.15]
    grime_level: 0.12,     // grime/dirt accumulation on glass [0, 0.5]
    normal_strength: 2.5,
};

Iron Grille

Rectangular or round-bar iron grille / portcullis with configurable bar count and joint-concentrated rust weathering.

use bevy_symbios_texture::iron_grille::IronGrilleConfig;

let config = IronGrilleConfig {
    seed: 71,
    bars_x: 4,             // vertical bars [2, 10]
    bars_y: 6,             // horizontal bars [2, 10]
    bar_width: 0.04,       // bar half-width as fraction of card [0.02, 0.20]
    round_bars: true,      // true = cylindrical cross-section, false = rectangular
    rust_level: 0.30,      // rust at joints [0, 1]
    color_iron: [0.14, 0.13, 0.13],
    color_rust: [0.42, 0.22, 0.08],
    normal_strength: 3.5,
};

Chain-Link

A woven diamond wire mesh: two cylindrical wire families at ±45° with over/under crossing relief and rust pooling at the joints. Transparent between the wires.

use bevy_symbios_texture::chain_link::ChainLinkConfig;

let config = ChainLinkConfig {
    seed: 83,
    cell_count: 8.0,       // diamond cells across the card [4, 16]
    wire_radius: 0.07,     // wire radius in lattice units [0.02, 0.2]
    weave_depth: 0.6,      // over/under relief [0, 1]
    rust_level: 0.2,       // crossing rust [0, 1]
    color_wire: [0.62, 0.64, 0.66],
    color_rust: [0.45, 0.24, 0.10],
    normal_strength: 3.0,
};

Log End

The sawn end of a log: irregular round silhouette, FBM-wobbled concentric growth rings, optional radial drying cracks, and a streaked bark rim. Completes the wood set alongside bark and plank.

use bevy_symbios_texture::log_end::LogEndConfig;

let config = LogEndConfig {
    seed: 7,
    ring_count: 14.0,      // growth rings [4, 30]
    ring_warp: 0.35,       // ring wobble [0, 1]
    ring_contrast: 1.8,    // latewood band sharpness [0.5, 4]
    crack_count: 5.0,      // radial drying cracks [0, 12]; 0 = none
    bark_width: 0.07,      // bark rim thickness [0.02, 0.2]
    color_early: [0.78, 0.62, 0.42],
    color_late: [0.48, 0.33, 0.18],
    color_bark: [0.30, 0.20, 0.12],
    normal_strength: 2.5,
};

Lava

Cooling lava: dark basalt plates from a toroidal Voronoi decomposition, separated by molten cracks that drive the emissive map — the glow colour ramps with crack depth and is written to StandardMaterial::emissive_texture. The material flow auto-enables a white emissive factor when a glow map is present, so lava glows out of the box; set emission_color / emission_strength only to tint or brighten it.

use bevy_symbios_texture::lava::LavaConfig;

let config = LavaConfig {
    seed: 666,
    plate_scale: 6.0,        // crust plates across the tile [3, 12]
    crack_width: 0.14,       // molten-crack width [0.02, 0.3]
    glow_falloff: 1.6,       // glow concentration exponent [0.5, 4]
    color_crust: [0.08, 0.07, 0.07],
    color_glow: [1.0, 0.45, 0.06],
    emissive_intensity: 1.0, // glow multiplier [0, 4]
    normal_strength: 4.0,
};

Sprite atlases

The atlas family produces alpha-silhouette cards for billboards. Unlike the single-image cards above, each generator here can bake a variant_rows × variant_cols atlas in a single image: every cell renders the same config with a per-cell derived seed, so a particle system using random atlas frames gets per-particle shape variety from one texture bake. Atlas dimensions are clamped to 1..=16 per axis; 1 × 1 bakes a single card.

The family spans two idioms. The particle sprites (soft disc, spark, snowflake, puff, ring, petal, shard, flame) use soft fractional alpha — glows and mist fade out smoothly. The foliage billboards (leaf sprite, grass tuft, frond, reed, needle, broadleaf) cut hard silhouettes like the foliage cards and default to 1 × 1 — a single vegetation card — with the atlas as an opt-in for per-instance variety.

Shared scaffolding (the SpriteCell trait, the generate_atlas driver, and the deterministic CellRng parameter stream) lives in the sprite module. Upload with map_to_images_card; sprites never tile.

use bevy_symbios_texture::{
    generator::{TextureGenerator, map_to_images_card},
    spark::{SparkConfig, SparkGenerator},
};

let map = SparkGenerator::new(SparkConfig {
    variant_rows: 4,       // 4 × 4 atlas = 16 spark variants in one bake
    variant_cols: 4,
    ..SparkConfig::default()
})
.generate(512, 512)
.expect("valid dimensions");

let handles = map_to_images_card(map, &mut images);

Soft Disc

Radial-falloff disc with a solid core and tunable halo — the workhorse particle sprite: fireflies, embers, mist motes, bokeh glints, additive glows.

use bevy_symbios_texture::soft_disc::SoftDiscConfig;

let config = SoftDiscConfig {
    seed: 0,
    variant_rows: 1,       // atlas rows [1, 16]
    variant_cols: 1,       // atlas columns [1, 16]
    color_core: [1.0, 0.98, 0.9],   // centre colour, linear RGB
    color_halo: [1.0, 0.72, 0.25],  // outer halo colour
    core_radius: 0.15,     // fully-opaque core radius [0, 0.9]
    falloff: 2.5,          // halo falloff exponent [0.3, 8]; higher = tighter glow
    ellipticity: 0.0,      // max per-variant elongation [0, 0.6]; 0 = always round
    scale_jitter: 0.15,    // per-variant shrink fraction [0, 0.5]
    normal_strength: 1.0,
};

Spark

N-pointed streak burst: a bright core with radial arms fading toward their tips. Embers, glints, impact sparks, magic sparkles.

use bevy_symbios_texture::spark::SparkConfig;

let config = SparkConfig {
    seed: 0,
    variant_rows: 2,
    variant_cols: 2,
    points: 4,             // number of streak arms [2, 12]
    color_core: [1.0, 0.95, 0.8],
    color_tip: [1.0, 0.45, 0.1],
    core_radius: 0.12,     // solid central glow radius [0.02, 0.5]
    arm_sharpness: 3.0,    // angular tightness [0.5, 10]; higher = needle-thin
    falloff: 1.8,          // radial fade exponent along each arm [0.5, 6]
    length_jitter: 0.3,    // per-arm length jitter [0, 0.8]
    normal_strength: 1.0,
};

Snowflake

Dendritic flake with N-fold symmetry: a central plate, one main arm per sector, and paired side branches. Per-variant jitter is where the "no two snowflakes alike" character comes from.

use bevy_symbios_texture::snowflake::SnowflakeConfig;

let config = SnowflakeConfig {
    seed: 0,
    variant_rows: 2,
    variant_cols: 2,
    arms: 6,               // symmetry order [3, 8]; real snow is hexagonal
    color: [0.92, 0.96, 1.0],
    core_radius: 0.12,     // central plate radius [0, 0.4]
    arm_width: 0.045,      // main-arm half-width at the centre [0.01, 0.12]
    branch_pairs: 3,       // side-branch pairs per arm [0, 5]
    branch_angle: 1.05,    // branch angle, radians [0.3, 1.4]; ~60° is realistic
    branch_scale: 0.45,    // branch length vs remaining arm length [0.1, 1]
    softness: 0.02,        // anti-aliasing edge width [0.005, 0.08]
    normal_strength: 1.5,
};

Puff

Billowy blob of domain-warped fractal noise masked by a soft radial falloff. Dust motes, smoke, fog banks, sea mist.

use bevy_symbios_texture::puff::PuffConfig;

let config = PuffConfig {
    seed: 0,
    variant_rows: 2,
    variant_cols: 2,
    color_base: [0.86, 0.86, 0.9],    // lit colour
    color_shadow: [0.52, 0.52, 0.58], // noise-trough colour
    noise_scale: 3.0,      // noise frequency across a cell [1, 8]
    octaves: 4,            // fractal octave count [1, 8]
    warp: 0.45,            // domain-warp strength [0, 1.5]; billows the silhouette
    density: 0.9,          // overall alpha multiplier [0, 1]
    edge_falloff: 2.0,     // radial mask exponent [0.5, 6]; higher = rounder puff
    contrast: 1.3,         // noise remap exponent [0.5, 4]; higher = wispier
    normal_strength: 1.0,
};

Ring

Soft annulus with optional angular waviness: shockwaves, water-drop ripples, magic circles, halos.

use bevy_symbios_texture::ring::RingConfig;

let config = RingConfig {
    seed: 0,
    variant_rows: 1,
    variant_cols: 1,
    color: [0.85, 0.93, 1.0],
    radius: 0.6,           // centreline radius [0.1, 0.9]
    thickness: 0.12,       // annulus half-thickness [0.01, 0.5]
    falloff: 2.0,          // cross-section falloff exponent [0.5, 6]
    waviness: 0.0,         // angular radius modulation [0, 0.3]; 0 = perfect circle
    wave_count: 6,         // waviness lobes around the ring [2, 16]
    radius_jitter: 0.1,    // per-variant radius jitter [0, 0.4]
    normal_strength: 1.0,
};

Petal

A single flower petal: an obovate blade with a soft throat-to-edge gradient and an optional notched tip. Petal-fall particles, blossom decals, or — at 1 × 1 — a building block for procedural flowers.

use bevy_symbios_texture::petal::PetalConfig;

let config = PetalConfig {
    seed: 0,
    variant_rows: 2,
    variant_cols: 2,
    color_base: [0.98, 0.72, 0.82],   // main blade colour
    color_edge: [0.93, 0.5, 0.66],    // silhouette-edge colour
    color_throat: [0.99, 0.88, 0.55], // attachment-point (nectar guide) tint
    length: 0.92,          // petal length as fraction of the cell [0.4, 1]
    width: 0.6,            // max blade width [0.15, 0.95]
    peak: 0.65,            // position of max width from the throat [0.3, 0.9]
    tip_notch: 0.08,       // tip notch radius [0, 0.25]; 0 = smooth tip
    curl: 0.4,             // lateral shading strength [0, 1]; fakes curl
    asymmetry: 0.15,       // max per-variant axis skew [0, 0.4]
    normal_strength: 1.5,
};

Shard

Irregular rock-chip / debris-flake silhouette: a jittered polygon with a darkened rim and noise-grained interior. Impact debris, crumbling masonry, shattered ice, kicked-up gravel.

use bevy_symbios_texture::shard::ShardConfig;

let config = ShardConfig {
    seed: 0,
    variant_rows: 2,
    variant_cols: 2,
    color_base: [0.46, 0.43, 0.4],  // interior colour
    color_edge: [0.24, 0.22, 0.21], // fractured-rim colour
    sides: 5,              // polygon vertex count [3, 9]
    irregularity: 0.45,    // vertex jitter [0, 0.9]; 0 = regular polygon
    edge_band: 0.18,       // darkened-rim width as fraction of radius [0.02, 0.5]
    grain: 0.35,           // interior fractal-grain strength [0, 1]
    normal_strength: 2.5,
};

Flame

A single tongue of fire: a teardrop envelope displaced by fractal turbulence that grows toward the tip, with a core→mid→tip colour ramp. Per-variant cells jitter lean, elongation, and turbulence phase, so random atlas frames read as flicker. Pairs well with additive blending.

use bevy_symbios_texture::flame::FlameConfig;

let config = FlameConfig {
    seed: 0,
    variant_rows: 2,       // atlas rows [1, 16]
    variant_cols: 2,       // atlas columns [1, 16]
    elongation: 1.6,       // vertical stretch [1, 3]; taller = lazier wisp
    turbulence: 0.55,      // tip displacement strength [0, 1.5]
    lean_jitter: 0.25,     // max per-variant sideways lean [0, 0.5]
    falloff: 1.6,          // envelope fade exponent [0.5, 4]
    color_core: [1.0, 0.97, 0.78],  // hot base
    color_mid: [1.0, 0.55, 0.10],
    color_tip: [0.85, 0.16, 0.02],  // cool fringe
    normal_strength: 1.0,
};

Flower

A radially composed blossom: petal blades (the petal sampler re-aimed outward) under a domed, stamen-dotted centre disc — the sprite counterpart of how twig composites leaves. Every petal in every variant draws its own jitter stream.

use bevy_symbios_texture::flower::FlowerConfig;
use bevy_symbios_texture::petal::PetalConfig;

let config = FlowerConfig {
    seed: 0,
    variant_rows: 2,       // atlas rows [1, 16]
    variant_cols: 2,       // atlas columns [1, 16]
    petal: PetalConfig::default(), // shared blade appearance
    petal_count: 6,        // blades [4, 12]
    center_radius: 0.14,   // centre disc radius [0.05, 0.3]
    center_color: [0.96, 0.78, 0.25],
    dot_density: 0.5,      // stamen dots [0, 1]
    normal_strength: 1.5,
};

Leaf Sprite

The atlas counterpart of the single-leaf foliage card: every cell bakes a per-cell-seeded leaf variant with bounded jitter on serration, lobes, vein count, and a green-preserving colour tint. Falling-foliage particle systems get per-particle leaf variety from one bake.

use bevy_symbios_texture::leaf::LeafConfig;
use bevy_symbios_texture::leaf_sprite::LeafSpriteConfig;

let config = LeafSpriteConfig {
    seed: 0,
    variant_rows: 2,       // atlas rows [1, 16]
    variant_cols: 2,       // atlas columns [1, 16]
    leaf: LeafConfig::default(), // base leaf appearance for every cell
    shape_jitter: 0.5,     // silhouette jitter [0, 1]
    tint_jitter: 0.25,     // colour tint jitter [0, 1]
};

Grass Tuft

A clump of curved, tip-tapered grass blades fanning from a common root line at the bottom edge — the workhorse ground-cover billboard. Blades jitter height, lean, curvature, width, and dryness per variant.

use bevy_symbios_texture::grass::GrassTuftConfig;

let config = GrassTuftConfig {
    seed: 0,
    variant_rows: 1,       // atlas rows [1, 16]; 1 × 1 bakes a single tuft
    variant_cols: 1,
    blade_count: 9,        // blades per tuft [1, 24]
    color_base: [0.11, 0.17, 0.06],  // shaded root colour
    color_tip: [0.36, 0.46, 0.14],   // bright tip colour
    color_dry: [0.46, 0.39, 0.15],   // dry/dead blade tone
    blade_width: 0.05,     // root half-width as cell fraction [0.01, 0.12]
    blade_taper: 1.3,      // tip taper exponent [0.5, 4]
    height_min: 0.55,      // shortest blade height [0.2, 1]
    height_max: 0.96,      // tallest blade height [0.2, 1]
    fan_spread: 0.34,      // lateral tip splay [0, 0.5]
    curve: 0.14,           // outward blade arc toward the tip [0, 0.5]
    base_spread: 0.16,     // horizontal root spread [0, 0.4]
    dry_fraction: 0.22,    // share of dry blades [0, 1]
    normal_strength: 1.2,
};

Reed

A shoreline reed / cattail clump: tall, near-vertical strap leaves rising from a common waterline base, with an optional share of stalks topped by the cattail's brown catkin spike. Far taller and straighter than the grass tuft.

use bevy_symbios_texture::reed::ReedConfig;

let config = ReedConfig {
    seed: 0,
    variant_rows: 1,       // atlas rows [1, 16]
    variant_cols: 1,
    blade_count: 6,        // leaves per clump [1, 12]
    color_base: [0.10, 0.16, 0.06],
    color_tip: [0.38, 0.44, 0.16],
    color_catkin: [0.24, 0.13, 0.05],  // seed-head colour
    blade_width: 0.022,    // base half-width as cell fraction [0.008, 0.08]
    height_min: 0.62,      // shortest leaf height [0.3, 1]
    height_max: 0.98,      // tallest leaf height [0.3, 1]
    lean: 0.09,            // lateral tip lean [0, 0.3]; reeds stand straight
    tip_fraction: 0.28,    // leaf-length fraction that tapers [0.05, 0.8]
    catkin_share: 0.4,     // stalks bearing a catkin [0, 1]
    catkin_length: 0.2,    // catkin length as cell fraction [0, 0.4]
    catkin_width: 0.022,   // catkin half-width [0.005, 0.06]
    normal_strength: 1.2,
};

Needle

A conifer needle-cluster shoot — the conifer counterpart of the broadleaf twig card. Paired needles splay outward and forward from a woody axis, shortening toward the tip. A wide needle_angle with long needles reads as pine, a narrow angle with short needles as spruce, a high pair_count with minimal taper as fir.

use bevy_symbios_texture::needle::NeedleConfig;

let config = NeedleConfig {
    seed: 0,
    variant_rows: 1,       // atlas rows [1, 16]
    variant_cols: 1,
    pair_count: 11,        // needle pairs along the shoot [1, 24]
    color_base: [0.05, 0.13, 0.07],
    color_tip: [0.16, 0.31, 0.14],
    color_shoot: [0.21, 0.13, 0.07],  // woody axis colour
    needle_angle: 42.0,    // splay from the shoot axis, degrees [5, 85]
    needle_length: 0.3,    // needle length as cell fraction [0.05, 0.6]
    needle_width: 0.009,   // needle half-width [0.002, 0.03]
    length_taper: 0.55,    // shortening toward the shoot tip [0, 1]
    shoot_length: 0.9,     // shoot length as cell fraction [0.2, 1]
    shoot_width: 0.009,    // shoot half-width [0.002, 0.04]
    normal_strength: 1.2,
};

Frond

A single leaflet (pinna) of a pinnate frond: a narrow lanceolate strap with a strong central midrib and shallow pinnate veins. One depth knob spans an entire (palm-leaflet) margin to the lobed pinnule of a fern — the drop-in leaflet card for an L-system palm or fern whose rachis geometry is drawn by the grammar.

use bevy_symbios_texture::frond::FrondConfig;

let config = FrondConfig {
    seed: 0,
    variant_rows: 1,       // atlas rows [1, 16]
    variant_cols: 1,
    color_base: [0.11, 0.30, 0.09],
    color_edge: [0.22, 0.42, 0.13],  // margin / tip colour
    width: 0.13,           // max half-width as cell fraction [0.04, 0.30]
    tip_taper: 1.4,        // tip acuteness [0.4, 3]
    midrib_width: 0.16,    // midrib ridge width as local half-width fraction
    vein_count: 9.0,       // pinnate secondary vein pairs
    lobe_count: 0.0,       // margin lobes per side; 0 = entire margin
    lobe_depth: 0.0,       // lobe cut depth [0, 0.6]; 0 = smooth palm leaflet
    normal_strength: 1.3,
};

Broadleaf

A palmate broadleaf built in polar coordinates about its petiole attachment: a radius function with lobe_count peaks carves the classic maple / sycamore / ivy silhouettes, with main veins radiating to each lobe tip and an optional cordate (heart) base notch. lobe_count: 1.0 with a shallow depth yields a plain ovate blade, so one generator covers both the palmate and simple-broadleaf families — a different leaf form from the pinnate, midrib-based leaf card.

use bevy_symbios_texture::broadleaf::BroadleafConfig;

let config = BroadleafConfig {
    seed: 0,
    variant_rows: 1,       // atlas rows [1, 16]
    variant_cols: 1,
    color_base: [0.13, 0.26, 0.08],
    color_edge: [0.28, 0.38, 0.12],  // margin colour
    lobe_count: 5.0,       // palmate lobes [1, 9]; 5 = maple, 3 = ivy
    lobe_depth: 0.34,      // sinus depth between lobes [0, 0.8]
    fan_angle: 78.0,       // fan half-angle, degrees [30, 110]
    radius: 0.92,          // blade radius as cell fraction [0.3, 1]
    base_notch: 0.18,      // cordate basal notch depth [0, 0.5]; 0 = wedge
    vein_width: 0.05,      // radiating main-vein width [0.01, 0.2]
    petiole_length: 0.1,   // V-axis fraction reserved for the stalk [0, 0.3]
    normal_strength: 1.4,
};

Evolutionary parameter search (genetics)

All config types implement symbios_genetics::Genotype, making them compatible with the evolutionary algorithms in the symbios-genetics crate (SimpleGA, Nsga2, MapElites).

Each field is independently perturbed during mutation and drawn uniformly from one of two parents during crossover:

use symbios_genetics::Genotype;
use bevy_symbios_texture::bark::BarkConfig;
use rand::SeedableRng;

let mut config = BarkConfig::default();
let mut rng = rand::rngs::StdRng::seed_from_u64(42);
config.mutate(&mut rng, 0.3);  // perturb each field with 30 % probability

let parent_b = BarkConfig { seed: 99, ..BarkConfig::default() };
let child = config.crossover(&parent_b, &mut rng);

The texture_viewer example uses this to mutate any displayed material when you click Mutate.

The Genotype implementations and the egui editor widgets are generated by declarative macros (impl_genotype! / impl_config_editor!) rather than hand-written per-config boilerplate. Each macro invocation declares the config struct, field kinds (seed, f64, colour, enum, etc.), and optional post-hooks for tiling-invariant fixups, keeping the per-config call site small while covering all 48 config types.

TextureConfig itself also implements Genotype (mutation delegates to the wrapped config; crossover recombines like variants field-wise) and exposes registry-derived helpers — all_defaults() for dropdowns and benches, module_name() for stable identifiers, generate_sync() for synchronous dispatch, and (behind the egui feature) ui::texture_config_editor for variant-generic parameter editing. The texture_viewer example and the criterion bench suite are built entirely on these, so they extend automatically when a generator is added to the registry.

Architecture

The crate is a two-layer stack: the Bevy-free core — symbios-texture — owns everything in the diagram below and is re-exported wholesale, while this wrapper adds the Bevy layer on top: SymbiosTexturePlugin, the async generation pool, the Image upload adapters (map_to_images / map_to_images_card), the TextureCache resource, the procedural-material builder, and the egui editors.

TextureGenerator (trait)
    │
    │  Tileable surface textures
    ├── BarkGenerator       ─── ToroidalNoise (domain-warped FBM + Worley plates)
    ├── RockGenerator       ─── ToroidalNoise (RidgedMulti)
    ├── GroundGenerator     ─── ToroidalNoise × 2 (dual-scale FBM)
    ├── BrickGenerator      ─── ToroidalNoise FBM + rounded-box SDF grid
    ├── PlankGenerator      ─── ToroidalNoise FBM + Worley knots (anisotropic)
    ├── ConcreteGenerator   ─── ToroidalNoise FBM + cosine formwork + pit FBM
    ├── MetalGenerator      ─── ToroidalNoise FBM (brushed/standing-seam) + rust FBM
    ├── ShingleGenerator    ─── ToroidalNoise FBM + sawtooth overlap ramp
    ├── PaversGenerator     ─── ToroidalNoise FBM + square/hex SDF grid
    ├── StuccoGenerator     ─── ToroidalNoise FBM (high-frequency, matte)
    ├── AshlarGenerator     ─── ToroidalNoise FBM + irregular SDF grid + chisel edge
    ├── CobblestoneGenerator─── toroidal Voronoi (domed F1, mud gap at F2−F1)
    ├── MarbleGenerator     ─── ToroidalNoise FBM (domain-warped sinusoidal veins)
    ├── ThatchGenerator     ─── ToroidalNoise FBM (anisotropic fibre + sawtooth layers)
    ├── CorrugatedGenerator ─── sine-wave ridge profile + rust FBM
    ├── AsphaltGenerator    ─── ToroidalNoise FBM × 3 (macro/micro/aggregate)
    ├── WainscotingGenerator─── ToroidalNoise grain FBM + panel margin SDF
    ├── EncausticGenerator  ─── ToroidalNoise glaze FBM + geometric pattern SDF
    ├── FabricGenerator     ─── perpendicular thread lattice + over/under weave
    ├── SandGenerator       ─── warped sine ripples + grain flecks
    ├── SnowGenerator       ─── FBM drift relief + sparkle flecks
    ├── IceGenerator        ─── sinusoidal crack veins + frost patches
    ├── LavaGenerator       ─── toroidal Voronoi plates + emissive crack glow
    ├── MossGenerator       ─── ToroidalNoise FBM × 3 (cushion/filament/dry)
    ├── LichenGenerator     ─── ToroidalNoise FBM (thresholded thallus patches)
    ├── CactusSkinGenerator ─── periodic rib/areole lattice + sinusoid mottle
    │
    │  Alpha-masked cards
    ├── LeafGenerator       ─── LeafSampler (silhouette + venation)
    ├── TwigGenerator       ─── LeafSampler × N (composite stem + leaves)
    ├── WindowGenerator     ─── rounded-box SDF frame/mullions + FBM grime
    ├── StainedGlassGenerator── toroidal Voronoi + lead came SDF + grime FBM
    ├── IronGrilleGenerator ─── bar SDF grid + joint rust FBM
    ├── ChainLinkGenerator  ─── diagonal wire lattice + over/under weave
    ├── LogEndGenerator     ─── warped concentric rings + bark rim
    │
    │  Sprite atlases (alpha-masked cards, via sprite::generate_atlas)
    ├── SoftDiscGenerator   ─── radial-falloff disc (core + halo)
    ├── SparkGenerator      ─── N-armed streak burst
    ├── SnowflakeGenerator  ─── dendritic N-fold flake
    ├── PuffGenerator       ─── domain-warped FBM blob + radial mask
    ├── RingGenerator       ─── soft annulus + angular waviness
    ├── PetalGenerator      ─── obovate blade + throat/edge gradient
    ├── ShardGenerator      ─── jittered polygon chip + grain FBM
    ├── LeafSpriteGenerator ─── LeafSampler atlas (per-cell leaf variants)
    ├── FlameGenerator      ─── teardrop envelope + FBM turbulence
    ├── FlowerGenerator     ─── PetalCell × N (radial composite blossom)
    ├── GrassTuftGenerator  ─── fanned, curved blade ribbons
    ├── FrondGenerator      ─── lanceolate pinna + pinnate veins
    ├── ReedGenerator       ─── strap leaves + catkin spikes
    ├── NeedleGenerator     ─── paired-needle conifer shoot
    └── BroadleafGenerator  ─── polar palmate silhouette + radiating veins
                                │
                        height_to_normal() → normal map
                        linear_to_srgb()   → albedo encoding
                                │
                 TextureMap { albedo, normal, roughness, emissive? }
                                │
                map_to_images()      → GeneratedHandles (repeat sampler)
                map_to_images_card() → GeneratedHandles (clamp sampler)
                                │
                        full mipmap chain (type-correct averaging)

Noise-in-constructor — the surface generators and the SDF-based cards (window, stained glass, iron grille) build their noise objects (Fbm<Perlin>, RidgedMulti<Perlin>, ToroidalNoise<…>) once in new() and store them as struct fields. Calling generate() multiple times (e.g. to produce size variants of the same material) skips the initialisation cost. Worley is the exception: it contains an Rc and is therefore !Send / !Sync, so the generators that use it (BarkGenerator, PlankGenerator) construct it locally — and, since generation is row-parallel, once per row inside the parallel loop (the construction cost is microseconds against the per-row pixel work). The foliage cards (LeafGenerator, TwigGenerator — leaf sampling also uses Worley) and the atlas generators hold only their config and build their samplers per generate() call. The cell-decomposition surfaces (CobblestoneGenerator, LavaGenerator) instead use a dependency-free, Sync hash-based toroidal Voronoi (noise::toroidal_voronoi).

Workspace buffer pooling — generators that allocate large intermediate grids (e.g. BarkGenerator, ThatchGenerator) accept an optional Workspace via generate_with_workspace(). The workspace maintains a pool of Vec<f64> buffers that are borrowed and returned across calls, eliminating repeated 128 MB+ allocations at 4096×4096 resolution.

Seamless tiling is provided by ToroidalNoise, which maps 2-D UV coordinates onto a 4-D torus so that noise wraps perfectly at every edge:

nx = cos(2π·u) · frequency
ny = sin(2π·u) · frequency
nz = cos(2π·v) · frequency
nw = sin(2π·v) · frequency

Because cos(0) = cos(2π) and sin(0) = sin(2π), u=0 and u=1 always resolve to the same 4-D point, guaranteeing zero-seam tiling.

Normal maps are derived from the height field via central-difference gradients. For the tileable surface textures the neighbours wrap toroidally, so the normals are also seamless. For card textures (the foliage and architectural cards and the whole atlas family) the boundary uses clamp-to-edge so normals do not bleed across the transparent silhouette border. Sprite atlases additionally dilate heights into fully-transparent texels before derivation so the normals do not crease at silhouette edges.

Colour encoding uses a 4096-entry sRGB lookup table (built once via OnceLock) to avoid repeated f32::powf calls during rasterisation. A 256-entry table would be insufficient because the sRGB curve is steep near zero; 4096 bins keep the maximum quantisation error well below one count in u8.

Mipmap generation uses a 2×2 box filter with type-correct averaging: sRGB values are decoded to linear light before averaging and re-encoded afterward (avoiding dark mipmaps), normal-map XYZ vectors are averaged and renormalized (avoiding zero-length normals in PBR shaders), and ORM values are averaged directly in linear space. Async generation tasks precompute the full chain on the worker thread (TextureMap::with_mips), so the main-thread upload in the polling systems is a pure buffer move; map_to_images / map_to_images_card compute the chain on demand for maps without one (synchronous callers, cache loads). 16× anisotropic filtering is enabled on all samplers.

Examples

texture_viewer

cargo run --release --example texture_viewer --features egui

Displays an interactive material viewer with three columns: albedo (left), normal map (centre), and a 3-D PBR preview (right) with the generated material applied. Tileable surface textures are shown on a spinning cube; alpha-masked cards and sprite atlases get a gently swaying alpha-blended quad in front of a checkerboard backdrop instead, so per-pixel alpha is visible. An egui panel on the left lets you select any of the 48 generators from a dropdown, trigger a random Mutate (rate = 0.3), and edit every parameter live.

procedural_material

cargo run --release --example procedural_material

Side-by-side comparison of build_procedural_material_async (left cube) against the manual PendingTexture + material-patching flow it replaces (right cube).

animated_rust

cargo run --release --example animated_rust

Animates rust coverage on a metal panel from 0 % to 100 % over ten seconds via AnimatedProceduralMaterial driving a Linear curve, throttled to roughly four regenerations per second.

License

MIT — see LICENSE.