ball2d 0.0.1 → 0.1.0

package/dist/types/core/engine.d.ts

@@ -0,0 +1,68 @@
+import type { MatchState } from './match-state.js';
+import { type DiscPropertyPatch } from './disc-properties.js';
+import { type Stadium } from './stadium.js';
+export declare const HZ = 60, STRIDE = 18, SLOTS = 32, ENGINE_VERSION = "ball2d-core/1/3de72bdcf92ccb0d235a";
+interface Exports extends WebAssembly.Exports {
+    memory: WebAssembly.Memory;
+    reset: () => void;
+    add_disc: () => number;
+    set_disc: (i: number, k: number, v: number) => void;
+    data_ptr: () => number;
+    count: () => number;
+    step: () => void;
+    wall: (...v: number[]) => void;
+    arc: (...v: number[]) => void;
+    plane: (...v: number[]) => void;
+    joint: (...v: number[]) => void;
+    configure: (...v: number[]) => void;
+    goal: (...v: number[]) => void;
+    physics_mode: (substeps: number) => void;
+    kick_limits: (...v: number[]) => void;
+    goal_event: () => number;
+    ball_kick_events: () => number;
+}
+export type { MatchState } from './match-state.js';
+export declare class Engine {
+    core: Exports;
+    stadium: Stadium;
+    source: string;
+    colors: number[];
+    tick: number;
+    elapsed: number;
+    readonly ballKicks: number[];
+    red: number;
+    blue: number;
+    phase: MatchState['phase'];
+    paused: boolean;
+    resumeTicks: number;
+    countdown: number;
+    kickoff: 1 | 2;
+    kickoffActive: boolean;
+    scoreLimit: number;
+    timeLimit: number;
+    lastGoal: number;
+    kickRate: number;
+    setKickRateLimit(min: number, rate: number, burst: number): void;
+    constructor(instance: WebAssembly.Instance);
+    static create(bytes?: BufferSource, signal?: AbortSignal): Promise<Engine>;
+    get data(): Float64Array<ArrayBuffer>;
+    load(source: string): void;
+    private add;
+    index(slot: number): number;
+    joinPlayer(slot: number): void;
+    setTeam(slot: number, team: number): void;
+    input(slot: number, keys: number): void;
+    applyDiscProperties(index: number, properties: DiscPropertyPatch): boolean;
+    private restoreDiscProperties;
+    private spawn;
+    resetPositions(newMatch?: boolean): void;
+    start(): void;
+    stop(): void;
+    setPaused(paused: boolean): void;
+    private finish;
+    step(): void;
+    snapshot(): MatchState;
+    restore(s: MatchState): void;
+}
+export declare function crosses(a: number[], b: number[], c: number[], d: number[]): boolean;
+export declare function packKickRate(min: number, rate: number, burst: number): number;

package/dist/types/core/host-types.d.ts

@@ -0,0 +1,21 @@
+import type { DiscProperties } from './disc-properties.js';
+export interface HostPlayer {
+    id: number;
+    peerId: string;
+    name: string;
+    team: 0 | 1 | 2;
+    admin: boolean;
+    avatar?: string | null;
+    position: {
+        x: number;
+        y: number;
+    } | null;
+}
+export interface HostScores {
+    red: number;
+    blue: number;
+    time: number;
+    scoreLimit: number;
+    timeLimit: number;
+}
+export type HostDiscProperties = DiscProperties;

package/dist/types/core/match-state.d.ts

@@ -0,0 +1,17 @@
+export interface MatchState {
+    tick: number;
+    elapsed: number;
+    red: number;
+    blue: number;
+    phase: 'lobby' | 'playing' | 'goal' | 'finished';
+    paused: boolean;
+    resumeTicks: number;
+    countdown: number;
+    kickoff: 1 | 2;
+    kickoffActive: boolean;
+    scoreLimit: number;
+    timeLimit: number;
+    kickRate: number;
+    discs: number[];
+    colors: number[];
+}

package/dist/types/core/protocol.d.ts

@@ -0,0 +1,24 @@
+import type { MatchState } from './engine.js';
+export declare const PROTOCOL = 5, MAX_PACKET = 1200;
+export declare function newer(a: number, b: number): boolean;
+export declare function inputPacket(seq: number, keys: number, time: number, epoch?: number): ArrayBuffer;
+export declare function readInput(b: ArrayBuffer): {
+    seq: number;
+    keys: number;
+    time: number;
+    epoch: number;
+};
+export declare function statePackets(state: MatchState, seq: number, epoch?: number): ArrayBuffer[];
+export declare class StateAssembler {
+    epoch: number;
+    constructor(epoch?: number);
+    tick: number;
+    parts: Map<number, Uint8Array<ArrayBufferLike>>;
+    count: number;
+    complete: number;
+    reset(epoch?: number, floor?: number): void;
+    push(b: ArrayBuffer, baseline: MatchState): {
+        state: MatchState;
+        ack: number;
+    } | null;
+}

package/dist/types/core/replay-codec.d.ts

@@ -0,0 +1,6 @@
+export declare const MAX_REPLAY_BYTES: number;
+/** B2DZ v1 envelope: magic, version/reserved, raw length, FNV checksum, raw DEFLATE. */
+export declare function encodeReplayText(text: string): Uint8Array<ArrayBuffer>;
+export declare function encodeReplayBytes(raw: Uint8Array): Uint8Array<ArrayBuffer>;
+export declare function decodeReplayText(input: string | ArrayBuffer | Uint8Array): string;
+export declare function decodeReplayBytes(input: string | ArrayBuffer | Uint8Array): Uint8Array;

package/dist/types/core/replay-types.d.ts

@@ -0,0 +1,41 @@
+import type { DiscPropertyPatch } from './disc-properties.js';
+import type { TeamStyles } from './team-colors.js';
+import type { MatchState } from './match-state.js';
+export type ReplayCommand = {
+    tick: number;
+    kind: 'input' | 'team' | 'start' | 'stop' | 'pause' | 'scoreLimit' | 'timeLimit' | 'kickRate' | 'join' | 'disc';
+    properties?: DiscPropertyPatch;
+    slot: number;
+    value: number;
+};
+interface Checkpoint {
+    tick: number;
+    state: MatchState;
+    hash: string;
+}
+export interface Replay {
+    magic: 'B2DR';
+    version: 1;
+    engine: string;
+    stadium: string;
+    initial: MatchState;
+    commands: ReplayCommand[];
+    checkpoints: Checkpoint[];
+    roster: {
+        tick: number;
+        slot: number;
+        name: string | null;
+        avatar?: string | null;
+    }[];
+    styles?: {
+        tick: number;
+        teams: TeamStyles;
+    }[];
+    orders?: {
+        tick: number;
+        slots: number[];
+    }[];
+    end: number;
+    finalHash: string;
+}
+export {};

package/dist/types/core/replay-wire.d.ts

@@ -0,0 +1,5 @@
+import type { Replay } from './replay.js';
+/** B2DP v2 stores checkpoint discs as lossless float64 before delta-tick commands. */
+export declare function encodeReplayDocument(replay: Replay): Uint8Array<ArrayBuffer>;
+export declare function packReplayDocument(replay: Replay): Uint8Array<ArrayBuffer>;
+export declare function decodeReplayDocument(input: string | ArrayBuffer | Uint8Array): Replay;

package/dist/types/core/replay.d.ts

@@ -0,0 +1,48 @@
+import { type TeamStyles } from './team-colors.js';
+import { Engine, type MatchState } from './engine.js';
+import type { ReplayCommand, Replay } from './replay-types.js';
+export type { ReplayCommand, Replay } from './replay-types.js';
+export declare function stateHash(state: MatchState): string;
+export declare function applyCommand(engine: Engine, c: ReplayCommand): void;
+export declare class Recorder {
+    replay: Replay;
+    private playerOrder;
+    private lastInputs;
+    private bytes;
+    private full;
+    canRecord(engine: Engine): boolean;
+    constructor(engine: Engine, players?: {
+        slot: number;
+        name: string;
+        avatar?: string | null;
+    }[], styles?: TeamStyles);
+    private reserve;
+    player(tick: number, slot: number, name: string | null, avatar?: string | null): boolean;
+    style(tick: number, teams: TeamStyles): boolean;
+    order(tick: number, slots: number[]): boolean;
+    command(c: ReplayCommand): boolean;
+    step(engine: Engine): void;
+    pack(engine: Engine): Uint8Array<ArrayBuffer>;
+    finish(engine: Engine): Blob;
+}
+export declare function readReplay(blob: Blob): Promise<Replay>;
+export declare function parseReplay(input: string | ArrayBuffer | Uint8Array): Replay;
+export declare class Playback {
+    engine: Engine;
+    replay: Replay;
+    cursor: number;
+    constructor(engine: Engine, replay: Replay);
+    teamStyles(): TeamStyles;
+    players(): {
+        id: string;
+        avatar: string | null;
+        slot: number;
+        name: string;
+        team: number;
+        admin: boolean;
+    }[];
+    private commands;
+    private final;
+    step(): boolean;
+    seek(tick: number): void;
+}

package/dist/types/core/stadium.d.ts

@@ -0,0 +1,91 @@
+export declare const FLAGS: Record<string, number>;
+export type Vec = [number, number];
+export interface Disc {
+    pos: Vec;
+    speed: Vec;
+    gravity: Vec;
+    radius: number;
+    invMass: number;
+    damping: number;
+    bCoef: number;
+    cGroup: number;
+    cMask: number;
+    color: string;
+}
+export interface Segment {
+    a: Vec;
+    b: Vec;
+    bCoef: number;
+    cGroup: number;
+    cMask: number;
+    bias: number;
+    color: string;
+    vis: boolean;
+    renderOnly?: boolean;
+}
+export interface Arc extends Segment {
+    center: Vec;
+    radius: number;
+    start: number;
+    sweep: number;
+    major: boolean;
+}
+export interface Stadium {
+    version: 1;
+    physicsMode: 'hbs' | 'substeps';
+    name: string;
+    canBeStored: boolean;
+    width: number;
+    height: number;
+    maxViewWidth: number;
+    cameraFollow: 'ball' | 'player';
+    bg: {
+        type: 'grass' | 'hockey' | 'none';
+        width: number;
+        height: number;
+        color: string;
+        kickOffRadius: number;
+        cornerRadius: number;
+        goalLine: number;
+    };
+    discs: Disc[];
+    segments: Segment[];
+    arcs: Arc[];
+    colliders: (Segment | Arc)[];
+    planes: {
+        normal: Vec;
+        dist: number;
+        bCoef: number;
+        cGroup: number;
+        cMask: number;
+    }[];
+    goals: {
+        p0: Vec;
+        p1: Vec;
+        team: 1 | 2;
+    }[];
+    joints: {
+        d0: number;
+        d1: number;
+        min: number;
+        max: number;
+        strength: number | 'rigid';
+        color: string;
+    }[];
+    redSpawnPoints: Vec[];
+    blueSpawnPoints: Vec[];
+    player: Disc & {
+        acceleration: number;
+        kickingAcceleration: number;
+        kickingDamping: number;
+        kickStrength: number;
+        kickback: number;
+    };
+    spawnDistance: number;
+    kickOffReset: 'full' | 'partial';
+    warnings: string[];
+}
+/** Conservative per-tick work bound, including all possible player slots and static discs. */
+export declare function assertCollisionBudget(mode: Stadium['physicsMode'], discs: number, segments: number, constraints: number, radius: number): void;
+export declare function parseStadium(text: string): Stadium;
+export declare function arenaSource(name?: string, width?: number, height?: number): string;

package/dist/types/core/team-colors.d.ts

@@ -0,0 +1,8 @@
+export interface TeamColors {
+    angle: number;
+    textColor: number;
+    colors: number[];
+}
+export declare function teamColors(angle: number, textColor: number, colors: number[]): TeamColors;
+export type TeamStyles = [TeamColors | null, TeamColors | null];
+export declare function readTeamStyles(value: unknown): TeamStyles;

package/dist/types/sdk/browser.d.ts

@@ -0,0 +1,11 @@
+import type { CreateRoomOptions } from './create-options.js';
+export type { CreateRoomOptions } from './create-options.js';
+import { type RoomConfig } from './config.js';
+import type { Room } from './types.js';
+/** Browser host SDK. Requires the matching Ball2D assets and API on this origin. */
+export declare function createRoom(config?: RoomConfig, options?: CreateRoomOptions): Promise<Room>;
+export { readReplay, type Replay } from './replay.js';
+export type { HostPlayer, HostScores, HostDiscProperties } from '../core/host-types.js';
+export type { Room } from './types.js';
+export type { RoomConfig } from './config.js';
+export { validateStadium, type StadiumValidation } from './stadium.js';

package/dist/types/sdk/command-queue.d.ts

@@ -0,0 +1,11 @@
+export declare class CommandQueue {
+    private readonly onError;
+    private pending;
+    private active?;
+    private scheduled;
+    private closed;
+    constructor(onError?: (error: unknown) => void);
+    enqueue<T>(run: () => T | Promise<T>): Promise<T>;
+    private drain;
+    close(): void;
+}

package/dist/types/sdk/config.d.ts

@@ -0,0 +1,6 @@
+import { type HostConfig } from '../client/host-config.js';
+export interface RoomConfig extends Omit<HostConfig, 'roomName'> {
+    roomName?: string;
+}
+/** SDK defaults follow the reference room contract; legacy page defaults are separate. */
+export declare function roomConfig(input: unknown): HostConfig;

package/dist/types/sdk/create-options.d.ts

@@ -0,0 +1,4 @@
+export interface CreateRoomOptions {
+    /** Cancels startup only. Close the returned room explicitly after it opens. */
+    signal?: AbortSignal;
+}

package/dist/types/sdk/node-transport.d.ts

@@ -0,0 +1,4 @@
+export declare function nativeTransport(): {
+    createPeerConnection(config: RTCConfiguration): RTCPeerConnection;
+    close(): Promise<void>;
+};

package/dist/types/sdk/node.d.ts

@@ -0,0 +1,18 @@
+import type { CreateRoomOptions } from './create-options.js';
+export type { CreateRoomOptions } from './create-options.js';
+import { type RoomConfig } from './config.js';
+import type { Room } from './types.js';
+export interface NodeRoomConfig extends RoomConfig {
+    /** Ball2D signaling service. Defaults to https://ball2d.com. */
+    serviceOrigin?: string;
+    /** Optional account-owned SDK key. Keep it in an environment variable, never browser code. */
+    apiKey?: string;
+}
+export type NodeRoom = Room & {
+    readonly closed: Promise<void>;
+};
+/** Native Node host. close() begins shutdown; closed settles after peer cleanup. */
+export declare function createRoom(config?: NodeRoomConfig, creation?: CreateRoomOptions): Promise<NodeRoom>;
+export { readReplay, type Replay } from './replay.js';
+export { validateStadium, type StadiumValidation } from './stadium.js';
+export type { HostPlayer, HostScores, HostDiscProperties } from '../core/host-types.js';

package/dist/types/sdk/replay.d.ts

@@ -0,0 +1,4 @@
+import type { Replay } from '../core/replay-types.js';
+export type { Replay } from '../core/replay-types.js';
+/** Decode a recording without exposing engine implementation types. */
+export declare function readReplay(blob: Blob): Promise<Replay>;

package/dist/types/sdk/room.d.ts

@@ -0,0 +1,7 @@
+import type { HeadlessRoom } from '../client/headless.js';
+import type { Room } from './types.js';
+export type { Room } from './types.js';
+export declare function roomFacade(host: HeadlessRoom): Room;
+export declare function roomFacade(host: HeadlessRoom, closed: Promise<void>): Room & {
+    readonly closed: Promise<void>;
+};

package/dist/types/sdk/stadium.d.ts

@@ -0,0 +1,9 @@
+export interface StadiumValidation {
+    readonly name: string;
+    readonly canBeStored: boolean;
+    readonly warnings: readonly string[];
+}
+/** Validates Ball2D's supported HBS contract without allocating a host or WASM engine.
+ * Throws on malformed or unsupported input. Warnings describe ignored field names.
+ */
+export declare function validateStadium(source: string): StadiumValidation;

package/dist/types/sdk/types.d.ts

@@ -0,0 +1,78 @@
+import type { HostPlayer, HostScores, HostDiscProperties } from '../core/host-types.js';
+import type { DiscPropertyPatch } from '../core/disc-properties.js';
+import type { MatchState } from '../core/match-state.js';
+import type { AnnouncementStyle } from '../client/announcement.js';
+/** Public room contract: runtime classes and transport types are deliberately absent. */
+export interface Room {
+    readonly roomId: string;
+    readonly roomLink: string;
+    readonly roomName: string;
+    readonly signal: AbortSignal;
+    readonly lastRecording: Blob | null;
+    onRecordingComplete?: (blob: Blob, reason: string) => void;
+    onRoomLink?: (url: string) => void;
+    onPlayerJoin?: (p: HostPlayer) => void;
+    onPlayerTeamChange?: (p: HostPlayer, byPlayer: HostPlayer | null) => void;
+    onPlayerAdminChange?: (p: HostPlayer, byPlayer: HostPlayer | null) => void;
+    onGameStart?: (byPlayer: HostPlayer | null) => void;
+    onGameStop?: (byPlayer: HostPlayer | null) => void;
+    onTeamVictory?: (scores: HostScores) => void;
+    /** Legacy Ball2D callback; prefer onTeamVictory. */
+    onGameVictory?: (scores: HostScores) => void;
+    onGamePauseChange?: (paused: boolean) => void;
+    onGamePause?: (byPlayer: HostPlayer | null) => void;
+    onGameUnpause?: (byPlayer: HostPlayer | null) => void;
+    onPlayerLeave?: (p: HostPlayer) => void;
+    onPlayerKicked?: (p: HostPlayer, reason: string, ban: boolean, byPlayer: HostPlayer | null) => void;
+    onPlayerActivity?: (p: HostPlayer) => void;
+    onPlayerChat?: (p: HostPlayer, text: string) => boolean | void;
+    onPlayerBallKick?: (p: HostPlayer) => void;
+    onTeamGoal?: (team: 1 | 2) => void;
+    onPositionsReset?: () => void;
+    onStadiumChange?: (name: string, byPlayer: HostPlayer | null) => void;
+    onTeamsLockChange?: (locked: boolean, byPlayer: HostPlayer | null) => void;
+    onKickRateLimitSet?: (min: number, rate: number, burst: number, byPlayer: HostPlayer | null) => void;
+    onGameTick?: () => void;
+    onError?: (message: string) => void;
+    getPlayerList(): HostPlayer[];
+    getPlayer(id: number): HostPlayer | null;
+    setTeamColors(team: number, angle: number, textColor: number, colors: number[]): Promise<void>;
+    reorderPlayers(playerIdList: number[], moveToTop: boolean): Promise<void>;
+    setPlayerAvatar(id: number, avatar: string | null): Promise<void>;
+    setPlayerTeam(id: number, team: 0 | 1 | 2): Promise<void>;
+    setPlayerAdmin(id: number, admin: boolean): Promise<void>;
+    setTeamsLock(locked: boolean): Promise<void>;
+    kickPlayer(id: number, reason?: string, ban?: boolean): Promise<void>;
+    clearBan(id: number): Promise<void>;
+    clearBans(): Promise<void>;
+    sendChat(text: string, targetId?: number | null): Promise<void>;
+    sendAnnouncement(text: string, targetId?: number | null, color?: number | null, style?: AnnouncementStyle | null, sound?: number | null): Promise<void>;
+    startGame(): Promise<void>;
+    stopGame(): Promise<void>;
+    pauseGame(paused: boolean): Promise<void>;
+    setKickRateLimit(min?: number, rate?: number, burst?: number): Promise<void>;
+    setPassword(password: string | null): Promise<void>;
+    readonly requireVerification: boolean | null;
+    setRequireVerification(required: boolean): Promise<void>;
+    /** Migration alias: Ball2D uses Turnstile, not Google's reCAPTCHA. */
+    setRequireRecaptcha(required: boolean): Promise<void>;
+    setScoreLimit(limit: number): Promise<void>;
+    setTimeLimit(minutes: number): Promise<void>;
+    setDefaultStadium(name: string): Promise<void>;
+    setCustomStadium(source: string): Promise<void>;
+    getScores(): HostScores | null;
+    getBallPosition(): {
+        x: number;
+        y: number;
+    } | null;
+    readonly CollisionFlags: Readonly<Record<string, number>>;
+    getDiscCount(): number;
+    getDiscProperties(discIndex: number): HostDiscProperties | null;
+    setDiscProperties(discIndex: number, properties: DiscPropertyPatch): Promise<void>;
+    setPlayerDiscProperties(playerId: number, properties: DiscPropertyPatch): Promise<void>;
+    getPlayerDiscProperties(playerId: number): HostDiscProperties | null;
+    getState(): MatchState;
+    startRecording(): void;
+    stopRecording(): Blob | null;
+    close(): void;
+}

package/dist/types/shared/room-link.d.ts

@@ -0,0 +1,6 @@
+/** Room codes are public addresses, never host credentials. */
+export declare function normalizeRoomId(value: string): string | null;
+export declare function invitePath(id: string): string;
+export declare function roomFromPath(path: string): string | null;
+export declare function parseRoomLink(input: string): string | null;
+export declare function createRoomCode(): string;

package/package.json

@@ -1,29 +1,31 @@
 {
   "name": "ball2d",
-  "version": "0.0.1",
-  "description": "Ball 2D by Fillbyte.",
+  "version": "0.1.0",
+  "description": "Ball2D browser and experimental native Node room SDK",
   "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/sdk/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./node": {
+      "types": "./dist/types/sdk/node.d.ts",
+      "node": "./dist/node.js"
+    }
+  },
   "license": "UNLICENSED",
   "homepage": "https://ball2d.com",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/fillbyte-com/ball2d.git"
-  },
-  "bugs": {
-    "url": "https://github.com/fillbyte-com/ball2d-issues/issues"
+    "url": "git+https://github.com/fillbyte/ball2d.com.git",
+    "directory": "packages/ball2d"
   },
-  "keywords": [
-    "ball2d",
-    "fillbyte",
-    "game",
-    "multiplayer"
-  ],
-  "files": [
-    "README.md",
-    "index.js"
-  ],
-  "exports": "./index.js",
-  "publishConfig": {
-    "access": "public"
+  "engines": {
+    "node": ">=24"
   }
 }

package/index.js

@@ -1,3 +0,0 @@
-export const name = "ball2d";
-export const version = "0.0.1";
-export const publisher = 'Fillbyte';