The Chaos Engine is a sophisticated, real-time generative physics sandbox built on a custom Vanilla JavaScript engine.
It simulates the emergent behavior of matter by bridging the gap between rigid-body physics, fluid dynamics, and
probabilistic organic chemistry. It runs without external libraries, utilizing a spatial hash grid to manage
interactions between hundreds of particles at 60 FPS.
1. Configuration Manual
The simulation is controlled via the HUD (Heads-Up Display), accessible by clicking the ⚙ Gear Icon.
Below is an exhaustive reference for every parameter.
Environment & Physics
Time Dilation
Controls the global delta-time (Delta t) of the simulation.
Low (0.1): "Matrix style" slow motion. Useful for observing rapid bonding events.
High (2.0): Fast-forward. Useful for accelerating structural evolution.
Viscosity
Determines the thickness/friction of the medium.
0.0: Vacuum (Particles drift forever).
High: Syrup/Gel (Particles stop quickly).
Turbulence
Injects procedural noise into the velocity field. It simulates Brownian motion and wind currents, preventing the system from becoming static and forcing atoms to mix.
Crowding
Simulates intermolecular repulsion (Van der Waals forces). It pushes separate molecules apart, preventing them from overlapping or collapsing into a singularity.
Chemistry & Bonding
Reactivity
A global multiplier for probabilistic chemical events.
High: Atoms aggressively break existing bonds to form new, more stable ones (e.g., Nucleophilic attacks).
Zero: Bonds are permanent once formed.
Bond Rigidity
Defines the "Spring Constant" (k) of covalent bonds.
Low: Floppy, rubber-like molecules.
High: Rigid, geometric structures (hexagons/triangles).
H-Strength
The attraction force of Hydrogen Bonds. These are weak, distance-and-angle dependent forces between Hydrogen and Nitrogen/Oxygen. Essential for "tissue" formation.
H-Capacity
The maximum number of Hydrogen bonds a single atom can sustain.
1: Linear strands (hair-like). 3+: Complex webs (tissue-like).
Chaos & Interaction
Probe Energy
Controls the behavior of "Probe" particles (Blue). Higher energy increases the probability that a Probe will emit a localized shockwave, shattering nearby molecular bonds.
Blast Radius
Determines the magnitude of high-energy events (Chain Reactions). If an atom is destroyed or unstable, this setting dictates how many neighbor bonds are severed in the shockwave.
Force Strength
Scales the power of the mouse cursor interactions (Push, Pull, etc.).
Composition
Atom Ratios
A series of sliders determining the elemental makeup of the universe upon reset. The system normalizes inputs to ensure they always sum to 100%. Available elements: Carbon (C), Hydrogen (H), Oxygen (O), Nitrogen (N), Phosphorus (P), Sulfur (S), Chlorine (Cl) as well as non-atom Probes.
2. Interaction Modes
The mouse interaction logic is state-dependent. Select a mode from the dropdown menu in the HUD.
- Push (Default): Applies a radial inverse-square repulsion force. Useful for clearing space or separating tangled molecules without damaging them.
- Push + Destroy: Functions as a "crusher." It pushes distant atoms away, but if the cursor physically touches an atom, that atom is annihilated.
- Pull (Strong): Creates a high-gravity well. This forces atoms to collide at high velocities, acting as a catalyst for bond formation.
- Cut (Laser): A precision tool. It calculates the intersection between the cursor and bond vectors, severing connections without destroying the atoms themselves.
- Destroy (Nuke): A high-energy eraser. Deleting an atom in this mode triggers a calculated "Blast Radius" event, potentially starting a chain reaction.
3. The Chemistry Engine
The simulation enforces strict Valency Logic. Atoms are not just graphical dots; they possess specific bonding slots (C=4, N=3, O=2, H=1, etc.).
Bonding Types
- Covalent Bonds: Strong, spring-like constraints. The engine iteratively solves for target bond lengths ($L_{target}$) to maintain structural integrity.
- Hydrogen Bonds: Weak, directional forces. The engine calculates the dot product of vectors between Donor and Acceptor atoms to ensure correct alignment before bonding.
- Disulfide Bridges: Special logic allows Sulfur-Sulfur bonds to be exceptionally rigid, stabilizing larger protein-like structures.
Organic Reactions
Stochastic checks run every 10 frames to simulate organic chemistry mechanisms based on proximity and temperature:
- Nucleophilic Attack: Oxygen/Nitrogen atoms can attack Carbonyl carbons ($C=O$), breaking the double bond to attach themselves.
- Thermal Elimination: At high temperatures (T > 150 K), carbon chains may eject "leaving groups" (H or Cl) to form double bonds.
- Cumulene Instability: Long chains of double bonds (R=C=C=C=R) are physically unstable; the engine detects and randomly shatters them.
4. Structural Analysis Algorithms
The engine performs graph theory analysis on the molecular topology in real-time (every 30 frames).
Aromaticity (The Mesomeric Effect)
A recursive Depth-First Search (DFS) scans the bond network for cycles.
If it finds a planar ring of 5 or 6 atoms (Carbon/Nitrogen) with alternating unsaturation, it flags the structure as Aromatic.
Visual: Rotating cyan "electrons" appear inside the ring to represent the delocalized $\pi$-system.
Conjugated Systems
The engine detects chains of alternating single and double bonds. These allow for electron flow across the molecule.
Visual: A static, conductive glow renders over the path of the conjugation.