⚡ Why Hypercube Engine?

Most physics or interactive simulations in JavaScript create thousands of objects ([{x, y, vx, vy}, ... ]). As the simulation grows, this leads to excessive CPU branching, Garbage Collection (GC) pauses, and cache misses. Eventually, the browser or Node process hangs.

Hypercube Engine turns this upside down. It uses a Contiguous Memory Architecture built on Float32Array or SharedArrayBuffer.

By structuring state as mathematical tensors ("faces" of a cube) rather than discrete logical objects:

• Computations are naturally vectorized.
• Performance is consistently O(1).
• Memory allocations during the computing loops are exactly 0.
• Multi-threading (via Web Workers & SharedArrayBuffer) and WebGPU hardware acceleration become trivial because all data is already in a raw binary buffer format.

If you are trying to implement Cellular Automata, Fluid Dynamics (LBM), Heat Diffusion, or massive procedurally generated ecosystems in JavaScript without resorting to C++ WebAssembly, Hypercube provides the high-performance memory layout you need.

🚀 Native 3D Compute (NEW in V4)

V4 introduces native 3D tensor support, allowing simulations to scale across [nx, ny, nz] dimensions while maintaining O(1) complexity.

🔥 Volume Diffusion Engine

A specialized 3D solver with a 7-point stencil and periodic boundaries.

• Hybrid Compute: Support for both CPU (multithreaded) and WebGPU hardware acceleration.
• Dynamic Limits: Adapts workgroup sizes (256 to 1024 threads) based on the physical GPU adapter limits.
• Applications: Smoke, heat, chemical concentration, volumetric fog.
• Performance: 64³ grid (262k voxels) processed in ~3ms on CPU and <1ms on GPU (compute only). 128³ grid remains playable at 60 FPS on compatible hardware.

🎨 Visualization Helpers

• IsoRenderer: 2.5D Isometric projection on Canvas 2D with depth sorting.
• MarchingCubes (Light): High-speed surface extraction for volumetric data.
• ThreeJS Bridge: Easy export to THREE.Data3DTexture and BufferGeometry.

🚀 Built-in Engines (The Showcase)

Hypercube comes out of the box with highly optimized, pre-built physics engines to demonstrate its power.

💨 Aerodynamics Engine (Lattice Boltzmann D2Q9)

A fully continuous computational fluid dynamics solver. It forces "wind" through a wind tunnel using the BGK collision operator. You can draw obstacles into the obstacles tensor, and the fluid will realistically compress and flow around them, producing Von Kármán vortex streets.

WEBGPU Performance: The LBM engine is fully ported to WGSL, capable of 60 FPS simulations with complex vorticity calculations entirely on the GPU.

Real-time fluid vorticity calculated at 60 FPS via WebGPU.

🌊 Ocean Simulator

An open-world toric-bounded oceanic current simulator powered by the D2Q9 LBM Engine, coupled with a procedural Heatmap generator. It computes fluid velocity and allows simple Boat entities to be routed across the continuous fluid grid.

🗺️ Flow-Field Engine (V3)

A massive crowd pathfinding engine generating an O(1) integration and vector field. Utilizing a multi-pass WebGPU Compute Shader (or CPU wavefront fallback), it can guide 10,000+ agents to a target simultaneously without per-entity path calculation overhead.

🧬 GameOfLife Ecosystem (O1 Tile)

Un automate cellulaire repensé en écosystème organique cyclique (Rock-Paper-Scissors). Les états (Plantes, Herbivores, Carnivores) naissent, survivent ou meurent selon des probabilités stochastiques et des voisinages pondérés (Von Neumann fort, Moore faible).

Visuel Soft : En plus de stocker l'état (Face 1), l'écosystème génère continuellement une carte de densité/âge (Face 3) allant de 0.0 à 1.0. Cette matrice peut être envoyée directement au HeatmapEngine pour un rendu organique flou et continu, sans l'effet "gros pixels" rigides habituels des Game of Life primitifs.

Faces clés

• Face 1 : L'état discret de l'espèce (0=Vide, 1=Plante, 2=Herbi, 3=Carni).
• Face 2 : Écriture (Swap internal memory).
• Face 3 : L'âge ou la densité de masse (0.0 → 1.0) idéale pour les gradients.

🔥 Heatmap Engine – Spatial Diffusion O(1) via Summed Area Table (V3)

