WASM Modules

import init, {
  update_world_transforms,
  update_quaternions_from_euler,
  compute_transform_matrices,
} from '@web-engine-dev/wasm';
 
// Initialize WASM module once at startup
await init();
 
// Update world transforms for entire entity hierarchy
// Processes parent-child relationships recursively in O(n) time
update_world_transforms(
  localPositions,      // Float32Array: [x, y, z] per entity
  localRotations,      // Float32Array: [x, y, z] Euler angles per entity
  localScales,         // Float32Array: [x, y, z] per entity
  localQuaternions,    // Float32Array: [x, y, z, w] per entity
  parents,             // Uint32Array: parent entity ID per entity
  entityIds,           // Uint32Array: entity IDs being processed
  outWorldPositions,   // Float32Array: output world positions
  outWorldRotations,   // Float32Array: output world rotations
  outWorldScales,      // Float32Array: output world scales
  outWorldQuaternions  // Float32Array: output world quaternions
);
 
// Convert Euler angles to quaternions (batch operation)
update_quaternions_from_euler(
  rotations,      // Float32Array: [x, y, z] Euler angles (radians)
  quaternions,    // Float32Array: output [x, y, z, w] quaternions
  entityIds       // Uint32Array: entity IDs
);
 
// Compute 4x4 matrices for instanced rendering
compute_transform_matrices(
  positions,   // Float32Array: world positions
  rotations,   // Float32Array: Euler rotations
  scales,      // Float32Array: scale vectors
  quaternions, // Float32Array: quaternions (preferred)
  entityIds,   // Uint32Array: entity IDs
  matrices     // Float32Array: output 4x4 matrices (16 floats each)
);

import { PhysicsWorld } from '@web-engine-dev/wasm';
 
// Create physics world
const physics = new PhysicsWorld();
 
// Bulk add bodies (single FFI call vs n calls)
physics.add_bodies_batch(
  entityIds,        // Uint32Array: entity IDs
  positions,        // Float32Array: initial positions [x, y, z]
  isDynamicArray    // Uint8Array: 0 = static, 1 = dynamic
);
 
// Update body properties in batch
physics.update_bodies_batch(
  entityIds,    // Uint32Array: entity IDs to update
  masses,       // Float32Array: mass per entity
  frictions,    // Float32Array: friction coefficients
  restitutions  // Float32Array: restitution (bounciness)
);
 
// Step simulation
physics.step(deltaTime);
 
// Sync physics state back to ECS (SIMD-accelerated)
const syncedCount = physics.sync_states_simd_bulk(
  positions,           // Float32Array: output positions
  rotations,           // Float32Array: output rotations
  entityIds,           // Uint32Array: entity IDs
  velocities,          // Float32Array: output velocities
  angularVelocities,   // Float32Array: output angular velocities
  true,                // use_velocities
  true                 // use_angular_velocities
);
 
// Raycast with shapecast support
const hit = physics.raycast(
  originX, originY, originZ,
  directionX, directionY, directionZ,
  maxDistance
);
if (hit) {
  console.log(`Hit entity ${hit.eid} at distance ${hit.toi}`);
}

import { OctreeBvh, SpatialGrid, cull_entities } from '@web-engine-dev/wasm';
 
// Create octree for hierarchical culling
const octree = new OctreeBvh(
  100000,  // max entities
  8        // max depth
);
 
// Rebuild octree from entity data
octree.rebuild(
  positions,   // Float32Array: [x, y, z] per entity
  radii,       // Float32Array: bounding sphere radius per entity
  entityIds,   // Uint32Array: entity IDs
  count        // number: entity count
);
 
// Frustum cull with front-to-back traversal
const visibleCount = octree.frustum_cull(
  viewProjMatrix,   // Float32Array: 4x4 view-projection matrix
  cameraPos,        // Float32Array: [x, y, z] camera position
  outVisibility,    // Uint8Array: visibility mask (indexed by EID)
  outVisibleIds     // Uint32Array: ordered list of visible entity IDs
);
 
console.log(`Visible: ${visibleCount} / ${count}`);
 
// Get octree statistics
const stats = octree.stats;
console.log(`Nodes: ${stats.node_count}, Leaves: ${stats.leaf_count}`);
console.log(`Depth: ${stats.max_depth}, Avg occupancy: ${stats.average_leaf_occupancy}`);
 
// Alternative: Simple frustum culling without octree
cull_entities(
  positions,      // Float32Array: entity positions
  radii,          // Float32Array: bounding radii
  count,          // number: entity count
  viewProjMatrix, // Float32Array: view-projection matrix
  outVisibility   // Uint8Array: output visibility mask
);

import { BatchCompressionWASM, CompressionConfig } from '@web-engine-dev/wasm';
 
// Create compression instance
const compressor = new BatchCompressionWASM(10000); // max entities
 
// Configure compression thresholds
const config: CompressionConfig = {
  enable_simd: true,
  position_threshold: 0.01,      // 1cm position change
  rotation_threshold: 0.001,     // ~0.06 degree rotation change
  velocity_threshold: 0.1,       // 10cm/s velocity change
  quantization_scale: 1000.0     // quantize to millimeters
};
 
// Compress entity state batch
const result = compressor.compress_batch(
  currentPositions,   // Float32Array: current frame positions
  previousPositions,  // Float32Array: previous frame positions
  currentRotations,   // Float32Array: current frame quaternions
  previousRotations,  // Float32Array: previous frame quaternions
  currentVelocities,  // Float32Array: current frame velocities
  previousVelocities, // Float32Array: previous frame velocities
  config
);
 
