Mechanics Relationship Map
A readable map of the simulation systems, how they exchange state, and which mechanics are artistic approximations versus closer physical models.
System Overview
Solid arrows are high-confidence coupling paths. Dashed arrows are softer or more approximate couplings that are useful visually but not fully physical.
Frame Loop
Why the ordering matters
The simulation is field-mediated. Particles do not only collide with each other; they write state into grids, the grids solve global effects, then particles read those fields back.
| Stage | Common failure when misordered |
|---|---|
| Raster before solve | Stale charge or magnetization makes forces lag and feel like a filter. |
| Scene-only magnetic solve | Prevents ferro from sustaining its own field after the source is gone. |
| Post force passes | Keeps SSBO binding pressure low and isolates chain/Coulomb behavior. |
| G2P coloring last | Debug views see the final force, thermal, and field state for that frame. |
Mechanics Atlas
Elastic, plastic, brittle, thermal, charged, ferro, bio, and foot-demo particles share P2G/G2P plumbing with material-specific stress branches.
Neighbor-density fluids with pressure, viscosity, XSPH smoothing, CSF surface tension, thermal states, and MPM contact.
MAC-grid velocity, temperature, smoke, vapor, airtight pressure, blast, reaction diffusion, and continuous automata.
Kinematic colliders with friction, thermal diffusion, and magnetic source presets. Mostly one-way collision into particles.
SDF/cursor/particle magnetization writes M, Poisson solve gives H, and MPM reads Kelvin force plus surface Maxwell stress.
Charge rasterization, Poisson solve, and post-MPM Coulomb acceleration for positive/negative ion materials.
Particle heat softens, burns, melts, boils, vents vapor, pressurizes cavities, changes magnetic phases, and drives regrowth.
Debug views expose velocity, stress, temperature, magnetic fields, charges, bio fields, automata drive, and authored layer colors.
Coupling Matrix
| Producer | Consumer | State exchanged | Relationship |
|---|---|---|---|
| MPM | Eulerian air | heat, vapor source, smoke source, velocity impulse, bio seed, automata seed | One-way per frame, then air feeds back through sampled temp/pressure/fields. |
| Eulerian air | MPM | air temperature, airtight pressure, bio gradients, automata gradients | Feedback loop for burning, cooling, puffing, regrowth, and colony steering. |
| MPM ferro and magnetic SDF | Magnetic solver | magnetization M, material occupancy, source field | Two-field solve: scene-only H for Langevin response, total H for force/stress. |
| Magnetic solver | MPM | H, |H|, grad |H|^2, occupancy-gradient cues | Kelvin body force, chain force, surface Maxwell stress, demag pressure, pseudo-thickness support. |
| MPM charged particles | Electrostatic solver | charge density | Poisson solve gives E for Coulomb post-pass. Triboelectric charge generation is still a placeholder. |
| SDF | MPM/SPH | distance, normal, friction, heat, material preset | Kinematic boundary. SDF does not receive momentum back from particles yet. |
| SPH | MPM | nearby occupancy and contact heat | Soft coupling for contact and thermal exchange, not a fully unified pressure solve. |
| XPBD | MPM particles | constraint corrections on selected particle graphs | Distance constraints for rope and future foot/cloth style rigs layered after MPM motion. |
Ferrofluid Lens
- Packed magnetic cells add pressure.
- Thin connected sheets get mild bridge tension.
- Cursor-follow lift keeps more source force.
- Spike stress is more surface-weighted.
What should look physical
Large volumes should climb when the source creates a broad upward gradient. The climb should be a column or wick, not a rigid hook. Stronger fields should increase surface corrugation and spike height before they merely fling isolated grains.
What is still approximate
The ferro free surface is not a full Rosensweig instability solve. It is a stack of practical terms: weakly compressible Tait pressure, Kelvin body force, field-aligned stress, demag pressure, occupancy capillarity, and pseudo-2.5D thickness.
Thickness is reliable as an art-directable closure for a 2D slice. It helps with tunnels, columns, and fluffy/porous materials. It is not a conserved hidden-volume model, so extreme values can hide real separation or make sheets feel too sticky.
Thermal, Explosion, and Regrowth Lens
Thermal chain
Particles carry temperature and material-specific thermal coupling. Hot particles inject heat, vapor, smoke, and sometimes combustion into air. Air temperature then cools or heats particles on the next G2P pass.
Explosion chain
Combustion and sealed-charge materials feed vapor, heat, airtight pressure, and blast impulses. The cavity mask decides whether gas can vent or builds pressure into a local explosion.
Regrowth chain
Ash now acts mostly as scaffold/support. Live regrowth seeds the bio and automata fields; ash alone no longer seeds a strong dark automata front. Recovery accelerates color restoration.
Debugging Map
Useful views when a mechanic feels wrong
| Symptom | First view to check | Likely subsystem |
|---|---|---|
| Ferro moves like a filter over the field | Magnetic field + material occupancy | External-drive gate, scene-only field, Kelvin cap, field iterations |
| Ferro collapses to a dot | Material occupancy and stress | Overpacked cells, insufficient EOS pressure, too much self-field |
| Spikes are too weak | Magnetic field gradient + surface force toggle | Surface Maxwell stress, capillary relief, field broadness |
| Regrowth turns black | Automata colony + material color | Ash seeding too much automata, recovery too slow, crumble shadow too strong |
| Explosions feel weak or too strong | Airtight pressure + vapor | Vent mask, vapor source, combustion heat, blast pass |
Page relationship to the in-app graph
The pipeline graph view is excellent for frame-order debugging. This page is meant to answer a different question: when a material does something surprising, which fields and couplings could be responsible?
Use the status report for implementation truth, this page for mental model, and the in-app views for live evidence. The useful workflow is: pick the symptom, identify the field path, toggle one force family, then compare against the expected visual from the diagrams.