@lobby-ws/lobbyworks-sdk

Runtime SDK for non-invasive Lobby multiplayer external game integrations.

This package is the reusable runtime layer behind the Lobby external-games flow. It is intended to work together with the bundled integration skill and the Lobby CLI:

• the SDK provides stable runtime helpers
• the bundled skill patches host repos to use those helpers
• the CLI verifies and publishes the result

Bundled Integration Skill

The canonical integration skill for coding agents now lives in this repo:

• skills/lobby-games-integration/SKILL.md

That keeps the runtime package, the integration workflow, and the supporting references in one place.

What It Solves

Use this package when you want an external multiplayer browser/server game to run on Lobby-managed identity and runtime services without rewriting core game systems.

Client-only singleplayer hosted games can publish through lobby.game.json and lobby games publish without this SDK. The SDK is for the managed-runtime multiplayer lane.

For both singleplayer and multiplayer titles, directory-facing metadata still lives in lobby.game.json:

• description for the public store copy
• media.cover_image for the published explorer card art, stored under client.root

The intended shape is:

1. Add the SDK.
2. Patch one client bootstrap or network entrypoint.
3. Patch one server auth or websocket entrypoint.
4. Patch one server startup entrypoint when managed fleets are used.

Everything else should stay where it already lives.

Goals

• Patch one client bootstrap or network file
• Patch one server auth or websocket file
• Patch one server startup file for managed fleets
• Leave gameplay, rendering, ECS, physics, and packet schemas alone
• Keep Lobby identity separate from local connection ids
• Support both direct API access and embedded parent-window bridges

Non-Goals

• Engine rewrites
• Gameplay rewrites
• Matchmaking UI
• Billing or checkout
• Manifest validation
• Publish/build orchestration

Package Surface

@lobby-ws/lobbyworks-sdk/client

• createLobbyClient(options)
  • fetchBootstrap()
  • fetchRuntimeAssignment(payload?)
  • fetchExchange()
  • resolveRuntime(payload?)
  • getRuntimeWsUrl(runtime)
  • getRuntimeArtifactBaseUrl(source)
  • createAssetResolver(source)
  • createLoaderConfig(source, options?)
  • resolveHostedConnection(options)
  • connectHostedGame(options)
  • registerServiceWorker(options?)

@lobby-ws/lobbyworks-sdk/server

• verifyLobbyPlayer(token, { verifyUrl, fetchImpl })
• createLobbyHeartbeat(options)
• createLobbyAgonesLifecycle(options)
• reportLobbyMatchComplete(reason, metadata?)

Quick Start

Install as a normal dependency once published:

npm install @lobby-ws/lobbyworks-sdk

Or consume locally during development:

{
  "dependencies": {
    "@lobby-ws/lobbyworks-sdk": "file:../lobbyworks-sdk"
  }
}

If the host repo is built into Docker as an isolated build context, prefer a workspace package or a published package. A parent-directory file: dependency will not exist inside the container unless you explicitly copy it into the build context.

Example

import { createLobbyClient } from '@lobby-ws/lobbyworks-sdk/client'

const lobby = createLobbyClient({ slug: 'my-game' })
const runtime = await lobby.resolveRuntime()
const runtimeUrl = lobby.getRuntimeWsUrl(runtime)
const token = runtime.exchange?.token || null
const resolveAssetUrl = lobby.createAssetResolver(runtime)
const loader = lobby.createLoaderConfig(runtime)

import { connectLobbyHostedGame } from '@lobby-ws/lobbyworks-sdk/client'

const connection = await connectLobbyHostedGame({
  slug: 'my-game',
  decode,
})

import {
  createLobbyAgonesLifecycle,
  createLobbyHeartbeat,
  resolveLobbyPlayerFromRequest,
  verifyLobbyPlayer,
} from '@lobby-ws/lobbyworks-sdk/server'

const lifecycle = createLobbyAgonesLifecycle()
await lifecycle.ready()

const heartbeat = createLobbyHeartbeat({
  getPlayerCount: () => sessions.size,
})
heartbeat.start()

const claims = await verifyLobbyPlayer(token, {
  verifyUrl: process.env.LOBBY_GAME_IDENTITY_VERIFY_URL,
})

const lobbyPlayer = await resolveLobbyPlayerFromRequest(req)

Typical Host-Repo Changes

In a healthy integration, the host repo usually only changes:

• one client source file
• one server auth source file
• one server startup file
• package manifests and lockfile
• optionally Dockerfile/build wiring

That is the bar for “non-invasive” in this package.

If a host repo needs more than that, the preferred fix is usually to add one more adapter/helper to the SDK rather than spreading more Lobby-specific logic into gameplay or engine code.

Docs

• Architecture
• API Reference
• Integration Guide
• Migration From Generated lobby/ Helpers
• Publishing Guide
• Bundled Skill

Local Development

Run tests with:

npm test

Consume locally from another repo with:

{
  "dependencies": {
    "@lobby-ws/lobbyworks-sdk": "file:../lobbyworks-sdk"
  }
}

For monorepos that publish Docker images from the repo root, a workspace package is often a better local-development shape than a parent-directory file: dependency.

See Publishing Guide for release steps and package-consumer guidance.