Generates a heatmap or influence map from a binary/context map in O(N) total time (independent of the radius size).

Used Faces:

• Face 1: Input (sources / binary context, e.g., agent density, hot obstacles, POIs)
• Face 4: SAT temp buffer (Summed Area Table) – reserved during compute
• Face 2: Output – final smoothed heatmap (weighted influence)

Typical Usage

const engine = new HeatmapEngine(20, 0.05); // Radius 20, Weight 0.05
grid.setEngine(engine); 
await grid.compute();
const heatmap = grid.cubes[0][0].faces[2]; // Float32Array ready for rendering!

Advantages

• Arbitrary box filter in O(N) instead of O(N·R²)
• Perfect for: Crowd heatmaps, risk zones, spatial blur, simple influence propagation
• GPU: Hillis-Steele parallel scan + 3 compute passes -> extremely fast even on mobile

🌊 OceanEngine – Shallow Water + Plankton Dynamics (D2Q9 LBM)

Simulation océanique simplifiée : courants, tourbillons, forcing interactif (vortex souris), + croissance/diffusion plancton.

Faces clés

• 0–8 : f (populations LBM)
• 9–17 : f_post (post-collision temp)
• 18 : ux (courant X)
• 19 : uy (courant Y)
• 20 : rho (densité/masse)
• 21 : bio (plancton/concentration spatiale)
• 22 : obst (îles/murs fixes à 1.0)

Interaction & Paramètres
tau_0 (relaxation globale), smagorinsky (bruit turbulent), vortexRadius/Strength pour paramétrer un tourbillon injecté à la position de la souris !

Multi-chunk LBM validé
OceanEngine conserve une masse parfaite (perte < 0.1 % sur 2000+ steps) même sur une grille 2×2 (ou plus).
Il suffit d’appeler grid.compute() (le composant se chargeant automatiquement de synchroniser les faces 0 à 8 aux interfaces).
→ Preuve que l’architecture zero-copy + boundary exchange est robuste pour solvers distribués.

☁️ Simplified Fluid Dynamics (V3)

A lightweight Eulerian fluid simulator using pure Advection and Bilinear Sampling. Designed to simulate smoke, gases, and empirical thermal buoyancy directly via WebGPU float32 arrays.

Minimal Example (/examples/fluid-simple.ts):

import { HypercubeGrid, HypercubeMasterBuffer, FluidEngine } from 'hypercube-compute';

const masterBuffer = new HypercubeMasterBuffer(1024 * 1024);
const grid = await HypercubeGrid.create(
    1, 1, 64, masterBuffer,
    () => new FluidEngine(1.0, 0.4, 0.98),
    6, false, 'cpu', false
);

// Splat some heat & density, then compute
const engine = grid.cubes[0][0]?.engine as FluidEngine;
engine.addSplat(grid.cubes[0][0]?.faces!, 64, 32, 60, 0, 0, 10, 1.0, 5.0);
await grid.compute();

🔒 Security & Performance (COOP/COEP)

Hypercube Engine leverages SharedArrayBuffer for zero-copy CPU multi-threading and high-speed data exchange with Workers.

Due to browser security requirements (Spectre/Meltdown mitigation), your web server MUST send the following headers to enable SharedArrayBuffer:

• Cross-Origin-Embedder-Policy: require-corp
• Cross-Origin-Opener-Policy: same-origin

If these headers are missing: The engine fallback to a standard ArrayBuffer (single-threading only).

📦 Installation

npm install hypercube-compute

License: MIT (Open Source, use it for anything!)

💡 Quick Start: See the "Wow" in 20 Lines

The easiest way to start is the Game of Life (O1 Ecosystem). Copy-paste this into an index.ts:

import { HypercubeGrid, HypercubeMasterBuffer, GameOfLifeEngine, HypercubeViz } from 'hypercube-compute';

// 1. Setup Canvas & Memory
const canvas = document.querySelector('canvas')!;
const master = new HypercubeMasterBuffer(); 
const grid = await HypercubeGrid.create(1, 1, 128, master, () => new GameOfLifeEngine(), 3);

// 2. Main Loop
const loop = () => {
    grid.compute(); // Process tensor logic O(1)
    
    // 3. Render directly (Face 2 = Organic Density/Age)
    const faceData = grid.cubes[0][0].faces[2]; 
    HypercubeViz.quickRender(canvas, faceData, 128); // Plug & Play!
    
    requestAnimationFrame(loop);
};
loop();

