Babylon.js NOA Engine Integration

Overview

Nova64 includes an optional, guarded integration with noa-engine, an experimental voxel game engine built on Babylon.js. The adapter is opt-in and must not replace Nova64's shared voxel API: existing carts should continue to call the normal voxel functions whether NOA is active or unavailable.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Cart (game code)                         │
│              uses nova64.voxel API (api-voxel.js)               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      runtime/api-voxel.js                       │
│            Shared voxel API - backend agnostic                  │
│   (terrain gen, physics, entities, lighting, persistence)       │
└─────────────────────────────────────────────────────────────────┘
                                │
                ┌───────────────┼───────────────┐
                ▼               ▼               ▼
┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│   Three.js GPU   │  │  Babylon.js GPU  │  │  Babylon.js GPU  │
│   (gpu-three.js) │  │  (voxel.js)      │  │  + NOA Adapter   │
│                  │  │                  │  │  (noa-adapter.js)│
└──────────────────┘  └──────────────────┘  └──────────────────┘
        │                       │                    │
        ▼                       ▼                    ▼
┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│   Three.js       │  │   Babylon.js     │  │   noa-engine     │
│   WebGL Renderer │  │   WebGL Engine   │  │   (optional)     │
└──────────────────┘  └──────────────────┘  └──────────────────┘

Dependency

noa-engine is an optional dependency pinned to the latest published 0.33.x line. In the Nova64 repo, install through the normal WSL workflow:

pnpm install

If a package manager skips optional dependencies, the adapter reports a graceful inactive status and Babylon continues to use Nova64's built-in voxel renderer.

Usage

Checking NOA Availability

// Check if NOA adapter is available (Babylon.js backend only)
const status = getVoxelNoaAdapterStatus();
console.log(status);
// { initialized: false, active: false, version: '0.1.0', ... }

Enabling NOA Adapter

// Enable NOA adapter (async; Babylon.js backend only)
const result = await enableVoxelNoaAdapter({
  debug: false,
  chunkSize: 16,
  renderDistance: 4,
});

if (result.active) {
  console.log('NOA adapter is now active!');
  console.log('Features:', result.features);
  // { physics: true, entities: true, terrain: true, meshing: true }
}

Checking NOA Status

// Check if NOA is currently active
if (isVoxelNoaActive()) {
  console.log('Using NOA-enhanced voxel backend');
} else {
  console.log('Using standard voxel backend');
}

Disabling NOA Adapter

// Disable NOA and return to standard backend
disableVoxelNoaAdapter();

Backwards Compatibility

Existing cart-facing voxel APIs must keep working whether NOA is active or not:

• updateVoxelWorld(x, z) - Load/unload chunks around position
• getVoxelBlock(x, y, z) - Get block type at position
• setVoxelBlock(x, y, z, blockId) - Set block at position
• raycastVoxelBlock(origin, direction, distance) - Raycast for block selection
• moveVoxelEntity(pos, velocity, size, dt) - Physics with collision detection
• spawnVoxelEntity(type, pos, opts) - Spawn entities
• configureVoxelWorld(opts) - Configure world settings
• ... and all other voxel API functions

NOA-Specific Features

When NOA is active, backend-level diagnostics can access additional NOA state:

// These only work when isVoxelNoaActive() returns true
const engine = gpu.noaEngine; // advanced backend diagnostics only

Configuration Options

When enabling the NOA adapter:

await enableVoxelNoaAdapter({
  // Debug mode - shows FPS, chunk boundaries, etc.
  debug: false,

  // Chunk size (must match Nova64's CHUNK_SIZE)
  chunkSize: 16,

  // Render distance in chunks
  renderDistance: 4,

  // Advanced NOA configuration (optional)
  noaConfig: {
    playerHeight: 1.8,
    playerWidth: 0.6,
    tickRate: 30,
    // ... see noa-engine docs for full options
  },
});

URL Parameters

You can enable NOA probing via URL parameters:

?noaVoxel=probe     Enable NOA feature detection
?noaVoxel=true      Enable NOA adapter if available
?noaVoxel=false     Disable NOA adapter

LocalStorage

NOA preference can also be stored:

localStorage.setItem('nova64:noaVoxel', 'probe');

Files

Testing

Run the voxel examples to test NOA integration:

# Test minecraft-demo with Babylon.js backend
pnpm dev
# Navigate to: http://localhost:5173/babylon_console.html?demo=minecraft-demo

# Test with NOA probing enabled
# Navigate to: http://localhost:5173/babylon_console.html?demo=minecraft-demo&noaVoxel=probe

Troubleshooting

"NOA adapter not available"

• Ensure you're using the Babylon.js backend (babylon_console.html)
• Check that optional dependencies were installed with pnpm install

"noa-engine does not export Engine class"

• Ensure you have a compatible version of noa-engine (>=0.33.0)
• Try updating: pnpm update noa-engine

Performance issues

• NOA adapter is experimental; if you experience performance issues, disable it:

  disableVoxelNoaAdapter();
  

• The standard Babylon.js voxel backend is highly optimized and recommended for production

Babylon peer dependency warning

noa-engine@0.33.0 currently declares an older Babylon peer range than Nova64 uses. Treat pnpm's peer warning as part of the experiment, keep the adapter opt-in, and validate Babylon voxel carts before expanding NOA ownership.

References

• noa-engine GitHub
• noa-engine API Documentation
• noa-examples
• Babylon.js Documentation