Skip to content
Ball2DDocs

Errors and types

Types

Players, scores, match state, discs, replays and the other shapes the SDK returns.

Each type notes where it can be imported from. Types that are not exported by name are still part of the public contract; reach them through the values that return them, for example ReturnType<NodeRoom['getState']>.

Players and scores

HostPlayer

Import fromball2dball2d/node

interface HostPlayer
idnumberrequired
Stable public ID for as long as the player is in the room. Not reused after they leave. The host player is 0.
peerIdstringrequired
Identifier of the player’s connection. Changes if the player rejoins.
namestringrequired
The name the player chose, 1–24 characters. Untrusted display text.
team0 | 1 | 2required
0 spectators, 1 red, 2 blue.
adminbooleanrequired
Whether the player has admin rights in this room.
mutedboolean
Room chat is suppressed while true; absent on older hosts.
avatarstring | null
The avatar drawn on the player’s disc: your override, else the player’s own, else null.
position{ x: number; y: number; } | nullrequired
Centre of the player’s disc during a match. null in the lobby and for spectators.
inputnumberrequired
Current authoritative key bitmask: up 1, down 2, left 4, right 8, kick 16.

HostScores

Import fromball2dball2d/node

interface HostScores
rednumberrequired
Goals scored by red.
bluenumberrequired
Goals scored by blue.
timenumberrequired
Played time in seconds. Stops while paused and between goals.
scoreLimitnumberrequired
Goals needed to win; 0 for no limit.
timeLimitnumberrequired
Match length in seconds; 0 for no limit.

Match state

MatchState

Not exported by name; reach it through the values that return it.

interface MatchState
lastTouchBallTouch | null
Host-simulated touch; null when no player has touched this kickoff.
goalTouchBallTouch | null
Frozen at the goal line, including the player's team for own goals.
ticknumberrequired
Simulation ticks since the stadium loaded, at 60 per second. Advances in every phase.
elapsednumberrequired
Ticks of played time. Counts only after kickoff is taken, and not while paused or between goals.
rednumberrequired
Goals scored by red.
bluenumberrequired
Goals scored by blue.
phase'lobby' | 'playing' | 'goal' | 'finished'required
lobby, playing, goal (5.5 s after a goal) or finished (5 s after a win).
pausedbooleanrequired
Whether the match is paused.
resumeTicksnumberrequired
Ticks left in the resume countdown, 0–119.
countdownnumberrequired
Ticks left in the goal or finished phase.
kickoff1 | 2required
The team taking kickoff: 1 red or 2 blue.
kickoffActivebooleanrequired
true until the kickoff is taken.
scoreLimitnumberrequired
Goals needed to win; 0 for no limit.
timeLimitnumberrequired
Match length in seconds; 0 for no limit.
kickRatenumberrequired
The kick rate limit packed as min | rate << 8 | burst << 16.
discsnumber[]required
Raw disc data: 18 numbers per disc, stadium discs first and then all 32 player slots. Prefer the physics methods.
colorsnumber[]required
Color of each disc as an RGB integer; -1 is transparent.

BallTouch

Not exported by name; reach it through the values that return it.

interface BallTouch
slotnumberrequired
Internal player slot, from 0. Not a player ID.
team1 | 2required
The toucher’s team: 1 red or 2 blue.

Discs

DiscProperty

Not exported by name; reach it through the values that return it.

type DiscProperty = 'x' | 'y' | 'xspeed' | 'yspeed' | 'xgravity' | 'ygravity' | 'radius' | 'bCoeff' | 'invMass' | 'damping' | 'color' | 'cMask' | 'cGroup'

Supported public disc properties; no internal solver offsets or validation tables.

Names of the disc properties you can read and change. See Physics for their ranges.

DiscProperties

Not exported by name; reach it through the values that return it.

type DiscProperties = Record<DiscProperty, number>
A complete set of disc properties, as the physics reads return.

HostDiscProperties

Import fromball2dball2d/node

type HostDiscProperties = DiscProperties
The exported name for DiscProperties.

DiscPropertyPatch

Not exported by name; reach it through the values that return it.

type DiscPropertyPatch = Partial<Record<DiscProperty, number | null>>

A partial update. Omitted and null fields keep their current value.

Chat

AnnouncementStyle

Not exported by name; reach it through the values that return it.

type AnnouncementStyle = 'normal' | 'bold' | 'italic' | 'small' | 'small-bold' | 'small-italic'
Text styles for sendAnnouncement().

Teams

TeamColors

Not exported by name; reach it through the values that return it.

interface TeamColors
anglenumberrequired
Stripe angle in degrees.
textColornumberrequired
Color of the player numbers, as an RGB integer.
colorsnumber[]required
One to three stripe colors, as RGB integers.

TeamStyles

Not exported by name; reach it through the values that return it.

type TeamStyles = [TeamColors | null, TeamColors | null]
Red and blue kits in a recording; null for a team that uses the default kit.

Replays

Replay

Import fromball2dball2d/node

interface Replay
magic'B2DR'required
Always B2DR.
version1required
Recording format version.
enginestringrequired
The engine build that made the recording. Only the same build can read it.
stadiumstringrequired
Source text of the stadium the match was played on.
initialMatchStaterequired
Match state when recording started.
commandsReplayCommand[]required
Inputs and room commands, in tick order.
checkpointsCheckpoint[]required
Periodic state hashes used to verify playback.
roster{ tick: number; slot: number; name: string | null; avatar?: string | null; }[]required
Players entering and leaving slots, with their names and avatars.
styles{ tick: number; teams: TeamStyles; }[]
Team kit changes.
orders{ tick: number; slots: number[]; }[]
Roster order changes.
endnumberrequired
The tick the recording ends on.
finalHashstringrequired
Hash of the final state, for verification.

ReplayCommand

Not exported by name; reach it through the values that return it.

type ReplayCommand = { tick: number; kind: 'input' | 'team' | 'start' | 'stop' | 'pause' | 'scoreLimit' | 'timeLimit' | 'kickRate' | 'join' | 'disc'; properties?: DiscPropertyPatch; slot: number; value: number; }
ticknumberrequired
The tick the command applies to.
kind'input' | 'team' | 'start' | 'stop' | 'pause' | 'scoreLimit' | 'timeLimit' | 'kickRate' | 'join' | 'disc'required
What happened: an input, a team change, a match control, a limit change, a join or a disc change.
propertiesDiscPropertyPatch
For disc commands, the properties that changed.
slotnumberrequired
The internal player slot the command affects.
valuenumberrequired
The command’s value, such as an input bitmask or a team number.

Checkpoint

Not exported by name; reach it through the values that return it.

interface Checkpoint
ticknumberrequired
The tick the checkpoint was taken at.
stateMatchStaterequired
The match state at that tick.
hashstringrequired
Hash of the full simulation state.