@defold-typescript/types 0.36.0 → 0.38.0

package/generated/versions/defold-1.12.4/sys.d.ts

@@ -294,7 +294,7 @@ declare global {
      * }
      * ```
      */
-    function get_ifaddrs(): { name: string; address: string; mac: string; up: boolean; running: boolean }[];
+    function get_ifaddrs(): { name: string; address?: string; mac?: string; up: boolean; running: boolean }[];
     /**
      * The save-file path is operating system specific and is typically located under the user's home directory.
      * This function will raise a Lua error if unable to get the save file path.
@@ -365,7 +365,7 @@ declare global {
      * }
      * ```
      */
-    function get_sys_info(options?: { ignore_secure?: boolean }): { device_model: string; manufacturer: string; system_name: string; system_version: string; api_version: string; language: string; device_language: string; territory: string; gmt_offset: number; device_ident: string; user_agent: string };
+    function get_sys_info(options?: { ignore_secure?: boolean }): { device_model?: string; manufacturer?: string; system_name: string; system_version: string; api_version: string; language: string; device_language: string; territory: string; gmt_offset: number; device_ident?: string; user_agent?: string };
     /**
      * If the file exists, it must have been created by `sys.save` to be loaded.
      * This function will raise a Lua error if an error occurs while loading the file.

package/generated/versions/defold-1.12.4/window.d.ts

@@ -95,7 +95,7 @@ declare global {
      *
      * - number `inset_bottom`
      */
-    function get_safe_area(): { safe_area: { x: number; y: number; width: number; height: number; inset_left: number; inset_top: number; inset_right: number; inset_bottom: number } };
+    function get_safe_area(): { x: number; y: number; width: number; height: number; inset_left: number; inset_top: number; inset_right: number; inset_bottom: number };
     /**
      * This returns the current window size (width and height).
      */

package/generated/versions/defold-1.13.0/b2d.d.ts

