@korial29/tiny-fps 0.0.0-stage → 0.1.0

package/dist/types/client/render.d.ts

@@ -0,0 +1,28 @@
+import type { Edge, Level, PlayerState } from '../shared/types';
+type Vec3 = [number, number, number];
+/**
+ * Column-major view-projection matrix: camera at eye looking along (-sin yaw cos pitch, sin pitch,
+ * -cos yaw cos pitch), y up, 70° vertical field of view.
+ */
+export declare const viewProj: (eye: Vec3, yaw: number, pitch: number, aspect: number) => Float32Array<ArrayBuffer>;
+/** A world point on screen, in [0, 1] from the top left; undefined behind the camera. */
+export declare const project: (m: Float32Array, x: number, y: number, z: number) => [number, number] | undefined;
+/**
+ * Appends the 36 vertices of a box centred on (cx, cy, cz) with half sizes (hx, hy, hz), turned
+ * by yaw about its own vertical axis (local forward, -z, ends up along forward(yaw)).
+ */
+export declare const pushBox: (out: number[], [cx, cy, cz]: Vec3, [hx, hy, hz]: Vec3, yaw: number, color: number[]) => void;
+/** Vertical spans [y0, y1] an edge draws on its own side: the wall, or the steps of a portal. */
+export declare const spans: ({ map }: Level, { front, back }: Edge) => [number, number][];
+/** Floors and ceilings as fans, then every edge's walls as quads, in the vertex format above. */
+export declare const levelVerts: (lvl: Level) => number[];
+export interface Renderer {
+    /** Draws one frame: the map and the others as seen from eye. colors maps player id to CSS. */
+    frame(eye: Vec3, yaw: number, pitch: number, others: PlayerState[], colors: ReadonlyMap<number, string>): void;
+    /** A world point on screen as of the last frame, in [0, 1] from the top left. */
+    project(x: number, y: number, z: number): [number, number] | undefined;
+    destroy(): void;
+}
+/** Throws when the browser has no WebGL2. */
+export declare const createRenderer: (canvas: HTMLCanvasElement, lvl: Level) => Renderer;
+export {};

package/dist/types/client/textures.d.ts

@@ -0,0 +1,4 @@
+export declare const SIZE = 128;
+export declare const LAYERS: number;
+/** All layers, RGBA, layer after layer, rows top to bottom: the upload of a texture array. */
+export declare const textures: () => Uint8ClampedArray;

package/dist/types/local/index.d.ts

@@ -0,0 +1,14 @@
+import type { Rules, SocketLike } from '../shared/types';
+/**
+ * Same-browser multiplayer: tabs of one origin play together over a
+ * BroadcastChannel. One tab hosts the Room (elected with navigator.locks);
+ * when it closes, another tab takes over with a fresh Room (score back to 0-0)
+ * and every socket replays its join, so the client only sees a new roster.
+ *
+ * Without navigator.locks (old browsers, or a non-secure context such as plain
+ * http on a LAN address) every tab hosts its own Room and plays alone.
+ *
+ * `rules` are the match rules of the Room this tab creates when it hosts (missing ones fall
+ * back to RULES). Only the host's count: pass the same ones from every tab.
+ */
+export declare const localSocket: (room: string, rules?: Partial<Rules>) => SocketLike;

package/dist/types/server/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/server/index.d.ts

@@ -0,0 +1,16 @@
+import type { Server } from 'node:http';
+import type { Rules } from '../shared/types';
+export interface ServeOptions {
+    /** Listen on this port (ignored when server is given). */
+    port?: number;
+    /** Attach to an existing HTTP server instead. */
+    server?: Server;
+    /** Match rules for every room; missing ones fall back to RULES. */
+    rules?: Partial<Rules>;
+}
+/**
+ * Starts the WebSocket server: one Room per URL path. Returns an idempotent stop
+ * function that closes every socket, room, the WebSocketServer, and the HTTP
+ * server only when serve created it (`{ port }`).
+ */
+export declare const serve: (opts: ServeOptions) => (() => Promise<void>);

package/dist/types/shared/constants.d.ts

