Configuration Manual

Access the HUD via the ⚙ icon (bottom-right). Click the 📌 pin icon to keep it open.

System Control

Mouse Interaction

Environment

Advanced Chemistry

Atom Composition

Chemistry Visualization v28.0+

Debug & Visualization

Simulation Controls

Configuration Export/Import

Mouse Interaction System

Select a mode from the Interaction Tool dropdown to change cursor behavior. Left-clicking always spawns 12 cyan sparks for visual feedback.

Interaction Modes

• Grab: Spring-force pickup tool. Finds the nearest atom within 80px of the cursor, then applies a spring-like force (max 40 units) to drag it. Includes 0.8× friction damping for stability. Release to fling the atom with mouse velocity.
• Push: Soft radial repulsion within 180px range. Force scales as (1 − dist/180) × Force × 4.5. Useful for gentle molecular separation without destruction.
• Push + Destroy: "Crusher" mode. Repels particles beyond 60px, but deletes any atom that enters the 60px danger zone. Triggers chain reactions and plasma sparks.
• Pull: High-gravity attractor within 180px. Pulls particles toward cursor with force (1 − dist/180) × Force × 4.5. Forces collisions and rapid bonding.
• Cut: Precision severing tool. Breaks all bonds within 50px radius. Atoms within 75px also have bonds severed. Creates plasma effects at cut sites.
• Destroy: Mass deletion within 80px radius. Triggers shatterMolecule() on all atoms, causing chain reactions that propagate to bonded neighbors. Creates large ripple effects.

Force Mechanics

Visual Feedback

• Plasma Sparks: 12 particles spawn at click location, velocity (−0.5 to 0.5) × 4, lifetime 50 frames
• Click Nodes: Pulsing circles (30 frame lifetime) mark interaction points
• Ripples: Expanding rings created by shattering events, fade over 50 frames
• Shockwaves: Impulse forces (4.0 – 8.0 magnitude) applied to shattered atoms

The Chemistry Engine

Reactions are evaluated stochastically every 10 frames (6 times/second at 60 FPS) to decouple reaction rates from frame rate.

Valency & Oxidation Rules

The simulation enforces strict electron shell constraints:

• Fixed Valency: C=4, N=3, O=2, H=1, Cl=1, Br=1
• Dynamic Hypervalency:
  • Sulfur: 2 bonds normally, expands to 8 if bonded to Oxygen (sulfates, sulfonyl)
  • Phosphorus: 3 bonds normally, expands to 5 if bonded to Oxygen (phosphates)
  • Nitrogen: 3 bonds normally, can accept 4 if bonded only to H/O (ammonium)
• Oxygen Rule: Cannot form chains > 2 atoms (O-O-O forbidden, prevents infinite peroxides)
• Nitrogen/Phosphorus Rule: Cannot form homonuclear chains (N-N-N or P-P-P forbidden)

Electronegativity & Bond Polarity v28.0

Every atom carries a fixed electronegativity (EN) value based on the Pauling scale. When two atoms share a bond, the engine calculates the EN difference to classify the bond and — when the visualization toggle is on — to color it accordingly.

Formal Charges v28.7

Each atom's formal charge (FC) is continuously recalculated using the standard chemistry formula based on true bond orders rather than geometric bond counts.

Radical Detection v28.0

An atom is flagged as a radical when it has an odd number of non-bonding electrons. Radicals are highly reactive — the stabilization system actively tries to pair them with other radicals or open-valence neighbors.

Intelligent Stabilization System v28.0

Every 60 frames, the engine scans all molecules for instability. If any atom carries a non-zero formal charge or is a radical, the system attempts automatic rearrangement to restore neutrality.

pH System & Hydronium / Hydroxide v28.0

The engine continuously tracks the concentration of H₃O⁺ (hydronium) and OH⁻ (hydroxide) ions and derives a live pH value from them.

Acid-Base Reactions v28.3

The solveAcidBase() system implements four distinct proton-transfer reaction types. All are proximity- and orientation-driven, respect the shared rearrangement cap, and run every 45 frames alongside autoFormHydronium().

A — Neutralization: H₃O⁺ + OH⁻ → 2 H₂O

