@modlock/modlock 0.0.0-stage → 0.1.64

package/format.d.ts

@@ -0,0 +1,29 @@
+/**
+ * clock writes seconds as minutes and seconds, such as 4:07, rounding up so a
+ * countdown reads 0:00 only once it has run out. Negative time reads 0:00.
+ */
+export declare function clock(seconds: number): string;
+/**
+ * stopwatch writes seconds with hundredths, such as 1:04.37, rounding down
+ * so a run's time never reads faster than it was. Negative time reads 0:00.00.
+ */
+export declare function stopwatch(seconds: number): string;
+/**
+ * percent writes part of whole as a whole percentage from 0% to 100%, such
+ * as 42%, or a dash while whole is not positive. A fraction is percent(f, 1).
+ */
+export declare function percent(part: number, whole: number): string;
+/** grouped writes a number rounded to a whole with comma thousands, such as 4,210. */
+export declare function grouped(value: number): string;
+/** ordinal writes a place, such as 1st, 2nd, 11th or 23rd. */
+export declare function ordinal(place: number): string;
+/**
+ * count writes a number of things, in the plural unless one, such as 1 kill
+ * or 3 kills. plural defaults to thing with an s.
+ */
+export declare function count(number: number, thing: string, plural?: string): string;
+/**
+ * clip shortens text to at most width characters, at a word break where one
+ * falls in the cut, and marks the cut with an ellipsis.
+ */
+export declare function clip(text: string, width: number): string;

package/frameclock.d.ts

@@ -0,0 +1,34 @@
+/** FrameClock times the frames of one mod. */
+declare class FrameClock {
+    /** frames holds the milliseconds each frame of the current minute took. */
+    private readonly frames;
+    private readonly costs;
+    /** laps holds the current frame's systems and milliseconds. */
+    private laps;
+    /** slowest holds the laps of the minute's slowest frame. */
+    private slowest;
+    /** slowestMs is the slowest frame's milliseconds, below any frame when none ran. */
+    private slowestMs;
+    private start;
+    private mark;
+    /** reportAt is the tick that ends the current minute. */
+    private reportAt;
+    /** begin starts timing a frame. */
+    begin(): void;
+    /** elapsed is the milliseconds since the frame began. */
+    get elapsed(): number;
+    /** lap charges the time since the previous lap, or the frame's start, to system. */
+    lap(system: string): void;
+    /**
+     * end finishes the frame and, once a minute of ticks passed, logs the
+     * minute's median and slowest frame with the systems that cost the most:
+     * each one's mean and slowest milliseconds a frame, and the slowest frame's
+     * costliest laps, to the server log.
+     * The minute ends on the first frame at or past its last tick, since the
+     * host skips a slow mod's frames and may skip that tick.
+     */
+    end(tick: bigint): void;
+}
+/** frameClock is the mod's one frame clock. */
+export declare const frameClock: FrameClock;
+export {};

package/globals.d.ts

@@ -0,0 +1,69 @@
+// The globals every Modlock JavaScript runtime gives a mod, beyond the
+// standard ECMAScript library. A mod reads them through these declarations
+// alone: scriptc lowers a global only when the name resolves to its own
+// declaration, so a mod that declares one itself shadows it.
+
+/** Console writes lines to the server log under the mod's name. */
+interface Console {
+  /** log writes its arguments, separated by spaces, as one line. */
+  log(...parts: unknown[]): void
+  /** info writes as log does. */
+  info(...parts: unknown[]): void
+  /** warn writes as log does. */
+  warn(...parts: unknown[]): void
+  /** error writes as log does. */
+  error(...parts: unknown[]): void
+  /** debug writes as log does. */
+  debug(...parts: unknown[]): void
+}
+
+/** console writes to the server log. */
+declare var console: Console
+
+/** Performance reads a monotonic clock. */
+interface Performance {
+  /** now returns the milliseconds since the mod started, with a fraction. */
+  now(): number
+}
+
+/** performance is the mod's clock for timing its own work. */
+declare var performance: Performance
+
+// TextEncoder and TextDecoder are interfaces with constructor variables, as
+// in the standard library, rather than classes: a mod whose source graph
+// reaches two copies of this file merges them instead of failing on a
+// duplicate identifier.
+
+/** TextEncoder encodes strings as UTF-8. */
+interface TextEncoder {
+  /** encoding is always "utf-8". */
+  readonly encoding: 'utf-8'
+  /** encode returns text's UTF-8 bytes. */
+  encode(text?: string): Uint8Array
+}
+
+/** TextEncoder constructs an encoder. */
+declare var TextEncoder: {
+  prototype: TextEncoder
+  new (): TextEncoder
+}
+
+/** TextDecoder decodes UTF-8 bytes. */
+interface TextDecoder {
+  /** encoding is always "utf-8". */
+  readonly encoding: 'utf-8'
+  /** decode returns the text in bytes. */
+  decode(bytes?: ArrayBuffer | ArrayBufferView): string
+}
+
+/** TextDecoder constructs a decoder. */
+declare var TextDecoder: {
+  prototype: TextDecoder
+  new (): TextDecoder
+}
+
+/**
+ * A style sheet in the mod's content/styles/ directory. Importing one, as
+ * import './content/styles/hud.css', adds it to every interface the mod shows.
+ */
+declare module '*.css' {}

