@aethervtt/shard-net 0.0.0-stage → 0.4.1

package/dist/server.d.ts

@@ -0,0 +1,239 @@
+import { type Entity, ShardError, type World } from '@aethervtt/shard-core';
+import { type PeerInfo } from './components.js';
+import { type InterestPeer, type InterestPolicy, RelevanceSet } from './interest.js';
+import type { NetCommandDef, NetEventDef } from './registry.js';
+import type { Channel, NetConnection, NetListener, PeerId } from './transport.js';
+import { NumberList } from './vec.js';
+import { Fragmenter, type Manifest } from './wire.js';
+/** What `accept` returns: `{ user }` (or nothing) admits, a ShardError refuses (0090). */
+export type AcceptResult<U = unknown> = {
+    readonly user?: U;
+} | ShardError | undefined;
+export interface JoinContext<U = unknown> {
+    readonly peer: PeerId;
+    readonly user: U;
+    readonly token: string;
+}
+export interface LeaveContext<U = unknown> {
+    readonly peer: PeerId;
+    readonly user: U;
+    /** Entities whose `Replicated.owner` is the peer. */
+    readonly owned: readonly Entity[];
+}
+/**
+ * Loading and saving a player around a session (0090). The async hooks never get the world;
+ * the ones that get the world are synchronous, so nothing reads it after an `await`.
+ */
+export interface PlayerHooks<U = unknown, L = unknown, S = unknown> {
+    /** Async: fetch what the player needs (a character row). Runs after accept, before welcome. */
+    load?(ctx: JoinContext<U>): L | Promise<L>;
+    /** Sync, in `net/receive`: spawn the player's entities, owned by `ctx.peer`. */
+    spawn?(world: World, ctx: JoinContext<U> & {
+        readonly data: L;
+    }): void;
+    /** Sync: read what to save from the owned entities, before they're despawned. */
+    capture?(world: World, ctx: LeaveContext<U>): S;
+    /** Async: write it. A rejection fires `PlayerSaveFailed`. */
+    store?(ctx: {
+        readonly peer: PeerId;
+        readonly user: U;
+        readonly data: S;
+    }): void | Promise<void>;
+    /** Despawn the owned entities when the player leaves. Default true. */
+    despawn?: boolean;
+}
+export interface ServerConfig {
+    readonly manifest: Manifest;
+    readonly interest: InterestPolicy;
+    readonly ticksPerNet: number;
+    readonly maxPeers: number;
+    readonly bytesPerTick: number;
+    readonly maxMessage: number;
+    readonly commandsPerSecond: number;
+    readonly accept?: (peer: PeerId, token: string, world: World) => AcceptResult | Promise<AcceptResult>;
+    readonly players?: PlayerHooks;
+    /** Milliseconds for accept + load before `net/join-timeout`. */
+    readonly joinTimeout: number;
+    readonly now: () => number;
+}
+/** What one peer has of one entity, as far as the server knows. */
+interface Known {
+    readonly netId: number;
+    readonly entity: Entity;
+    /** Per manifest component: on the client. */
+    readonly present: Uint8Array;
+    /** Per component: the change tick last sent, and the newest one the client confirmed. */
+    readonly sent: Uint32Array;
+    readonly acked: Uint32Array;
+    /** Per component: the fixed tick it was last sent on, for resends. */
+    readonly sentAt: Float64Array;
+    /** The fixed tick anything of it was last sent: older entities go first under a budget. */
+    lastSent: number;
+}
+interface PacketRecord {
+    seq: number;
+    acked: boolean;
+    readonly netIds: NumberList;
+    readonly comps: NumberList;
+    readonly ticks: NumberList;
+}
+/** A command the server received, until a system answers it (0089). */
+export declare class ServerCommand<T = Record<string, unknown>> {
+    readonly def: NetCommandDef;
+    readonly peer: PeerId;
+    readonly seq: number;
+    readonly data: T;
+    readonly arrivedTick: number;
+    status: 'pending' | 'accepted' | 'rejected';
+    error: ShardError | undefined;
+    private readonly answer;
+    constructor(def: NetCommandDef, peer: PeerId, seq: number, data: T, arrivedTick: number, answer: (cmd: ServerCommand<T>) => void);
+    accept(): void;
+    reject(code: string, message?: string, hint?: string): void;
+}
+interface QueuedEvent {
+    readonly index: number;
+    readonly data: Record<string, unknown>;
+    readonly to: PeerId | 'all' | ((peer: PeerId) => boolean);
+}
+interface Answer {
+    seq: number;
+    error: ShardError | undefined;
+}
+export interface PeerStats {
+    bytesSent: number;
+    bytesByComponent: Record<string, number>;
+    deferred: number;
+    resends: number;
+    commands: number;
+    rejected: number;
+}
+declare class PeerState implements InterestPeer {
+    readonly id: PeerId;
+    readonly info: PeerInfo;
+    readonly connection: NetConnection;
+    readonly fragmenter: Fragmenter;
+    readonly inbox: {
+        channel: Channel;
+        bytes: Uint8Array;
+    }[];
+    readonly known: Map<number, Known>;
+    relevant: RelevanceSet;
+    /** Last tick's relevant set, for hysteresis (`knows`). */
+    previous: RelevanceSet;
+    readonly focus: Entity[];
+    readonly packets: PacketRecord[];
+    readonly answers: Answer[];
+    nextSeq: number;
+    closed: string | undefined;
+    /** When the join started (config.now), for the timeout. */
+    joinStarted: number;
+    /** Command rate limit: tokens refill at commandsPerSecond. */
+    tokens: number;
+    lastRefill: number;
+    readonly stats: PeerStats;
+    constructor(connection: NetConnection, id: PeerId, tick: number, tokens: number);
+    /** Whether the peer had the entity after the last network tick. */
+    knows(entity: Entity): boolean;
+}
+export declare class NetServer {
+    readonly world: World;
+    readonly config: ServerConfig;
+    readonly peers: Map<number, PeerState>;
+    /** The same peers as an array, so per-frame loops don't allocate iterators. */
+    private readonly peerList;
+    readonly byNetId: Map<number, number>;
+    readonly commands: ServerCommand[];
+    /** Recent commands for `net.commands`. */
+    readonly recentCommands: ServerCommand[];
+    readonly recentEvents: {
+        name: string;
+        tick: number;
+        to: string;
+    }[];
+    private nextNetId;
+    private nextPeer;
+    /** Joins whose async accept/load finished, applied in the next receive. */
+    private readonly settled;
+    private readonly saveFailures;
+    private readonly stores;
+    private readonly incoming;
+    private readonly events;
+    private readonly codecs;
+    private readonly commandCodecs;
+    private readonly eventCodecs;
+    private readonly commandIndex;
+    private readonly eventIndex;
+    private readonly reader;
+    private readonly out;
+    private readonly state;
+    private readonly spawns;
+    private readonly sets;
+    private readonly removes;
+    private readonly despawns;
+    private readonly tail;
+    private current;
+    private pendingRef;
+    private despawnCount;
+    private lastNetTick;
+    private readonly unassigned;
+    private readonly replicatedQuery;
+    private readonly focusQuery;
+    private readonly relevanceQuery;
+    private readonly newEntities;
+    private readonly candidates;
+    private readonly scores;
+    private order;
+    private readonly despawnKnown;
+    listener: NetListener | undefined;
+    private unsubscribe;
+    constructor(world: World, config: ServerConfig);
+    attach(listener: NetListener): void;
+    /** Saves every connected player (0090), closes their connections, and waits for the stores. */
+    dispose(): Promise<void>;
+    /** Resolves when every player store in flight has settled. */
+    flush(): Promise<void>;
+    private toWire;
+    private fromWire;
+    netIdOf(entity: Entity): number | undefined;
+    receive(): void;
+    private handle;
+    private hello;
+    private join;
+    private joinAsync;
+    /** Applies finished joins, and times out the slow ones. */
+    private settleJoins;
+    private finishJoin;
+    private ownedBy;
+    /** Captures a connected player's data and starts its store. Undefined without hooks. */
+    save(peer: PeerId): Promise<void> | undefined;
+    private captureAndStore;
+    private saveFailed;
+    /** A connected peer left: save it, despawn what it owned, tell the game. */
+    private leave;
+    private refuse;
+    private drop;
+    private sendDisconnect;
+    /** Disconnects a peer (`net.disconnect`). */
+    disconnect(peer: PeerId, reason?: string): boolean;
+    private ack;
+    private command;
+    private remember;
+    /** Delivers a command from the server's own world (single-player, or a host's local player). */
+    local(def: NetCommandDef, data: Record<string, unknown>, onAnswer: (cmd: ServerCommand) => void): ServerCommand<Record<string, unknown>>;
+    private answer;
+    /** Commands of one type still waiting for an answer. */
+    pending(def: NetCommandDef): ServerCommand[];
+    sendEvent(def: NetEventDef, data: Record<string, unknown>, to: QueuedEvent['to']): void;
+    commandIndexOf(def: NetCommandDef): number | undefined;
+    /** Runs in Last: answers unhandled commands, and on network ticks sends state to every peer. */
+    send(): void;
+    private assignIds;
+    private collectFocus;
+    private readonly keepRelevant;
+    private relevance;
+    private sendTo;
+    /** Describes one entity for `net.inspect`. */
+    inspect(entity: Entity): Record<string, unknown>;
+}
+export {};