The most thermodynamically favorable reaction in the engine. When a hydronium oxygen comes within range of a hydroxide oxygen, one H is broken from H₃O⁺ and bonded to OH⁻. Both become neutral water. The two new water molecules receive a gentle velocity kick apart to prevent immediate re-interaction.

B — Generic Proton Donation: H-X + :B → X⁻ + H-B

Any H bonded to an electronegative atom (O or N) can donate to a nearby base — an O or N in a different molecule that has an open valence slot. The system classifies bases by strength:

• Strong base: O with ≤ 1 bond, or N with < 3 bonds → 12% × temp probability
• Weak base: All other qualifying O/N → 3% × temp probability

Geometry matters: the engine picks the H that is physically closest to the acceptor base, ensuring the transferred proton takes the most plausible path.

C — Autoionization: H₂O + H₂O → H₃O⁺ + OH⁻

Two clean water molecules (each O with exactly 2 H bonds, in separate molecules) near each other have a tiny chance of spontaneously exchanging a proton. One becomes H₃O⁺, the other OH⁻. This is the engine's equilibrium mechanism — it continuously seeds the ion pool that neutralization then consumes, keeping pH dynamic even in pure water.

D — HCl Strong Acid Dissociation: H-Cl + :B → Cl⁻ + H-B

HCl is a strong acid — its dissociation probability is much higher than generic O-H or N-H donation. When an H-Cl molecule encounters any base (O or N with open valence) in a different molecule, the H transfers and Cl⁻ is released as a free ion. To prevent immediate re-capture, Cl⁻ receives a 90-frame rejoin cooldown and a velocity kick away from the reaction site.

Advanced Organic Synthesis v28.5+

The engine implements a suite of 26 distinct organic reactions that evaluate stochastically every 10 frames based on atomic geometry, temperature, and electronegativity characteristics.

1. Substitution & Elimination

• SN1 (Unimolecular): Tertiary carbons lose a leaving group (Cl), forming a carbocation which is later attacked by a nucleophile (requires high temperature).
• SN2 (Bimolecular): Strong nucleophiles attack primary/secondary carbons with a leaving group, resulting in a single concerted step (inversion visualized via repulsion).
• E1 / E2 Elimination: Thermal elimination (> 300 K) strips adjacent H and Cl atoms to form C=C double bonds. Driven by strong bases.

2. Radical Chain Reactions

• Initiation: Weak bonds (like peroxides O-O) break homolytically under high heat, creating two radicals.
• Propagation: A radical rips a hydrogen off a stable molecule, transferring the radical state to the carbon chain.
• Termination: Two radicals collide and bond, creating a singlet state.

3. Addition Modifications

• Electrophilic Addition (Markovnikov): Radicals or ions attack C=C double bonds. The engine attempts to place the nucleophile on the more substituted carbon.
• Hydrogenation: Free H₂ molecules attack double bonds under high pressure/crowding, reducing them to single bonds.
• Hydrolysis: Esters break apart in the presence of H₂O (aided by acidic environments) into an acid and an alcohol.
• Dehydration: Alcohols bounded to neighboring H-bearing carbons eject H₂O to form C=C bonds (temperature dependent).

4. Advanced Synthetic Mechanisms

• Aldol Condensation: Enolate attacks a carbonyl carbon forming a beta-hydroxy ketone, which can further dehydrate into a conjugated enone.
• Diels-Alder Cycloaddition: A conjugated diene reacts with a dienophile (alkene) to form a new six-membered ring simultaneously.
• Esterification: Carboxylic acids and alcohols merge to form esters, releasing water.
• Michael Addition: Conjugate 1,4-addition where a nucleophile attacks the beta-carbon of an alpha,beta-unsaturated carbonyl.
• Wittig Reaction: Phosphorus ylides swap with carbonyl oxygens to form specific C=C geometries.
• Amide/Peptide Bonding: Amines condense with carboxylic acids to form rigid amide bonds.
• Disulfide Bridging: Two S-H groups oxidize to form an S-S bridge, cross-linking polymers.

5. Isomerization & Rearrangements

