@defold-typescript/types 0.45.0 → 0.47.0

package/hsm/async.d.ts

@@ -1,8 +1,26 @@
 // Generated from packages/hsm/src/async.ts by `bun run --cwd packages/hsm declarations`; do not edit.
 import type { EventObject, TaskStart } from "./index";
-/** @noSelf */
+/**
+ * The second argument of a `sequence` function: a wait that leaving the state cancels, and a flag
+ * that tells the state was left.
+ * @noSelf
+ */
 export interface SequenceSignal {
+    /**
+     * Turns `true` once the state is left. Check it after awaiting anything other than `wait`: such
+     * a promise can still resolve after the state is left, and the code after it then runs.
+     */
     readonly aborted: boolean;
+    /**
+     * Resolves after `seconds`, counted by `timer.delay` rather than by `update(dt)`. A wait still
+     * pending when the state is left never resolves, so the code after it does not run.
+     */
     readonly wait: (seconds: number) => Promise<void>;
 }
+/**
+ * Turns an `async` function into a state's `task`. The function gets the context and a
+ * `SequenceSignal`, and the event it returns is sent to the machine; one returned after the state
+ * is left is ignored. An error thrown inside it leaves the machine where it is and is raised
+ * again from a timer callback, so it shows in the engine console.
+ */
 export declare function sequence<Ctx, E extends EventObject>(run: (ctx: Ctx, signal: SequenceSignal) => Promise<NoInfer<E> | void>): TaskStart<Ctx, E>;

package/hsm/debug.d.ts

@@ -1,7 +1,21 @@
 // Generated from packages/hsm/src/debug.ts by `bun run --cwd packages/hsm declarations`; do not edit.
 import type { EventObject, MachineInstance } from "./index";
-/** @noSelf */
+/**
+ * Returned by `inspect`. Keep it on `self` and call its `draw` from `update`.
+ * @noSelf
+ */
 export interface MachineInspector {
+    /**
+     * Draws the label and the active leaves as debug text, 40 units above `target`'s world
+     * position. Each call also advances the frame number the console lines show. In a release
+     * build it does nothing.
+     */
     readonly draw: (target: Hash | Url | string) => void;
 }
+/**
+ * Prints one line when it is called, then one line for each move `instance` makes, each starting
+ * with `hsm` and the label. Call it once after `start`. A label another `inspect` call already
+ * used gets an ordinal, such as `enemy#2`. In a release build it registers nothing and returns an
+ * inspector whose `draw` does nothing, so the calls can stay in shipped code.
+ */
 export declare function inspect<Ctx, E extends EventObject, P extends string>(instance: MachineInstance<Ctx, E, P>, label: string): MachineInspector;

package/hsm/defold.d.ts

@@ -1,10 +1,30 @@
 // Generated from packages/hsm/src/defold.ts by `bun run --cwd packages/hsm declarations`; do not edit.
+/**
+ * The event `messageEvents` builds from the Defold message `K`, for a machine's event union. It
+ * holds the message id as `type`, the payload fields declared through `BuiltinMessages` and
+ * `CustomMessages`, and the `sender`.
+ */
 export type MessageEvent<K extends MessageId> = K extends MessageId ? {
+    /** The message id. A payload field named `type` never overrides it. */
     readonly type: K;
+    /** The URL the message came from. A payload field named `sender` never overrides it. */
     readonly sender: Url;
 } & Omit<MessagePayload<K>, "type" | "sender"> : never;
-/** @noSelf */
+/**
+ * Returned by `messageEvents`. Build it once at module scope: it hashes the ids when it is
+ * created.
+ * @noSelf
+ */
 export interface MessageEventMapper<K extends MessageId> {
+    /**
+     * Turns the parameters of `on_message` into the event for that message, a new table on each
+     * call. Returns `undefined` for a message id that `messageEvents` was not given.
+     */
     readonly toEvent: (message_id: Hash, message: Record<string | number, unknown>, sender: Url) => MessageEvent<K> | undefined;
 }
+/**
+ * Builds a mapper that turns the Defold messages listed in `ids` into typed machine events of
+ * the shape `{ type: id, ...payload, sender }`. Call it once at module scope: the ids are hashed
+ * here.
+ */
 export declare function messageEvents<const K extends MessageId>(ids: readonly K[]): MessageEventMapper<K>;

package/hsm/index.d.ts

@@ -1,18 +1,60 @@
 // Generated from packages/hsm/src/index.ts by `bun run --cwd packages/hsm declarations`; do not edit.
