@modlock/modlock 0.0.0-stage → 0.1.64

package/ui.d.ts

@@ -0,0 +1,428 @@
+import type { Player } from './host.gen.js';
+/**
+ * Length is a size: pixels, a percentage of the parent, 'fit' to size to the
+ * children, or 'fill' to share the space left in the parent's flow.
+ */
+export type Length = number | `${number}%` | 'fit' | 'fill';
+/**
+ * Edges are distances in pixels: one for every side, [vertical, horizontal],
+ * or [top, right, bottom, left]. They are an array rather than a union of
+ * tuples, which scriptc does not compile.
+ */
+export type Edges = number | readonly number[];
+/**
+ * Overflow decides what happens to children that do not fit: 'squish' shrinks
+ * them, 'clip' cuts them off, 'scroll' lets the player scroll to them, and
+ * 'show' draws them outside the element.
+ */
+export type Overflow = 'squish' | 'clip' | 'scroll' | 'show';
+/**
+ * Gradient blends colors across an element in place of its background. The
+ * colors run down by default; at places each color from 0 to 1, spaced evenly
+ * when unset.
+ */
+export interface Gradient {
+    shape?: 'down' | 'right' | 'up' | 'left' | 'radial';
+    colors: readonly string[];
+    at?: readonly number[];
+}
+/**
+ * Shadow is a soft shadow, offset by x and y and softened by blur, in pixels.
+ * Spread grows a box's shadow in pixels, or strengthens a text shadow, where 0
+ * draws it at full strength; inset draws a box's shadow inside its edge.
+ */
+export interface Shadow {
+    x?: number;
+    y?: number;
+    blur?: number;
+    spread?: number;
+    color: string;
+    inset?: boolean;
+}
+/**
+ * Transition animates each change of an element's style, and the move to its
+ * hover style and back, over seconds after delay. Easing is 'out' unless set.
+ */
+export interface Transition {
+    seconds: number;
+    delay?: number;
+    easing?: 'out' | 'in' | 'inOut' | 'linear';
+}
+/**
+ * Style lays out and paints an element. Colors are '#rrggbb' or '#rrggbbaa'.
+ * Options that take one or two numbers are an array rather than a union of
+ * tuples, which scriptc does not compile.
+ */
+export interface Style {
+    width?: Length;
+    height?: Length;
+    /** minWidth, maxWidth, minHeight and maxHeight bound the element's size. */
+    minWidth?: Length;
+    maxWidth?: Length;
+    minHeight?: Length;
+    maxHeight?: Length;
+    /**
+     * flow places the children in a column or a row, or in columns or rows that
+     * wrap where one is full; unset stacks them.
+     */
+    flow?: 'down' | 'right' | 'downWrap' | 'rightWrap';
+    /**
+     * x and y place the element at an offset from its parent's top left corner,
+     * in pixels or a percent of the parent, outside the parent's flow.
+     */
+    x?: number | `${number}%`;
+    y?: number | `${number}%`;
+    /** zIndex draws the element above its siblings with a lower index. */
+    zIndex?: number;
+    /** overflow decides what children that do not fit do, across and down. */
+    overflow?: Overflow;
+    /** overflowX and overflowY set overflow for one direction. */
+    overflowX?: Overflow;
+    overflowY?: Overflow;
+    horizontalAlign?: 'left' | 'center' | 'right';
+    verticalAlign?: 'top' | 'center' | 'bottom';
+    margin?: Edges;
+    padding?: Edges;
+    background?: string;
+    color?: string;
+    fontSize?: number;
+    bold?: boolean;
+    textAlign?: 'left' | 'center' | 'right';
+    borderRadius?: number;
+    /** opacity fades the element and its children, from 0 to 1. */
+    opacity?: number;
+    /**
+     * face is one of the game's typefaces: 'body' its text, 'block' the
+     * capitals of its clock and titles, 'serif' its menus.
+     */
+    face?: 'body' | 'block' | 'serif';
+    /** uppercase sets the text in capitals. */
+    uppercase?: boolean;
+    /** letterSpacing widens the space between letters, in pixels. */
+    letterSpacing?: number;
+    /** shadow draws a soft drop shadow under the text, to read over the world. */
+    shadow?: boolean;
+    /** textShadow draws this shadow under the text in place of shadow's. */
+    textShadow?: Shadow;
+    /**
+     * borderWidth and borderColor draw a line around the element's edge; it
+     * shows only when both are set.
+     */
+    borderWidth?: number;
+    borderColor?: string;
+    /** gradient fills the element in place of its background. */
+    gradient?: Gradient;
+    /** boxShadow draws a shadow around or inside the element's box. */
+    boxShadow?: Shadow;
+    /** tint washes the element and its children with a color, recoloring a white icon. */
+    tint?: string;
+    /** saturation, brightness and contrast scale the colors; 1 leaves them. */
+    saturation?: number;
+    brightness?: number;
+    contrast?: number;
+    /** blur blurs the element and its children by a radius in pixels. */
+    blur?: number;
+    italic?: boolean;
+    /** weight sets the text's weight in place of bold. */
+    weight?: 'thin' | 'light' | 'normal' | 'medium' | 'semiBold' | 'bold' | 'black';
+    /** lineHeight is the height of each line of text, in pixels. */
+    lineHeight?: number;
+    /** noWrap keeps the text on one line. */
+    noWrap?: boolean;
+    /**
+     * textOverflow ends text that does not fit with an 'ellipsis', 'shrink's it
+     * until it fits, or 'clip's it at the edge.
+     */
+    textOverflow?: 'ellipsis' | 'shrink' | 'clip';
+    /** decoration draws a line under or through the text. */
+    decoration?: 'underline' | 'strike';
+    /** translate moves the element as drawn by [x, y] pixels. */
+    translate?: readonly number[];
+    /** scale scales the element as drawn: one factor, or [x, y]. */
+    scale?: number | readonly number[];
+    /** rotate turns the element clockwise, in degrees. */
+    rotate?: number;
+    /**
+     * origin is the point the element scales and turns about, as [x, y]
+     * percents of its size; unset is its center.
+     */
+    origin?: readonly number[];
+    /**
+     * transition animates each change of the style: seconds, or a Transition.
+     * Animate transform, opacity and colors; size and placement animate too, but
+     * move the element's neighbors each frame.
+     */
+    transition?: number | Transition;
+}
+/**
+ * HudPart is a part of the game's own HUD: 'levelUp' the notice for each boon,
+ * ability point and power increase, 'ownHealth' the player's health bar with
+ * its shields and regeneration, 'topBar' the bar of team scores, portraits
+ * and clock across the top, 'ammo' the clip ring, count and ammo warnings at
+ * the crosshair, 'souls' the souls and level readout, 'minimap' the minimap
+ * with its hints and district name, 'abilities' the ability and active item
+ * bar. Whatever a part does not name stays, such as the crosshair and chat.
+ */
+export type HudPart = 'levelUp' | 'ownHealth' | 'topBar' | 'ammo' | 'souls' | 'minimap' | 'abilities';
+/** Child is anything an element may hold. Text becomes a label. */
+export type Child = UiElement | string | number | boolean | null | undefined | readonly Child[];
+/** Component returns the elements that stand for its props. */
+export type Component<P> = (props: P) => Child;
+/**
+ * UiElement is one element of an interface, as JSX builds it. A component's
+ * element is a fragment holding what the component returned.
+ */
+export interface UiElement {
+    readonly type: string;
+    readonly props: Props;
+    readonly key?: string;
+}
+/**
+ * Props are an element's props: every intrinsic element's, by name, so the
+ * encoder reads them as typed fields. A component's props pass through to it.
+ */
+export interface Props {
+    readonly class?: string;
+    readonly style?: Style;
+    readonly hover?: Style;
+    readonly tooltip?: string;
+    readonly hoverSound?: string;
+    readonly children?: Child;
+    readonly src?: string;
+    readonly scaling?: Scaling;
+    readonly hero?: number;
+    readonly look?: HeroLookName;
+    readonly data?: unknown;
+    readonly sound?: string;
+    readonly disabled?: boolean;
+    readonly onPress?: (player: Player) => void;
+    readonly enter?: Style;
+    readonly exit?: Style;
+    readonly cycle?: Cycle;
+    readonly token?: string;
+    readonly variables?: Readonly<Record<string, string | number>>;
+    readonly steamId?: bigint;
+    readonly value?: string | number;
+    readonly placeholder?: string;
+    readonly maxLength?: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+    readonly on?: boolean;
+    readonly options?: readonly string[];
+    readonly selected?: number;
+    readonly onChange?: (player: Player, value: never) => void;
+}
+/**
+ * ElementProps are the props every drawn element takes. hover is the style
+ * drawn over style while the pointer is over the element; tooltip is the text
+ * the game's tooltip shows then, and hoverSound the game's sound event played
+ * as the pointer enters, such as 'UI.MainMenu.Hover'. An element with any of
+ * them takes the pointer, so the game behind it does not.
+ */
+export interface ElementProps {
+    /** class names the element's classes in the mod's sheets, separated by spaces. */
+    class?: string;
+    style?: Style;
+    hover?: Style;
+    tooltip?: string;
+    hoverSound?: string;
+    /** enter is the style the element's panel starts from when it first shows. */
+    enter?: Style;
+    /** exit is the style the element's panel eases to as it leaves. */
+    exit?: Style;
+    /** cycle swings the element to another style and back while it shows. */
+    cycle?: Cycle;
+}
+/**
+ * Cycle swings an element from its style to style and back, each way taking
+ * seconds, count times or, without a count, while it shows.
+ */
+export interface Cycle {
+    style: Style;
+    seconds: number;
+    count?: number;
+}
+/** PanelProps lay out a panel, which groups its children. */
+export interface PanelProps extends ElementProps {
+    children?: Child;
+}
+/**
+ * LabelProps show text: the label's text children, joined, or the game's text
+ * for token in the player's language, with each {s:name} place in it filled
+ * from variables.
+ */
+export interface LabelProps extends ElementProps {
+    children?: Child;
+    token?: string;
+    variables?: Readonly<Record<string, string | number>>;
+}
+/** AvatarProps show the Steam picture of the player with steamId. */
+export interface AvatarProps extends ElementProps {
+    steamId: bigint;
+}
+/**
+ * InputProps are the props every input takes. A disabled input takes no
+ * changes.
+ */
+export interface InputProps extends ElementProps {
+    disabled?: boolean;
+}
+/**
+ * EntryProps make a box the player types a line into: value is its text,
+ * placeholder the faint text it shows empty, and maxLength its limit in
+ * characters, 100 unless set, and at most 240 bytes of text.
+ */
+export interface EntryProps extends InputProps {
+    value?: string;
+    placeholder?: string;
+    maxLength?: number;
+    onChange?: (player: Player, text: string) => void;
+}
+/**
+ * SliderProps make a bar the player drags to a number from min to max, 0 to 1
+ * unless set, stopping at each step when step is set.
+ */
+export interface SliderProps extends InputProps {
+    value?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    onChange?: (player: Player, value: number) => void;
+}
+/** ToggleProps make a box the player checks, labeled by its text children. */
+export interface ToggleProps extends InputProps {
+    children?: Child;
+    on?: boolean;
+    onChange?: (player: Player, on: boolean) => void;
+}
+/** DropdownProps let the player pick one of options; selected is its index. */
+export interface DropdownProps extends InputProps {
+    options: readonly string[];
+    selected?: number;
+    onChange?: (player: Player, index: number) => void;
+}
+/**
+ * Scaling fits a picture into its element's box: 'fit' shows it whole, 'cover'
+ * fills the box and crops, 'stretch' fills the box and stretches, 'fitWidth'
+ * and 'fitHeight' fit one side, and 'none' draws it at its own size.
+ */
+export type Scaling = 'fit' | 'cover' | 'stretch' | 'fitWidth' | 'fitHeight' | 'none';
+/** ImageProps show an image from the game's content, such as 'file://{images}/hud/icon.png'. */
+export interface ImageProps extends ElementProps {
+    src: string;
+    scaling?: Scaling;
+}
+/**
+ * HeroLookName is one of the game's pictures of a hero: 'small' the square
+ * portrait of the kill feed, 'card' the hero picker's tall card, 'icon' the
+ * round icon, 'vertical' the hero grid's narrow portrait, 'topBar' the top
+ * bar's portrait and 'minimap' the minimap icon.
+ */
+export type HeroLookName = 'small' | 'card' | 'icon' | 'vertical' | 'topBar' | 'minimap';
+/** HeroProps show a picture of hero, by the game's hero id. */
+export interface HeroProps extends ElementProps {
+    hero: number;
+    look?: HeroLookName;
+    scaling?: Scaling;
+}
+/**
+ * ButtonProps make a button, which holds its children and calls onPress
+ * with the player who pressed it. Players press buttons while they have a
+ * cursor. sound is the game's sound event the press plays, such as
+ * 'UI.MainMenu.Activate', and a disabled button takes no presses.
+ */
+export interface ButtonProps extends ElementProps {
+    children?: Child;
+    sound?: string;
+    disabled?: boolean;
+    onPress?: (player: Player) => void;
+}
+/**
+ * LayoutProps load a layout from the mod's content addon: src is its path
+ * there, such as 'shop.xml', and data is the JSON value its script reads with
+ * Modlock.data.
+ */
+export interface LayoutProps {
+    class?: string;
+    style?: Style;
+    src: string;
+    data?: unknown;
+}
+/** JSX types the elements a mod's JSX may use. */
+export declare namespace JSX {
+    type Element = UiElement;
+    interface IntrinsicElements {
+        panel: PanelProps & IntrinsicAttributes;
+        label: LabelProps & IntrinsicAttributes;
+        image: ImageProps & IntrinsicAttributes;
+        hero: HeroProps & IntrinsicAttributes;
+        button: ButtonProps & IntrinsicAttributes;
+        layout: LayoutProps & IntrinsicAttributes;
+        avatar: AvatarProps & IntrinsicAttributes;
+        entry: EntryProps & IntrinsicAttributes;
+        slider: SliderProps & IntrinsicAttributes;
+        toggle: ToggleProps & IntrinsicAttributes;
+        dropdown: DropdownProps & IntrinsicAttributes;
+    }
+    interface IntrinsicAttributes {
+        key?: string | number;
+    }
+    interface ElementChildrenAttribute {
+        children: unknown;
+    }
+}
+/**
+ * jsx builds one element, rendering a component in place; the TypeScript
+ * compiler calls it for JSX.
+ */
+export declare function jsx(type: string | Component<Props>, props: Props, key?: string | number): UiElement;
+/** jsxs builds an element with several children, as jsx does. */
+export declare const jsxs: typeof jsx;
+/** Fragment groups children without a panel of its own. */
+export declare function Fragment(props: {
+    children?: Child;
+}): Child;
+/**
+ * show replaces the interface the mod shows player with root. A player who
+ * left and a mod that restarted show nothing until the next call.
+ */
+export declare function show(player: Player, root: Child): boolean;
+/**
+ * hideHud hides parts of the game's own HUD from player until the next call;
+ * an empty list shows them all again.
+ */
+export declare function hideHud(player: Player, parts: readonly HudPart[]): boolean;
+/**
+ * sheet adds the style sheet at path in the mod's content styles directory,
+ * such as 'hud.css', to every interface the mod shows, after the sheets added
+ * before it. Adding a sheet again changes nothing. A path is letters, digits,
+ * '_', '-' and '.' in segments separated by '/', ending in '.css'; another
+ * adds nothing and returns false. The build turns an import of a sheet, such
+ * as import './content/styles/hud.css', into this call.
+ */
+export declare function sheet(path: string): boolean;
+/**
+ * route sends player value under name, for every layout of the mod to read
+ * with Modlock.route, until the next call; undefined removes it. A name is
+ * letters, digits, '_', '-' and '.', and the value is anything JSON.stringify
+ * takes. A route with another name, or a value JSON cannot hold, sends nothing
+ * and returns false.
+ */
+export declare function route(player: Player, name: string, value: unknown): boolean;
+/** hide removes the interface, the routes and the notices the mod shows player. */
+export declare function hide(player: Player): boolean;
+/**
+ * toast shows player text in a notice at the lower left for seconds.
+ * Notices stack, newest last, slide in, and fade as they expire.
+ */
+export declare function toast(player: Player, text: string, seconds?: number): boolean;
+/** press runs the handler of the button the player pressed. */
+export declare function press(player: Player, node: string): void;
+/**
+ * change runs the handler of the input the player changed, with its value as
+ * the host checked it.
+ */
+export declare function change(player: Player, node: string, value: string | number | boolean | undefined): void;
+/** tick advances the clock to the frame at seconds and fades expiring notices. */
+export declare function tick(seconds: number): void;

