noa-engine Documentation

The renderSystem handlers are responsible for updating the visual representation of entities. They run in a specific order to ensure that movement and positioning logic is applied before the final mesh rendering occurs.

| name | order | render system |
| ---- | ----- | ------------- |
| `physics`       | `40` | backtrack entity `renderPosition` towards physics position |
| `followsEntity` | `50` | moves entity's `renderPosition` to match its follow target |
| `shadow`         | `80` | update shadow's `x/z` position |
| `mesh`           | `100`| moves rendering mesh to entity `renderPosition` |

The position component stores data in local coordinates. Understanding these properties is useful for engine hacking or advanced customization:

• _localPosition: The single source of truth for the entity's position (used for game logic).
• _renderPosition: The position used in the 3D scene. This can change every render frame, whereas _localPosition only changes once per tick.
• _extents: An array representing dimensions: [lox, loy, loz, hix, hiy, hiz].

The offset between local and global coordinates is defined by noa.worldOriginOffset.

To start building with noa, the primary entry point is the Engine class. This core class manages the voxel engine lifecycle and serves as the foundation for your game implementation.

// Reference to the core engine class
import { Engine } from 'noa';

const engine = new Engine();

The recommended way to begin developing a voxel game with noa is to use the noa-examples repository as a foundation. This repository contains a hello-world example that serves as a template for:

• Instantiating the engine.
• Defining world geometry.
• Importing peer dependencies.
• Testing a world.
• Building for production.

Instead of starting from scratch, clone the examples repo and modify the existing source code to suit your game's needs.

git clone https://github.com/fenomas/noa-examples

The Container class manages the game's HTML container element, the <canvas> element, fullscreen mode, and pointer lock. It wraps micro-game-shell to handle timing, rendering rates, and input states.

When initializing a Container, you can provide a specific DOM element via opts.domElement. If no element is provided, it creates a default full-screen div with the ID noa-container and a <canvas> with the ID noa-canvas.

// Example initialization (internal usage pattern)
const container = new Container(noa, {
  domElement: '#my-game-container',
  tickRate: 60,
  maxRenderRate: 60,
  stickyPointerLock: true,
  stickyFullscreen: true
});

When registering a block, the material parameter determines how textures are applied to the 6 faces of a voxel. The engine maps these to the direction indices 0..5 as follows:

• 0: +x
• 1: -x
• 2: +y
• 3: -y
• 4: +z
• 5: -z

(Note: The source code uses blockMats[id * 6 + i] where i is the face index. The mapping logic for shorthand arrays like [top, bottom, sides] is: [sides, sides, top, bottom, sides, sides] based on the internal mats array construction).

The Camera manages the player's perspective through two main concepts: Rotation and Zoom.

Rotation (Heading and Pitch)

• heading: The yaw angle (rotation around the vertical axis) in the range 0..2π.
• pitch: The up/down rotation angle in the range -π/2..π/2. The engine clamps this value slightly to prevent the camera from pointing perfectly vertical.
• Note: While these properties are writable, they are managed by the engine and will be overwritten every frame based on mouse input.

Zooming

• zoomDistance: The desired distance the camera should maintain from the target.
• currentZoom: The actual distance the camera is currently at. This value interpolates towards zoomDistance based on zoomSpeed. It is also clamped by the engine to prevent the camera from clipping into solid terrain behind the player.

The Entities class is an Entity Component System (ECS) that manages game entities and their associated components. It extends ent-comp and provides specialized helpers for querying entity positions, physics bodies, and meshes.

Built-in components available via this.names include:

• collideEntities
• collideTerrain
• fadeOnZoom
• followsEntity
• mesh
• movement
• physics
• position
• receivesInputs
• shadow
• smoothCamera

import ECS from 'ent-comp'
// The Entities class is typically accessed via the engine instance, e.g., noa.ents

The World class manages chunk lifecycles by requesting data from the client. When a new chunk is needed within the player's range, the engine emits the worldDataNeeded event. The client must listen for this event, generate or fetch the voxel data, and provide it back to the engine using setChunkData.

// 1. Listen for the request
world.on('worldDataNeeded', (requestID, dataArr, x, y, z, worldName) => {
  // 2. Generate your voxel data (dataArr is an ndarray)
  const myData = generateVoxelData(x, y, z);
  
  // 3. Send it back to the engine
  world.setChunkData(requestID, myData);
});