@@ -14,7 +14,7 @@ declare global {
      * @param url - the url to the game object collision component
      * @returns the body if successful. Otherwise `nil`.
      */
-    function get_body(url: string | Hash | Url): Opaque<"b2Body">;
+    function get_body(url: string | Hash | Url): Opaque<"b2Body"> | undefined;
     /**
      * Get the Box2D version information for the active backend.
      *

package/generated/versions/defold-1.13.0/b2d_body.d.ts

@@ -133,10 +133,12 @@ declare global {
      * @example
      * ```ts
      * const body = b2d.get_body("#collisionobject");
-     * const triangle = b2d.body.create_fixture(body, {
-     *   density: 1.0, friction: 0.3,
-     *   shape: { type: b2d.shape.SHAPE_TYPE_POLYGON, vertices: [vmath.vector3(-16, -16, 0), vmath.vector3(16, -16, 0), vmath.vector3(0, 16, 0)] },
-     * });
+     * if (body !== undefined) {
+     *   const triangle = b2d.body.create_fixture(body, {
+     *     density: 1.0, friction: 0.3,
+     *     shape: { type: b2d.shape.SHAPE_TYPE_POLYGON, vertices: [vmath.vector3(-16, -16, 0), vmath.vector3(16, -16, 0), vmath.vector3(0, 16, 0)] },
+     *   });
+     * }
      * ```
      */
     function create_fixture(body: Opaque<"b2Body">, definition: { shape?: { type?: number; radius?: number; center?: Vector3; v0?: Vector3; v1?: Vector3; v2?: Vector3; v3?: Vector3; vertices?: Vector3[]; hx?: number; hy?: number; angle?: number; loop?: boolean; prev_vertex?: Vector3; next_vertex?: Vector3 }; friction?: number; restitution?: number; density?: number; sensor?: boolean; filter?: { category_bits?: number; mask_bits?: number; group_index?: number } }): { index: number; type: number; sensor: boolean; density: number; friction: number; restitution: number; child_count: number };

package/generated/versions/defold-1.13.0/b2d_fixture.d.ts

@@ -134,10 +134,12 @@ declare global {
      * @example
      * ```ts
      * const body = b2d.get_body("#collisionobject");
-     * const circle = b2d.fixture.get_shape(body, 1);
-     * circle.center = vmath.vector3(24, 0, 0);
-     * b2d.fixture.set_shape(body, 1, circle, true);
-     * b2d.fixture.set_shape(body, 2, { type: b2d.shape.SHAPE_TYPE_EDGE, v1: vmath.vector3(-32, 0, 0), v2: vmath.vector3(32, 0, 0) });
+     * if (body !== undefined) {
+     *   const circle = b2d.fixture.get_shape(body, 1);
+     *   circle.center = vmath.vector3(24, 0, 0);
+     *   b2d.fixture.set_shape(body, 1, circle, true);
+     *   b2d.fixture.set_shape(body, 2, { type: b2d.shape.SHAPE_TYPE_EDGE, v1: vmath.vector3(-32, 0, 0), v2: vmath.vector3(32, 0, 0) });
+     * }
      * ```
      */
     function set_shape(body: Opaque<"b2Body">, fixture_index: number, shape: { type?: number; radius?: number; center?: Vector3; v0?: Vector3; v1?: Vector3; v2?: Vector3; v3?: Vector3; vertices?: Vector3[]; hx?: number; hy?: number; angle?: number; loop?: boolean; prev_vertex?: Vector3; next_vertex?: Vector3 }, update_mass?: boolean): void;

package/generated/versions/defold-1.13.0/b2d_shape.d.ts

@@ -202,10 +202,12 @@ declare global {
      * @example
      * ```ts
      * const body = b2d.get_body("#collisionobject");
-     * const circle = b2d.shape.get_shape(body, 1);
-     * circle.center = vmath.vector3(24, 0, 0);
-     * b2d.shape.set_shape(body, 1, circle, true);
-     * b2d.shape.set_shape(body, 2, { type: b2d.shape.SHAPE_TYPE_SEGMENT, v1: vmath.vector3(-32, 0, 0), v2: vmath.vector3(32, 0, 0) });
+     * if (body !== undefined) {
+     *   const circle = b2d.shape.get_shape(body, 1);
+     *   circle.center = vmath.vector3(24, 0, 0);
+     *   b2d.shape.set_shape(body, 1, circle, true);
+     *   b2d.shape.set_shape(body, 2, { type: b2d.shape.SHAPE_TYPE_SEGMENT, v1: vmath.vector3(-32, 0, 0), v2: vmath.vector3(32, 0, 0) });
+     * }
      * ```
      */
     function set_shape(shape_id: Opaque<"b2Shape">, definition: { type?: number; radius?: number; center?: Vector3; v0?: Vector3; v1?: Vector3; v2?: Vector3; v3?: Vector3; vertices?: Vector3[]; hx?: number; hy?: number; angle?: number; loop?: boolean; prev_vertex?: Vector3; next_vertex?: Vector3 }, update_mass: boolean): void;

package/generated/versions/defold-1.13.0/resource.d.ts

@@ -844,7 +844,7 @@ declare global {
      *     // the info table contains meta data about all the render target attachments
      *     // so it's not necessary to use resource.get_texture here, but we do it here
      *     // just to show that it's possible:
-     *     const info_attachment_1 = resource.get_texture_info(info.attachments[0].handle);
+     *     const info_attachment_1 = resource.get_texture_info(info.attachments[0]!.handle);
      *   },
      * });
      *
@@ -852,7 +852,7 @@ declare global {
      * export default defineScript({
      *   init() {
      *     const info = resource.get_render_target_info("/my_render_target.render_targetc");
-     *     const attachment = info.attachments[0].texture;
+     *     const attachment = info.attachments[0]!.texture!;
      *     // you can also get texture info from the 'texture' field, since it's a resource hash
      *     const texture_info = resource.get_texture_info(attachment);
      *     go.set("#model", "texture0", attachment);
@@ -860,7 +860,7 @@ declare global {
      * });
      * ```
      */
-    function get_render_target_info(path: Hash | string | number): { handle: number; width: number; height: number; depth: number; mipmaps: number; type: number; buffer_type: number; texture: Hash };
+    function get_render_target_info(path: Hash | string | number): { handle: number; attachments: { handle: number; width: number; height: number; depth: number; mipmaps: number; type: number; buffer_type: number; texture?: Hash }[] };
     /**
      * Gets the text metrics from a font
      *
@@ -1051,7 +1051,7 @@ declare global {
      * export default defineScript({
      *   init(self) {
      *     const rt_info = resource.get_render_target_info(self.my_render_target);
-     *     go.set("#model", "texture0", rt_info.attachments[0].texture);
+     *     go.set("#model", "texture0", rt_info.attachments[0]!.texture!);
      *   },
      * });
      * ```

package/generated/versions/defold-1.13.0/sys.d.ts

@@ -294,7 +294,7 @@ declare global {
      * }
      * ```
      */
-    function get_ifaddrs(): { name: string; address: string; mac: string; up: boolean; running: boolean }[];
+    function get_ifaddrs(): { name: string; address?: string; mac?: string; up: boolean; running: boolean }[];
     /**
      * The save-file path is operating system specific and is typically located under the user's home directory.
      * This function will raise a Lua error if unable to get the save file path.
@@ -365,7 +365,7 @@ declare global {
      * }
      * ```
      */
-    function get_sys_info(options?: { ignore_secure?: boolean }): { device_model: string; manufacturer: string; system_name: string; system_version: string; api_version: string; language: string; device_language: string; territory: string; gmt_offset: number; device_ident: string; user_agent: string };
+    function get_sys_info(options?: { ignore_secure?: boolean }): { device_model?: string; manufacturer?: string; system_name: string; system_version: string; api_version: string; language: string; device_language: string; territory: string; gmt_offset: number; device_ident?: string; user_agent?: string };
     /**
      * If the file exists, it must have been created by `sys.save` to be loaded.
      * This function will raise a Lua error if an error occurs while loading the file.

package/generated/versions/defold-1.13.0/window.d.ts

@@ -95,7 +95,7 @@ declare global {
      *
      * - number `inset_bottom`
      */
-    function get_safe_area(): { safe_area: { x: number; y: number; width: number; height: number; inset_left: number; inset_top: number; inset_right: number; inset_bottom: number } };
+    function get_safe_area(): { x: number; y: number; width: number; height: number; inset_left: number; inset_top: number; inset_right: number; inset_bottom: number };
     /**
      * This returns the current window size (width and height).
      */

package/generated/window.d.ts

@@ -95,7 +95,7 @@ declare global {
      *
      * - number `inset_bottom`
      */
-    function get_safe_area(): { safe_area: { x: number; y: number; width: number; height: number; inset_left: number; inset_top: number; inset_right: number; inset_bottom: number } };
+    function get_safe_area(): { x: number; y: number; width: number; height: number; inset_left: number; inset_top: number; inset_right: number; inset_bottom: number };
     /**
      * This returns the current window size (width and height).
      */

package/package.json

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

package/src/emit-dts.ts

@@ -245,6 +245,32 @@ export const RETURN_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
   ["editor.tx.add", 'Opaque<"transaction_step">'],
 ]);
 
+// A function whose `returnvalues` declare a concrete type while the same slot's
+// prose documents a `nil` alternative. Distinct from RETURN_TYPE_OVERRIDES
+// above, which fills an *empty* `returnvalues`: these contradict a token
+// upstream explicitly declares, so each entry records it and
+// `return-correction-provenance.test.ts` pins it against every vendored
+// ref-doc. Upstream adding `nil` to `types` hands the case to the top-level
+// `nil` projection in `mapSlotUnion` and reds the entry, which is then deleted
+// rather than re-pinned.
+export interface ReturnTypeCorrection {
+  readonly ts: string;
+  readonly upstream: readonly string[];
+  readonly reason: string;
+}
+
+// Keyed by FQN, mirroring PROPERTY_TYPE_CORRECTIONS.
+export const RETURN_TYPE_CORRECTIONS: ReadonlyMap<string, ReturnTypeCorrection> = new Map([
+  [
+    "b2d.get_body",
+    {
+      ts: 'Opaque<"b2Body"> | undefined',
+      upstream: ["b2Body"],
+      reason: "the body if successful. Otherwise nil.",
+    },
+  ],
+]);
+
 // A property whose upstream `<span class="type">` states a type the engine does
 // not use. Unlike every other override here, which fills a gap upstream left
 // empty, these contradict a token upstream explicitly declares — so each entry
@@ -819,6 +845,38 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
       ],
     },
   ],