package/vector.d.ts

@@ -0,0 +1,31 @@
+import type { Angles, Vector } from './host.gen.js';
+/** at builds a point or direction from its coordinates. */
+export declare function at(x: number, y: number, z: number): Vector;
+/** add is a moved by b. */
+export declare function add(a: Vector, b: Vector): Vector;
+/** sub is the step from b to a. */
+export declare function sub(a: Vector, b: Vector): Vector;
+/** scale is a times s. */
+export declare function scale(a: Vector, s: number): Vector;
+/** dot is the dot product of a and b. */
+export declare function dot(a: Vector, b: Vector): number;
+/** length is a's length. */
+export declare function length(a: Vector): number;
+/** normalize is a at unit length, or +x for a zero vector. */
+export declare function normalize(a: Vector): Vector;
+/** lerp is the point t of the way from a to b: a at 0, b at 1. */
+export declare function lerp(a: Vector, b: Vector, t: number): Vector;
+/** distance is how far apart a and b are. */
+export declare function distance(a: Vector, b: Vector): number;
+/** flatDistance is how far apart a and b are seen from above, ignoring height. */
+export declare function flatDistance(a: Vector, b: Vector): number;
+/** toward is the unit direction from from to to, or zero when they meet. */
+export declare function toward(from: Vector, to: Vector): Vector;
+/** yawToward is the yaw that faces from from toward to, in degrees. */
+export declare function yawToward(from: Vector, to: Vector): number;
+/** level is the view that looks along yaw, straight ahead. */
+export declare function level(yaw: number): Angles;
+/** aimAt is the view from from that looks at to, without roll. */
+export declare function aimAt(from: Vector, to: Vector): Angles;
+/** forward is the unit direction a view looks along; roll does not change it. */
+export declare function forward(angles: Angles): Vector;