Energy Perception & Physics Stability

[M1thieu]

Objective

Add energy-aware AI perception and fix critical physics stability issues.

Been waiting for MPM to finish but wanted to get actual game features in. This adds temperature/electric field sensing for creatures plus some needed physics infrastructure that was blocking progress.

Implementation

1. AI Energy Perception (New)

• ThermalSensor/ThermalTracker: creatures sense temperature gradients
  • Detects hot/cold zones, calculates thermal comfort
  • Integrates with homeostasis needs (discomfort → need satisfaction)
  • Range-based sensing with sensitivity thresholds
• ElectricSensor/ElectricTracker: electroreception (like sharks)
  • Superposition of electric fields (proper EM physics)
  • Creatures can detect and avoid electric hazards

Design: MPM-safe from the start. Trackers READ Temperature/ElectricField components that MPM will UPDATE later. No hardcoded physics, just perception layer.

2. Thermal Diffusion Stability (Critical Fix)

• Added CFL condition check: dt ≤ C·dx²/α
• Warns at startup if timestep will cause numerical explosion
• Prevents "simulation goes to infinity" bugs before they happen

3. Wave Energy Conservation

• Wave damping now reports energy loss to accounting ledger
• Energy ∝ amplitude² (proper wave physics)
• Records transactions for later MPM thermal coupling
• Closes energy conservation gap

4. Forces Improvements (Pre-existing work merged)

• Fixed mutual gravitational attraction (mutable aliasing bug)
• Added symplectic Euler integration option
• Forces diagnostics plugin (momentum/KE tracking for debugging)
• Configurable integrator and gravity modes

Visibility cleanup:

• Made internal system functions pub(crate) (better SoC)
• Removed internal systems from public preludes

Testing

cargo check --all-targets  # Clean compile
cargo clippy --workspace   # No new warnings

Physics verified:

• CFL condition: Industry-standard for explicit diffusion (same as CFD/climate models)
• Wave energy: E ∝ A² is fundamental (sound, EM, water waves all follow this)
• Electric superposition: Maxwell's equations (fields add vectorially)
• Gravity: Newton's 3rd law (equal & opposite forces)
• Symplectic Euler: Standard game physics integrator

Behavior:

• Creatures with ThermalSensor actively seek comfortable temperatures
• ElectricSensor lets them avoid electric hazards
• Thermal comfort affects homeostasis need (0 discomfort = full satisfaction)

No breaking changes to existing APIs.

Code Example

Adding thermal sensing to a creature:

commands.spawn((
    Transform::default(),
    // Thermal perception
    ThermalSensor {
        range: 500.0,          // Sense up to 500 units away
        sensitivity: 5.0,       // Detect 5K temperature changes
        preferred_temp: 293.0,  // Likes room temperature (20°C)
    },
    ThermalTracker::default(),  // Auto-updated each frame
));

Reading thermal state:

fn creature_ai(creatures: Query<&ThermalTracker>) {
    for tracker in creatures.iter() {
        if tracker.discomfort > 0.5 {
            // Creature is uncomfortable!
            let direction = tracker.gradient_direction; // Points toward comfort
            // Move creature toward comfort...
        }
    }
}

Technical Notes

MPM Integration Path:

• When MPM lands, it will own Temperature/ElectricField updates
• AI trackers already designed to just READ those components
• Zero refactoring needed when MPM arrives

Energy Conservation:

• Wave damping → ledger
• Thermal transfer → ledger (already done)
• EM energy → ledger (future work)
• MPM will close the loop by converting dissipated energy to heat

Limitations:

• Thermal perception is simplified biophysics (good enough for gameplay)
• Electric field sensing doesn't model conductivity yet (future)
• CFL check is advisory (warns but doesn't auto-fix timestep)

Future trackers planned:

• Acoustic sensing (sound waves)
• Chemical sensing (smell/pheromones)
• Pressure sensing (water flow, wind)