package/ground.d.ts

@@ -0,0 +1,16 @@
+import { type Vector } from './host.gen.js';
+/** GroundOptions shape the trace ground runs; each one has a default. */
+export interface GroundOptions {
+    /** above is how far over the point the trace starts, 64 units by default. */
+    readonly above?: number;
+    /** below is how far under the point the trace ends, 1024 units by default. */
+    readonly below?: number;
+    /** layers is what counts as floor: solid and player clip by default. */
+    readonly layers?: bigint;
+}
+/**
+ * ground returns the floor under point, searched from just above it. It
+ * returns undefined when no floor answers in reach, when the trace starts
+ * inside a wall, and before the world's collision is ready.
+ */
+export declare function ground(point: Vector, { above, below, layers, }?: GroundOptions): Vector | undefined;

package/heroes.d.ts

@@ -0,0 +1,21 @@
+/** Titled is something players pick by name: the game's name and the one players read. */
+export interface Titled {
+    readonly name: string;
+    readonly title: string;
+}
+/** Hero is one released hero: its game name, such as 'hero_atlas', its title and its fixed id. */
+export interface Hero extends Titled {
+    readonly id: number;
+    /** portrait is the hero's small stock portrait, as an image's src. */
+    readonly portrait: string;
+}
+/** heroes are the released heroes, by title. */
+export declare const heroes: readonly Hero[];
+/** findHero matches what a player typed to a hero, as findTitled does. */
+export declare function findHero(typed: string): Hero | undefined;
+/**
+ * findTitled matches what a player typed, such as 'geist', 'Lady Geist' or
+ * 'hero_ghost', to an entry of list: an exact name first, then the first
+ * title that starts with or contains it.
+ */
+export declare function findTitled<T extends Titled>(list: readonly T[], typed: string): T | undefined;

package/hook.d.ts

@@ -0,0 +1,55 @@
+/** hookAbility is the designer name of Bebop's hook. */
+export declare const hookAbility = "citadel_ability_hook";
+/** hookUpgrades unlocks the hook with all three upgrades. */
+export declare const hookUpgrades = 15;
+/** HookAbility is the part of the host's Ability that Hook reads. */
+export interface HookAbility {
+    readonly name: string;
+    readonly entity: number;
+    readonly upgrades: number;
+    readonly cooldownStart: number;
+    readonly cooldownEnd: number;
+}
+/** HookPlayer is the part of the host's Player that Hook moves. */
+export interface HookPlayer {
+    abilities(): readonly HookAbility[];
+    setAbility(options: {
+        ability: string;
+        upgrades?: number;
+        cooldownEnd?: number;
+    }): boolean;
+    refreshAbility(ability: string): boolean;
+}
+/** ReadHandle is the host's readField, which Hook calls for the hook's victim. */
+export type ReadHandle = (entity: number, className: string, field: string, type: 'handle') => unknown;
+/**
+ * HookRead is what the hook did this frame: the hero it holds, if any, and
+ * whether a new throw began since the last frame Hook reported one.
+ */
+export interface HookRead {
+    readonly victim: number | undefined;
+    readonly thrown: boolean;
+}
+/**
+ * Hook watches one thrower's hook. Its cooldown lasts cooldownSeconds from
+ * each throw; zero ends it at once, so the hook is always ready.
+ */
+export declare class Hook {
+    private readonly read;
+    private readonly cooldownSeconds;
+    /** thrownAt is the start of the latest cooldown counted as a throw. */
+    private thrownAt;
+    constructor(read: ReadHandle, cooldownSeconds?: number);
+    /** reset forgets the throws counted so far, for a thrower in a new world. */
+    reset(): void;
+    /**
+     * update reads the thrower's hook at game time now, keeps it fully upgraded
+     * and sets the length of any cooldown a throw started. It reports nothing
+     * for a hero without the hook.
+     */
+    update(player: HookPlayer, now: number): HookRead | undefined;
+    /** victim is the hero the hook entity holds, or undefined while it holds none. */
+    private victim;
+    /** setCooldown ends the cooldown cooldownSeconds after the hook's throw. */
+    private setCooldown;
+}

package/host.d.ts

@@ -0,0 +1,19 @@
+/** Transport exchanges an encoded Call for the host's encoded Reply. */
+export type Transport = (call: Uint8Array) => Uint8Array;
+/** Dispatch answers one encoded Call the host delivers with its encoded Reply. */
+export type Dispatch = (call: Uint8Array) => Uint8Array;
+/** bind routes the mod's host calls through t from now on. */
+export declare function bind(t: Transport): void;
+/** serveEvents answers each event the host delivers with d. */
+export declare function serveEvents(d: Dispatch): void;
+/**
+ * deliver answers one encoded Call from the host. The library registers its
+ * dispatch when it loads, before any event can arrive.
+ */
+export declare function deliver(call: Uint8Array): Uint8Array;
+/**
+ * call calls one Host method with its encoded request and returns the
+ * encoded response, or undefined when the call failed; the host logs why.
+ * The response may be a view into the reply the transport returned.
+ */
+export declare function call(method: string, request: Uint8Array): Uint8Array | undefined;