+  // resource.get_render_target_info's return `<dl>` writes one key as
+  // `<dt>'attachments'</dt>` — quoted rather than wrapped in `<code>` — so
+  // TABLE_FIELD drops it and parseTableFields hoists the seven per-attachment
+  // fields to the top level, contradicting the `info.attachments[0].handle`
+  // access in the doc's own `@example`. Same shape and same remedy as
+  // font.get_info:return:info above: replace the mis-parsed field list with the
+  // faithful nested isList object. `texture` is documented "only available if
+  // the render target passed in is a resource", hence optional.
+  [
+    "resource.get_render_target_info:return:table",
+    {
+      kind: "object",
+      fields: [
+        { name: "handle", types: ["number"] },
+        {
+          name: "attachments",
+          types: ["table"],
+          isList: true,
+          fields: [
+            { name: "handle", types: ["number"] },
+            { name: "width", types: ["number"] },
+            { name: "height", types: ["number"] },
+            { name: "depth", types: ["number"] },
+            { name: "mipmaps", types: ["number"] },
+            { name: "type", types: ["number"] },
+            { name: "buffer_type", types: ["number"] },
+            { name: "texture", types: ["hash"], optional: true },
+          ],
+        },
+      ],
+    },
+  ],
   // profiler.view_recorded_frame's `frame_index` is a typed `<ul>` "specify one
   // of the following": `distance` and `frame`, both numeric frame offsets. The
   // <li> items carry no `<span class="type">`, so parseTableFields recovers