@@ -0,0 +1,33 @@
+import type { Rules } from './types';
+/** Physics steps per second: one client input per step, the host steps a player per input. */
+export declare const TICK_HZ = 60;
+/** A snapshot goes out every SNAP_EVERY host ticks: 60 / 2 = 30 Hz. */
+export declare const SNAP_EVERY = 2;
+/**
+ * Render delay of the other players, interpolated between snapshots, in ms: about three snapshot
+ * intervals, so one lost or late snapshot does not freeze them. The own player is predicted.
+ */
+export declare const INTERP_DELAY = 100;
+/** Player cylinder. */
+export declare const PLAYER_R = 0.4;
+export declare const PLAYER_H = 1.8;
+/** Camera height above the feet. */
+export declare const EYE = 1.6;
+/** Metres per second. */
+export declare const RUN_SPEED = 6;
+export declare const JUMP_SPEED = 7;
+/** Metres per second squared. */
+export declare const GRAVITY = 20;
+/** Pitch is clamped to ±MAX_PITCH radians, just short of straight up or down. */
+export declare const MAX_PITCH = 1.55;
+/** A floor at most this much higher is walked onto; a higher one needs a jump. */
+export declare const STEP_H = 0.5;
+/**
+ * Host-side speed-hack guard: each player earns one input per host tick and may bank up to
+ * INPUT_BURST of them; inputs beyond the bank are dropped (and not acked).
+ */
+export declare const INPUT_BURST = 10;
+export declare const MAX_PLAYERS = 16;
+/** Longest player name, in characters (code points). */
+export declare const MAX_NAME = 16;
+export declare const RULES: Rules;

package/dist/types/shared/level.d.ts

@@ -0,0 +1,13 @@
+import type { Level, MapDef, Sector } from './types';
+/** Joins every edge a→b with the sector that has b→a, if any: that edge is a portal. */
+export declare const compile: (map: MapDef) => Level;
+/** Whether (x, z) is inside the sector, its edges included. */
+export declare const inside: ({ pts }: Sector, x: number, z: number) => boolean;
+/** Index of the first sector holding (x, z), -1 outside the map. */
+export declare const sectorAt: ({ map }: Level, x: number, z: number) => number;
+/**
+ * Whether a wall, a step or a ceiling hides b from a (both inside the map). Between two edge
+ * crossings the segment stays in one sector, and each crossing is checked against the opening of
+ * its portal, so floors and ceilings need no test of their own.
+ */
+export declare const blocked: ({ map, edges }: Level, [ax, ay, az]: [number, number, number], [bx, by, bz]: [number, number, number]) => boolean;

package/dist/types/shared/map.d.ts

@@ -0,0 +1,6 @@
+import type { MapDef } from './types';
+/**
+ * The first sector map, a test bed for heights: a start room, a low corridor, a tall hall around a
+ * lava pit, stairs up to a balcony. Each spot is reachable on foot; the pit is a 1 m drop.
+ */
+export declare const HALL: MapDef;

package/dist/types/shared/physics.d.ts

@@ -0,0 +1,17 @@
+import type { Input, Level, PlayerState } from './types';
+export declare const TAU: number;
+/** An angle in [0, 2π). */
+export declare const norm: (a: number) => number;
+/** Unit vector the player faces at yaw, on the floor plane: yaw 0 looks toward -z. */
+export declare const forward: (yaw: number) => [x: number, z: number];
+/**
+ * Applies one input for 1 / TICK_HZ s, in place: yaw and pitch from the input (pitch clamped to
+ * MAX_PITCH), RUN_SPEED along the held keys (diagonals not faster), a jump from the ground,
+ * GRAVITY, then collisions of the cylinder (PLAYER_R, PLAYER_H) with the sectors of the level:
+ * it slides along shut edges (see shut and push), stands on the highest floor under the circle
+ * (a step up to STEP_H is climbed at once, a higher one needs a jump, a ledge is a fall), and
+ * bumps its head on the lowest ceiling.
+ */
+export declare const move: (p: PlayerState, i: Input, lvl: Level) => void;
+/** A player standing on the floor at spawn point n of the map (modulo the count). */
+export declare const spawn: (id: number, lvl: Level, n: number) => PlayerState;

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

@@ -0,0 +1,30 @@
+import type { Input, PlayerInfo, Snapshot } from './types';
+export type ClientText = {
+    t: 'join';
+    name: string;
+};
+export type ServerText = {
+    t: 'roster';
+    you: number;
+    players: PlayerInfo[];
+} | {
+    t: 'full';
+};
+export declare const MSG_INPUT = 1;
+export declare const MSG_SNAPSHOT = 2;
+export declare const INPUT_BYTES = 8;
+export declare const SNAP_HEAD = 4;
+export declare const SNAP_PLAYER = 24;
+/**
+ * The input as the host will read it after encodeInput and decodeInput: yaw and pitch rounded to
+ * the wire. The client predicts with this, so both sides move with the same values.
+ */
+export declare const onWire: (i: Input) => Input;
+export declare const encodeInput: (i: Input) => ArrayBuffer;
+/** Null on anything that is not a well-formed input frame. */
+export declare const decodeInput: (buf: ArrayBuffer) => Input | null;
+export declare const encodeSnapshot: (s: Snapshot) => ArrayBuffer;
+/** Null on anything that is not a well-formed snapshot frame. */
+export declare const decodeSnapshot: (buf: ArrayBuffer) => Snapshot | null;
+/** Returns null on anything that is not a known text message. */
+export declare const parseText: <T extends ClientText | ServerText>(raw: string) => T | null;

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