• Keto-Enol Tautomerism: Hydrogen rapidly shifts between alpha-carbons and carbonyl oxygens.
• Sigmatropic Rearrangements: Concerted movement of pi-bonds within a conjugated system (e.g., Claisen or Cope).
• Aromatic Substitution: Electrophiles replace hydrogens on benzene rings without breaking the aromaticity.

Geometric Strain & Topology

Triangle Purge (Baeyer Strain)

3-membered rings are detected and destabilized. With 70% probability (reduced to 5% for aromatic), one bond randomly breaks. Atoms receive 2.0 unit impulse forces to separate. Creates red sparks. Simulates angle strain (~60° vs ideal 109.5°/120°).

Square Strain

4-membered rings experience torsional strain. With 1% probability per check and 10% final chance, one bond breaks. Aromatic squares have 80% resistance. Simulates deviation from ideal tetrahedral/planar angles (~90° vs 109.5°/120°).

Cumulene Instability

Consecutive double bonds (C=C=C) are thermally unstable. With probability 1% × Temperature × Reactivity, the central bond breaks. Creates yellow sparks. Simulates steric and orbital overlap strain.

Bond Mechanics

Probe Particle System

Probes are autonomous non-chemical particles that form temporary connections with atoms and each other, simulating "measurement" effects from external fields.

Probe Behavior

Connection Mechanics

Atom Connections (Temporary)

• Formation: 5% chance per frame when within 130px of atom
• Lifetime: 60 frames (1 second @ 60 FPS)
• Decay: −1.0 per frame
• Rule: Probes can only connect to ONE atom at a time
• Visual: Dashed lines (5px dash, 5px gap), thickness 0.66px
• Effect: If atom is isolated (0 bonds), probe applies drag force: 0.5 × Temperature
• High Energy: 2% chance × 4.0 (ProbeEnergy) to create glowing cyan connection with detonation capability

Probe-Probe Connections (Permanent)

• Formation: 5% chance per frame when within 130px of another probe
• Lifetime: 9999 frames (permanent until range exceeded)
• No Decay: Life value stays constant
• Rule: Unlimited probe-probe connections allowed
• Visual: Dashed lines, thickness 0.66px, alpha 1.0 (no fade)
• High Energy: Cannot be high-energy (safety rule)

Range & Cooldown System

High-Energy Detonation

High-energy probe connections (glowing cyan) have a 10% chance per frame to trigger when connected to an atom:

• Calls triggerChainReaction() on target atom
• Chain depth determined by Blast Radius setting (50% propagation chance per layer)
• Creates plasma spark burst (12 particles)
• Connection consumed (deleted)
• 60-frame cooldown applied to probe

Visual Rendering

Visual Legend

Particle Colors

Colors shift between dark and light themes. Values shown are HSL (Hue, Saturation, Lightness):

Structure Overlays

Quantum Visualizations v28.8+

When Orbitals and Chirality are toggled on, the engine dynamically processes atomic hybridization geometries (sp³, sp², sp) and stereocenters.

Bond Rendering

Electronegativity & Charge Overlays v28.0+

Spark Color Reference

Different chemical events produce color-coded spark bursts for instant visual identification:

Special Effects

• Plasma Sparks: Small glowing particles (1–4px radius) that fly outward from interaction sites. Color varies by event type.
• Ripples: Expanding circles from shattering events. White/black depending on theme, 1px stroke, fade over 50 frames.
• Valency Ghosts: Small dots orbiting atoms with unfilled valence shells (8px orbit, 1.5px size).
• Charge Labels: '+' or '−' symbols near charged atoms (10px monospace font, red for +, blue for −).

Heatmap Mode

When enabled, particle colors are replaced by velocity-based heatmap:

• Intensity = min(1, speed / 5.0)
• Hue = 240 × (1 − intensity)
• Blue (240°) = stationary
• Cyan (180°) = slow
• Green (120°) = medium
• Yellow (60°) = fast
• Red (0°) = very fast (> 5 units/frame)

Architecture & Algorithms

Core Systems

Physics Integration

Structural Detection

Geometry Enforcement

Update Scheduling v28.0+

Systems run at different intervals to balance accuracy against performance. All intervals are in frames at 60 FPS.

Performance Optimizations v32.0

