3dfusion

A deterministic, 3D world runtime for modern browsers.

Overview

3dfusion is a packaged runtime that moves core 3D simulation, procedural generation, and rendering orchestration into WebAssembly, exposing a clean, predictable API for JavaScript and TypeScript consumers. Designed for browser delivery, it provides deterministic terrain and chunk generation, memory-managed mesh pipelines, rigid-body physics, adaptive streaming, and runtime telemetry without requiring consumers to manage internal engine architecture.

The project emphasizes:

• Predictable outputs from stable seeds and deterministic pipelines
• Browser-first delivery with optimized WASM artifacts and lightweight JS bindings
• Explicit resource management to maintain stable memory profiles in long-running sessions

Key Features

• Deterministic Generation & Streaming
  Seeded terrain and chunk production, heightfield sampling, and bounded streaming around a moving viewpoint with motion-aware prioritization.
• Geometry & Mesh Pipeline
  Primitive and semantic geometry construction, procedural mesh generation with LOD support, and direct vertex and index buffer access.
• Physics & Rendering Orchestration
  Fixed-step rigid-body simulation, configurable spatial broadphase, and renderer-side draw queueing with material and shader variant support.
• Performance & Memory Management
  Frame scheduling, execution-path optimization, memory budgeting with priority-based upload queues, and automated resource eviction.
• Telemetry & Diagnostics
  Centralized dashboard payload generation, debug control overrides, mobile and touch input tracking, and per-stage performance breakdowns.
• Explicit Lifetime Management
  Structured disposal via free() and [Symbol.dispose]() for deterministic cleanup of native WASM resources.

Quick Start

npm install 3dfusion

import { init, TerrainGenHandle, MeshGeneratorHandle, StreamerHandle } from "3dfusion";

async function main() {
  await init();

  const terrainGen = new TerrainGenHandle(0, 50.0, 0.01, 64, 64.0);
  const streamer = new StreamerHandle(12345n, "", 0, 50.0, 0.01, 64, 64.0);
  streamer.set_active_region(3, 2, 2);
  streamer.set_budget(8, 12);
  streamer.update(0, 0, 0);

  const heightfield = terrainGen.generate_heightfield(12345n, 0, 0, 0, 0);
  const mesh = heightfield.toMesh(terrainGen, 12345n, 0, 0, 0, 0);

  console.log(`Generated mesh: ${mesh.vertex_count()} vertices`);
}

main();

Architecture

3dfusion follows a strict separation between the core simulation layer and the browser integration surface:

1. Rust Core: All deterministic logic, simulation, and data structures are implemented in Rust.
2. WebAssembly Compilation: The core is compiled to wasm32-unknown-unknown for near-native browser execution.
3. Binding Generation: wasm-pack produces JavaScript and TypeScript bindings, handles memory marshaling, and exposes the public API surface.
4. Supplemental Tooling: Debug panels, diagnostic dashboards, and platform harnesses are bundled as lightweight JS modules.
5. Distribution: The final artifact is packaged for direct consumption via standard module bundlers.

Development

Prerequisites

• Rust stable toolchain
• wasm-pack
• Node.js

Setup & Commands

rustup target add wasm32-unknown-unknown
npm install
npm run build:wasm
npm run dev

Build Script Behavior

• If wasm-pack is unavailable but cargo is present, the build script installs it automatically.
• wasm-opt is applied when available to reduce release artifact size; builds gracefully fall back if absent.
• The development script installs missing vite dependencies before launching the local server.

Documentation

The complete API reference, including handle constructors, method signatures, and expected behavior, is documented in FUNCTIONALITY.md.

The reference covers:

• runtime bootstrap
• semantic parsing and geometry authoring
• mesh generation, bounds reporting, and buffer extraction
• terrain and chunk generation plus streaming controls
• physics, rendering, scheduling, optimization, and memory management
• platform diagnostics and telemetry payloads

Best Practices

• Explicit Disposal: Always call handle.free() or use [Symbol.dispose]() when handles are no longer needed.
• Frame Budgets: Respect work and upload budgets to maintain consistent frame pacing, especially on mobile or constrained environments.
• Deterministic Seeding: Use consistent world_seed values for reproducible terrain, chunk, and streaming outputs.

For integration support, bug reports, or contribution guidelines, refer to the project repository.