NetClient

Installation

NetClient is a single ES module file with no dependencies. Drop it into your project and import it.

1. Download netClient.jsCopy netClient.js into your project folder alongside your HTML file.
2. Import it as an ES module

   your-game.js

   import NetClient from "./netClient.js";

   NoteYour script tag must use type="module" for ES module imports to work.
3. Add type="module" to your script tag

   index.html

   <script type="module" src="./your-game.js"></script>

4. Point to a server NetClient connects to any WebSocket server that speaks its protocol. Self-host server.js on Node.js, or deploy it for free on Render.

   Free hosting tipRender's free tier supports persistent WebSocket connections. Deploy server.js with node server.js.

Quick Start

Get two players connected and talking in under 20 lines.

import NetClient from "./netClient.js";

const net = new NetClient("wss://your-server.onrender.com", "myGame");
net.connect();

net.on("roomCreated", (roomId) => {
  console.log("Room ready:", roomId); // Share this code with others
});

net.on("relay", (fromId, payload) => {
  updatePlayer(fromId, payload);
});

net.on("error", (msg) => console.warn("NetClient error:", msg));

// Trigger room creation from user action, not automatically on connect
document.getElementById("createBtn").onclick = () => net.createRoom([], 4, false);

Constructor

const net = new NetClient("wss://gamebackend-dk2p.onrender.com", "demoGame");

Instance Properties

Connection

Rooms

net.createRoom([], 8, false, { name: "My Lobby", map: "forest" });

net.joinRoom("AB3XY");

net.on("roomList", (rooms) => {
  // each room: roomId, ownerId, playerCount, maxClients, tags, metaData
  rooms.forEach(r => console.log(r.roomId, r.playerCount + "/" + r.maxClients, r.metaData));
});
net.listRooms(); // Always register listener before calling

Messaging

net.sendRelay({ x: player.x, y: player.y, anim: "run" });

net.tellOwner({ action: "shoot", targetId: 4521 });

net.tellPlayer(98234, { msg: "You were hit!", damage: 25 });

// Sender
const buf = new ArrayBuffer(8);
const dv  = new DataView(buf);
dv.setFloat32(0, player.x);
dv.setFloat32(4, player.y);
net.sendBinary(buf);

// Receiver
net.on("binary", (fromId, buffer) => {
  const dv = new DataView(buffer);
  const x  = dv.getFloat32(0);
  const y  = dv.getFloat32(4);
  updatePlayerPosition(fromId, x, y);
});

Events

Register listeners with net.on(eventName, callback). Multiple listeners per event are supported and all will fire. There is no off() method — listeners persist for the lifetime of the instance. Use a flag variable to gate a callback if you need to stop handling an event.

Connection Events

Room Events

Host Events

Message Events

Host Controls

These methods only take effect if you are the current room host (net.isHost === true). The server silently ignores them from non-hosts.

// { name: "My Lobby", map: "desert" } → { name: "My Lobby", map: "forest" }
net.updateMeta({ map: "forest" });

// { name: "My Lobby", map: "desert" } → { map: "forest" }
net.setMeta({ map: "forest" });

net.addTag("closed");  // Lock the room — no new joins allowed
net.addTag("ranked"); // Custom tag for lobby filtering

net.removeTag("closed"); // Re-open the room

Server Setup

The companion server.js is a Node.js WebSocket server using the ws package. It handles all room logic, host reassignment, and message routing. HTTP and WebSocket share a single port.

1. Install dependencies

   npm install ws

2. Start the server locally

   node server.js
   # Server listening on port 8080
   # Wake endpoint: http://localhost:8080/wake

3. Deploy to Render (free) Fork the repo on GitHub, create a new Web Service on Render pointing at your fork, set the start command to node server.js, and deploy.

   Cold startsRender's free tier spins down after 15 minutes of inactivity. Use the wake endpoint with an uptime monitor like UptimeRobot to prevent this — or expect the first connection after idle to take 30–60 seconds.

Environment Variables

Wake Endpoint

The server exposes a public HTTP endpoint at GET /wake that always returns 200 regardless of the origin whitelist. Use it to warm up the server before connecting, or as a health check.

