Multiplayer apps

Every file Arg can edit together has a room: the live channel its editor uses to show you who else is there and to merge everyone’s edits. An app can join that room through document.collaborate() and use it for its own multiplayer - players walking around a map, cursors on a canvas, a shared vote - without running a server. A room carries two things, and they behave differently:

	Presence (`session.awareness`)	Shared state (Yjs updates)
What it is	One small JSON object per viewer, replaced as it changes	A CRDT document every viewer converges on
Lifetime	Gone when that viewer closes the file or disconnects	Kept by the room; only the format’s own content reaches the file
Good for	Position, cursor, selection, typing, emotes, “who is here”	Data everyone should see and keep
Needs `yjs`	No	Yes - your app brings its own copy

Getting a room

A room belongs to a file, and an app reaches the room of its document. There are two ways to give an app one, and they decide who is in the room and what it can hold:

	Launched from its `.app`	Opened on a file of a registered type
`document` is	The `.app` launcher, read-only	The file, e.g. `team.farm`
Who is in a room	Everyone running the app from that launcher	Everyone with that file open
Presence	Yes	Yes
Shared Yjs state	No - `session.readOnly` is `true`	Yes, for viewers who may edit the file
Saved data	None - use `fs` for anything that must last	The file’s own content

Presence for every launch

Every .app launcher (the file that gives an app its name and icon in Apps) is that app’s room. Open the launcher - from Apps, the activity rail or Files - and document.current() describes it, with editor: "app" and readOnly: true, and collaborate() joins everyone else who opened the same launcher. The app’s relative paths still resolve beside its own source, not beside the launcher. This room carries presence only. The launcher’s bytes are its manifest, so document.write is refused and session.update does nothing. An .html or .tsx file opened directly, rather than through a launcher, has no document.

A shared file for shared state

For state that everyone edits and that lasts, register the app for a file type in its launcher, then have people open a file of that type:

/apps/farm.app

{
  "version": 2,
  "name": "Farm",
  "icon": "<svg viewBox=\"0 0 24 24\">...</svg>",
  "entry": { "kind": "file", "id": null, "path": "/apps/farm.html" },
  "file_types": ["farm"],
  "permissions": { "files": { "access": "readwrite", "scope": "folder" } }
}

Now team.farm offers Farm in its App switcher, and everyone who opens team.farm with it is in the same room. Any extension works, including one Arg has no editor for: such a file opens in the plain text editor, which has a room. A different file is a different room, so team.farm and practice.farm are separate games. Formats with no room of their own - a PDF, a .docx - reject collaborate() with unsupported_capability.

Joining

import { auth, document } from "@arg-ai/sdk";

const active = await document.current();
if (!active) return runSolo(); // an .html opened directly, or outside Arg

const session = await document.collaborate();
const me = session.awareness.clientId;

Wrap the import in a dynamic import("@arg-ai/sdk").catch(() => null) if the page should also run where Arg is not hosting it, such as a share link, and fall back to a single-player mode there. session.readOnly is true in a launcher’s room, and in a file’s room when this viewer may not write the file (a viewer grant, a read-only Workspace access grant, a locked file). Presence still works, and updates still arrive; session.update does nothing.

Presence

session.awareness is the room’s presence. Each viewer has one entry, keyed by a numeric clientId:

type ArgAwarenessState = {
  clientId: number;
  state: {
    user?: {
      userId: string;
      name: string;
      color: string;
      avatarUrl?: string;
      avatarEmoji?: string;
    };
    [field: string]: unknown; // whatever each client published
  } | null;
};

user is filled in by Arg for every signed-in viewer - name, a stable colour, avatar - so you do not need auth.principal() to label someone. Everything else is yours.

// Publish this viewer's player when it changes (throttled - see below).
session.awareness.setLocalStateField("player", { x, z, facing, emote });

// Draw everyone else.
const render = (states) => {
  for (const { clientId, state } of states) {
    if (clientId === me) continue; // your own entry is in the list
    if (!state?.player) continue; // open in the file's editor, not the game
    drawPlayer(
      clientId,
      state.user?.name ?? "guest",
      state.user?.color,
      state.player,
    );
  }
};
render(session.awareness.states());
session.awareness.onChange(render);

Four things to get right:

Your own entry is in states(). Skip the one whose clientId is session.awareness.clientId.
Not everyone in the room is running your app. Someone with the same file open in its regular editor has a user and nothing else. Key what you draw on your own field.
Your fields are merged into the viewer’s entry, never replacing it. setLocalState({ player }) sets player and leaves the rest; setLocalState(null) clears only the fields your app published. user is never written, so an app cannot remove a person from the file’s collaborator list. Use a field name specific to your app, so it cannot collide with the editor’s own cursor fields.
Presence is relayed to every viewer in the room. Send on change, and cap a moving value at around ten updates a second; interpolate between them on the receiving side. There is no need to re-send an unchanged state to keep it alive.

When a viewer closes the file, loses access or disconnects, their entry disappears and onChange fires without it.

Shared state

Updates are Yjs update bytes. The SDK has no dependency on yjs, so import your own copy and connect it once:

import * as Y from "yjs";

const doc = new Y.Doc();
Y.applyUpdate(doc, session.initialState, session);
session.onUpdate((update) => Y.applyUpdate(doc, update, session));
doc.on("update", (update, origin) => {
  if (origin !== session) session.update(update);
});

Apply initialState before any live update - it is the whole room as one update. Pass session as the origin when applying the room’s updates, so the update listener can tell them from your own; sending the room’s updates back to it duplicates content. Only the format’s own content is saved to the file. The room keeps every shared type it is given, but what reaches disk is what the file’s editor writes. For a format that opens in the text editor - any extension Arg does not know - that is the Y.Text named content, which holds the file’s text. Two rules follow:

Data that must survive belongs in the file. For a custom format, keep it as JSON in doc.getText("content") and update it through the text, or write it with document.write(json, { expectRevision }) and let the room pick up the change.
A shared type of your own, such as doc.getMap("farm"), is shared live but never written to the file, and is not guaranteed to survive the room reloading from the file - which happens after anything writes the file outside the room (an agent, a sync, fs.write). Use it for state that may reset, such as a lobby or a round in progress.

For a format Arg has its own editor for, the shared types belong to that editor - a kanban board’s lanes, a document’s text. Read that editor’s shape rather than inventing a new one, or your writes will not appear in it and will not be saved.

Leaving

session.onClose((reason) => showSolo(reason));
window.addEventListener("pagehide", () => session.close());

onClose fires when the room goes away under the app: room_closed (the file was closed), room_replaced (the editor reconnected into a new room - call collaborate() again) or document_changed (the app was moved to a different file). close() withdraws your presence fields and stops the updates.

Where it works

Web and the desktop app support rooms in .html, .tsx and .jsx apps. The iOS and Android apps do not yet: collaborate() reports unsupported_capability there, so keep the solo fallback. A published Site has no document and no room. Everything in document is listed in the SDK reference; reading and writing the document without a room is covered in Apps inside Arg.

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

Multiplayer apps

Getting a room

Presence for every launch

A shared file for shared state

Joining

Presence

Shared state

Leaving

Where it works

​Getting a room

​Presence for every launch

​A shared file for shared state

​Joining

​Presence

​Shared state

​Leaving

​Where it works

Getting a room

Presence for every launch

A shared file for shared state

Joining

Presence

Shared state

Leaving

Where it works