@web-engine-dev/netcode-ecs

Shared ECS simulation layer for multiplayer games. Server and client execute identical system functions on the same world definition, ensuring deterministic behavior across the network boundary with automatic component replication.

Layer 7 · Gameplay

Features

• Automatic Component Replication: Components marked with replication metadata sync between server and clients
• Delta Compression: Only changed fields are transmitted — static entities consume zero bandwidth
• Shared Simulation: Server and client share the same ECS world definition and system functions
• Authority Model: Per-component authority (server-authoritative for game state, client-authoritative for input)
• Conflict Resolution: Handles simultaneous mutations from server and client
• Priority-Based Updates: Gameplay-critical components replicate at higher frequency than cosmetic data
• Smallest-3 Quaternion Encoding: Rotations compressed to 30 bits (3 × 10-bit components)
• Deterministic System Ordering: Identical simulation results given identical inputs

Installation

npm install @web-engine-dev/netcode-ecs
# or
pnpm add @web-engine-dev/netcode-ecs

Quick Start

import { NetworkedWorld, replicated, authority } from '@web-engine-dev/netcode-ecs';
import { defineComponent } from '@web-engine-dev/ecs';

// Define a replicated component
const Position = defineComponent('Position', { x: 'f32', y: 'f32', z: 'f32' });
const Health = defineComponent('Health', { current: 'f32', max: 'f32' });
const PlayerInput = defineComponent('PlayerInput', { moveX: 'f32', moveY: 'f32' });

// Mark components for replication
replicated(Position, { priority: 'high', quantization: '16bit' });
replicated(Health, { priority: 'high' });
replicated(PlayerInput, { authority: 'client' });

// Create a networked world (works on both server and client)
const world = new NetworkedWorld({
  tickRate: 60,
  interpolation: 'hermite',
});

// Systems run identically on server and client
function movementSystem(world: NetworkedWorld) {
  // Same code produces same results on both sides
}

Quantization Presets

Value Type	Encoding	Precision
Positions	16-bit or 24-bit	±32K range or ±8M range
Rotations	Smallest-3	10 bits per component (30 bits total)
Normalized values	8-bit	0–255 mapped to 0.0–1.0

Dependencies

• @web-engine-dev/ecs — Entity-Component-System
• @web-engine-dev/netcode — Transport and prediction
• @web-engine-dev/serialization — Binary serialization