HTTP (fetch)

<script>
  (async () => {
    try {
      const res  = await fetch("https://your-server.onrender.com/wake");
      const data = await res.json();
      console.log("[wake] Server awake at", new Date(data.timestamp).toLocaleTimeString());
    } catch (e) {
      console.warn("[wake] Server may be cold-starting...", e);
    }
  })();
</script>

Response

{ "status": "awake", "timestamp": 1234567890123 }

WebSocket

Also works over an open WebSocket connection:

ws.send(JSON.stringify({ type: "wake" }));
// → { type: "awake", timestamp: 1234567890123, playerId: 98234 }

Origin Whitelist

By default the whitelist is empty, allowing connections from any origin. To restrict access, edit ORIGIN_WHITELIST at the top of server.js. Origins must include the protocol.

const ORIGIN_WHITELIST = [
  "https://yourgame.com",
  "http://localhost:3000",
];

Server Behaviour

Heartbeat / Timeout

The server pings all connected clients every 30 seconds using WebSocket ping frames. Clients that do not respond with a pong are terminated and removed from their room. playerLeft fires for players who drop without calling leaveRoom().

Host Reassignment

When the host disconnects or calls leaveRoom(), the server promotes the first remaining client in the room to host. The new host receives makeHost with the old host's ID. All other clients receive reassignedHost with both IDs. If no clients remain, the room is deleted.

Room Capacity

The maxClients limit includes the host. A room with maxClients: 4 supports 1 host + 3 clients. Joining a full room returns an error event with "Room full".

Closed Rooms

Adding the "closed" tag prevents new players from joining — joinRoom() returns an error event with "Room Closed". It does not disconnect existing players. Remove the tag with net.removeTag("closed") to re-open the room.

Binary Protocol

When the server receives a binary (non-JSON) message, it prepends the sender's player ID as a 4-byte big-endian uint32, then forwards the combined buffer to all other clients in the room. The binary event on recipients provides the parsed fromId and the original buffer with the prepended bytes already stripped.

In-Memory State

All room and player state lives in the server process. A server restart wipes everything — rooms, players, and metadata. Do not build persistence assumptions on top of room state.

Room Filtering

listRooms() excludes rooms tagged "private" or "closed", and always filters by the instance's game:<gameName> tag so results are automatically scoped to your game.

Example: Basic Room

A minimal host/join flow with a shared room code.

import NetClient from "./netClient.js";

const net = new NetClient("wss://your-server.onrender.com", "myGame");
net.connect();

document.getElementById("createBtn").onclick = () => {
  net.createRoom([], 8, false, { name: "My Game" });
};

net.on("roomCreated", (roomId) => {
  document.getElementById("roomCode").textContent = roomId;
});

document.getElementById("joinBtn").onclick = () => {
  const code = document.getElementById("codeInput").value.trim();
  net.joinRoom(code);
};

net.on("roomJoined", (roomId, ownerId, maxClients, metaData) => {
  console.log(`Joined room ${roomId}. Host: ${ownerId}. Lobby: "${metaData.name}"`);
});

net.on("playerJoined", (id) => console.log("Player joined:", id));
net.on("playerLeft",  (id) => console.log("Player left:",  id));
net.on("error",        (msg) => console.warn("Error:", msg));

Example: Relaying State

Broadcast your player's position every frame and sync incoming state from others. Use playerJoined to re-send your state so newcomers can see you.

const players = {};
let myId = null;

net.on("assignedId", (id) => { myId = id; });

net.on("roomJoined", () => {
  players[myId] = { x: 100, y: 100, color: randomColor() };
  net.sendRelay(players[myId]); // Announce yourself
});

net.on("playerJoined", () => {
  net.sendRelay(players[myId]); // Re-send state so newcomer can see you
});

net.on("playerLeft", (id) => { delete players[id]; });

net.on("relay", (fromId, data) => {
  if (!players[fromId]) players[fromId] = {};
  Object.assign(players[fromId], data);
});

function loop() {
  const me = players[myId];
  if (me) {
    handleInput(me);
    net.sendRelay({ x: me.x, y: me.y });
  }
  renderAll(players);
  requestAnimationFrame(loop);
}
loop();

