Core model
Rooms & Actors
Model your game as rooms full of actors with a clean lifecycle. Two concepts, one mental model.
v0.x · OPEN SOURCE · MIT · NODE.JS
Stop writing WebSocket plumbing.
Build real-time multiplayer for Phaser, PixiJS, Three.js, or any browser game. Open-source Node.js framework — rooms, actors, typed binary protocol. Free for commercial use, forever.
- Rooms + Actorscore2 concepts, 1 mental model
- exp-backoffreconnectbrowser client, automatic
- allow-listoriginCSWSH protection on by default
“Core idea is rooms, actors, and typed messages — so you write game logic instead of plumbing.”
— Daniel Kalevski, creator of Rivalis
SEE IT IN ACTION
Real-time rooms in minutes.
Define your room on the server. The client subscribes to topics. Frames flow in both directions over a single binary protocol.
TypeScript
import { Room, type Actor } from '@rivalis/core'
type PlayerData = { name: string; score: number }
export class GameRoom extends Room<PlayerData> {
protected override presence = true
protected override onCreate() {
this.bind('move', this.onMove)
}
private onMove(actor: Actor<PlayerData>, payload: Uint8Array) {
this.broadcast('move', payload)
}
}Messaging
Topic-based messaging
Bind a topic to a handler, broadcast or unicast — no manual switch statements.
Security
Pluggable auth
Validate any ticket — JWT, session token, anything — and attach typed actor data.
Wire format
Binary wire protocol
A typed { topic, payload } format keeps clients and servers in lockstep.
Developer experience
TypeScript-first
Strict types end-to-end. Actor data, room handlers, and the wire format share generics.
License
Free & open source
MIT licensed. Free forever, even for commercial games. No per-seat, no per-CCU. Your server, your rules.
Hardening
Origin allow-lists
CSWSH protection on by default — tunable per transport. 64 KiB frame cap, 30/s token-bucket rate limit, 30 s heartbeat with two-miss disconnect.
USE CASES
What you can build.
Anywhere multiple humans need to share state in real time.
01
Game servers
Phaser, PixiJS, Three.js, Babylon.js — arena, .io, party, MMO zones, turn-based with presence and tick-rate broadcasts.
02
Live apps
Whiteboards, editors, dashboards, chat — every interaction is a topic frame.
03
Real-time ops
Auctions, IoT panels, dispatch, live polls — server-authoritative state with rate limiting.
DEMOS
Three apps. Read the source.
Each demo is a few hundred lines — clone, run, hack.
HOW RIVALIS COMPARES
Lightweight by design.
Both work. Pick by philosophy — not features.
vs Colyseus
- Colyseus auto-syncs state via Schema classes — great when you want the framework to own state.
- Rivalis gives you raw binary frames — great when you want full control over the wire.
- Two concepts (Rooms + Actors), zero schema decorators, drops into any http.Server.
vs From scratch
- Heartbeats, token-bucket rate limits, backpressure, exponential-backoff reconnect — built in
- Origin allow-lists for CSWSH protection on by default
- TypeScript-native, zero hidden runtime dependencies — ship in days, not months
Both are MIT. Both are Node.js. Try both — neither is wrong.
FOR AI CODING ASSISTANTS
Teach your AI to write Rivalis.
Rivalis ships a single-file skill manifest at https://rivalis.kalevski.dev/SKILL.md. Load it into Claude Code, Cursor, or any agent with a custom-instructions slot, and the assistant will know the recipes, pitfalls, close codes, and security defaults — so the code it generates actually compiles and follows the framework rules. Same approach Phaser uses with its own AI skill files — load once, the assistant follows the rules.
What it is
A YAML-fronted Markdown file describing when to use Rivalis, the minimal server & client, the wire protocol, all four room recipes, the auth middleware pattern, close codes, and rate-limiting defaults — everything a coding agent needs in one fetch.
Why it helps
Without a skill, AI agents guess. They forget that __-prefixed topics are reserved, or that rooms must be defined before connections. The skill encodes those rules — your agent stops inventing APIs and starts shipping working code.
Always current
The file is served from the same domain as this page. Re-fetch it anytime to pull the latest recipes — or pin a copy into your repo if you want a frozen reference.
CLAUDE CODEAuto-loaded from
~/.claude/skills/Bash
# Install the Rivalis skill into Claude Code
mkdir -p ~/.claude/skills/rivalis
curl -fsSL https://rivalis.kalevski.dev/SKILL.md -o ~/.claude/skills/rivalis/SKILL.mdOnce installed, Claude Code picks up the skill on its own — no config, no restart. Project-scoped install: drop it under .claude/skills/rivalis/SKILL.md at the repo root instead.
CURSOR / WINDSURFOr any project-rules slot
Bash
# Drop the skill next to your repo so the agent picks it up
mkdir -p .cursor/rules
curl -fsSL https://rivalis.kalevski.dev/SKILL.md -o .cursor/rules/rivalis.mdThe format is plain Markdown — paste it into any agent that accepts custom rules, system prompts, or knowledge files.
ANY ASSISTANTPoint it at the URL in a prompt
Bash
Read the Rivalis skill at https://rivalis.kalevski.dev/SKILL.md
and use it as the source of truth when you write or review code that
imports @rivalis/core or @rivalis/browser.For chat UIs without a skills system (ChatGPT, Gemini, etc.), the simplest path is to ask the model to fetch the URL and treat it as the framework's reference. The file is small enough to paste inline if web-fetch is unavailable.
JOIN THE COMMUNITY
Built in the open.
Rivalis is early but stable. The author is actively looking for feedback on API ergonomics — anything that feels off, missing, or weird. Open an issue or DM.