@aethervtt/shard-net 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+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

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# @aethervtt/shard-net
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Multiplayer for [Shard](https://github.com/aethervtt/shard): state replication with per-player
+interest and redaction, validated commands and events, accounts and player persistence, and
+peer-to-peer hosting. The authority is always a Shard app running your game's systems. Transports
+are separate packages:
+
+- `@aethervtt/shard-net-websocket`: a browser/Node client and a Node server (`./server`).
+- `@aethervtt/shard-net-webrtc`: peer-to-peer data channels, a lobby client, and a lobby server
+  (`./server`).
+
+Design: specs 0086–0092 in the repository.
+
+## Shared definitions
+
+```ts
+import { defineComponent, t } from '@aethervtt/shard-core'
+import { Transform } from '@aethervtt/shard-transform'
+import { defineNetCommand, defineNetEvent, ownerOnly, replicate } from '@aethervtt/shard-net'
+
+export const Health = defineComponent('game/Health', { hp: t.u16({ max: 1000 }) })
+export const Gold = defineComponent('game/Gold', { amount: t.u32() })
+export const Attack = defineNetCommand('game/Attack', { target: t.entity() })
+export const Chat = defineNetEvent('game/Chat', { text: t.string() })
+
+// Both sides pass the same lists; a mismatch is refused at connect (net/schema-mismatch).
+export const net = {
+  replicate: [
+    replicate(Transform, { mode: 'interpolate', quantize: { translation: { step: 0.01 } } }),
+    replicate(Health),
+    replicate(Gold, { visibleTo: ownerOnly }),
+  ],
+  commands: [Attack],
+  events: [Chat],
+}
+```
+
+## Server (Node)
+
+```ts
+import { App, intervalRunner } from '@aethervtt/shard-runtime'
+import { commands, netPlugin, Replicated } from '@aethervtt/shard-net'
+import { webSocketServer } from '@aethervtt/shard-net-websocket/server'
+
+const app = new App()
+app.addPlugin(
+  netPlugin({
+    ...net,
+    role: 'server',
+    transport: webSocketServer({ port: 7000 }),
+    async accept(peer, token) {
+      return { user: await verify(token) } // or a ShardError to refuse
+    },
+    players: {
+      spawn: (world, { peer }) => void world.spawn([Replicated, { owner: peer }], [Health, { hp: 100 }]),
+      capture: (world, { owned }) => world.get(owned[0]!, Health),
+      store: ({ user, data }) => db.save(user, data),
+    },
+  }),
+)
+// Game rules: systems gated with onServer read commands(world, Attack) and accept or reject them.
+app.setRunner(intervalRunner())
+await app.run()
+```
+
+## Client (browser)
+
+```ts
+import { netPlugin, sendCommand } from '@aethervtt/shard-net'
+import { webSocketTransport } from '@aethervtt/shard-net-websocket'
+
+app.addPlugin(
+  netPlugin({ ...net, role: 'client', transport: webSocketTransport(), address: 'wss://game.example.com', token }),
+)
+const pending = sendCommand(app.world, Attack, { target }) // pending.status: accepted | rejected
+```
+
+## Peer to peer: a lobby, a host, and a room code
+
+```ts
+// Node: the lobby only introduces peers; game traffic goes peer to peer.
+import { lobbyServer } from '@aethervtt/shard-net-webrtc/server'
+await lobbyServer({ port: 7500, host: '0.0.0.0' })
+
+// Browser, hosting: the game's server runs in this page; the host joins it over loopback.
+import { startHost } from '@aethervtt/shard-net'
+import { webRtcLobby } from '@aethervtt/shard-net-webrtc'
+const session = webRtcLobby({ url: 'wss://lobby.example.com', iceServers: [{ urls: 'stun:…' }] })
+const host = await startHost({ plugins: () => [game()], net, session })
+clientApp.addPlugin(netPlugin({ ...net, role: 'client', ...host.local }))
+show(host.code)
+
+// Browser, joining with the code.
+clientApp.addPlugin(netPlugin({ ...net, role: 'client', session, code }))
+```
+
+Peers on different networks need STUN servers in `iceServers`, and TURN behind strict NATs.
+
+## Tests
+
+`@aethervtt/shard-net/testing` runs a server and N clients in one process over a loopback with
+seeded latency, jitter and loss: `netHarness({ clients, net, conditions })`, then `connect()`,
+`run(ticks)`, and `differences(...components)` to check every client matches the server.

package/dist/client.d.ts

@@ -0,0 +1,76 @@
+import { type Entity, ShardError, type World } from '@aethervtt/shard-core';
+import type { NetCommandDef } from './registry.js';
+import type { NetConnection } from './transport.js';
+import { type Manifest } from './wire.js';
+export interface ClientConfig {
+    readonly manifest: Manifest;
+    readonly ticksPerNet: number;
+    readonly maxMessage: number;
+    readonly token: string;
+    readonly spawnPrefab: ((world: World, prefab: string) => Entity) | undefined;
+    readonly now: () => number;
+}
+/** A command this client sent, until the server answers (0089). */
+export declare class PendingCommand {
+    readonly def: NetCommandDef;
+    readonly seq: number;
+    status: 'pending' | 'accepted' | 'rejected';
+    error: ShardError | undefined;
+    constructor(def: NetCommandDef, seq: number);
+}
+export declare class NetClient {
+    readonly world: World;
+    readonly config: ClientConfig;
+    readonly byNetId: Map<number, number>;
+    connection: NetConnection | undefined;
+    /** Why the server refused or dropped this client, if it did. */
+    lastError: ShardError | undefined;
+    readonly pending: Map<number, PendingCommand>;
+    private readonly fragmenter;
+    private readonly inbox;
+    private readonly applied;
+    private readonly interp;
+    private readonly codecs;
+    private readonly commandCodecs;
+    private readonly eventCodecs;
+    private readonly floatFields;
+    private readonly widths;
+    private readonly commandIndex;
+    private readonly reader;
+    private readonly out;
+    private latestSeq;
+    private seqBits;
+    private ackDirty;
+    private lastPing;
+    private lastNetTick;
+    private nextCommand;
+    private readonly rtts;
+    private readonly offsets;
+    private readonly sortScratch;
+    private closedReason;
+    private unsubscribe;
+    constructor(world: World, config: ClientConfig);
+    attach(connection: NetConnection): void;
+    dispose(): void;
+    private toWire;
+    private forget;
+    receive(): void;
+    private handle;
+    private welcome;
+    private pong;
+    private stale;
+    /** Decodes one component update into its entity. False if it named an unknown entity. */
+    private apply;
+    private reliable;
+    private state;
+    private received;
+    private sample;
+    /** Writes interpolated values for every remote entity (PreUpdate). */
+    interpolate(): void;
+    private renderTick;
+    private readonly interpolateEntity;
+    private write;
+    /** Runs in Last: acks and pings on network ticks. */
+    send(): void;
+    sendCommand(def: NetCommandDef, data: Record<string, unknown>): PendingCommand;
+}