Module field 

3D spatial fields for particle-environment interaction.

Fields provide persistent spatial data that particles can read from and write to. Unlike the inbox system (particle-to-particle), fields are spatially indexed and persist independently of particles.

Field Types

• Scalar fields (f32 per cell): density, temperature, pheromones
• Vector fields (vec3 per cell): velocity, forces, gradients

Use Cases

• Pheromone trails: Particles deposit chemicals, others follow gradients
• Density fields: Accumulate particle presence for fluid-like behavior
• Temperature/heat: Particles emit/absorb heat from spatial field
• Flow/velocity fields: Particles advect through vector field for fluid simulation

Single Field Example

Simulation::<Agent>::new()
    .with_field("pheromone", FieldConfig::new(64).with_decay(0.98).with_blur(0.1))
    .with_rule(Rule::Custom(r#"
        // Deposit pheromone at current position
        field_write(0u, p.position, 0.1);

        // Sample and follow gradient
        let grad = field_gradient(0u, p.position, 0.05);
        p.velocity += normalize(grad) * 0.5 * uniforms.delta_time;
    "#.into()))
    .run();

Multiple Fields Example

Each field can have independent resolution, decay, and blur settings:

Simulation::<Agent>::new()
    .with_field("food", FieldConfig::new(64).with_decay(0.99))       // Index 0
    .with_field("danger", FieldConfig::new(32).with_decay(0.9))      // Index 1
    .with_rule(Rule::Custom(r#"
        // Read from different fields by index
        let food = field_read(0u, p.position);
        let danger = field_read(1u, p.position);

        // Seek food, avoid danger
        let food_grad = field_gradient(0u, p.position, 0.05);
        let danger_grad = field_gradient(1u, p.position, 0.05);
        p.velocity += food_grad * 2.0 - danger_grad * 5.0;
    "#.into()))
    .run();

Structs

FieldConfig

Configuration for a 3D spatial field.

FieldRegistry

Registry holding all field configurations for a simulation.

Enums

FieldType

Type of field data stored at each cell.