@@ -0,0 +1,45 @@
+import type { Conn, Every, Rules } from './types';
+/**
+ * One game, transport-agnostic. The Node server and the local host tab both drive a Room: they
+ * feed it connections and frames, the room answers through Conn.send.
+ *
+ * - A peer joins with { t: 'join', name }: unique name (`Bob 2`), unique colour, a spawn point not
+ *   taken by another player; 'full' beyond rules.maxPlayers. Everyone gets a fresh 'roster' on
+ *   every join and leave.
+ * - Each input frame moves its player at once with move(); the INPUT_BURST bank drops the excess.
+ * - Every SNAP_EVERY ticks of TICK_HZ, one snapshot with every player goes to every peer.
+ */
+export declare class Room {
+    /** Every connected peer; null until it joins. */
+    private peers;
+    private ticks;
+    private halt;
+    private rules;
+    /** Round-robin cursor over the spawn points, used once they are all taken. */
+    private rr;
+    /** Missing rules fall back to RULES. */
+    constructor(rules?: Partial<Rules>);
+    /** Number of joined players. */
+    get size(): number;
+    /** A peer opened. Nothing is sent until it joins. */
+    connect(conn: Conn): void;
+    /** A text (JSON) or binary frame from a peer. */
+    receive(conn: Conn, data: string | ArrayBuffer): void;
+    /** A peer left: its player goes, the roster goes out again. */
+    disconnect(conn: Conn): void;
+    /** One host tick. Public so tests can drive the room without a timer. */
+    tick(): void;
+    /**
+     * Drives tick() with a timer. An accumulator on performance.now() keeps the
+     * simulation at TICK_HZ whatever the timer jitter; after a stall at most
+     * MAX_CATCH_UP ticks are replayed and the rest of the backlog is dropped.
+     * `every` replaces setInterval, e.g. with a Worker-backed timer that
+     * background tabs do not throttle.
+     */
+    start(every?: Every): void;
+    stop(): void;
+    private players;
+    private join;
+    /** Each joined peer gets the full roster with its own id. */
+    private roster;
+}

package/dist/types/shared/types.d.ts

@@ -0,0 +1,131 @@
+export interface PlayerInfo {
+    id: number;
+    name: string;
+    /** CSS colour, unique within the room. */
+    color: string;
+}
+/** Bits of Input.keys. Keys are read by KeyboardEvent.code, so WASD is ZQSD on AZERTY. */
+export declare const KEY: {
+    readonly FORWARD: 1;
+    readonly BACK: 2;
+    readonly LEFT: 4;
+    readonly RIGHT: 8;
+    readonly JUMP: 16;
+};
+/** One client step: what the player held during 1 / TICK_HZ s, and where they looked. */
+export interface Input {
+    /** Client step counter, u16, wraps. The host acks the last one it applied. */
+    seq: number;
+    /** KEY bits. */
+    keys: number;
+    /** Radians, [0, 2π). */
+    yaw: number;
+    /** Radians, [-MAX_PITCH, MAX_PITCH]. */
+    pitch: number;
+}
+export interface PlayerState {
+    id: number;
+    /** Feet position. */
+    x: number;
+    y: number;
+    z: number;
+    /** Vertical speed, m/s. */
+    vy: number;
+    yaw: number;
+    pitch: number;
+    /** Standing on a floor: a jump is allowed. */
+    ground: boolean;
+}
+/** Procedural textures, generated by the client. A sector names one per surface. */
+export declare const TEX: {
+    readonly BRICK: 0;
+    readonly TILE: 1;
+    readonly LAVA: 2;
+    readonly STONE: 3;
+};
+/**
+ * A room, Doom style: a convex polygon on the floor plane with a flat floor and a flat ceiling.
+ * Two sectors are joined where one has the edge a→b and the other b→a with the very same
+ * coordinates (a portal); every other edge is a solid wall. Split an edge with collinear points
+ * when several sectors meet it (no T-junctions).
+ */
+export interface Sector {
+    /**
+     * Corners as (x, z), counter-clockwise: the signed area Σ (x_i z_{i+1} - x_{i+1} z_i) is positive.
+     * Collinear points are allowed.
+     */
+    pts: [x: number, z: number][];
+    /** Heights in metres, ceil > floor. */
+    floor: number;
+    ceil: number;
+    /** TEX ids of the floor, the walls (and steps) on its edges, and the ceiling. */
+    ft: number;
+    wt: number;
+    ct: number;
+    /** Light level multiplied into the shading, 0 to 1. Absent: 1. */
+    light?: number;
+}
+export interface MapDef {
+    sectors: Sector[];
+    /** Spawn points: feet x, z (inside a sector, standing on its floor) and the yaw to face. */
+    spawns: [x: number, z: number, yaw: number][];
+}
+/** One directed edge of a sector, see compile in level.ts. */
+export interface Edge {
+    ax: number;
+    az: number;
+    bx: number;
+    bz: number;
+    /** Index of the sector the edge belongs to (the side it faces into). */
+    front: number;
+    /** Index of the sector across a portal, -1 for a solid wall. */
+    back: number;
+}
+/** A map ready for physics and drawing. */
+export interface Level {
+    map: MapDef;
+    /** Every edge of every sector, in sector then point order. */
+    edges: Edge[];
+}
+/** One player in a snapshot. */
+export interface SnapPlayer {
+    id: number;
+    x: number;
+    y: number;
+    z: number;
+    vy: number;
+    yaw: number;
+    pitch: number;
+    ground: boolean;
+    /** Seq of the last input of this player the host applied: the client replays the ones after. */
+    ack: number;
+}
+export interface Snapshot {
+    /** Host tick, u16, wraps. */
+    tick: number;
+    players: SnapPlayer[];
+}
+/** Room rules, set by the host. Defaults in constants.ts (RULES). */
+export interface Rules {
+    maxPlayers: number;
+}
+/**
+ * The subset of WebSocket the client relies on. A real WebSocket (with
+ * binaryType 'arraybuffer') and the local BroadcastChannel socket both fit.
+ */
+export interface SocketLike {
+    binaryType: string;
+    onopen: (() => void) | null;
+    onclose: (() => void) | null;
+    onmessage: ((ev: {
+        data: string | ArrayBuffer;
+    }) => void) | null;
+    send(data: string | ArrayBuffer): void;
+    close(): void;
+}
+/** Calls cb every ms milliseconds until the returned function is called. */
+export type Every = (cb: () => void, ms: number) => () => void;
+/** One connected peer, as the room sees it. Transport-agnostic. */
+export interface Conn {
+    send(data: string | ArrayBuffer): void;
+}

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@korial29/tiny-fps",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Tiny multiplayer first-person shooter for the browser: raw WebGL, zero runtime dependencies, WebSocket or same-browser multi-tab play.",
+  "license": "Apache-2.0",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/client/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./local": {
+      "types": "./dist/types/local/index.d.ts",
+      "default": "./dist/local.js"
+    },
+    "./server": {
+      "types": "./dist/types/server/index.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "bin": {
+    "tiny-fps-server": "dist/cli.js"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/korial29/tiny-fps.git"
+  },
+  "homepage": "https://korial29.github.io/tiny-fps/",
+  "keywords": [
+    "fps",
+    "game",
+    "browser-game",
+    "html5-game",
+    "webgl",
+    "multiplayer",
+    "realtime",
+    "websocket",
+    "broadcastchannel",
+    "typescript",
+    "zero-dependency",
+    "js13k"
+  ],
+  "author": "Ludovic Dupont <ludovic.dupont29@gmail.com>",
+  "peerDependencies": {
+    "ws": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "start": "vite demo --config vite.config.ts",
+    "dev:server": "tsx watch src/server/cli.ts",
+    "build": "rm -rf dist && vite build && BUILD_LOCAL=true vite build && BUILD_SERVER=true vite build && tsc -p tsconfig.build.json",
+    "build:demo": "BUILD_DEMO=true vite build",
+    "size": "node scripts/size.mjs",
+    "lint:eslint": "eslint .",
+    "format:eslint": "eslint . --fix",
+    "lint:prettier": "prettier --check \"**/*.{js,mjs,ts}\"",
+    "format:prettier": "prettier \"**/*.{js,mjs,ts}\" --write",
+    "lint:tsc": "tsc --noEmit",
+    "lint": "npm run lint:prettier && npm run lint:eslint && npm run lint:tsc",
+    "format": "npm run format:prettier && npm run format:eslint",
+    "test": "vitest run --coverage",
+    "test:ci": "vitest run --coverage --passWithNoTests",
+    "test:watch": "vitest --watch"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "@types/ws": "^8.18.2",
+    "@vitest/coverage-v8": "^5.0.5",
+    "eslint": "^10.13.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.7",
+    "jsdom": "^30.1.3",
+    "prettier": "^3.9.10",
+    "tsx": "^4.23.15",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.72.0",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5",
+    "ws": "^8.22.0"
+  }
+}