Trait ParticleTrait 

pub trait ParticleTrait:
    Clone
    + Send
    + Sync {
    type Gpu: Copy + Clone + Pod + Zeroable + Send + Sync;

    const WGSL_STRUCT: &'static str;
    const COLOR_FIELD: Option<&'static str>;
    const COLOR_OFFSET: Option<u32>;
    const ALIVE_OFFSET: u32;
    const SCALE_OFFSET: u32;
    const EXTRA_WGSL: &'static str = "";

    // Required methods
    fn to_gpu(&self) -> Self::Gpu;
    fn from_gpu(gpu: &Self::Gpu) -> Self;
    fn inspect_fields(&self) -> Vec<(&'static str, String)>;
}

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

This trait bridges your Rust particle struct to GPU-compatible memory layout. The derive macro generates:

• A companion {Name}Gpu struct with proper alignment/padding
• WGSL struct definition for compute shaders
• Conversion between Rust and GPU representations

Do Not Implement Manually

This trait should only be derived, never implemented by hand. The derive macro handles complex GPU memory layout requirements.

Example

#[derive(Particle, Clone)]
struct MyParticle {
    position: Vec3,           // Required
    velocity: Vec3,           // Required
    #[color]
    color: Vec3,              // Optional: custom color
    particle_type: u32,       // Optional: for typed rules
    energy: f32,              // Optional: custom data
}

Required Associated Constants

const WGSL_STRUCT: &'static str

WGSL struct definition for use in compute shaders.

Generated to match the GPU struct layout exactly.

const COLOR_FIELD: Option<&'static str>

Name of the field marked with #[color], if any.

Used by the renderer to determine which field contains particle color. If None, particles are colored based on position.

const COLOR_OFFSET: Option<u32>

Byte offset of the color field within the GPU struct.

Used to configure vertex attributes for rendering.

const ALIVE_OFFSET: u32

Byte offset of the alive field within the GPU struct.

Used to configure vertex attributes for culling dead particles. Always present since lifecycle fields are auto-injected.

const SCALE_OFFSET: u32

Byte offset of the scale field within the GPU struct.

Used to configure vertex attributes for particle sizing. Always present since lifecycle fields are auto-injected.

Provided Associated Constants

const EXTRA_WGSL: &'static str = ""

Additional WGSL code prepended to shaders.

Used by MultiParticle enums to inject type constants and helper functions. Regular particle structs leave this empty.

Example for a multi-particle enum:

const BOID: u32 = 0u;
const PREDATOR: u32 = 1u;
fn is_boid(p: Particle) -> bool { return p.particle_type == BOID; }

Required Associated Types

type Gpu: Copy + Clone + Pod + Zeroable + Send + Sync

GPU-compatible representation with proper memory alignment.

Generated automatically by the derive macro. Includes padding fields to satisfy WGSL alignment requirements (vec3 → 16-byte aligned).

Required Methods

fn to_gpu(&self) -> Self::Gpu

Convert this particle to its GPU representation.

Called once per particle during initialization.

fn from_gpu(gpu: &Self::Gpu) -> Self

Convert from GPU representation back to this particle type.

Used for CPU readback of particle data (e.g., for inspection).

fn inspect_fields(&self) -> Vec<(&'static str, String)>

Get field names and their display values for inspection.

Returns a vector of (field_name, formatted_value) pairs for all user-defined fields in the particle struct. Used by the built-in particle inspector panel.

This is automatically generated by the derive macro and should not be implemented manually.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors