@hax-brasil/replay-decoder 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 N-API for Rust
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @hax-brasil/replay-decoder
+
+Node.js native decoder and validator for Haxball `HBR2` replay files.
+
+This package wraps [`haxball-replay-decoder`](https://crates.io/crates/haxball-replay-decoder) with N-API and exposes:
+
+- sync + async replay decoding
+- sync + async replay validation
+- rich structured decode errors
+- full TypeScript types for decoded replay structures and validation reports
+
+## Install
+
+```bash
+pnpm add @hax-brasil/replay-decoder
+```
+
+## Usage
+
+```ts
+import { decode, validate, tryDecode, ReplayDecodeError } from '@hax-brasil/replay-decoder'
+import { readFileSync } from 'node:fs'
+
+const bytes = readFileSync('./recording.hbr2')
+
+const replay = decode(bytes)
+console.log(replay.version, replay.totalFrames)
+
+const report = validate(bytes, 'strict')
+console.log(report.issues)
+
+const safe = tryDecode(bytes)
+if (!safe.ok) {
+  console.error(safe.error.kind, safe.error.details)
+}
+
+try {
+  decode(Buffer.from('bad'))
+} catch (error) {
+  if (error instanceof ReplayDecodeError) {
+    console.error(error.kind, error.details)
+  }
+}
+```
+
+## API
+
+- `decode(bytes, options?) => ReplayData`
+- `decodeAsync(bytes, options?) => Promise<ReplayData>`
+- `tryDecode(bytes, options?) => DecodeResult`
+- `tryDecodeAsync(bytes, options?) => Promise<DecodeResult>`
+- `validate(bytes, profile?) => ValidationReport`
+- `validateAsync(bytes, profile?) => Promise<ValidationReport>`
+
+### Input
+
+All APIs accept only bytes:
+
+- `Buffer`
+- `Uint8Array`
+
+### Decode options
+
+```ts
+interface DecodeOptions {
+  validationProfile?: 'strict' | 'structural'
+  allowUnknownEventTypes?: boolean
+}
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+```

package/index.d.ts

@@ -0,0 +1,29 @@
+export * from './types'
+
+import type {
+  BytesLike,
+  DecodeFailure,
+  DecodeOptions,
+  DecodeResult,
+  DecodeErrorDetails,
+  DecodeErrorKind,
+  ReplayData,
+  ValidationProfile,
+  ValidationReport,
+} from './types'
+
+export declare class ReplayDecodeError extends Error {
+  name: 'ReplayDecodeError'
+  kind: DecodeErrorKind
+  details: DecodeErrorDetails
+  constructor(error: DecodeFailure)
+}
+
+export declare function decode(bytes: BytesLike, options?: DecodeOptions): ReplayData
+export declare function decodeAsync(bytes: BytesLike, options?: DecodeOptions): Promise<ReplayData>
+
+export declare function tryDecode(bytes: BytesLike, options?: DecodeOptions): DecodeResult
+export declare function tryDecodeAsync(bytes: BytesLike, options?: DecodeOptions): Promise<DecodeResult>
+
+export declare function validate(bytes: BytesLike, profile?: ValidationProfile): ValidationReport
+export declare function validateAsync(bytes: BytesLike, profile?: ValidationProfile): Promise<ValidationReport>

package/index.js

@@ -0,0 +1,294 @@
+// prettier-ignore
+/* eslint-disable */
+
+const { readFileSync } = require('node:fs')
+
+const loadErrors = []
+
+const isMusl = () => {
+  let musl = false
+  if (process.platform === 'linux') {
+    musl = isMuslFromFilesystem()
+    if (musl === null) {
+      musl = isMuslFromReport()
+    }
+    if (musl === null) {
+      musl = isMuslFromChildProcess()
+    }
+  }
+  return musl
+}
+
+const isFileMusl = (file) => file.includes('libc.musl-') || file.includes('ld-musl-')
+
+const isMuslFromFilesystem = () => {
+  try {
+    return readFileSync('/usr/bin/ldd', 'utf-8').includes('musl')
+  } catch {
+    return null
+  }
+}
+
+const isMuslFromReport = () => {
+  let report = null
+  if (typeof process.report?.getReport === 'function') {
+    process.report.excludeNetwork = true
+    report = process.report.getReport()
+  }
+  if (!report) {
+    return null
+  }
+  if (report.header && report.header.glibcVersionRuntime) {
+    return false
+  }
+  if (Array.isArray(report.sharedObjects)) {
+    if (report.sharedObjects.some(isFileMusl)) {
+      return true
+    }
+  }
+  return false
+}
+
+const isMuslFromChildProcess = () => {
+  try {
+    return require('child_process').execSync('ldd --version', { encoding: 'utf8' }).includes('musl')
+  } catch {
+    return false
+  }
+}
+
+const makeCandidates = () => {
+  const candidates = []
+  const add = (localFile, packageName) => {
+    candidates.push({ type: 'local', id: localFile })
+    candidates.push({ type: 'package', id: packageName })
+  }
+
+  const { platform, arch } = process
+
+  if (platform === 'win32') {
+    if (arch === 'x64') {
+      add('./replay-decoder.win32-x64-msvc.node', '@hax-brasil/replay-decoder-win32-x64-msvc')
+      return candidates
+    }
+    if (arch === 'arm64') {
+      add('./replay-decoder.win32-arm64-msvc.node', '@hax-brasil/replay-decoder-win32-arm64-msvc')
+      return candidates
+    }
+    throw new Error(`Unsupported Windows architecture: ${arch}`)
+  }
+
+  if (platform === 'darwin') {
+    add('./replay-decoder.darwin-universal.node', '@hax-brasil/replay-decoder-darwin-universal')
+
+    if (arch === 'x64') {
+      add('./replay-decoder.darwin-x64.node', '@hax-brasil/replay-decoder-darwin-x64')
+      return candidates
+    }
+    if (arch === 'arm64') {
+      add('./replay-decoder.darwin-arm64.node', '@hax-brasil/replay-decoder-darwin-arm64')
+      return candidates
+    }
+    throw new Error(`Unsupported macOS architecture: ${arch}`)
+  }
+
+  if (platform === 'linux') {
+    const musl = isMusl()
+
+    if (arch === 'x64') {
+      if (musl) {
+        add('./replay-decoder.linux-x64-musl.node', '@hax-brasil/replay-decoder-linux-x64-musl')
+      }
+      add('./replay-decoder.linux-x64-gnu.node', '@hax-brasil/replay-decoder-linux-x64-gnu')
+      return candidates
+    }
+
+    if (arch === 'arm64') {
+      if (musl) {
+        add('./replay-decoder.linux-arm64-musl.node', '@hax-brasil/replay-decoder-linux-arm64-musl')
+      }
+      add('./replay-decoder.linux-arm64-gnu.node', '@hax-brasil/replay-decoder-linux-arm64-gnu')
+      return candidates
+    }
+
+    throw new Error(`Unsupported Linux architecture: ${arch}`)
+  }
+
+  throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+const loadNativeBinding = () => {
+  if (process.env.NAPI_RS_NATIVE_LIBRARY_PATH) {
+    try {
+      return require(process.env.NAPI_RS_NATIVE_LIBRARY_PATH)
+    } catch (error) {
+      loadErrors.push(error)
+    }
+  }
+
+  let candidates = []
+  try {
+    candidates = makeCandidates()
+  } catch (error) {
+    loadErrors.push(error)
+  }
+
+  for (const candidate of candidates) {
+    try {
+      return require(candidate.id)
+    } catch (error) {
+      loadErrors.push(error)
+    }
+  }
+
+  if (loadErrors.length > 0) {
+    throw new Error('Failed to load native @hax-brasil/replay-decoder binding', {
+      cause: loadErrors.reduce((error, current) => {
+        current.cause = error
+        return current
+      }),
+    })
+  }
+
+  throw new Error('Native binding was not loaded')
+}
+
+const nativeBinding = loadNativeBinding()
+
+class ReplayDecodeError extends Error {
+  constructor(error) {
+    super(error.message)
+    this.name = 'ReplayDecodeError'
+    this.kind = error.kind
+    this.details = error.details
+  }
+}
+
+const normalizeBytesLike = (bytes) => {
+  if (Buffer.isBuffer(bytes)) {
+    return bytes
+  }
+  if (bytes instanceof Uint8Array) {
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  }
+  throw new TypeError('Expected bytes to be a Buffer or Uint8Array')
+}
+
+const normalizeValidationProfile = (profile) => {
+  if (profile == null) {
+    return 'strict'
+  }
+  if (profile === 'strict' || profile === 'structural') {
+    return profile
+  }
+  throw new TypeError("validationProfile must be 'strict' or 'structural'")
+}
+
+const normalizeDecodeOptions = (options) => {
+  if (options == null) {
+    return undefined
+  }
+
+  if (typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('decode options must be an object')
+  }
+
+  const normalized = {}
+
+  if (Object.hasOwn(options, 'validationProfile') && options.validationProfile !== undefined) {
+    normalized.validationProfile = normalizeValidationProfile(options.validationProfile)
+  }
+
+  if (Object.hasOwn(options, 'allowUnknownEventTypes') && options.allowUnknownEventTypes !== undefined) {
+    if (typeof options.allowUnknownEventTypes !== 'boolean') {
+      throw new TypeError('allowUnknownEventTypes must be a boolean')
+    }
+    normalized.allowUnknownEventTypes = options.allowUnknownEventTypes
+  }
+
+  if (Object.keys(normalized).length === 0) {
+    return undefined
+  }
+
+  return normalized
+}
+
+const parseNativeJson = (raw, apiName) => {
+  try {
+    return JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`Native ${apiName} returned invalid JSON`, { cause: error })
+  }
+}
+
+const decodeTrySyncInternal = (bytes, options) => {
+  const normalizedBytes = normalizeBytesLike(bytes)
+  const normalizedOptions = normalizeDecodeOptions(options)
+  const optionsJson = normalizedOptions ? JSON.stringify(normalizedOptions) : undefined
+  const raw = nativeBinding.__decode_try_json_sync(normalizedBytes, optionsJson)
+  return parseNativeJson(raw, '__decode_try_json_sync')
+}
+
+const decodeTryAsyncInternal = async (bytes, options) => {
+  const normalizedBytes = normalizeBytesLike(bytes)
+  const normalizedOptions = normalizeDecodeOptions(options)
+  const optionsJson = normalizedOptions ? JSON.stringify(normalizedOptions) : undefined
+  const raw = await nativeBinding.__decode_try_json_async(normalizedBytes, optionsJson)
+  return parseNativeJson(raw, '__decode_try_json_async')
+}
+
+const validateSyncInternal = (bytes, profile) => {
+  const normalizedBytes = normalizeBytesLike(bytes)
+  const normalizedProfile = normalizeValidationProfile(profile)
+  const raw = nativeBinding.__validate_json_sync(normalizedBytes, normalizedProfile)
+  return parseNativeJson(raw, '__validate_json_sync')
+}
+
+const validateAsyncInternal = async (bytes, profile) => {
+  const normalizedBytes = normalizeBytesLike(bytes)
+  const normalizedProfile = normalizeValidationProfile(profile)
+  const raw = await nativeBinding.__validate_json_async(normalizedBytes, normalizedProfile)
+  return parseNativeJson(raw, '__validate_json_async')
+}
+
+const decode = (bytes, options) => {
+  const result = decodeTrySyncInternal(bytes, options)
+  if (result.ok) {
+    return result.data
+  }
+  throw new ReplayDecodeError(result.error)
+}
+
+const decodeAsync = async (bytes, options) => {
+  const result = await decodeTryAsyncInternal(bytes, options)
+  if (result.ok) {
+    return result.data
+  }
+  throw new ReplayDecodeError(result.error)
+}
+
+const tryDecode = (bytes, options) => decodeTrySyncInternal(bytes, options)
+
+const tryDecodeAsync = async (bytes, options) => decodeTryAsyncInternal(bytes, options)
+
+const validate = (bytes, profile) => validateSyncInternal(bytes, profile)
+
+const validateAsync = async (bytes, profile) => validateAsyncInternal(bytes, profile)
+
+module.exports = {
+  ReplayDecodeError,
+  decode,
+  decodeAsync,
+  tryDecode,
+  tryDecodeAsync,
+  validate,
+  validateAsync,
+}
+
+module.exports.ReplayDecodeError = ReplayDecodeError
+module.exports.decode = decode
+module.exports.decodeAsync = decodeAsync
+module.exports.tryDecode = tryDecode
+module.exports.tryDecodeAsync = tryDecodeAsync
+module.exports.validate = validate
+module.exports.validateAsync = validateAsync

package/package.json

@@ -0,0 +1,115 @@
+{
+  "name": "@hax-brasil/replay-decoder",
+  "version": "1.0.0",
+  "description": "Node.js HBR2 decoder and validator powered by haxball-replay-decoder",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hax-brasil/node-haxball-replay-decoder.git"
+  },
+  "license": "MIT",
+  "keywords": [
+    "haxball",
+    "replay",
+    "hbr2",
+    "decoder",
+    "napi-rs",
+    "node-addon"
+  ],
+  "files": [
+    "index.d.ts",
+    "types.d.ts",
+    "index.js",
+    "README.md"
+  ],
+  "napi": {
+    "binaryName": "replay-decoder",
+    "targets": [
+      "x86_64-pc-windows-msvc",
+      "x86_64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-unknown-linux-gnu",
+      "aarch64-apple-darwin"
+    ]
+  },
+  "engines": {
+    "node": ">= 16"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "artifacts": "napi artifacts",
+    "bench": "node --import @oxc-node/core/register benchmark/bench.ts",
+    "build": "napi build --platform --release --no-js --dts native.d.ts",
+    "build:debug": "napi build --platform --no-js --dts native.d.ts",
+    "format": "run-p format:prettier format:rs format:toml",
+    "format:prettier": "prettier . -w",
+    "format:toml": "taplo format",
+    "format:rs": "cargo fmt",
+    "lint": "oxlint .",
+    "prepublishOnly": "napi prepublish -t npm",
+    "test": "pnpm typecheck && pnpm build:debug && ava",
+    "typecheck": "tsc -p __test__/tsconfig.json --noEmit",
+    "preversion": "napi build --platform --no-js --dts native.d.ts && git add .",
+    "version": "napi version",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "@napi-rs/cli": "^3.2.0",
+    "@oxc-node/core": "^0.0.35",
+    "@taplo/cli": "^0.7.0",
+    "ava": "^7.0.0",
+    "chalk": "^5.6.2",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.1.6",
+    "npm-run-all2": "^8.0.4",
+    "oxlint": "^1.14.0",
+    "prettier": "^3.6.2",
+    "tinybench": "^6.0.0",
+    "typescript": "^5.9.2"
+  },
+  "lint-staged": {
+    "*.@(js|ts|tsx)": [
+      "oxlint --fix"
+    ],
+    "*.@(js|ts|tsx|yml|yaml|md|json)": [
+      "prettier --write"
+    ],
+    "*.toml": [
+      "taplo format"
+    ]
+  },
+  "ava": {
+    "extensions": {
+      "ts": "module"
+    },
+    "timeout": "2m",
+    "workerThreads": false,
+    "environmentVariables": {
+      "OXC_TSCONFIG_PATH": "./__test__/tsconfig.json"
+    },
+    "nodeArguments": [
+      "--import",
+      "@oxc-node/core/register"
+    ]
+  },
+  "prettier": {
+    "printWidth": 120,
+    "semi": false,
+    "trailingComma": "all",
+    "singleQuote": true,
+    "arrowParens": "always"
+  },
+  "packageManager": "pnpm@10.13.1",
+  "optionalDependencies": {
+    "@hax-brasil/replay-decoder-win32-x64-msvc": "1.0.0",
+    "@hax-brasil/replay-decoder-darwin-x64": "1.0.0",
+    "@hax-brasil/replay-decoder-linux-x64-gnu": "1.0.0",
+    "@hax-brasil/replay-decoder-linux-arm64-gnu": "1.0.0",
+    "@hax-brasil/replay-decoder-darwin-arm64": "1.0.0"
+  }
+}

