Docs

Publishing guide

Everything a Node.js multiplayer game needs to run on MultiPlayground, and how to put it online. It takes about ten minutes to read; the sample game already follows all of it.

What a game needs

A game is a Node.js project that serves its own page and runs its own multiplayer server. To run here it needs four things:

  1. 1package.json at the top of the zipZipping the game's folder is fine: a single folder at the top is opened for you.
  2. 2npm start starts the serverA "start" script in package.json, such as "node server.js".
  3. 3It listens on process.env.PORTThe platform gives each game its own port. Never a fixed number.
  4. 4On 0.0.0.0, not localhostYour server runs in a container: localhost would be reachable only from inside it. It must start listening within 20 seconds.
server.listen(process.env.PORT || 3000, "0.0.0.0");

Express and Socket.IO, as in the sample, are the usual choice. Any Node server that keeps these four rules works, including plain WebSockets.

How a game is laid out

One server serves everything: the page players open, its files, and the real-time connection. The sample is laid out like this:

my-game/
  package.json      "start": "node server.js", and your dependencies
  server.js         the game: rules, the world, the players
  public/
    index.html      the page players see
    client.js       draws the game and sends what players do
    style.css

Put every package your server uses in the dependencies of package.json. The platform runs npm install for you, so leave node_modules out.

Addresses in the page

Your game lives below your page: https://your-name.multiplayground.io/my-game/. Your server still sees its own paths from /, as on your computer. In the browser, ask for files relative to the page, with no / in front:

<script src="socket.io/socket.io.js?v=22a45cf"></script>
<link rel="stylesheet" href="style.css?v=22a45cf">
fetch("api/scores")

Connect Socket.IO below the page's address too:

const socket = io({ path: location.pathname.replace(/[^/]*$/, "") + "socket.io" });

Never write localhost or a port number in the page. If your server needs its full address, the platform sends the part it removed in the X-Forwarded-Prefix header (/my-game).

Try it on your computer

With Node.js installed, in the game's folder:

$ npm install
$ npm start

Open http://localhost:3000 in two browser tabs. Both players should appear and see each other move. If that works, it will work here.

Zip and upload

  1. Zip the game's folder. On a Mac, right-click it and choose Compress. On Windows, right-click it, then Send to, Compressed (zipped) folder. Delete node_modules first if it is there. A zip can be up to 100 MB.
  2. Sign in to the developer console. New? Pick a username and a password: the console asks before it creates the account. Your username becomes your address, your-name.multiplayground.io.
  3. Drop the zip on the upload box and choose a name. The name becomes the game's address: lowercase letters, digits and hyphens. A name another developer uses is taken.
  4. Wait about half a minute. The platform installs your packages and starts your server. When it says live, the link is ready to send, and the game is on the games page.

Put up a new version

Upload again under the same name. The link stays the same, and the console shows which version is live.

The game restarts with the new version: players in it at that moment are disconnected, and whatever the game held in memory starts fresh. There is no rollback, so a broken upload takes the game offline until you upload a working one.

Changing a game's name shown on the games page is done in the console (Change name). It never changes the link.

How your game is run

  • Its own container. Each game runs in its own Docker container with Node.js 22, with up to 512 MB of memory and its own share of the processor, kept apart from every other game.
  • Files are read-only. Your game can read its files but not change them, and it has a small temporary folder in memory. Keep game state in memory: there is no database or lasting disk storage yet.
  • Real-time connections. WebSockets and Socket.IO work through the platform, over HTTPS.
  • Restarts after a crash. If your server stops, the platform starts it again, waiting a little longer after each failure, until you stop it in the console.
  • Sleep. After 15 minutes without players a game is paused. It wakes as soon as someone opens its link.
  • Players. The console and the games page show how many people are in each game right now.

When it doesn't start

Open the game's Logs in the console: they show what npm install and your server printed. The usual causes:

"Didn't start" after 20 seconds

The server listens on a fixed port or on localhost. Listen on process.env.PORT, on 0.0.0.0.

"package.json was not found"

The zip holds more than one folder at the top, or the game is one folder deeper. Zip the folder that has package.json in it.

"Cannot find module"

A package your server uses is missing from dependencies in package.json.

The page loads, but nothing moves

The page connects to localhost or a port number. Use addresses relative to the page (above).

"The zip is too big"

Delete node_modules before zipping; large pictures, sounds and videos add up too.

Building with an AI agent

Download the sample game, open its folder in Claude Code, Cursor, Codex or your favourite tool, and paste:

I'm making a multiplayer browser game for multiplayground.io. This folder has a
compatible sample game: it's here only so my game runs on multiplayground. Read
AGENTS.md and keep that compatibility, but the game itself can be completely
different: [describe your game]. Then tell me how to try it with two players on
my computer.

The sample's AGENTS.md tells your agent the rules on this page. Ask it to let the server decide what happens (positions, scores, winners) and to support touch as well as keys: players join from phones too.

Publish your game