@modlock/modlock 0.0.0-stage → 0.1.64

package/jsx-runtime.d.ts

@@ -0,0 +1 @@
+export { Fragment, JSX, jsx, jsxs } from './index.js'

package/jsx-runtime.js

@@ -0,0 +1 @@
+export { Fragment, jsx, jsxs } from './index.js'

package/package.json

@@ -1,6 +1,24 @@
 {
+  "bin": {
+    "modlock": "bin/modlock.js"
+  },
+  "description": "Build, test and publish mods for Deadlock.",
+  "homepage": "https://github.com/paralin/modlock#readme",
+  "license": "MIT",
   "name": "@modlock/modlock",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "optionalDependencies": {
+    "@modlock/darwin-arm64": "0.1.64",
+    "@modlock/darwin-x64": "0.1.64",
+    "@modlock/linux-arm64": "0.1.64",
+    "@modlock/linux-x64": "0.1.64",
+    "@modlock/win32-x64": "0.1.64"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paralin/modlock.git"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "types": "index.d.ts",
+  "version": "0.1.64"
+}

package/players.d.ts

@@ -0,0 +1,13 @@
+import { type Connection } from './host.gen.js';
+/** keepPlayers keeps the player list the host reported and tells the watchers. */
+export declare function keepPlayers(players: Connection[]): void;
+/**
+ * watchPlayers calls watcher with each player list the host reports, and at
+ * once with the last one when a report already arrived.
+ */
+export declare function watchPlayers(watcher: (players: readonly Connection[]) => void): void;
+/**
+ * players lists the occupied player slots in slot order. It answers from the
+ * roster the host last reported, and asks the host until a report arrives.
+ */
+export declare function players(): Connection[];

package/probe.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Check returns true when a probe passes, a failure message when it fails, or
+ * false to check again next frame.
+ */
+export type Check = () => boolean | string;
+/**
+ * ProbeRun drives one probe to a verdict. It times the run from its first
+ * frame, logs each step the probe waits on once, fails a run that outlasts its
+ * timeout, and reports PASS or FAIL before quitting the server. A frame costs
+ * the check alone; the run makes host calls only when the step changes and at
+ * the verdict.
+ */
+export declare class ProbeRun {
+    private readonly name;
+    private readonly timeout;
+    private started?;
+    private finished;
+    private logged?;
+    /**
+     * @param name is the name the verdict line reports, such as the mod's.
+     * @param timeout bounds the run in seconds.
+     */
+    constructor(name: string, timeout: number);
+    /** elapsed returns the seconds since the run's first frame, starting it at now. */
+    elapsed(now: number): number;
+    /**
+     * tick runs check for the frame at now until the run ends. step names what
+     * the probe waits on, and describe adds the probe's state to a timeout.
+     */
+    tick(now: number, step: string, check: Check, describe?: () => string): void;
+}

package/puppet.d.ts

@@ -0,0 +1,143 @@
+import { type Angles, type BotOptions, Player, type Vector } from './host.gen.js';
+/** ticksPerSecond is the game's tick rate; a track's steps count ticks. */
+export declare const ticksPerSecond = 64;
+/**
+ * Track is a recorded hero path in columns: sample i was taken at tick
+ * i * stepTicks. The columns of x, y, z and yaw are as long as the track.
+ */
+export interface Track {
+    /** stepTicks is the ticks between two samples. */
+    stepTicks: number;
+    /** x, y and z are the hero's origin, at its feet. */
+    x: number[];
+    y: number[];
+    z: number[];
+    /** yaw is where the hero faces, in degrees. */
+    yaw: number[];
+    /** pitch is where the hero looks up or down, in degrees; level when absent. */
+    pitch?: number[];
+    /** health is the hero's health; the hero's own is kept when absent. */
+    health?: number[];
+}
+/** Pose is a track read at one tick. */
+export interface Pose {
+    position: Vector;
+    facing: Angles;
+    /** velocity is the motion between the two samples the pose lies in. */
+    velocity: Vector;
+    /** health is absent when the track records none. */
+    health?: number;
+}
+/** trackTicks is the tick of the track's last sample. */
+export declare function trackTicks(track: Track): number;
+/**
+ * poseAt reads track at tick, blending the two samples around it: positions
+ * and health linearly, angles along the shorter arc. A tick past either end
+ * reads that end. It returns undefined for a track without samples.
+ */
+export declare function poseAt(track: Track, tick: number): Pose | undefined;
+/**
+ * PuppetState is where playback stands: paused holds the hero at the tick,
+ * playing advances it with the game clock, and ended is a play that reached
+ * the track's last tick, which seek or play from a lower tick restarts.
+ */
+export type PuppetState = 'paused' | 'playing' | 'ended';
+/** PuppetOptions tunes a puppet. */
+export interface PuppetOptions {
+    /**
+     * snapUnits is the distance, in world units, beyond which the hero
+     * teleports to the pose instead of gliding to it: after a seek, or across a
+     * gap in the recording. The default is 200.
+     */
+    snapUnits?: number;
+    /** ghost starts the puppet as a ghost. */
+    ghost?: boolean;
+}
+/**
+ * ghostStates are the modifier states of a ghost: it takes no damage, enemies
+ * and units neither target nor count it, and its unit status stays hidden.
+ */
+export declare const ghostStates: string[];
+/**
+ * advancePuppets moves every playing puppet to the game clock at seconds.
+ * The library calls it once per frame.
+ */
+export declare function advancePuppets(seconds: number): void;
+/**
+ * Puppet plays a Track on a hero. Playback starts paused at tick 0; the hero
+ * moves only while the puppet is playing or after a seek.
+ */
+export declare class Puppet {
+    readonly player: Player;
+    readonly track: Track;
+    private tickAt;
+    private rateNow;
+    private current;
+    /** clock is the game time of the last frame, unset until one arrives. */
+    private clock;
+    /** drawn is whether the hero needs placing at the current tick. */
+    private drawn;
+    private ghostNow;
+    private dead;
+    /** looked is the entity and ghost setting syncLook last wrote. */
+    private looked?;
+    private lastHealth;
+    private readonly snapUnits;
+    /**
+     * The puppet drives player's hero along track. It owns the hero's placement
+     * and, when the track records health, its health.
+     */
+    constructor(player: Player, track: Track, options?: PuppetOptions);
+    /**
+     * spawn adds a bot and returns a puppet for it, or undefined when no bot
+     * could join. The bot appears at the track's first pose.
+     */
+    static spawn(bot: BotOptions, track: Track, options?: PuppetOptions): Puppet | undefined;
+    /** state is where playback stands. */
+    get state(): PuppetState;
+    /** tick is the playback position, in track ticks. */
+    get tick(): number;
+    /** rate is the playback speed: 1 is real time, 0.5 half speed, negative runs backward. */
+    get rate(): number;
+    set rate(rate: number);
+    /** isGhost reports whether the puppet is a ghost. */
+    get isGhost(): boolean;
+    /** play starts or resumes playback; from the end it restarts at tick 0. */
+    play(): void;
+    /** pause holds the hero where it stands. */
+    pause(): void;
+    /**
+     * seek moves playback to tick, clamped to the track, and places the hero
+     * there on the next frame. Playback keeps its state, except that an ended
+     * puppet paused at the new tick.
+     */
+    seek(tick: number): void;
+    /**
+     * setGhost draws the hero translucent and holds the modifier states of
+     * ghostStates, so it takes no damage and is not targeted; off restores
+     * both. The hero's collision with other heroes is the game's own.
+     */
+    setGhost(ghost: boolean): void;
+    /**
+     * syncLook writes the ghost look and states to the hero entity when the
+     * entity or the ghost setting differs from what it last wrote, so a hero
+     * that respawned takes them again.
+     */
+    private syncLook;
+    /** stop ends the puppet and removes its bot; a hero that is not a bot stays. */
+    stop(): void;
+    /**
+     * advance moves playback to the game clock at seconds and places the hero.
+     * The library calls it each frame; a mod calls it only to step a puppet by
+     * hand.
+     */
+    advance(seconds: number): void;
+    /** place puts the hero at the current tick; it retries next frame without a hero. */
+    private place;
+    /**
+     * setHealth gives the hero the recorded health. A recorded zero kills the
+     * hero once; the first health above zero after that respawns it, and the
+     * next frame places it.
+     */
+    private setHealth;
+}

package/quickjs.d.ts

@@ -0,0 +1 @@
+export * from './index.js';

package/replayed-damage.d.ts

@@ -0,0 +1,27 @@
+import { type Player } from './host.gen.js';
+/** ReplayedHit is one recorded hit. */
+export interface ReplayedHit {
+    /** victim is the player whose hero takes the hit. */
+    victim: Player;
+    /**
+     * attacker is the player credited with the hit, usually a puppet. Without
+     * one the hit is a hazard that credits no one.
+     */
+    attacker?: Player;
+    /** amount is the damage before resistances. */
+    amount: number;
+    /** headshot makes the hit land on the head. */
+    headshot?: boolean;
+    /**
+     * ability names the attacker's ability that dealt the hit, such as
+     * citadel_ability_hornet_snipe. It is left out of the hit when the attacker
+     * does not own it.
+     */
+    ability?: string;
+}
+/**
+ * replayDamage deals hit through the game's own damage, so resistances,
+ * kill credit, hit effects and the Damage events apply. It returns false
+ * when either hero is not alive to take part; the host logs why.
+ */
+export declare function replayDamage(hit: ReplayedHit): boolean;

package/restore.d.ts

@@ -0,0 +1,43 @@
+import { type Angles, type EquipmentTarget, type Player, type TimerTarget, type Vector } from './host.gen.js';
+/**
+ * HeroSnapshot is the state restoreHero gives a hero. Omitted parts keep the
+ * hero's own.
+ */
+export interface HeroSnapshot {
+    /** position is the hero's origin. */
+    position: Vector;
+    /** facing is where the hero and its camera face. */
+    facing: Angles;
+    /** health and maxHealth are the hero's health and its base maximum. */
+    health: number;
+    maxHealth: number;
+    /** level is the hero's level. */
+    level?: number;
+    /**
+     * souls is the souls the hero holds unspent, once the build is in place.
+     * The build a snapshot lists is not paid for from them.
+     */
+    souls?: number;
+    /** upgradeBonuses are the three stat bonuses purchases add. */
+    upgradeBonuses?: readonly number[];
+    /** abilities are the hero's abilities in their slots, with their bought tiers. */
+    abilities?: readonly EquipmentTarget[];
+    /** items replace every item the hero owns; an empty list removes them. */
+    items?: readonly EquipmentTarget[];
+    /** timers are the charges and cooldowns of owned abilities and items. */
+    timers?: readonly TimerTarget[];
+}
+/**
+ * restoreHero gives player's live hero the snapshot over the next few
+ * seconds, and calls done with undefined once the state has held, or with
+ * the reason it did not. A new restore for the player replaces the running
+ * one, which never calls done. It returns false when the restore could not
+ * start. Shields are not restored.
+ */
+export declare function restoreHero(player: Player, snapshot: HeroSnapshot, done?: (error: string | undefined) => void): boolean;
+/**
+ * settleRestore finishes player's restore when the host reports its end: it
+ * sets the souls the snapshot holds and calls the restore's callback. The
+ * library calls it for each Restored event.
+ */
+export declare function settleRestore(player: Player, error: string | undefined): void;

package/scriptc.d.ts

@@ -0,0 +1,8 @@
+import './index.js';
+/**
+ * event answers the Call the host holds, size bytes long. call hands the
+ * host an encoded Call and returns the size of its Reply; read copies the
+ * bytes the host holds, the Call first and then each Reply, into its
+ * argument.
+ */
+export declare function event(size: number, call: (data: Uint8Array) => number, read: (data: Uint8Array) => void): Uint8Array;

package/spot.d.ts

@@ -0,0 +1,82 @@
+import { type Angles, type MovementSample, type Vector, type WorldObject } from './host.gen.js';
+/** SpotObject is one solid object placed in a spot. */
+export interface SpotObject {
+    /** model is the model's path, which the mode precached. */
+    readonly model: string;
+    /** position is the model's origin. */
+    readonly position: Vector;
+    /** facing is the model's rotation. */
+    readonly facing: Angles;
+    /** scale multiplies the model's size. */
+    readonly scale: number;
+    /**
+     * bounce launches a hero who stands on the object upward at this speed, in
+     * units per second; zero makes an ordinary object.
+     */
+    readonly bounce: number;
+    /** placedBy is the Steam ID of the player who placed the object, or zero. */
+    readonly placedBy: bigint;
+}
+/** Spot is a base map and the objects placed on it, in placement order. */
+export interface Spot {
+    readonly map: string;
+    readonly objects: readonly SpotObject[];
+}
+/**
+ * encodeSpot returns the spot document. Equal spots encode to equal bytes.
+ * Positions and angles keep single precision.
+ */
+export declare function encodeSpot(spot: Spot): Uint8Array;
+/** decodeSpot reads a spot document. */
+export declare function decodeSpot(bytes: Uint8Array): Spot;
+/** Placed is one spot object standing in the world. */
+export interface Placed {
+    readonly object: SpotObject;
+    readonly world: WorldObject;
+    /** entity is the model's entity handle, as traces report it. */
+    readonly entity: number;
+}
+/**
+ * triggers is the trigger collision layer. Traces that look for placed
+ * objects exclude it: spawn rooms and other volumes enclose the ground, and a
+ * line starting inside one stops there.
+ */
+export declare const triggers: bigint;
+/**
+ * LoadedSpot is a spot standing in the world. It keeps the placed objects in
+ * placement order, so spot() returns what a player sees.
+ */
+export declare class LoadedSpot {
+    readonly map: string;
+    private placed;
+    private entities;
+    constructor(map: string);
+    /** objects returns the placed objects in placement order. */
+    objects(): readonly Placed[];
+    /**
+     * place spawns object as a solid model and adds it to the spot. A model
+     * the game cannot place logs why and returns nothing.
+     */
+    place(object: SpotObject): Placed | undefined;
+    /** at returns the placed object whose entity a trace hit, if any. */
+    at(entity: number): Placed | undefined;
+    /** move puts a placed object at position and facing, keeping its order. */
+    move(placed: Placed, position: Vector, facing: Angles): Placed;
+    /** remove takes a placed object out of the world and the spot. */
+    remove(placed: Placed): void;
+    /** clear removes every placed object. */
+    clear(): void;
+    /** spot returns the spot as it stands. */
+    spot(): Spot;
+    /**
+     * bounce launches each sampled hero who stands on a bouncing object. A
+     * mode calls it with each frame's movement samples, for the heroes it
+     * watches.
+     */
+    bounce(movement: readonly MovementSample[]): void;
+}
+/**
+ * loadSpot places every object of spot and returns it standing. Objects the
+ * game cannot place are skipped with a log line; the rest load.
+ */
+export declare function loadSpot(spot: Spot): LoadedSpot;

package/theme.d.ts

@@ -0,0 +1,137 @@
+/** Tone names the colors a surface may use for meaning. */
+export type Tone = 'text' | 'muted' | 'accent' | 'onAccent' | 'amber' | 'sapphire' | 'gas' | 'success' | 'danger' | 'gold';
+/**
+ * tones maps each meaning to one color. Text, team and danger colors are the
+ * stock HUD's offWhite, team1Color, team2Color and colorEnemy.
+ */
+export declare const tones: Record<Tone, string>;
+/**
+ * teamTones colors each game team, by its team number: 2 is the Hidden
+ * King's amber, 3 the Archmother's sapphire.
+ */
+export declare const teamTones: Readonly<Record<number, Tone>>;
+/**
+ * shades are the neutrals a full screen draws with, from the stock main menu's
+ * base styles, so a full screen reads as part of the game's own menus. Fills are
+ * opaque offWhite tints of the offBlack backdrop: Panorama blends translucent
+ * fills far stronger than their alpha, which let the stock menu show through.
+ */
+export declare const shades: {
+    /** offWhite at about half strength: idle navigation and secondary text. */
+    readonly quiet: '#ffefd78c';
+    /** offWhite at the popup button's 44%: idle pill borders. */
+    readonly faint: '#ffefd770';
+    /** offWhite at about 40%: counts, placeholders and offline players. */
+    readonly dim: '#6b675d';
+    /** offWhite at 13%: hairlines between sections and plate edges. */
+    readonly hairline: '#2b2a24';
+    /** offBlack: text on light fills, and the backdrop's hue. */
+    readonly ink: '#10130d';
+    /** The menu backdrop: an opaque offBlack that hides the stock menu. */
+    readonly backdrop: '#0b0d09';
+    /** The backdrop at 95%, under a panel the player reads over the game. */
+    readonly veil: '#0b0d09f2';
+    /** offWhite at 4%: a plate on the backdrop. */
+    readonly plate: '#151611';
+    /** offWhite at 8%: a row or stat inside a plate. */
+    readonly raised: '#1e1f19';
+    /** offWhite at 13%: a hovered or joined row. */
+    readonly lit: '#2b2a24';
+    /** The full-strength fill of a lit primary button. */
+    readonly white: '#ffffff';
+    /** No fill or border, where a state turns one off. */
+    readonly clear: '#00000000';
+};
+/**
+ * sizes holds the shared sizes: panel buttons and fields share one height, row
+ * buttons a shorter one, and every control and tag one corner radius.
+ */
+export declare const sizes: {
+    /** control is the height of panel buttons and fields. */
+    readonly control: 32;
+    /** rowControl is the height of a button inside a list row. */
+    readonly rowControl: 28;
+    /** row is the height of one list row. */
+    readonly row: 32;
+    /** radius rounds buttons, fields and tags. */
+    readonly radius: 4;
+    /** panelRadius rounds panels. */
+    readonly panelRadius: 8;
+};
+/**
+ * Face is one of the game's typefaces: body is Retail Demo, its text; block is
+ * VALVEPulp, set in capitals for the stock clock, round titles and callouts;
+ * serif is Reaver, its menus.
+ */
+export type Face = 'body' | 'block' | 'serif';
+/** TextRole names one step of the HUD type scale. */
+export type TextRole = 'display' | 'title' | 'body' | 'label' | 'caption';
+/** Type is one type role: its face, size in pixels, and whether in capitals. */
+export interface Type {
+    readonly face: Face;
+    readonly size: number;
+    readonly uppercase: boolean;
+}
+/** types gives every build the same typography. */
+export declare const types: Record<TextRole, Type>;
+/**
+ * plate is the translucent plate under HUD text. It stays dark enough for
+ * muted captions to read over a bright sky.
+ */
+export declare const plate: {
+    color: string;
+    radius: number;
+    /** padding is [vertical, horizontal] in pixels. */
+    padding: readonly [10, 18];
+};
+/** pillEdge is a pill's resting edge, a faint parchment line. */
+export declare const pillEdge = "#ffefd71a";
+/** PipShape is a round point, as in the stock round counter, or a narrow tick. */
+export type PipShape = 'round' | 'tick';
+/** pipShapes are each pip shape's size and corner radius, in pixels. */
+export declare const pipShapes: Record<PipShape, {
+    readonly width: number;
+    readonly height: number;
+    readonly radius: number;
+}>;
+/** pipRings are the stock round counter's point borders, empty and filled. */
+export declare const pipRings: {
+    readonly empty: '#ffefd72e';
+    readonly filled: '#10130de6';
+};
+/** emptyPip is an unearned pip's fill: clear, so only its faint ring shows. */
+export declare const emptyPip = "#00000000";
+/**
+ * teamBarBottom is where the stock team bar ends, in pixels on a 1080 high
+ * HUD; a strip that keeps the bar sits below it.
+ */
+export declare const teamBarBottom = 84;
+/**
+ * objectiveBarBottom is where the stock objective bar under the team bar ends,
+ * its urn and Rift progress, in pixels on a 1080 high HUD; a strip's line goes
+ * below it so the bar's labels stay clear.
+ */
+export declare const objectiveBarBottom = 220;
+/**
+ * fpsReadoutBottom is how far down the top right corner HUD starts, in pixels
+ * on a 1080 high HUD: under the game's FPS readout, whose third line, the red
+ * slow server frame warning, shows during server spikes and ends about 62px
+ * down.
+ */
+export declare const fpsReadoutBottom = 68;
+/**
+ * sounds are the game's interface sound events for the kit's controls: the
+ * main menu's hover tick and press.
+ */
+export declare const sounds: {
+    readonly hover: 'UI.MainMenu.Hover';
+    readonly press: 'UI.MainMenu.Activate';
+};
+/**
+ * motion is how long the kit's controls take to answer the pointer and a
+ * meter to reach its value, in seconds: quick enough to feel immediate.
+ */
+export declare const motion: {
+    readonly hover: 0.15;
+    readonly meter: 0.25;
+};

package/timer.d.ts

@@ -0,0 +1,22 @@
+/** Timer is one scheduled callback. */
+export interface Timer {
+    /** finished reports whether the timer ran its last time or was cancelled. */
+    readonly finished: boolean;
+    /** cancel stops the timer; it does nothing once the timer is finished. */
+    cancel(): void;
+}
+/** after runs fn once, seconds from now. */
+export declare function after(seconds: number, fn: () => void): Timer;
+/** every runs fn each seconds, keeping its cadence through a late frame. */
+export declare function every(seconds: number, fn: () => void): Timer;
+/**
+ * sequence calls fn on the next frame with the number of times it has run,
+ * starting at 1. fn returns the seconds to wait before it runs again, or
+ * nothing to end the sequence.
+ */
+export declare function sequence(fn: (run: number) => number | void): Timer;
+/**
+ * advance moves the clock to a frame and runs the timers that came due. A
+ * callback that throws ends only its own timer.
+ */
+export declare function advance(seconds: number): void;