@@ -1369,6 +1427,95 @@ export const TABLE_FIELD_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
   ["material.get_vertex_attributes:return:table:value", ATTRIBUTE_VALUE_TS],
 ]);
 
+// A return-slot field upstream documents as platform-gated or nil-valued while
+// declaring it like any other. Lua removes a key assigned `nil`, so "might be
+// nil if not available" and "only available on iOS and Android" describe the
+// same runtime state — the key is absent — and the correction is always `?`,
+// never a required field widened to `| undefined`.
+//
+// Separate from TABLE_FIELD_TYPE_OVERRIDES because presence is the other axis:
+// the parser reads these fields' types correctly and stays authoritative for
+// them, so an entry here restates no type and cannot drift when upstream
+// retypes a field. `upstream` is pinned rather than consumed, and `evidence` is
+// the decoded prose `return-correction-provenance.test.ts` searches the slot doc
+// for; both red the entry once upstream marks the field or drops the gate.
+//
+// Keyed `<element>:<kind>:<slot>:<field>`, the TABLE_FIELD_TYPE_OVERRIDES shape.
+export interface ReturnFieldOptionalityCorrection {
+  readonly upstream: readonly string[];
+  readonly evidence: string;
+}
+
+// The platform-gate markers upstream renders as `<span class="icon-*">` decode
+// to `[ios]`, `[android]`, `[html5]` — `user_agent` states its gate through the
+// marker alone, with no availability sentence to pin.
+export const RETURN_FIELD_OPTIONALITY_CORRECTIONS: ReadonlyMap<
+  string,
+  ReturnFieldOptionalityCorrection
+> = new Map([
+  [
+    "sys.get_sys_info:return:sys_info:device_model",
+    { upstream: ["string"], evidence: "[ios][android] Only available on iOS and Android." },
+  ],
+  [
+    "sys.get_sys_info:return:sys_info:manufacturer",
+    { upstream: ["string"], evidence: "[ios][android] Only available on iOS and Android." },
+  ],
+  [
+    "sys.get_sys_info:return:sys_info:device_ident",
+    {
+      upstream: ["string"],
+      evidence: '[ios] "identifierForVendor" on iOS. [android] "android_id" on Android.',
+    },
+  ],
+  [
+    "sys.get_sys_info:return:sys_info:user_agent",
+    { upstream: ["string"], evidence: "[html5] The HTTP user agent" },
+  ],
+  [
+    "sys.get_ifaddrs:return:ifaddrs:address",
+    { upstream: ["string"], evidence: "might be nil if not available." },
+  ],
+  [
+    "sys.get_ifaddrs:return:ifaddrs:mac",
+    { upstream: ["string"], evidence: "might be nil if not available." },
+  ],
+]);
+
+// Mark a parser-recovered field optional from RETURN_FIELD_OPTIONALITY_CORRECTIONS,
+// leaving every other field — and every field's type — untouched. Sets the
+// `optional` flag `TableField` already carries and `inlineTableType` already
+// reads, so no `mapType` is needed and no correction can change a type.
+//
+// A correction keyed to this slot that matches no recovered field throws rather
+// than no-opping: a field upstream renamed would otherwise leave a stale entry
+// looking applied while the emitted declaration silently re-widened.
+// Returns a new array; never mutates the parser's result.
+export function applyFieldOptionalityCorrections(
+  elementName: string,
+  slotKind: "param" | "return" | undefined,
+  slotName: string | undefined,
+  fields: readonly TableField[],
+): TableField[] {
+  if (slotKind === undefined || slotName === undefined) return [...fields];
+  const prefix = `${tableSlotKey(elementName, slotKind, slotName)}:`;
+  const corrected = fields.map((field) =>
+    RETURN_FIELD_OPTIONALITY_CORRECTIONS.has(`${prefix}${field.name}`)
+      ? { ...field, optional: true }
+      : field,
+  );
+  const recovered = new Set(fields.map((field) => field.name));
+  const stale = [...RETURN_FIELD_OPTIONALITY_CORRECTIONS.keys()].filter(
+    (key) => key.startsWith(prefix) && !recovered.has(key.slice(prefix.length)),
+  );
+  if (stale.length > 0) {
+    throw new Error(
+      `field-optionality correction names no recovered field: ${stale.sort().join(", ")}`,
+    );
+  }
+  return corrected;
+}
+
 // Pin a parser-recovered field's TS type from TABLE_FIELD_TYPE_OVERRIDES,
 // leaving every other field parser-authoritative. A field the override does not
 // name is returned unchanged; a field it names gains a `tsType` (emitted