console.log(`Compression: ${result.compression_ratio.toFixed(2)}x`);
console.log(`Size: ${result.compressed_size} / ${result.uncompressed_size} bytes`);
console.log(`Time: ${result.processing_time_ms.toFixed(2)}ms`);
console.log(`SIMD ops: ${result.simd_operations}`);
 
// Low-level delta computation (SIMD-accelerated)
const changedCount = compressor.compute_position_deltas_simd(
  currentPositions,
  previousPositions,
  deltaOutput,
  threshold
);

# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 
# Install wasm-pack
cargo install wasm-pack
 
# Add wasm32 target
rustup target add wasm32-unknown-unknown

# Navigate to WASM package
cd packages/wasm
 
# Build optimized WASM binary (production)
pnpm run build
 
# Build with SIMD support (requires browser support)
pnpm run build:simd
 
# Development build (faster compilation, larger binary)
wasm-pack build --target web --dev
 
# Run Rust tests
cargo test
 
# Run WASM tests in headless browser
wasm-pack test --headless --firefox

[profile.release]
opt-level = 3              # Maximum optimization
lto = true                 # Link Time Optimization
codegen-units = 1          # Single codegen unit for better optimization
panic = "abort"            # Smaller binary size
strip = true               # Strip debug symbols
 
[package.metadata.wasm-pack.profile.release]
wasm-opt = [
  "-O3",                   # Maximum optimization
  "--enable-simd",         # SIMD instructions
  "-ffm",                  # Fast float math
  "--precompute-propagate" # Aggressive constant propagation
]

// Allocate data in JavaScript (you own this memory)
const positions = new Float32Array(entityCount * 3);
const matrices = new Float32Array(entityCount * 16);
 
// Pass to WASM (zero-copy, shares memory)
compute_transform_matrices(
  positions,   // Rust sees this as &[f32]
  rotations,
  scales,
  quaternions,
  entityIds,
  matrices     // Rust sees this as &mut [f32]
);
 
// Data is modified in-place, no copies made
console.log(matrices[0]); // Updated by WASM
 
// WASM objects need manual disposal
const octree = new OctreeBvh(10000, 8);
// ... use octree ...
octree.free(); // Release WASM memory

// Check SIMD support at runtime
const simdSupported = WebAssembly.validate(
  new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0, 1, 5, 1, 96, 0, 1, 123, 3, 2, 1, 0, 10, 10, 1, 8, 0, 65, 0, 253, 15, 253, 98, 11])
);
 
if (simdSupported) {
  console.log('WASM SIMD available - using optimized code paths');
} else {
  console.log('WASM SIMD unavailable - using scalar fallback');
}
 
// Most WASM functions automatically use SIMD when available
// Some modules provide explicit control:
const config = {
  enable_simd: simdSupported,
  // ... other config
};

// Auto-generated TypeScript definitions
export function update_world_transforms(
  local_positions: Float32Array,
  local_rotations: Float32Array,
  local_scales: Float32Array,
  local_quaternions: Float32Array,
  parents: Uint32Array,
  entity_ids: Uint32Array,
  out_world_positions: Float32Array,
  out_world_rotations: Float32Array,
  out_world_scales: Float32Array,
  out_world_quaternions: Float32Array
): void;
 
export class PhysicsWorld {
  constructor();
  free(): void;
  step(dt: number): void;
  add_body(eid: number, x: number, y: number, z: number, is_dynamic: boolean): void;
  // ... all methods fully typed
}
 
export class OctreeBvh {
  constructor(max_entities: number, max_depth: number);
  free(): void;
  rebuild(positions: Float32Array, radii: Float32Array, entity_ids: Uint32Array, count: number): void;
  frustum_cull(view_proj_matrix: Float32Array, camera_pos: Float32Array, out_visibility: Uint8Array, out_visible_ids: Uint32Array): number;
  readonly stats: OctreeStats;
}

import init, { wasm_version } from '@web-engine-dev/wasm';
 
try {
  await init();
  console.log(`WASM version: ${wasm_version()}`);
} catch (error) {
  console.error('WASM initialization failed:', error);
}
 
// WASM panics are caught and displayed in console with full Rust backtrace
// Example panic output:
// panicked at 'index out of bounds: the len is 1000 but the index is 1001', src/transform.rs:42:5
 
// Enable source maps for better debugging (development builds only)
// Production builds are stripped and optimized

// Initialize WASM once at app startup
import init from '@web-engine-dev/wasm';
 
let wasmInitialized = false;
 
export async function initializeWasm() {
  if (wasmInitialized) return;
 
  try {
    await init();
    wasmInitialized = true;
    console.log('WASM initialized successfully');
  } catch (error) {
    console.error('Failed to initialize WASM:', error);
    throw error;
  }
}
 
// Call before using any WASM functions
await initializeWasm();

// ❌ Bad: Multiple FFI calls (slow)
for (let i = 0; i < entities.length; i++) {
  physics.add_body(entities[i], x[i], y[i], z[i], true);
}
 
// ✅ Good: Single batch call (fast)
physics.add_bodies_batch(entityIds, positions, isDynamicArray);
 
// Minimize FFI boundary crossings
// Each JS -> WASM call has overhead (~10-50ns)
// Process data in large batches to amortize this cost

// ❌ Bad: Allocate new arrays every frame
function update() {
  const positions = new Float32Array(count * 3);
  const matrices = new Float32Array(count * 16);
  compute_transform_matrices(positions, rotations, scales, quaternions, entityIds, matrices);
}
 
// ✅ Good: Reuse pre-allocated buffers
const positions = new Float32Array(MAX_ENTITIES * 3);
const matrices = new Float32Array(MAX_ENTITIES * 16);
 
function update() {
  compute_transform_matrices(positions, rotations, scales, quaternions, entityIds, matrices);
}
 
// Zero allocations in the hot path