+/**
+ * An event a machine handles: an object with a string `type`, plus any payload fields. A
+ * machine's event type is a union of these.
+ */
 export interface EventObject {
+    /** Names the event. A state's `on` takes these values as its keys. */
     readonly type: string;
 }
+/**
+ * What made a move happen: `event` for a sent event, `after` for a timer, `update` for a path an
+ * `update` hook returned, `always` for an `always` rule, `stop` for `stop()`, and `reload` for a
+ * hot reload that changed the current state.
+ */
 export type MoveCause = "event" | "after" | "update" | "stop" | "reload" | "always";
-/** @noSelf */
+/**
+ * A listener given to `onMove`. It gets the leaf left, the leaf entered (`undefined` after
+ * `stop()`), the cause, and the event, which is `undefined` unless the cause is `event`. It runs
+ * after the move's `enter` hooks.
+ * @noSelf
+ */
 export type MoveListener<E extends EventObject, P extends string = string> = (from: P, to: P | undefined, cause: MoveCause, event: E | undefined) => void;
-/** @noSelf */
+/**
+ * One running machine, returned by `start`. `P` is the union of the machine's state paths; the
+ * `machine` a hook, a `run` or a `task` receives uses plain `string` paths instead.
+ * @noSelf
+ */
 export interface MachineInstance<Ctx, E extends EventObject, P extends string = string> {
+    /** The context passed to `start`. */
     readonly ctx: Ctx;
+    /**
+     * The full path of the deepest active state, or `undefined` once stopped. In a parallel state
+     * it is the first region's leaf.
+     */
     readonly path: P | undefined;
+    /**
+     * The full path of every active leaf, in region order: one path without parallel states, empty
+     * once stopped. It is the same array on every read, updated in place.
+     */
     readonly leaves: readonly P[];
+    /** Whether the state at the full path `path` is active. Ancestors of the current state count. */
     readonly matches: (path: P) => boolean;
+    /**
+     * Handles `event`, or queues it when called during a step. An event no active state handles is
+     * dropped, and once the machine is stopped the call does nothing.
+     */
     readonly send: (event: E) => void;
+    /**
+     * Advances the machine by `dt` seconds: runs the `update` hooks, then the `after` timers if no
+     * hook moved it. A machine whose `update` is not called is frozen in time, and once the machine
+     * is stopped the call does nothing.
+     */
     readonly update: (dt: number) => void;
+    /**
+     * Exits every active state, deepest first, and sets `path` to `undefined`. Called during a
+     * step, it lets that step finish and drops the queued events.
+     */
     readonly stop: () => void;
     /**
      * Adds a listener called after each move completes, with the leaf left, the leaf entered and
@@ -22,13 +64,21 @@ export interface MachineInstance<Ctx, E extends EventObject, P extends string =
      */
     readonly onMove: (listener: MoveListener<E, P>) => () => void;
 }
+/**
+ * A function a rule's `run` calls during the move, after the `exit` hooks and before the `enter`
+ * hooks. Its `event` is the variant the `on` key names.
+ */
 export type MoveAction<Ctx, E extends EventObject, V extends E = E> = (ctx: Ctx, event: V, machine: MachineInstance<Ctx, E>) => void;
 interface RuleList<Rule> {
     readonly 0: Rule;
     readonly [index: number]: Rule;
     readonly length: number;
 }
-/** @noSelf */
+/**
+ * The object form of a rule under `on`: a `to`, a `when` and a `run`, each optional. A rule with
+ * no `to` runs its `run` and nothing else: no state exits or enters.
+ * @noSelf
+ */
 export interface TransitionConfig<Ctx, E extends EventObject, V extends E = E, To extends string = string> {
     /**
      * The full path of the state to move to. A `to` naming the state the rule is on exits and
@@ -56,9 +106,21 @@ export interface TransitionConfig<Ctx, E extends EventObject, V extends E = E, T
     /** Removed: a `to` naming the state the rule is on restarts it. */
     readonly reenter?: never;
 }
+/**
+ * What an `on` key maps to: a target path, a `TransitionConfig`, or a non-empty list of them
+ * tried in order. The first rule with no `when`, or whose `when` returns `true`, is taken.
+ */
 export type TransitionSpec<Ctx, E extends EventObject, V extends E = E, To extends string = string> = To | TransitionConfig<Ctx, E, V, To> | RuleList<TransitionConfig<Ctx, E, V, To>>;