• Configurable FPS Cap: Server-side via CHAOS_FPS_CAP constant — or live at runtime via CHAOS_API.fpsLimit = 0 (0 = uncapped)
• SoA Physics Kernel: All particle state in flat TypedArrays — sequential memory access eliminates GC and maximizes cache hit rate
• Pre-allocated Scratch Buffers: Ring solver uses Uint16Array(64) / Float64Array(64) per-frame — zero allocations in hot path
• WebGL2 Instanced Bond Draw: Single drawArraysInstanced() replaces N gradient stroke calls
• Bitmask Aromatic Flags: (_flagsBuf[i] & FLAG_IS_AROMATIC) — bitwise op vs object property lookup
• Task Breaking (TBT): Physics dispatched via setTimeout(0) after draw — splits render and physics into separate browser tasks, reducing Total Blocking Time
• Reaction Throttling: Chemistry evaluated every 10 frames (6 Hz)
• Structure Detection: Runs every 30 frames (2 Hz)
• Trail Subsampling: Records position every 4 frames, max 60 points
• High Performance Mode: Auto-engages below 24 FPS (2-second window)
• Grid-Based Culling: Only checks particles in adjacent 9-cell neighborhood
• Rearrangement Cap: All reactive systems share a hard limit of 5 events per frame

Memory Architecture v32.0

Batched Rendering Architecture v32.0

To bypass the high CPU overhead of the Canvas2D API's createLinearGradient and individual stroke() calls, the engine utilizes a custom data-oriented batching system.

HPC Kernel Profiler v32.0

A built-in telemetry system measures every physics sub-system over a 150-frame rolling window and prints a formatted ASCII table to the browser console.

Rendering Pipeline

1. Clear canvas
2. Draw grid (if enabled)
3. Draw flow field vectors (if enabled)
4. Update particle colors (heatmap or type-based)
5. Draw trails (if enabled)
6. Draw bonds — gradient mode selects between: default color, stress, or electronegativity (v28.0)
7. Draw hydrogen bonds (dashed lines)
8. Draw probe connections (dashed, fading)
9. Draw aromatic electrons (rotating)
10. Draw conjugated electrons (flowing)
11. Draw cumulene glow (pulsing)
12. Draw particles (atoms as circles, probes as triangles)
13. Draw formal charge labels (v28.1, if toggle ON)
14. Draw radical indicators (v28.0, if toggle ON)
15. Draw molecule name labels (if toggle ON, including H₃O⁺/OH⁻)
16. Draw valency ghosts (orbiting dots)
17. Draw sparks/ripples/click nodes
18. Draw pH background tint (if toggle ON)

Engine Internals

This section documents the modular subsystems that support the core simulation — the gamification engine, the scripted showcase theater, and the HUD architecture.

Event System & Gamification v28.5+

A comprehensive achievement engine tracks over 120 discrete events across 15 categories, powered by a statistics model that records every meaningful interaction in the simulation.

Chemical Showcase Theater

The scripted reaction demonstration system powers the interactive chemistry showcase, displaying 24 real chemical reactions with deterministic visual outcomes.

Reaction Categories (5)

Phase-State Machine (FSM)

Isolation Architecture

• iframe Sandbox: Each reaction runs in a dedicated <iframe> with its own Chaos Engine instance — fully isolated from the main simulation.
• Per-Reaction Configuration: Temperature, atom ratios, pH, seed, and particle count are set independently for each reaction to guarantee optimal viewing conditions.
• Spawn Geometry: Reactant atoms are placed at calculated distances with directed velocities, guaranteeing collisions within 3–8 seconds regardless of seed.
• Proximity Watchdog: A 400ms polling interval monitors inter-atom distances. If reactants drift beyond threshold, gentle corrective forces re-engage.
• Director Fallback: If the engine's stochastic chemistry hasn't triggered the reaction within the scheduled window, the director programmatically forces approach phase — ensuring every showcase completes reliably.

HUD & UI Architecture

The Head-Up Display is a modular control panel that exposes 50+ engine parameters via an on-demand lazy-loaded architecture.

Loading Architecture

Control Groups

Performance Monitor

Responsive Behavior