💨 Want Fluid? (Ocean Engine)

To see vortices instead of cells, use the Ocean Engine:

const grid = await HypercubeGrid.create(1, 1, 256, master, () => new OceanEngine(), 23);

const loop = () => {
    // Sync all LBM populations (Faces 0-8)
    grid.compute([0, 1, 2, 3, 4, 5, 6, 7, 8]); 

    const curl = grid.cubes[0][0].faces[21]; // Vorticity/Rotation
    HypercubeViz.renderToCanvas(canvas, curl, 256, 256, 'heat');
    
    requestAnimationFrame(loop);
};

🏗 Architecture Overview

---
title: Hypercube Architecture - Contiguous O(1) Memory
---
graph TD
    A[HypercubeMasterBuffer<br>Raw ArrayBuffer] -->|Partitions| B(HypercubeGrid)
    
    B --> C1[HypercubeChunk<br>Chunk A]
    B --> C2[HypercubeChunk<br>Chunk B]
    
    C1 <-->|Face-to-Face Data Link| C2
    
    C1 -->|Holds| F1[Face 0: Float32Array]
    C1 -->|Holds| F2[Face 1: Float32Array]
    C1 -->|Holds| F3[Face N: Float32Array]
    
    F1 -.->|Pointers Pass to| E[IHypercubeEngine<br>Physics Logic]
    F2 -.->|Pointers Pass to| E

🗺️ Engine & Face Dictionary

Hypercube uses Faces (tensor layers) instead of objects. Use this table as your "Cheat Sheet":

| Engine | Face | Usage Snippet | Description | | :--- | :--- | :--- | :--- | | GameOfLife | 1 | chunk.faces[1] | Discrete State (0=Empty, 1=Plant, 2=Herbi, 3=Carni) | | | 2 | chunk.faces[2] | Visual Density/Age (0.0 to 1.0) - Perfect for "soft" renders | | Heatmap | 0 | chunk.faces[0] | Inputs (binary sources) | | | 2 | chunk.faces[2] | Result (Blurred spatial influence map) | | Ocean/LBM | 18 | chunk.faces[18] | Velocity X (Horizontal current) | | | 21 | chunk.faces[21] | Curl/Vorticity (Rotation/Eddies of the fluid) | | | 22 | chunk.faces[22] | Obstacles (1.0 = Wall, 0.0 = Fluid) | | Vol. Diffusion | 0 | chunk.faces[0] | Input Concentration (3D Grid) |

⚡ Live Interaction & Parameters

Important: All parameters can be changed in live without rebuilding the grid or the engine.

const engine = grid.cubes[0][0].engine as VolumeDiffusionEngine;
engine.diffusionRate = 0.15; // Updated in the next grid.compute()

🎮 Mouse Interaction

Inject data (vortices, heat, etc.) directly into the tensors:

canvas.onmousemove = (e) => {
    const engine = grid.cubes[0][0].engine as OceanEngine;
    engine.addVortex(grid.cubes[0][0].faces, e.offsetX, e.offsetY, 15.0); 
};

⚙️ Hardware Acceleration (WebGPU)

Hypercube auto-detects support, but for maximum perf:

🚀 Activate WebGPU

await HypercubeGPUContext.init(); // MUST call this first
const grid = await HypercubeGrid.create(..., 'gpu'); 
console.log(grid.isGpuReady); // Fallback to 'cpu' if hardware is unsupported

� Multi-threading (SharedArrayBuffer)

Requires these server security headers:

• Cross-Origin-Embedder-Policy: require-corp
• Cross-Origin-Opener-Policy: same-origin

🌐 Live Demos

👉 View Interactive Multi-Engine Demo

• Switch Engines: Use the buttons to swap logic.
• Interact: Click and drag to create vortices or draw obstacles.
• 3D: Check the 07-volume-diffusion-3d example for volumetric rendering.

🤖 AI-Friendly Guidelines (For Copilots)

1. Never use standard arrays for physics. Use chunk.faces[n].
2. Iterations must be flat: const idx = y * size + x. No .map().
3. Stick to GodMode V8 loops (raw C-style) for O(1) efficiency.

Built with passion for high-performance creative computing.