package/types.d.ts

@@ -0,0 +1,443 @@
+export type BytesLike = Buffer | Uint8Array
+
+export type ValidationProfile = 'strict' | 'structural'
+
+export interface DecodeOptions {
+  validationProfile?: ValidationProfile
+  allowUnknownEventTypes?: boolean
+}
+
+export type ValidationSeverity = 'error' | 'warning'
+
+export interface ValidationIssue {
+  code: string
+  severity: ValidationSeverity
+  path: string
+  message: string
+}
+
+export interface ValidationReport {
+  profile: ValidationProfile
+  issues: ValidationIssue[]
+}
+
+export type OperationType =
+  | 'sendAnnouncement'
+  | 'sendChatIndicator'
+  | 'checkConsistency'
+  | 'sendInput'
+  | 'sendChat'
+  | 'joinRoom'
+  | 'kickBanPlayer'
+  | 'startGame'
+  | 'stopGame'
+  | 'pauseResumeGame'
+  | 'setGamePlayLimit'
+  | 'setStadium'
+  | 'setPlayerTeam'
+  | 'setTeamsLock'
+  | 'setPlayerAdmin'
+  | 'autoTeams'
+  | 'setPlayerSync'
+  | 'ping'
+  | 'setAvatar'
+  | 'setTeamColors'
+  | 'reorderPlayers'
+  | 'setKickRateLimit'
+  | 'setHeadlessAvatar'
+  | 'setDiscProperties'
+  | 'customEvent'
+  | 'binaryCustomEvent'
+  | 'setPlayerIdentity'
+
+export type BackgroundType = 'none' | 'grass' | 'hockey' | { unknown: number }
+
+export type CameraFollow = 'none' | 'player' | { unknown: number }
+
+export type GamePlayState = 'beforeKickOff' | 'playing' | 'afterGoal' | 'ending' | { unknown: number }
+
+export interface Point {
+  x: number
+  y: number
+}
+
+export interface Vertex {
+  pos: Point
+  bCoef: number
+  cMask: number
+  cGroup: number
+}
+
+export interface Segment {
+  flags: number
+  v0: number
+  v1: number
+  bias: number
+  curve: number
+  color: number
+  vis: boolean
+  bCoef: number
+  cMask: number
+  cGroup: number
+}
+
+export interface Plane {
+  normal: Point
+  dist: number
+  bCoef: number
+  cMask: number
+  cGroup: number
+}
+
+export interface Goal {
+  p0: Point
+  p1: Point
+  teamId: number
+}
+
+export interface Disc {
+  pos: Point
+  speed: Point
+  gravity: Point
+  radius: number
+  bCoef: number
+  invMass: number
+  damping: number
+  color: number
+  cMask: number
+  cGroup: number
+}
+
+export interface Joint {
+  d0: number
+  d1: number
+  minLength: number
+  maxLength: number
+  strength: number
+  color: number
+}
+
+export interface PlayerPhysics {
+  bCoef: number
+  invMass: number
+  damping: number
+  acceleration: number
+  kickingAcceleration: number
+  kickingDamping: number
+  kickStrength: number
+  gravity: Point
+  cGroup: number
+  radius: number
+  kickback: number
+}
+
+export interface TeamColors {
+  angle: number
+  text: number
+  inner: number[]
+}
+
+export interface Stadium {
+  defaultStadiumId: number
+  name: string | null
+  backgroundType: BackgroundType | null
+  backgroundWidth: number | null
+  backgroundHeight: number | null
+  backgroundKickoffRadius: number | null
+  backgroundCornerRadius: number | null
+  backgroundGoalLine: number | null
+  backgroundColor: number | null
+  width: number | null
+  height: number | null
+  spawnDistance: number | null
+  playerPhysics: PlayerPhysics | null
+  maxViewWidth: number | null
+  cameraFollow: CameraFollow | null
+  canBeStored: boolean | null
+  fullKickoffReset: boolean | null
+  vertices: Vertex[]
+  segments: Segment[]
+  planes: Plane[]
+  goals: Goal[]
+  discs: Disc[]
+  joints: Joint[]
+  redSpawnPoints: Point[]
+  blueSpawnPoints: Point[]
+}
+
+export interface Player {
+  isAdmin: boolean
+  avatarNumber: number
+  avatar: string | null
+  headlessAvatar: string | null
+  sync: boolean
+  flag: string | null
+  metadata: number
+  name: string | null
+  input: number
+  id: number
+  isKicking: boolean
+  kickRateMaxTickCounter: number
+  kickRateMinTickCounter: number
+  teamId: number
+  discIndex: number
+}
+
+export interface GameState {
+  discs: Disc[]
+  goalTickCounter: number
+  state: GamePlayState
+  redScore: number
+  blueScore: number
+  timeElapsed: number
+  pauseGameTickCounter: number
+  goalConcedingTeam: number
+}
+
+export interface RoomState {
+  name: string | null
+  teamsLocked: boolean
+  scoreLimit: number
+  timeLimit: number
+  kickRateMax: number
+  kickRateRate: number
+  kickRateMin: number
+  stadium: Stadium
+  gameState: GameState | null
+  players: Player[]
+  redTeamColors: TeamColors
+  blueTeamColors: TeamColors
+}
+
+export interface GoalMarker {
+  frameNo: number
+  teamId: number
+}
+
+export interface SendAnnouncementEvent {
+  msg: string
+  color: number
+  style: number
+  sound: number
+}
+
+export interface SendChatIndicatorEvent {
+  value: number
+}
+
+export interface CheckConsistencyEvent {
+  data: number[]
+}
+
+export interface SendInputEvent {
+  input: number
+}
+
+export interface SendChatEvent {
+  text: string
+}
+
+export interface JoinRoomEvent {
+  playerId: number
+  name: string | null
+  flag: string | null
+  avatar: string | null
+}
+
+export interface KickBanPlayerEvent {
+  playerId: number
+  reason: string | null
+  ban: boolean
+}
+
+export type StartGameEvent = Record<string, never>
+export type StopGameEvent = Record<string, never>
+
+export interface PauseResumeGameEvent {
+  paused: boolean
+}
+
+export interface SetGamePlayLimitEvent {
+  limitType: number
+  newValue: number
+}
+
+export interface SetStadiumEvent {
+  stadium: Stadium
+}
+
+export interface SetPlayerTeamEvent {
+  playerId: number
+  teamId: number
+}
+
+export interface SetTeamsLockEvent {
+  newValue: boolean
+}
+
+export interface SetPlayerAdminEvent {
+  playerId: number
+  value: boolean
+}
+
+export type AutoTeamsEvent = Record<string, never>
+
+export interface SetPlayerSyncEvent {
+  value: boolean
+}
+
+export interface PingEvent {
+  pings: number[]
+}
+
+export interface SetAvatarEvent {
+  value: string | null
+}
+
+export interface SetTeamColorsEvent {
+  teamId: number
+  colors: TeamColors
+}
+
+export interface ReorderPlayersEvent {
+  moveToTop: boolean
+  playerIdList: number[]
+}
+
+export interface SetKickRateLimitEvent {
+  min: number
+  rate: number
+  burst: number
+}
+
+export interface SetHeadlessAvatarEvent {
+  value: string | null
+  playerId: number
+}
+
+export type DiscFloatProperties = [
+  number | null,
+  number | null,
+  number | null,
+  number | null,
+  number | null,
+  number | null,
+  number | null,
+  number | null,
+  number | null,
+  number | null,
+]
+
+export type DiscIntegerProperties = [number | null, number | null, number | null]
+
+export interface SetDiscPropertiesEvent {
+  id: number
+  isPlayer: boolean
+  flags: number
+  data1: DiscFloatProperties
+  data2: DiscIntegerProperties
+}
+
+export interface CustomEvent {
+  eventType: number
+  data: unknown
+}
+
+export interface BinaryCustomEvent {
+  eventType: number
+  data: number[]
+}
+
+export interface SetPlayerIdentityEvent {
+  id: number
+  data: unknown
+}
+
+export interface UnknownEvent {
+  eventType: number
+  rawPayload: number[]
+}
+
+export type EventPayload =
+  | { kind: 'sendAnnouncement'; value: SendAnnouncementEvent }
+  | { kind: 'sendChatIndicator'; value: SendChatIndicatorEvent }
+  | { kind: 'checkConsistency'; value: CheckConsistencyEvent }
+  | { kind: 'sendInput'; value: SendInputEvent }
+  | { kind: 'sendChat'; value: SendChatEvent }
+  | { kind: 'joinRoom'; value: JoinRoomEvent }
+  | { kind: 'kickBanPlayer'; value: KickBanPlayerEvent }
+  | { kind: 'startGame'; value: StartGameEvent }
+  | { kind: 'stopGame'; value: StopGameEvent }
+  | { kind: 'pauseResumeGame'; value: PauseResumeGameEvent }
+  | { kind: 'setGamePlayLimit'; value: SetGamePlayLimitEvent }
+  | { kind: 'setStadium'; value: SetStadiumEvent }
+  | { kind: 'setPlayerTeam'; value: SetPlayerTeamEvent }
+  | { kind: 'setTeamsLock'; value: SetTeamsLockEvent }
+  | { kind: 'setPlayerAdmin'; value: SetPlayerAdminEvent }
+  | { kind: 'autoTeams'; value: AutoTeamsEvent }
+  | { kind: 'setPlayerSync'; value: SetPlayerSyncEvent }
+  | { kind: 'ping'; value: PingEvent }
+  | { kind: 'setAvatar'; value: SetAvatarEvent }
+  | { kind: 'setTeamColors'; value: SetTeamColorsEvent }
+  | { kind: 'reorderPlayers'; value: ReorderPlayersEvent }
+  | { kind: 'setKickRateLimit'; value: SetKickRateLimitEvent }
+  | { kind: 'setHeadlessAvatar'; value: SetHeadlessAvatarEvent }
+  | { kind: 'setDiscProperties'; value: SetDiscPropertiesEvent }
+  | { kind: 'customEvent'; value: CustomEvent }
+  | { kind: 'binaryCustomEvent'; value: BinaryCustomEvent }
+  | { kind: 'setPlayerIdentity'; value: SetPlayerIdentityEvent }
+  | { kind: 'unknown'; value: UnknownEvent }
+
+export interface ReplayEvent {
+  frameNo: number
+  byId: number
+  payload: EventPayload
+}
+
+export interface ReplayData {
+  roomData: RoomState
+  events: ReplayEvent[]
+  goalMarkers: GoalMarker[]
+  totalFrames: number
+  version: number
+}
+
+export type DecodeErrorKind =
+  | 'invalidMagic'
+  | 'unexpectedEof'
+  | 'invalidVarInt'
+  | 'invalidUtf8'
+  | 'invalidJson'
+  | 'compression'
+  | 'incompleteCompression'
+  | 'trailingCompressedData'
+  | 'unsupportedReplayVersion'
+  | 'unsupportedEventType'
+  | 'unknownEventBoundaryUnsupported'
+  | 'integerOverflow'
+  | 'trailingBytes'
+  | 'validationFailed'
+
+export type DecodeErrorDetails =
+  | { kind: 'invalidMagic'; found: number[] }
+  | { kind: 'unexpectedEof'; context: string }
+  | { kind: 'invalidVarInt'; context: string }
+  | { kind: 'invalidUtf8'; context: string; source: string }
+  | { kind: 'invalidJson'; context: string; source: string }
+  | { kind: 'compression'; context: string; source: string }
+  | { kind: 'incompleteCompression'; context: string }
+  | { kind: 'trailingCompressedData'; context: string }
+  | { kind: 'unsupportedReplayVersion'; version: number }
+  | { kind: 'unsupportedEventType'; eventType: number }
+  | { kind: 'unknownEventBoundaryUnsupported'; eventType: number }
+  | { kind: 'integerOverflow'; context: string }
+  | { kind: 'trailingBytes'; context: string; remaining: number }
+  | { kind: 'validationFailed'; report: ValidationReport }
+
+export interface DecodeFailure {
+  kind: DecodeErrorKind
+  message: string
+  details: DecodeErrorDetails
+}
+
+export type DecodeResult = { ok: true; data: ReplayData } | { ok: false; error: DecodeFailure }