Stadiums and replays · Ball2D Docs

Both functions are exported by ball2d and ball2d/node and work without an API key or a running room.

validateStadium()

function

validateStadium(source: string): StadiumValidation

Parses the stadium exactly as a room would and throws if a room could not load it. It checks syntax, structure, geometry and the collision budget; passing means the stadium loads, not that it plays well.

Sources are limited to 256 KB, 63 discs, 1,024 vertexes, 64 planes, 16 goals and 128 joints. Unknown fields don't fail validation; each is reported in warnings, such as Unsupported stadium field: $.discs[2].bar.

Parameters

sourcestringrequired

Stadium source text: the contents of a .ball2dstadium or JSON file.

Returns

StadiumValidationThe stadium name, whether it may be stored, and warnings for fields Ball2D ignores.

check-stadium.mjs

import { readFile } from 'node:fs/promises';
import { validateStadium } from 'ball2d/node';

const source = await readFile(
  'futsal.ball2dstadium',
  'utf8',
);
try {
  const report = validateStadium(source);
  console.log(report.name, report.warnings);
} catch (error) {
  console.error(
    'Stadium rejected:',
    error.message,
  );
}

readReplay()

function

readReplay(blob: Blob): Promise<Replay>

Decodes and verifies a recording. Recordings are binary; don't parse them as JSON.

Only recordings made with the same engine build can be read. A recording from another engine rejects with Unsupported replay engine/version, so keep the SDK version you recorded with if you need to read old files.

Parameters

blobBlobrequired

A recording, as returned by stopRecording() or read from a .ball2drep file. Up to 32 MB.

Returns

Promise<Replay>The decoded recording.

JavaScript

import { readFile } from 'node:fs/promises';
import { readReplay } from 'ball2d/node';

const bytes = await readFile('final.ball2drep');
const replay = await readReplay(
  new Blob([bytes]),
);
const seconds =
  (replay.end - replay.initial.tick) / 60;
console.log(
  `${seconds.toFixed(1)} s,` +
    ` ${replay.commands.length} commands`,
);

StadiumValidation

Import fromball2dball2d/node

interface StadiumValidation

readonly namestringrequired

The stadium name, up to 64 characters. Untitled stadium when the source has none.

readonly canBeStoredbooleanrequired

false only when the source sets canBeStored: false.

readonly warningsreadonly string[]required

Unsupported fields, with their paths. At most 64 are listed.