@magmacrunch/adenosine-multiplayer

Game-agnostic multiplayer WebSocket client: lobby, rooms, colour picking, chat and turn relay, plus a board-game HTML template. No runtime dependencies.

npm install @magmacrunch/adenosine-multiplayer

Use

import { MP, MSG, BoardGameTemplate } from '@magmacrunch/adenosine-multiplayer';

MP.onWelcome     = (data)   => console.log('joined room', data.room);
MP.onGameStarted = (data)   => startGame(data);
MP.onGameAction  = (action) => handleAction(action);

MP.connect();
MP.join('Player1', '#ff2d55');

MP.sendAction({ type: 'play_card', card }) relays a move to the other players; MSG holds the protocol's message-type constants and MP_PALETTE the colours the lobby offers.

Board game scaffolding

document.body.innerHTML = BoardGameTemplate.render({
  title: 'CHESS',
  instructions: '<h3>Rules</h3><p>…</p>',
  credits: '<h3>Chess</h3><p>Your name here</p>',
});

render() returns markup; it does not insert it. Note that <script> elements in a string assigned through innerHTML never execute; load your game scripts with real tags.

Configuration

With nothing configured, MP.connect() targets the origin that served the page, choosing wss: or ws: from the page protocol.

MP.configure({
  defaultServer: 'games.example.com/chess',   // bare host[:port][/path]
  allowlist: ['games.example.com'],           // hosts a ?server= link may name
});

Prefer a bare host over a ws://-prefixed value: a value already starting with ws is used verbatim, which silently defeats protocol selection on https: pages. Private ranges (RFC1918) and loopback are always allowed so LAN and dev play keep working; anything else a ?server= link names must be in allowlist, or it is ignored and logged.

Bring your own server

This is the client half only. Nothing here listens; MP.connect() expects a WebSocket server that keeps rooms and relays frames between the players in one. No such server ships with this package, so a fresh install has nothing to talk to until you provide one.

PROTOCOL.md specifies the whole wire format; every frame in both directions with its fields, plus the six things a minimal server must do. It is short, and writing a server against it is a normal afternoon's work in any language with a WebSocket library.

Without a bundler

No bundler? jsDelivr serves the lobby styles and the client:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@magmacrunch/[email protected]/lobby.css">
<script src="https://cdn.jsdelivr.net/npm/@magmacrunch/[email protected]/dist/index.global.js"></script>

The client lands on window.AdMP. @0.6 holds it to this minor line, since an unversioned URL resolves to latest and would jump majors silently. With npm, use dist/index.global.js.

Full API

API.md documents every export, with parameters and return shapes.

Theming

| Property | Default | What it colours | |---|---|---| | --accent | #00f5ff | Borders, titles, focus | | --gold | #ffe03a | Host badge, primary button | | --bg-dark | #060e1a | Overlay backdrop | | --bg-mid | #1a2a44 | Panel | | --border | #1a2a44 | Dividers | | --cream | #f0ead8 | Body text | | --slate | #4a6a7a | Muted text | | --font-pixel / --font-mono | Press Start 2P / VT323 | Headings / body |

Glows and translucent fills derive from --accent and --bg-dark through color-mix, so overriding the accent recolours them too rather than leaving a cyan halo behind.

color-mix() does the deriving, so browsers need to be from 2023 or later: Chrome 111, Safari 16.2, Firefox 113.

Module format

Published as ES modules only. require() fails since exports declares no CommonJS condition; use import or the IIFE bundle.

License

PolyForm Noncommercial 1.0.0. Copyright 2026 magmacrunch media.

Any noncommercial purpose is permitted. For a commercial licence, ask.

Part of adenosine, a collection of lightweight web game engines by magmacrunch media. Keep the NOTICE file with any copy you distribute.