• 1400px+: Full side panel with all controls visible.
• 1200px–1400px: Compressed layout, smaller slider labels.
• 1024px–1200px: Two-column grid for parameter groups.
• < 1024px (mobile): Bottom-sheet overlay with enlarged touch targets (34px), simplified diagnostics (histogram only), and swipe-to-dismiss.
• Pin Toggle (📌): Keeps HUD open when mouse leaves the panel area.
• Collapsible Groups: Each control group remembers its collapse state per session.

Molecule Hover Tooltips

Advanced Features & Tips

Configuration Export/Import System

The engine supports full state serialization using Base64-encoded JSON snapshots.

Export Format (Decoded)

{
  "version": "32.0",
  "timestamp": 1704067200000,
  "settings": {
    "seed": 12345,
    "atomCount": 250,
    "temp": 0.5,
    "ratios": { "C": 25, "H": 20, ... },
    "showElectronegativity": false,
    "showFormalCharges": false,
    "showRadicals": false,
    ...
  },
  "particles": [
    {
      "x": 512.3, "y": 384.7,
      "vx": 0.12, "vy": -0.34,
      "type": "C", "isAtom": true,
      "bonds": [1, 5, 12], "id": 0,
      "ringState": 6, "isAromatic": true,
      "formalCharge": 0, "isRadical": false,
      "isHydronium": false, "isHydroxide": false,
      ...
    },
    ...
  ],
  "uidCounter": 256
}

Import Behavior

• Seed-Only: If input is pure digits (e.g., "12345"), treats as seed and generates new random simulation
• Full Snapshot: If Base64-encoded JSON, restores exact particle positions, velocities, bonds, and all settings
• Validation: Invalid codes show alert "Invalid Configuration Code"
• UI Refresh: Automatically updates all sliders to match imported settings

Hidden Mechanics & Easter Eggs

Debugging & Development

Mobile Optimizations

• Auto-Scaling: 0.55× scale multiplier for all distances and radii
• Reduced Particles: Default 150 atoms (vs 250 desktop)
• Slower Flow Morphing: 0.4× time factor for turbulence evolution
• UI Adjustments: Larger touch targets (34px gear button), bottom-centered menu
• Diagnostics Hidden: FPS panel hides detailed diagnostics on mobile (histogram only)

Common Workflows

Known Quirks & Gotchas

• Rejoin Cooldown: After thermal elimination, ejected H/Cl atoms have 120-frame cooldown. They can't rebond immediately. HCl dissociation gives Cl⁻ a 90-frame cooldown separately.
• Aromatic Immunity: Benzene rings resist 80% of triangle purge attempts and 100% of turbulence shear.
• Probe Cooldown Visualization: Gray overlay means probe is in cooldown (can't form new connections).
• Grid Reset Required: Changing atom count doesn't take effect until "Flip Table" is pressed.
• Configuration Persistence: Settings are NOT saved to localStorage (unlike theme preference). Use export code to save states.
• Seed Determinism: Same seed = same initial positions, but reactions are still stochastic. Two runs may diverge after ~10 seconds.
• Acid-Base Rate Limiting: Neutralization, proton donation, autoionization, and HCl dissociation all share the 5-rearrangements-per-frame cap with the stabilization system. In very dense ion-heavy systems, some reactions queue for the next cycle.
• pH Smoothing: At neutral balance, pH exponentially decays toward 7 (factor 0.95/frame) rather than jumping. This prevents flickering.

Accessibility & Motion Safety

The Chaos Engine implements a comprehensive accessibility layer that respects user preferences and ensures the simulation never causes discomfort or unwanted resource consumption.

Motion Safety (prefers-reduced-motion)

Performance & Battery Considerations

• Visibility API: Animation loop pauses when the browser tab is not visible (document.hidden), eliminating background CPU usage.
• 60 FPS Cap: Hard frame-rate limit prevents unnecessary GPU cycles on high-refresh-rate displays (120Hz, 144Hz).
• Adaptive Quality: High Performance Mode automatically reduces visual fidelity on low-end devices before battery drain becomes significant.
• Idle Startup: requestIdleCallback with 30ms budget chunks ensures engine initialization never blocks Largest Contentful Paint or First Input Delay.