Suroi

Suroi is an open‑source, browser‑based 2D battle royale engine written in TypeScript and delivered through a single‑page application powered by PixiJS. The server side is a lightweight Node.js runtime (Bun) that manages real‑time gameplay logic, player state, and network messaging over WebSocket. The architecture deliberately separates the rendering client from the authoritative server to reduce latency and allow independent scaling of each tier.

Technical Stack & Architecture

• Runtime – Bun (v1+), a fast JavaScript/TypeScript engine that bundles the server and client into a single binary, reducing deployment overhead.
• Client – PixiJS 8+ for WebGL rendering; Vite as the dev server and build tool, with SCSS for styling.
• Server – Pure TypeScript using Bun’s built‑in WebSocket API; no external framework (e.g., Express) to keep the loop tight.
• Data Persistence – The current release uses an in‑memory store for game state; persistent data (high scores, user profiles) can be hooked to any SQL/NoSQL store via a simple adapter layer.
• Communication – Custom binary protocol over WebSocket with message IDs, enabling sub‑10 ms tick rates on a typical LAN.

The codebase follows a modular pattern: client/src/ houses rendering, input handling, and UI; server/src/ contains game logic (physics, map generation, entity lifecycle). Both sides share a common type definition package (shared/) ensuring compile‑time consistency.

Core Capabilities & APIs

• Real‑time multiplayer – Tick‑based loop at 60 Hz, with client prediction and server reconciliation.
• Procedural map generation – Per‑session terrain created via noise functions; can be overridden by a custom map generator.
• Event hooks – Developers can register callbacks for player joins, deaths, and item spawns via the server’s event emitter.
• WebSocket API – Exposes a minimal JSON/MessagePack interface; clients can query server status, subscribe to match events, or inject custom entities for modding.
• Extensibility – The plugins folder accepts plug‑in modules that export a register(server) function, allowing new weapons, power‑ups, or AI behaviors to be added without touching core code.

Deployment & Infrastructure

Suroi is designed for self‑hosting on commodity hardware. A single Docker image can run both client and server; the container exposes port 3000 for HTTP (client) and 4000 for WebSocket. NGINX can be used as a reverse proxy to serve the static build and handle TLS termination. The lightweight server allows horizontal scaling: multiple instances can share a Redis pub/sub layer for cross‑server state, enabling larger player counts.

Integration & Extensibility

• Plugin system – Plug‑ins are pure TypeScript modules that can modify the game loop, add new entity types, or hook into existing events.
• Webhook support – The server can emit HTTP POST requests on critical events (e.g., match end), enabling integration with Discord, Slack, or custom dashboards.
• Custom assets – The asset pipeline (Vite + Pixi) supports sprite sheets, JSON maps, and audio; developers can replace the entire visual theme without recompiling the server.
• Modding API – A subset of the game logic is exposed to client‑side mods via a sandboxed scripting environment, allowing community creators to add new gameplay mechanics.

Developer Experience

The repository is well‑documented with a dedicated self‑hosting wiki. TypeScript provides strong typing across client and server, reducing runtime errors. The build system is zero‑config: bun dev launches hot‑reload for both tiers, and bun build:client outputs an optimized bundle. Community support is active on Discord and GitHub Discussions, where contributors discuss feature requests and troubleshooting.

Use Cases

• Educational projects – Demonstrate real‑time networking, game loops, and WebGL rendering in a single codebase.
• Custom battle royale servers – Deploy private arenas with bespoke maps, weapons, or rules for clubs and tournaments.
• Modding platforms – Use the plugin API to create a mod ecosystem around the core game, similar to Minecraft or Factorio.
• Rapid prototyping – The modular architecture allows swapping physics engines or AI modules to experiment with new gameplay mechanics.

Advantages Over Alternatives

• Zero‑dependency server – No Express or Koa boilerplate; the core is just a WebSocket loop, minimizing attack surface and resource usage.
• Unified TypeScript codebase – Shared types between client and server guarantee consistency and ease of refactoring.
• Fast startup – Bun’s bundling speeds up both development and production launches, cutting cold‑start latency.
• Open licensing – MIT license encourages commercial use and internal tooling without legal overhead.
• Scalable yet lightweight – Suitable for small LAN parties or large public servers, with straightforward Docker deployment.

Suroi offers developers a clean, modern stack for building and extending a battle royale experience while keeping operational complexity low.