@defold-typescript/types 0.37.0 → 0.39.0

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;
+  }
 }

package/src/msg-overloads.d.ts

@@ -2,6 +2,44 @@
 import type { Hash, Url } from "./core-types";
 
 declare global {
+  /**
+   * A `Url` that also names the messages its receiver declares. `__receives` is
+   * type-only and never exists at runtime; the value is an ordinary `Url`.
+   */
+  type ReceiverUrl<M> = Url & { readonly __receives?: M };
+
+  /**
+   * The script-local messages a script declares by handling them: each
+   * annotated `onMessage` handler key outside the built-in and `CustomMessages`
+   * catalogs, mapped to its payload. Read it off the script module's default
+   * export and pass it to `msg.url<M>` to get a receiver-typed address.
+   *
+   * @example
+   * ```ts
+   * type WaveMessages = ScriptMessages<typeof import("./wave").default>;
+   * ```
+   */
+  type ScriptMessages<T> = T extends { on_message?: infer D }
+    ? NonNullable<D> extends { readonly __messages?: infer L }
+      ? L extends object
+        ? L
+        : Record<never, never>
+      : Record<never, never>
+    : Record<never, never>;
+
+  /**
+   * The messages a `msg.post` receiver declares: the `M` of a
+   * {@link ReceiverUrl}, or the handled messages of the script a scene address
+   * names in `SceneComponentAddresses`. Empty for every other receiver.
+   */
+  type ReceiverMessages<R> = R extends { readonly __receives?: infer M }
+    ? M extends object
+      ? M
+      : Record<never, never>
+    : R extends keyof SceneComponentAddresses
+      ? ScriptMessages<SceneComponentAddresses[R]>
+      : Record<never, never>;
+
   namespace msg {
     /**
      * Post a message to a receiving URL. The most common case is to send messages
@@ -25,11 +63,31 @@ declare global {
      *   position: go.get_world_position(),
      * });
      * ```
+     *
+     * @remarks
+     * The `(string & {})` term keeps every declared message id as a completion
+     * while still accepting any other string, so no existing call is rejected.
+     *
+     * A receiver from `msg.url<M>` also offers and checks the ids in `M`, and a
+     * scene address whose generated value is a script module offers and checks
+     * that script's handled messages. A built-in id keeps its built-in payload,
+     * and any other id stays open.
+     *
+     * Both receiver routes live in this one signature on purpose: a separate,
+     * stricter overload ahead of it would let a mismatched payload fall through
+     * to the open one and compile anyway.
      */
-    function post<K extends string>(
-      receiver: SceneAddress | Url | Hash,
+    function post<
+      R extends SceneAddress | Hash | Url,
+      K extends (keyof ReceiverMessages<R> & string) | MessageId | (string & {}),
+    >(
+      receiver: R,
       message_id: K,
-      message?: MessagePayload<K>,
+      message?: K extends BuiltinMessageId
+        ? MessagePayload<K>
+        : K extends keyof ReceiverMessages<R>
+          ? ReceiverMessages<R>[K]
+          : MessagePayload<K>,
     ): void;
     function post(
       receiver: SceneAddress | Url | Hash,
@@ -60,6 +118,11 @@ declare global {
      * component (`msg.url("#main")`). The `socket:` prefix only crosses
      * into a collection-proxy-loaded world.
      *
+     * Pass the receiver's message map as `M` (for example
+     * `msg.url<ScriptMessages<typeof import("./wave").default>>("/logic#wave")`)
+     * to get a receiver-typed address: `msg.post` then completes and checks
+     * those ids. The value is still an ordinary `Url`.
+     *
      * @example
      * ```ts
      * // No-arg, then take the current game object's URL.
@@ -91,5 +154,12 @@ declare global {
       path: string | Hash,
       fragment: string | Hash,
     ): Url;
+    function url<M extends object>(): ReceiverUrl<M>;
+    function url<M extends object>(urlstring: SceneAddress | undefined): ReceiverUrl<M>;
+    function url<M extends object>(
+      socket: string | Hash | undefined,
+      path: string | Hash,
+      fragment: string | Hash,
+    ): ReceiverUrl<M>;
   }
 }

package/src/render-overloads.d.ts

@@ -4,23 +4,6 @@ import type { Opaque } from "./core-types";
 
 declare global {
   namespace render {
-    /**
-     * The buffer keys `render.clear` accepts: the three `graphics.BUFFER_TYPE_*`
-     * constants the reference names. Declare the clear table with this alias —
-     * `LuaMap`'s iterator makes its key parameter invariant, so a
-     * `LuaMap<number, ...>` is not assignable however its entries were set.
-     *
-     * @example
-     * ```ts
-     * const buffers = new LuaMap<render.ClearBufferKey, number | Vector4>();
-     * buffers.set(graphics.BUFFER_TYPE_COLOR0_BIT, vmath.vector4(0, 0, 0, 0));
-     * render.clear(buffers);
-     * ```
-     */
-    type ClearBufferKey =
-      | typeof graphics.BUFFER_TYPE_COLOR0_BIT
-      | typeof graphics.BUFFER_TYPE_DEPTH_BIT
-      | typeof graphics.BUFFER_TYPE_STENCIL_BIT;
     /**
      * Creates a new render target according to the supplied specification table.
      * The parameter table is keyed by buffer type, with one parameter table per