Modu Engine

A modern, TypeScript-first multiplayer game engine with sandboxed JavaScript scripting, client-side prediction, and single-player development mode.

Features

• TypeScript throughout — strict mode, ES modules, full type safety
• Three.js rendering — sprites, animated sprites, entity renderers, HUD, post-processing
• Rapier 2D + 3D physics — WASM-based, fast, with collision events and sensor support
• Sandboxed JS scripting — game logic written in plain JavaScript with a fluent API, executed in an isolated environment
• Client-side prediction — near-zero input latency with server reconciliation
• Interest management — area-of-interest filtering for 200 CCU per game
• Delta compression — binary protocol (msgpack) with property-level diffing
• Single-player mode — default for development, engine core runs directly in browser
• Security hardened — per-player per-action rate limiting, input validation, bandwidth budgets, XSS prevention
• A* pathfinding — 8-directional with diagonal corner-cutting prevention
• In-game editor — dev mode tools with external editor bridge
• Fly.io deployment — one machine per game, auto-stop/auto-start

Quick Start

# Install dependencies
npm install
# Run tests
npm run test# Run in development (single-player mode)
npm run dev
# Run in multiplayer mode (server + client)
npm run dev:multi
# Build for production
npm run build
# Run benchmarks
npm run bench

Architecture

engine/
core/ # Shared isomorphic game logic (runs everywhere)
ecs/ # Entity-Component-System (Entity, Component, System)
math/ # Vec2, Vec3, Matrix2d, Rect, Polygon
physics/ # Rapier 2D + 3D physics (PhysicsWorld, RigidBody, Collider, PhysicsWorld3d, RigidBody3d)
network/ # Protocol, Serializer, DeltaCompressor, InputBuffer, InterestManagement
scripting/ # ScriptEngine, ScriptAPI, Sandbox, JSON-to-JS transpiler
game/ # Game entities (Unit, Player, Item, Projectile, Prop, Region, Sensor)
# Game systems (Inventory, Ability, Attribute, AI)
map/ # TileMap, Map2d, A* Pathfinding
events/ # EventEmitter
time/ # Clock with timers and intervals
Engine.ts # Core engine singleton
client/ # Browser-side only
renderer/ # Three.js (Renderer, Camera, Sprites, Entity Renderers, HUD, PostProcessing)
network/ # Predictor, Interpolator, Reconciler, ClientClock
input/ # InputManager, MobileControls
audio/ # AudioManager
ui/ # UIManager, Shop, Scoreboard, DevConsole, GameText
Client.ts # Client entry point
SinglePlayer.ts
server/ # Node.js server only
network/ # ServerSocket, RateLimiter, InputValidator, BandwidthBudget
Server.ts # Server entry point
editor/ # In-game dev tools
DevMode.ts # Developer mode coordinator
EditorBridge.ts # Interface with external React editor
deploy/ # Fly.io deployment
Dockerfile
fly.toml
tests/
unit/ # 376 unit tests
performance/ # Benchmarks (physics, serialization, spatial, ECS)

Scripting

Game logic is written in plain JavaScript with a fluent API:

on('unitAttacked',(attacker,target)=>{constdamage=attacker.attr('attack')-target.attr('defense');if(damage>0){target.attr('health',hp=>hp-damage);target.floatingText(`-${damage}`,'red');if(target.attr('health')<=0){target.die();attacker.attr('xp',xp=>xp+target.attr('xpReward'));}}});every(5000,()=>{world.units.where(u=>u.type==='zombie').forEach(z=>{z.moveTo(nearestPlayer(z));});});

Scripts run in an isolated sandbox (Function-based for development, isolated-vm for production) with:

• No access to Node.js APIs (process, fs, require)
• Hard memory limits
• CPU timeout per tick
• Per-game isolation

Networking

Player presses W
|-> Client: Apply movement IMMEDIATELY (predicted state)
|-> Client: Send input + tick number to server
|-> Server: Simulate authoritatively, send back state + tick
'-> Client: Compare prediction vs server
|- Match -> do nothing
'- Diverge -> smoothly reconcile over 2-3 frames

Entity	Strategy	Perceived Latency
Own player	Client-side prediction	~0ms
Own actions	Optimistic + rollback	~0ms visual
Other players	Entity interpolation	~50-100ms, smooth
Projectiles	Client-spawned, server reconciles	~0ms visual

Security

• Input validation — every client message validated before reaching game logic
• Rate limiting — per-player, per-action-type (e.g., pickupItem: 5/sec, chat: 3/sec)
• Bandwidth budgets — per-player outbound byte cap per tick
• XSS prevention — centralized string sanitization
• Script sandbox — isolated execution, no shared references with host

License

See LICENSE for details.