RPGJS v5 Is Stable: Build an RPG Once, Run It as an MMORPG

RPGJS v5.0.0 is out. After the beta announced in April and a long series of release candidates, the open-source engine behind RPGJS Studio is now stable and published on npm.

RPGJS is a TypeScript framework for 2D RPGs and MMORPGs in the browser. Maps, events, dialogs, inventory, skills, combat, save/load, GUI and multiplayer synchronization are already there: you write the game, not the engine.

GitHub · Quick start · Documentation · Discord

---

RPGJS Explained

Start here: a short tour of the idea behind the engine, and why the same code can power a single-player RPG and an online world.

---

Your First Game in 30 Seconds

npx degit rpgjs/starter#v5 my-rpg-game
cd my-rpg-game
npm install
npm run dev

Open the link: your hero is already walking around a map. Want to follow along step by step? The getting started tutorial goes from an empty folder to a multiplayer RPG in five steps.

---

One Codebase, Two Games

The gameplay you write runs on a server-owned model from day one. Switching from a single-player RPG to an MMORPG is a runtime choice, not a rewrite.

Standalone RPG, where the server runs in the browser:

startGame({
  ...config,
  providers: [provideRpg(startServer)],
});

MMORPG:

startGame({
  ...config,
  providers: [provideMmorpg({})],
});

RPG_TYPE=mmorpg npm run dev

In MMORPG mode the server stays authoritative, each map becomes a synchronized room, and the client predicts movement so the game still feels instant.

---

Gameplay Reads Like a Script

Events are plain TypeScript. A merchant that sells potions looks like this:

import { type EventDefinition, type RpgPlayer } from "@rpgjs/server";

export function Merchant(): EventDefinition {
  return {
    name: "Merchant",
    onInit() {
      this.setGraphic("merchant");
    },
    async onAction(player: RpgPlayer) {
      const choice = await player.showChoices("Need something for the road?", [
        { text: "A potion (20 gold)", value: "potion" },
        { text: "Just looking", value: "no" },
      ]);

      if (choice?.value === "potion" && player.gold >= 20) {
        player.gold -= 20;
        player.addItem("potion");
        await player.showText("Safe travels!");
      }
    },
  };
}

Want enemies that fight back? Give an event a battle AI:

new BattleAi(this, { enemyType: EnemyType.Aggressive });

---

What Landed Since the Beta

The beta laid the foundations. The road to 5.0.0 filled in what a real game needs:

• Production MMORPG hosting: room adapters for persistent Node servers and Cloudflare Durable Objects, the same game module running on both.
• Map streaming: maps are sent progressively in render and physics chunks, with spatial interest management so each player only receives what is around them.
• Live map updates: publish maps and events to a running server from an editor, without restarting it.
• Accounts: a pre-connection login and registration screen, with themeable visuals, music and optional password recovery.
• Official chat: an authoritative, replaceable chat module with default and pixel themes and moderation hooks.
• Character select and classes: a cinematic character selector, runtime actor switching that keeps progression, and class skill progression.
• Hotbar: a persistent hotbar for skills and items, with keyboard shortcuts, a radial gamepad selector and mobile support.
• Custom gameplay rooms: scenes that run independently of maps (mini-games, battle screens), with seamless player transfers.
• Audio: one playSound() API with mixer channels, spatial sound, and coordinated map and battle music.
• Terrain rendering: the same terrain renderer as the RPGJS Studio editors, including water and submerged elements.

---

What’s in the Box

🗺️ World	Maps, world maps, Tiled support, events, shared and per-player scenarios, weather, lighting, day/night
⚔️ Gameplay	Items, skills, states, classes, real-time action battle, projectiles, hotbar, save/load
🌐 Multiplayer	Authoritative server, map rooms, client prediction and reconciliation, live map updates, accounts, chat
🖼️ Interface	Title screen, dialogs, menus, shop, HUD, character select, themes, mobile controls, gamepad, Vue overlays
🌍 i18n	One translation catalog for server dialogs, client menus and modules
🛠️ Tooling	TypeScript first, Vite, Vitest testing helpers, dependency injection, modules and plugins
☁️ Deploy	Node or Cloudflare Workers, with no lock-in to a database or host

---

Build It With Your AI Assistant

Teach your coding assistant how RPGJS v5 works:

npx skills add https://github.com/RSamaium/RPG-JS#v5

The framework handles the hard parts (synchronization, prediction, persistence, deployment), so AI-assisted code builds on solid ground instead of reinventing them.

---

Coming From v4?

compatibilityV4Plugin() from @rpgjs/vite runs a v4 project layout on the v5 runtime. See the migration guide.

---

Code or Visual, Your Choice

RPGJS v5 is the MIT-licensed, code-first foundation. RPGJS Studio is the visual workflow built on top of it: paint maps, build events and generate assets, then export RPGJS-compatible source whenever you want.

---

Join the Community

• Questions, ideas and showcases: Discord
• News and updates: @rpgjs_dev on X
• Bugs: GitHub Issues

RPGJS is MIT licensed and free for commercial use. If it helps you build your game, a ⭐ on GitHub helps others find it.