Crate rdpe 

RDPE - Reaction Diffusion Particle Engine

GPU-accelerated particle simulations with a simple, declarative API.

RDPE handles all the GPU complexity (buffers, shaders, spatial hashing) so you can focus on defining particle behavior through composable rules.

Quick Start

use rdpe::prelude::*;

#[derive(Particle, Clone)]
struct Ball {
    position: Vec3,
    velocity: Vec3,
}

fn main() {
    Simulation::<Ball>::new()
        .with_particle_count(10_000)
        .with_bounds(1.0)
        .with_spawner(|i, _| Ball {
            position: Vec3::new(0.0, 0.5, 0.0),
            velocity: Vec3::ZERO,
        })
        .with_rule(Rule::Gravity(9.8))
        .with_rule(Rule::BounceWalls { restitution: 1.0 })
        .run();
}

Core Concepts

Particles

Define your particle struct with #[derive(Particle)]. Required fields:

• position: Vec3 - particle position in 3D space
• velocity: Vec3 - particle velocity

Optional fields:

• #[color] color: Vec3 - custom particle color (RGB, 0.0-1.0)
• particle_type: u32 - for typed interactions (auto-added if not present)
• Any other f32, u32, i32, Vec2, Vec3, Vec4 fields

Rules

Rules define particle behavior. They execute every frame in order:

.with_rule(Rule::Gravity(9.8))        // Apply forces
.with_rule(Rule::Separate { ... })    // Neighbor interactions
.with_rule(Rule::SpeedLimit { ... })  // Constrain velocity
.with_rule(Rule::Drag(1.0))           // Apply friction
.with_rule(Rule::BounceWalls { restitution: 1.0 })         // Boundary conditions

Typed Interactions

Use ParticleType derive for type-safe particle categories:

#[derive(ParticleType, Clone, Copy, PartialEq)]
enum Species {
    Prey,
    Predator,
}

// Predators chase prey
Rule::Chase {
    self_type: Species::Predator.into(),
    target_type: Species::Prey.into(),
    radius: 0.3,
    strength: 2.0,
}

Spatial Hashing

Neighbor-based rules (Separate, Cohere, Align, etc.) use spatial hashing for efficient neighbor queries. Configure with:

.with_spatial_config(cell_size, grid_resolution)

• cell_size should be >= your largest interaction radius
• grid_resolution must be a power of 2 (16, 32, 64)

Feature Overview

Category	Rules
Physics	Rule::Gravity, Rule::Drag, Rule::Acceleration
Boundaries	Rule::BounceWalls, Rule::WrapWalls
Forces	Rule::AttractTo, Rule::RepelFrom
Movement	Rule::Wander, Rule::SpeedLimit
Flocking	Rule::Separate, Rule::Cohere, Rule::Align
Collision	Rule::Collide
Types	Rule::Typed, Rule::Convert, Rule::Chase, Rule::Evade
Custom	Rule::Custom for raw WGSL

Re-exports

pub use error::GpuError;

pub use error::SimulationError;

pub use error::TextureError;

pub use field::FieldConfig;

pub use field::FieldRegistry;

pub use field::FieldType;

pub use lifecycle::Lifecycle;

pub use rules::AgentState;

pub use rules::CustomRuleBuilder;

pub use rules::Falloff;

pub use rules::Rule;

pub use rules::Transition;

pub use sub_emitter::SpawnTrigger;

pub use sub_emitter::SubEmitter;

pub use textures::AddressMode;

pub use textures::FilterMode;

pub use textures::TextureConfig;

pub use textures::TextureRegistry;

pub use visuals::BlendMode;

pub use visuals::ColorMapping;

pub use visuals::ConfigDiff;

pub use visuals::GlyphColorMode;

pub use visuals::GlyphConfig;

pub use visuals::GlyphMode;

pub use visuals::HotSwapChange;

pub use visuals::Palette;

pub use visuals::ParticleShape;

pub use visuals::VertexEffect;

pub use visuals::VisualConfig;

pub use visuals::WireframeMesh;

pub use bytemuck;

Modules

error

Error types for RDPE.

field

3D spatial fields for particle-environment interaction.

input

Input handling for RDPE simulations.

lifecycle

Particle lifecycle management.

prelude

Convenient re-exports for common usage.

rules

Particle behavior rules.

selection

Particle selection utilities.

shader_utils

Built-in WGSL utility functions for shader code.

sub_emitter

Sub-emitter system for spawning particles on particle death.

textures

Texture loading and configuration for shaders.

time

Time facilities for simulation timing.

visuals

Visual configuration for particle rendering.

Structs

AdjacencyConfig

Configuration for adjacency buffer (stores neighbor indices per particle).

AdjacencyGpu

GPU resources for adjacency buffer management.

CustomUniforms

Collection of custom uniform values.

FieldSystemGpu

GPU state for all fields in a simulation.

GlyphRenderer

GPU resources for glyph rendering.

InteractionMatrix

Interaction matrix storing force relationships between particle types.

Simulation

A particle simulation builder.

SpatialConfig

Configuration for spatial hashing grid

SpatialGpu

GPU resources for spatial hashing

SpatialGridViz

GPU state for spatial grid visualization.

SpawnContext

Context provided to spawner functions with helpers for common spawn patterns.

UpdateContext

Context passed to the update callback each frame.

Vec2

A 2-dimensional vector.

Vec3

A 3-dimensional vector.

Vec4

A 4-dimensional vector.

VolumeConfig

Configuration for volume rendering.

VolumeRenderState

GPU state for volume rendering.

Enums

Emitter

Particle emitter configuration.

UniformValue

Supported uniform value types.

Traits

ParticleTrait

Trait automatically implemented by #[derive(Particle)].

Functions

create_particle_field_bind_group_layout

Create bind group layout for particle shader field access

Derive Macros

MultiParticle

Derive macro for multi-particle enums with inline struct definitions.

Particle

Derive macro for particle structs.

ParticleType

Derive macro for particle type enums.