@@ -1605,7 +1752,11 @@ export function buildTableDocResolver(sources: readonly TableDocSource[]): Table
   return (elementName) => docByName.get(elementName);
 }
 
-export function parseTableFields(doc: string, resolver?: TableDocResolver): TableField[] | null {
+export function parseTableFields(
+  doc: string,
+  resolver?: TableDocResolver,
+  slotName?: string,
+): TableField[] | null {
   const fields: TableField[] = [];
   for (const match of doc.matchAll(TABLE_FIELD)) {
     const name = (match[1] ?? "").trim();
@@ -1624,14 +1775,20 @@ export function parseTableFields(doc: string, resolver?: TableDocResolver): Tabl
   }
   // Nested recovery, scoped to the one unambiguous shape: a `<dl>` declaring a
   // single `table`-typed field whose keys sit in an immediately-following
-  // top-level `<ul>` typed-field list (`window.get_safe_area`). Attach the
-  // `<ul>` fields as that field's nested shape so the slot recovers as a nested
-  // object instead of a `Record`.
+  // top-level `<ul>` typed-field list. Attach the `<ul>` fields as that field's
+  // nested shape so the slot recovers as a nested object instead of a `Record`.
+  //
+  // Unless the header restates the slot it describes (`window.get_safe_area`'s
+  // `safe_area` return documented under a `safe_area` header): that is a
+  // restatement, not a nesting level, and wrapping it emits a level the engine
+  // never returns. Only a caller that knows the slot name can tell the two
+  // apart, so the `<ul>` keys are returned directly when they match.
   if (fields.length === 1) {
     const only = fields[0];
     if (only && only.types.length === 1 && only.types[0] === "table") {
       const nested = parseUlFields(doc);
       if (nested.length > 0) {
+        if (slotName !== undefined && slotName === only.name) return nested;
         only.fields = nested;
         return [only];
       }
@@ -2586,6 +2743,10 @@ function emitReturn(
   // slots and leaves the consumer on its token-derived fallback.
   const override = RETURN_TYPE_OVERRIDES.get(elementName);
   if (override !== undefined) return { type: override, trailing: "", slots: [] };
+  // Kept beside the override lookup so the two stay visibly distinct: this one
+  // contradicts a declared token rather than filling an empty `returnvalues`,
+  // and it is a per-slot render, so it reports its slot.
+  const correction = RETURN_TYPE_CORRECTIONS.get(elementName);
   if (returnValues.length === 0) return { type: "void", trailing: "", slots: [] };
   if (returnValues.length > 1) {
     // Defold multi-returns are positional and always present; each slot maps
@@ -2617,6 +2778,13 @@ function emitReturn(
   }
   const first = returnValues[0];
   if (!first) return { type: "void", trailing: "", slots: [] };
+  if (correction !== undefined) {
+    return {
+      type: correction.ts,
+      trailing: "",
+      slots: [{ position: 0, name: first.name, ts: correction.ts }],
+    };
+  }
   const ts =
     first.types.length > 0
       ? mapSlotUnion(
@@ -2727,19 +2895,25 @@ function mapSlotUnion(
         // arbitrary name. Reusing the parser keeps the inner fields in lockstep
         // with the doc instead of a hand-listed drift-prone copy; a documented
         // array-form field is pinned via TABLE_FIELD_TYPE_OVERRIDES.
-        const parsed = applyFieldTypeOverrides(
+        const parsed = applyFieldOptionalityCorrections(
           elementName,
           slotKind,
           slotName,
-          parseTableFields(doc, resolver) ?? [],
+          applyFieldTypeOverrides(
+            elementName,
+            slotKind,
+            slotName,
+            parseTableFields(doc, resolver, slotName) ?? [],
+          ),
         );
         const object = inlineTableType(parsed, mapType, optionalFields);
         ts = `Record<string, ${object}>`;
       } else {
-        const parsed = parseTableFields(doc, resolver);
+        const parsed = parseTableFields(doc, resolver, slotName);
         if (parsed !== null) {
           const nested = applyNestedFieldCurations(elementName, slotKind, slotName, parsed);
-          const fields = applyFieldTypeOverrides(elementName, slotKind, slotName, nested);
+          const typed = applyFieldTypeOverrides(elementName, slotKind, slotName, nested);
+          const fields = applyFieldOptionalityCorrections(elementName, slotKind, slotName, typed);
           const object = inlineTableType(fields, mapType, optionalFields);
           ts = isSlotLevelList(doc) ? `${object}[]` : object;
         } else {

package/src/lifecycle.ts

@@ -571,6 +571,14 @@ export type RenderScriptHooksWithProperties<TProps, TSelf, TInitState> = Omit<
   properties?: TProps;
 };
 
+// The script-local message map an `onMessage` dispatcher carries, lifted onto
+// the factory result so `ScriptMessages<typeof script>` can read it. Matched
+// structurally so this module stays usable through its own `./lifecycle`
+// subpath, where the ambient `MessageDispatcher` is not declared.
+export type ScriptMessageChannel<TMessages> = {
+  on_message?: { readonly __messages?: TMessages };
+};
+
 /**
  * Extract a script module's declared property channel (`TProps`) as a nameable
  * type. A script declares its editor properties with the value-keyed
@@ -617,9 +625,15 @@ export type ScriptPropertiesOf<T extends { properties?: object }> = NonNullable<
  * });
  * ```
  */
-export function defineScript<TProps extends object = Record<never, never>, TInitState = TProps>(
-  hooks: ScriptHooksWithProperties<TProps, TProps & TInitState, TInitState>,
-): ScriptHooksWithProperties<TProps, TProps & TInitState, TInitState> {
+export function defineScript<
+  TProps extends object = Record<never, never>,
+  TInitState = TProps,
+  TMessages extends object = Record<never, never>,
+>(
+  hooks: ScriptHooksWithProperties<TProps, TProps & TInitState, TInitState> &
+    ScriptMessageChannel<TMessages>,
+): ScriptHooksWithProperties<TProps, TProps & TInitState, TInitState> &
+  ScriptMessageChannel<TMessages> {
   return hooks;
 }
 
@@ -652,9 +666,15 @@ export function defineScript<TProps extends object = Record<never, never>, TInit
  * });
  * ```
  */
-export function defineGuiScript<TProps extends object = Record<never, never>, TInitState = TProps>(
-  hooks: GuiScriptHooksWithProperties<TProps, TProps & TInitState, TInitState>,
-): GuiScriptHooksWithProperties<TProps, TProps & TInitState, TInitState> {
+export function defineGuiScript<
+  TProps extends object = Record<never, never>,
+  TInitState = TProps,
+  TMessages extends object = Record<never, never>,
+>(
+  hooks: GuiScriptHooksWithProperties<TProps, TProps & TInitState, TInitState> &
+    ScriptMessageChannel<TMessages>,
+): GuiScriptHooksWithProperties<TProps, TProps & TInitState, TInitState> &
+  ScriptMessageChannel<TMessages> {
   return hooks;
 }
 
@@ -689,8 +709,11 @@ export function defineGuiScript<TProps extends object = Record<never, never>, TI
 export function defineRenderScript<
   TProps extends object = Record<never, never>,
   TInitState = TProps,
+  TMessages extends object = Record<never, never>,
 >(
-  hooks: RenderScriptHooksWithProperties<TProps, TProps & TInitState, TInitState>,
-): RenderScriptHooksWithProperties<TProps, TProps & TInitState, TInitState> {
+  hooks: RenderScriptHooksWithProperties<TProps, TProps & TInitState, TInitState> &
+    ScriptMessageChannel<TMessages>,
+): RenderScriptHooksWithProperties<TProps, TProps & TInitState, TInitState> &
+  ScriptMessageChannel<TMessages> {
   return hooks;
 }

package/src/message-dispatch.d.ts

@@ -3,8 +3,9 @@ import type { Hash, Url } from "./core-types";
 
 declare global {
   // DU-style dispatcher built on `isMessage`'s receive-side narrowing
-  // (message-guard.d.ts): each handler key is a `BuiltinMessageId` and its
-  // `message` param narrows to that id's `BuiltinMessages` payload. It returns
+  // (message-guard.d.ts): each catalog handler key is a `MessageId` and its
+  // `message` param narrows to that id's `MessagePayload`; any other key is a
+  // script-local id declared by its annotated `message`. It returns
   // an `on_message` handler so it reads as `on_message: onMessage<Self>({ ... })`;
   // `self` threads via the explicit type argument, mirroring `defineScript<Self>`.
   // The transpiler lowers the call to a flat `message_id == hash("...")`
@@ -18,7 +19,11 @@ declare global {
    * explicit type argument, mirroring `defineScript<Self>`. The transpiler lowers
    * it to a flat `if/elseif message_id == hash("...")` chain.
    *
-   * @param handlers - a partial map from builtin message id to its handler; each handler's `message` is narrowed to that id's payload.
+   * A key outside the catalogs declares a script-local message when its handler
+   * annotates `message`; the returned dispatcher carries those ids so
+   * {@link ScriptMessages} can hand them to senders.
+   *
+   * @param handlers - a partial map from message id to its handler; a catalog id's `message` is narrowed to that id's payload, and an annotated handler under any other key declares a script-local id.
    * @returns the `on_message` lifecycle handler that dispatches to the matching entry.
    * @example
    * ```ts
@@ -27,18 +32,55 @@ declare global {
    *     contact_point_response(self, message, sender) {
    *       print(message.other_group);
    *     },
+   *     spawn_wave(self, message: { count: number }) {
+   *       print(message.count);
+   *     },
    *   }),
    * });
    * ```
    */
-  function onMessage<TSelf = Record<never, never>>(
-    handlers: Partial<{
-      [K in MessageId]: (self: TSelf, message: MessagePayload<K>, sender: Url) => void;
-    }>,
-  ): (
-    self: TSelf,
-    message_id: Hash,
-    message: Record<string | number, unknown>,
-    sender: Url,
-  ) => void;
+  function onMessage<TSelf = Record<never, never>, H extends object = Record<never, never>>(
+    handlers: H &
+      Partial<{
+        [K in MessageId]: (self: TSelf, message: MessagePayload<K>, sender: Url) => void;
+      }> &
+      OnMessageLocalHandlers<TSelf, H>,
+  ): MessageDispatcher<TSelf, OnMessageLocalMessages<H>>;
+
+  // A key outside `MessageId` is a script-local id only when its handler
+  // annotates `message`; an unannotated one infers no payload and reds as an
+  // implicit `any`, which is the typo guard.
+  type OnMessageHandlerPayload<F> = F extends (
+    self: never,
+    message: infer M,
+    ...rest: never[]
+  ) => unknown
+    ? M
+    : never;
+
+  type OnMessageLocalHandlers<TSelf, H> = {
+    [K in Exclude<keyof H, MessageId>]: (
+      self: TSelf,
+      message: OnMessageHandlerPayload<H[K]>,
+      sender: Url,
+    ) => void;
+  };
+
+  // A numeric key is sent under its JavaScript property key (`1e3` is "1000"),
+  // the id the transpiler hashes.
+  type OnMessageLocalMessages<H> = {
+    [K in Exclude<keyof H, MessageId> as K extends number ? `${K}` : K]: OnMessageHandlerPayload<
+      H[K]
+    >;
+  };
+
+  /**
+   * The `on_message` handler {@link onMessage} returns. `__messages` is a
+   * type-only record of the script-local ids its handlers declared; it never
+   * exists at runtime.
+   */
+  interface MessageDispatcher<TSelf, TLocal = Record<never, never>> {
+    (self: TSelf, message_id: Hash, message: Record<string | number, unknown>, sender: Url): void;
+    readonly __messages?: TLocal;
+  }
 }