-/** @noSelf */
+/**
+ * The object form of an `always` rule: a `to` and an optional `when`. It gets no event and has
+ * no `run`; side effects belong in the target's `enter`.
+ * @noSelf
+ */
 export interface AlwaysConfig<Ctx, To extends string = string> {
+    /**
+     * The full path of the state to move to. An `always` rule without one throws when the machine
+     * is defined.
+     */
     readonly to: To;
     /** Checked on every recheck, so it must have no side effects. */
     readonly when?: (ctx: Ctx) => boolean;
@@ -67,7 +129,15 @@ export interface AlwaysConfig<Ctx, To extends string = string> {
     /** Renamed to `when`. */
     readonly guard?: never;
 }
+/**
+ * What `always` takes: a target path, an `AlwaysConfig`, or a non-empty list of them. The first
+ * whose `when` is missing or passes is taken.
+ */
 export type AlwaysSpec<Ctx, To extends string = string> = To | AlwaysConfig<Ctx, To> | RuleList<AlwaysConfig<Ctx, To>>;
+/**
+ * A state's rules by event `type`. Only the machine's event types are keys, and each rule's
+ * `when` and `run` see the event variant its key names.
+ */
 export type OnConfig<Ctx, E extends EventObject, To extends string = string> = {
     readonly [K in E["type"]]?: TransitionSpec<Ctx, E, Extract<E, {
         type: K;
@@ -79,6 +149,11 @@ export type OnConfig<Ctx, E extends EventObject, To extends string = string> = {
  * event; event data reaches `enter` through `ctx`, set in `run`.
  */
 export type StateHook<Ctx, E extends EventObject> = (ctx: Ctx, machine: MachineInstance<Ctx, E>) => void;
+/**
+ * Runs on every `update(dt)` while the state is active, deepest state first. It returns a full
+ * path to move there, or `undefined` to pass. The first hook to return a path wins: the hooks
+ * above it and the `after` timers do not run on that call, and the move has no `run`.
+ */
 export type UpdateHook<Ctx, E extends EventObject, To extends string = string> = (ctx: Ctx, dt: number, machine: MachineInstance<Ctx, E>) => To | undefined;
 /**
  * Starts work that lives as long as the state. `finish` sends one event and is ignored after the
@@ -86,8 +161,17 @@ export type UpdateHook<Ctx, E extends EventObject, To extends string = string> =
  * @noSelf
  */
 export type TaskStart<Ctx, E extends EventObject> = (ctx: Ctx, finish: (event: E) => void, machine: MachineInstance<Ctx, E>) => (() => void) | void;
-/** @noSelf */
+/**
+ * A machine definition, returned by the second `defineMachine` call. Its `start` creates the
+ * instances that run.
+ * @noSelf
+ */
 export interface Machine<Ctx, E extends EventObject, P extends string = string> {
+    /**
+     * Creates an instance with `ctx` as its context and enters the root's `initial` chain. Each
+     * call returns a separate instance, which has already handled the events its `enter` hooks
+     * sent.
+     */
     readonly start: (ctx: Ctx) => MachineInstance<Ctx, E, P>;
 }
 type PathDepth = [never, 0, 1, 2, 3];
@@ -105,6 +189,10 @@ type TreeOf<C> = C extends {
 } ? {
     readonly [K in keyof Children]: TreeOf<Children[K]>;
 } : unknown;
+/**
+ * The union of a config's state paths, each with its leading `/`. Paths are spelled out four
+ * levels deep; below that, any string under a fourth-level path is accepted.
+ */
 export type StatePath<C> = TreePath<TreeOf<C>>;
 type TreeDepth<T, D extends number> = unknown extends T ? number : [D] extends [never] ? number : 1 | ({
     [K in keyof T]: unknown extends T[K] ? never : TreeDepth<T[K], PathDepth[D]>;
@@ -114,16 +202,43 @@ type AnyChild<Ctx, E extends EventObject, T, To extends string> = unknown extend
 } : unknown;
 /** @noSelf */
 interface StateBase<Ctx, E extends EventObject, T, Self extends string, To extends string> {
+    /** Child states, by name. A name is non-empty and contains no `/`. */
     readonly states?: {
         readonly [K in keyof T]: StateNode<Ctx, E, T[K], `${Self}/${K & string}`, To>;
     } & NoInfer<AnyChild<Ctx, E, T, To>>;
+    /**
+     * Rules by event `type`, each a target path, a rule object or a list of them. An event starts
+     * at the deepest active state and moves up to the parent while no rule takes it.
+     */
     readonly on?: NoInfer<OnConfig<Ctx, E, To>>;
+    /**
+     * Targets by delay in seconds of game time. The delay is counted by `update(dt)` while the
+     * state is active, from zero on each entry. One `update` call fires at most one timer, and
+     * none when an `update` hook moved the machine.
+     */
     readonly after?: NoInfer<{
         readonly [seconds: number]: To;
     }>;
+    /**
+     * Targets taken right after any move that leaves this state active; the first whose `when` is
+     * missing or passes wins. It is checked after a move only: not after a rule with no `to`, and
+     * not on an `update` call that moves nothing.
+     */
     readonly always?: AlwaysSpec<Ctx, To>;
+    /**
+     * Runs each time the state is entered, outermost state first: on a move, at `start`, and when
+     * a hot reload adds the state. It gets no event.
+     */
     readonly enter?: StateHook<Ctx, E>;
+    /**
+     * Runs each time the state is left, deepest state first, including on `stop()`. A state a hot
+     * reload removes is dropped without it.
+     */
     readonly exit?: StateHook<Ctx, E>;
+    /**
+     * Runs on every `update(dt)` while the state is active. Return one of the machine's full paths
+     * to move there, or `undefined` to stay.
+     */
     readonly update?: NoInfer<UpdateHook<Ctx, E, To>>;
     /** Started on each entry; see `TaskStart`. */
     readonly task?: TaskStart<Ctx, E>;
@@ -132,12 +247,30 @@ interface StateBase<Ctx, E extends EventObject, T, Self extends string, To exten
 }
 /** @noSelf */
 interface CompoundState<Ctx, E extends EventObject, T, Self extends string, To extends string> extends StateBase<Ctx, E, T, Self, To> {
+    /**
+     * `"parallel"` keeps every child active at once, each as a region with its own active state.
+     * Not allowed on the root.
+     */
     readonly type?: never;
+    /**
+     * The full path of the child entered with this state, such as `/on/bright` inside `on`.
+     * Required when `states` is set, unless the state is parallel.
+     */
     readonly initial?: NoInfer<unknown extends T ? string : `${Self}/${keyof T & string}`>;
+    /**
+     * Makes the state remember which child was active when it was last left, and enter it again
+     * instead of `initial`. The count is how many levels down to restore, and `"all"` restores
+     * every level below the state. The first entry uses `initial`, and a move that targets a state
+     * inside this one lands on that target.
+     */
     readonly restoreDepth?: NoInfer<TreeDepth<T, 4> | "all">;
 }
 /** @noSelf */
 interface ParallelState<Ctx, E extends EventObject, T, Self extends string, To extends string> extends StateBase<Ctx, E, T, Self, To> {
+    /**
+     * `"parallel"` keeps every child active at once, each as a region with its own active state.
+     * Not allowed on the root.
+     */
     readonly type: "parallel";
     readonly initial?: never;
     readonly restoreDepth?: never;
@@ -147,12 +280,135 @@ type RootState<Ctx, E extends EventObject, T> = CompoundState<Ctx, E, T, "", NoI
     readonly initial: string;
     readonly states: object;
 };
+/**
+ * The config of one state. Every field is optional. A state with child `states` is a compound
+ * state and needs an `initial`, unless its `type` is `"parallel"`; a state without children is a
+ * leaf.
+ */
 export type StateConfig<Ctx, E extends EventObject> = StateNode<Ctx, E, unknown, string, string>;
+/**
+ * The root config passed to `defineMachine`. It takes the fields of a state and requires
+ * `initial` and `states`. The root has no name and cannot be parallel.
+ */
 export type MachineConfig<Ctx, E extends EventObject> = CompoundState<Ctx, E, unknown, string, string> & {
     readonly initial: string;
     readonly states: {
         readonly [name: string]: StateConfig<Ctx, E>;
     };
 };
+/**
+ * Defines a machine in two calls: `defineMachine<Ctx, E>()` fixes the context and event types and
+ * takes an optional hot-reload key, and the second call takes the config. The config is checked
+ * when that call runs, and a mistake throws, naming the state path. With a key, a later
+ * definition under it puts its states into the machine already built, so every running instance
+ * sees the edit; without one, each call builds a separate machine.
+ */
 export declare function defineMachine<Ctx, E extends EventObject>(key?: string): <T>(config: RootState<Ctx, E, T>) => Machine<Ctx, E, TreePath<T>>;
+/**
+ * The key a `definePrivateMachine` config adds to the root, beside `initial` and `states`.
+ * @noSelf
+ */
+export interface PrivateCtxConfig<Ctx, Priv> {
+    /**
+     * Builds the fields only the machine uses. It runs once per `start`, before the root's `enter`
+     * hook, so every instance gets fresh fields of its own; a value written straight into the
+     * config would be one array or table shared by every instance. It takes no arguments: to set
+     * a private field from a field of `Ctx`, do it in the root's `enter` hook.
+     *
+     * The fields are added to the object passed to `start`, which stays the instance's `ctx`, so
+     * restarting with `start(old.ctx)` keeps the public fields and builds the private ones fresh.
+     * A hot reload under the machine's key adds the fields a new factory introduces and leaves
+     * every field that already holds a value alone. A private field may not share a name with a
+     * field of `Ctx`.
+     *
+     * The fields are hidden from callers by type only. At run time `ctx` is one table, and hooks,
+     * `hsm-view` and a debugger see every field.
+     */
+    readonly privateCtx: () => Priv & {
+        readonly [K in keyof Ctx & keyof Priv]: never;
+    };
+}
+/**
+ * Like `defineMachine`, for a machine that keeps fields of its own, such as a counter, a heat
+ * level or a list it builds up. The config's `privateCtx` returns those fields. Every hook,
+ * `when`, `run`, `task` and `update` sees them beside `Ctx`, while `start` takes only `Ctx` and
+ * the instance it returns shows only `Ctx` in its `ctx`. A machine without fields of its own
+ * uses `defineMachine`.
+ *
+ * There are two ways to type the fields.
+ *
+ * @example
+ * **Inferred.** For a few fields, write them inline and let TypeScript infer their types. Add
+ * `as` where the inferred type is wrong: an empty array is `never[]` until it reads
+ * `[] as Hash[]`, and a field holding one of several strings is any `string` until it reads
+ * `"cool" as "cool" | "hot"`.
+ *
+ * ```ts
+ * type TurretEvent = { type: "SPOTTED" } | { type: "LOST" };
+ *
+ * export const turret = definePrivateMachine<{ readonly fireRate: number }, TurretEvent>("turret")({
+ *   privateCtx: () => ({ heat: 0, targets: [] as Hash[] }),
+ *   initial: "/idle",
+ *   states: {
+ *     idle: { on: { SPOTTED: "/firing" } },
+ *     firing: {
+ *       enter: (ctx) => {
+ *         ctx.heat += 1 / ctx.fireRate;
+ *       },
+ *       on: { LOST: "/idle" },
+ *     },
+ *   },
+ * });
+ *
+ * const gun = turret.start({ fireRate: 2 }); // gun.ctx shows fireRate only
+ * ```
+ *
+ * @example
+ * **A named type.** For more fields, or when a helper outside the config needs the whole
+ * context, declare the fields as an interface and make it the factory's return type. The fields
+ * need no `as`, a misspelled or unknown field is a compile error, and the whole context is
+ * `TurretOptions & TurretPrivate`. `satisfies TurretPrivate` does not do this: it checks the
+ * object but keeps its narrow types, so an empty array stays `never[]`.
+ *
+ * ```ts
+ * interface TurretOptions {
+ *   readonly fireRate: number;
+ * }
+ *
+ * interface TurretPrivate {
+ *   heat: number;
+ *   mode: "cool" | "hot";
+ * }
+ *
+ * type TurretEvent = { type: "SPOTTED" } | { type: "LOST" };
+ *
+ * const overheated = (ctx: TurretOptions & TurretPrivate) => ctx.heat > ctx.fireRate;
+ *
+ * export const turret = definePrivateMachine<TurretOptions, TurretEvent>("turret")({
+ *   privateCtx: (): TurretPrivate => ({ heat: 0, mode: "cool" }),
+ *   initial: "/idle",
+ *   states: {
+ *     idle: { on: { SPOTTED: "/firing" } },
+ *     firing: {
+ *       enter: (ctx) => {
+ *         ctx.heat += 1 / ctx.fireRate;
+ *       },
+ *       always: { to: "/cooling", when: overheated },
+ *       on: { LOST: "/idle" },
+ *     },
+ *     cooling: {
+ *       enter: (ctx) => {
+ *         ctx.mode = "hot";
+ *       },
+ *       exit: (ctx) => {
+ *         ctx.heat = 0;
+ *         ctx.mode = "cool";
+ *       },
+ *       after: { 2: "/idle" },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare const definePrivateMachine: <Ctx, E extends EventObject>(key?: string) => <T, Priv extends object>(config: RootState<Ctx & Priv, E, T> & PrivateCtxConfig<Ctx, Priv>) => Machine<Ctx, E, TreePath<T>>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/types",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "description": "TypeScript types for the Defold engine's Lua APIs.",
   "license": "MIT",
   "repository": {