Example: Binary Position Updates

Use sendBinary for high-frequency position updates to reduce JSON serialisation overhead. Pack custom data layouts with DataView.

// Layout: [float32 x][float32 y][float32 rotation] = 12 bytes
function sendPosition(x, y, rotation) {
  const buf = new ArrayBuffer(12);
  const dv  = new DataView(buf);
  dv.setFloat32(0, x);
  dv.setFloat32(4, y);
  dv.setFloat32(8, rotation);
  net.sendBinary(buf);
}

net.on("binary", (fromId, buffer) => {
  const dv       = new DataView(buffer);
  const x        = dv.getFloat32(0);
  const y        = dv.getFloat32(4);
  const rotation = dv.getFloat32(8);
  updateRemotePlayer(fromId, x, y, rotation);
});

function loop() {
  handleInput(player);
  sendPosition(player.x, player.y, player.rotation);
  renderAll();
  requestAnimationFrame(loop);
}
loop();

Example: Full Game Loop

A complete pattern with room locking, host authority, and clean teardown.

import NetClient from "./netClient.js";

const net = new NetClient("wss://your-server.onrender.com", "shooter");
const players = {};
let myId = null;

net.connect();
net.on("assignedId", (id) => (myId = id));

net.on("roomCreated", (roomId) => { showLobby(roomId); });
net.on("roomJoined",  (roomId) => { showLobby(roomId); });

// Host locks and starts the match
function startGame() {
  if (!net.isHost) return;
  net.addTag("closed");
  net.sendRelay({ type: "start" });
  initGame();
}

// Apply incoming state and events
net.on("relay", (fromId, data) => {
  if (data.type === "start") { initGame(); return; }
  if (data.type === "hit")   { applyHit(data.targetId, data.by); return; }
  if (!players[fromId]) players[fromId] = {};
  Object.assign(players[fromId], data);
});

// Host validates and broadcasts authoritative events
net.on("tellOwner", (fromId, data) => {
  if (!net.isHost) return;
  if (data.action === "shoot") {
    net.sendRelay({ type: "hit", targetId: data.targetId, by: fromId });
  }
});

// Handle host promotion mid-game
net.on("makeHost", () => {
  console.log("You are now the host");
});

net.on("playerLeft", (id) => { delete players[id]; });
window.addEventListener("beforeunload", () => net.disconnect());

Known Limitations

No existing players on join

roomJoined gives you the host ID and room metadata, but no list of other players already in the room. The recommended pattern is to relay your state immediately on join, and re-send it when a new player joins so they can see you:

net.on("roomJoined", () => {
  net.sendRelay({ type: "hello", x: player.x, y: player.y }); // user-defined type
});
net.on("playerJoined", () => {
  net.sendRelay({ type: "hello", x: player.x, y: player.y }); // Re-send state so newcomer can see you
});
net.on("relay", (fromId, data) => {
  if (data.type === "hello") players[fromId] = { x: data.x, y: data.y };
});

This works well in practice but requires all existing players to be connected and listening. A future version may include a players array in the roomJoined payload.

No reconnection

If a player's connection drops, they receive a new playerId on reconnect and cannot reclaim their previous slot. Design your game state around players leaving and rejoining as new players.

No listRooms timeout

listRooms() fires roomList when the server responds, but there is no built-in timeout if the response is slow or lost. Always register your listener before calling listRooms(), and implement a timeout in userland if needed:

const timeout = setTimeout(() => console.warn("listRooms timed out"), 5000);
net.on("roomList", (rooms) => {
  clearTimeout(timeout);
  // handle rooms
});
net.listRooms();

No off() method

Listeners registered with net.on() persist for the lifetime of the instance. Use a flag variable to gate a callback if you need to stop handling an event.

In-memory state only

All room and player state lives in the server process. A server restart wipes everything. Do not build persistence assumptions on top of room state.

Silent send when disconnected

Calling any messaging or room method before connected fires, or after a disconnect, silently does nothing. Check the browser console for WebSocket errors if messages seem to be disappearing.