@defold-typescript/types 0.30.0 → 0.32.0

package/api-signatures.json

@@ -349,14 +349,14 @@
       "camera\u0000FUNCTION\u0000camera.set_orthographic_mode\u0000[{\"types\":[\"nil\",\"number\",\"url\"],\"isOptional\":false},{\"types\":[\"number\"],\"isOptional\":false}]->[]": "function set_orthographic_mode(camera: Url | number | undefined, mode: number): void;",
       "camera\u0000FUNCTION\u0000camera.set_orthographic_zoom\u0000[{\"types\":[\"nil\",\"number\",\"url\"],\"isOptional\":false},{\"types\":[\"number\"],\"isOptional\":false}]->[]": "function set_orthographic_zoom(camera: Url | number | undefined, orthographic_zoom: number): void;",
       "camera\u0000FUNCTION\u0000camera.world_to_screen\u0000[{\"types\":[\"vector3\"],\"isOptional\":false},{\"types\":[\"nil\",\"number\",\"url\"],\"isOptional\":true}]->[{\"types\":[\"vector3\"],\"isOptional\":false}]": "function world_to_screen(world_pos: Vector3, camera?: Url | number): Vector3;",
-      "camera\u0000PROPERTY\u0000aspect_ratio\u0000": "aspect_ratio: unknown;",
-      "camera\u0000PROPERTY\u0000far_z\u0000": "far_z: unknown;",
-      "camera\u0000PROPERTY\u0000fov\u0000": "fov: unknown;",
-      "camera\u0000PROPERTY\u0000near_z\u0000": "near_z: unknown;",
-      "camera\u0000PROPERTY\u0000orthographic_auto_zoom\u0000": "orthographic_auto_zoom: unknown;",
-      "camera\u0000PROPERTY\u0000orthographic_zoom\u0000": "orthographic_zoom: unknown;",
-      "camera\u0000PROPERTY\u0000projection\u0000": "projection: unknown;",
-      "camera\u0000PROPERTY\u0000view\u0000": "view: unknown;",
+      "camera\u0000PROPERTY\u0000aspect_ratio\u0000": "aspect_ratio: number;",
+      "camera\u0000PROPERTY\u0000far_z\u0000": "far_z: number;",
+      "camera\u0000PROPERTY\u0000fov\u0000": "fov: number;",
+      "camera\u0000PROPERTY\u0000near_z\u0000": "near_z: number;",
+      "camera\u0000PROPERTY\u0000orthographic_auto_zoom\u0000": "orthographic_auto_zoom: number;",
+      "camera\u0000PROPERTY\u0000orthographic_zoom\u0000": "orthographic_zoom: number;",
+      "camera\u0000PROPERTY\u0000projection\u0000": "projection: Matrix4;",
+      "camera\u0000PROPERTY\u0000view\u0000": "view: Matrix4;",
       "collectionfactory\u0000CONSTANT\u0000collectionfactory.STATUS_LOADED\u0000": "const STATUS_LOADED: number & { readonly __brand: \"collectionfactory.STATUS_LOADED\" };",
       "collectionfactory\u0000CONSTANT\u0000collectionfactory.STATUS_LOADING\u0000": "const STATUS_LOADING: number & { readonly __brand: \"collectionfactory.STATUS_LOADING\" };",
       "collectionfactory\u0000CONSTANT\u0000collectionfactory.STATUS_UNLOADED\u0000": "const STATUS_UNLOADED: number & { readonly __brand: \"collectionfactory.STATUS_UNLOADED\" };",
@@ -1168,7 +1168,7 @@
       "sprite\u0000FUNCTION\u0000sprite.set_vflip\u0000[{\"types\":[\"hash\",\"string\",\"url\"],\"isOptional\":false},{\"types\":[\"boolean\"],\"isOptional\":false}]->[]": "function set_vflip(url: string | Hash | Url, flip: boolean): void;",
       "sprite\u0000PROPERTY\u0000animation\u0000": "animation: Hash;",
       "sprite\u0000PROPERTY\u0000cursor\u0000": "cursor: number;",
-      "sprite\u0000PROPERTY\u0000frame_count\u0000": "frame_count: Hash;",
+      "sprite\u0000PROPERTY\u0000frame_count\u0000": "frame_count: number;",
       "sprite\u0000PROPERTY\u0000image\u0000": "image: Hash;",
       "sprite\u0000PROPERTY\u0000material\u0000": "material: Hash;",
       "sprite\u0000PROPERTY\u0000playback_rate\u0000": "playback_rate: number;",
@@ -1661,14 +1661,14 @@
       "camera\u0000FUNCTION\u0000camera.set_orthographic_mode\u0000[{\"types\":[\"nil\",\"number\",\"url\"],\"isOptional\":false},{\"types\":[\"number\"],\"isOptional\":false}]->[]": "function set_orthographic_mode(camera: Url | number | undefined, mode: number): void;",
       "camera\u0000FUNCTION\u0000camera.set_orthographic_zoom\u0000[{\"types\":[\"nil\",\"number\",\"url\"],\"isOptional\":false},{\"types\":[\"number\"],\"isOptional\":false}]->[]": "function set_orthographic_zoom(camera: Url | number | undefined, orthographic_zoom: number): void;",
       "camera\u0000FUNCTION\u0000camera.world_to_screen\u0000[{\"types\":[\"vector3\"],\"isOptional\":false},{\"types\":[\"nil\",\"number\",\"url\"],\"isOptional\":true}]->[{\"types\":[\"vector3\"],\"isOptional\":false}]": "function world_to_screen(world_pos: Vector3, camera?: Url | number): Vector3;",
-      "camera\u0000PROPERTY\u0000aspect_ratio\u0000": "aspect_ratio: unknown;",
-      "camera\u0000PROPERTY\u0000far_z\u0000": "far_z: unknown;",
-      "camera\u0000PROPERTY\u0000fov\u0000": "fov: unknown;",
-      "camera\u0000PROPERTY\u0000near_z\u0000": "near_z: unknown;",
-      "camera\u0000PROPERTY\u0000orthographic_auto_zoom\u0000": "orthographic_auto_zoom: unknown;",
-      "camera\u0000PROPERTY\u0000orthographic_zoom\u0000": "orthographic_zoom: unknown;",
-      "camera\u0000PROPERTY\u0000projection\u0000": "projection: unknown;",
-      "camera\u0000PROPERTY\u0000view\u0000": "view: unknown;",
+      "camera\u0000PROPERTY\u0000aspect_ratio\u0000": "aspect_ratio: number;",
+      "camera\u0000PROPERTY\u0000far_z\u0000": "far_z: number;",
+      "camera\u0000PROPERTY\u0000fov\u0000": "fov: number;",
+      "camera\u0000PROPERTY\u0000near_z\u0000": "near_z: number;",
+      "camera\u0000PROPERTY\u0000orthographic_auto_zoom\u0000": "orthographic_auto_zoom: number;",
+      "camera\u0000PROPERTY\u0000orthographic_zoom\u0000": "orthographic_zoom: number;",
+      "camera\u0000PROPERTY\u0000projection\u0000": "projection: Matrix4;",
+      "camera\u0000PROPERTY\u0000view\u0000": "view: Matrix4;",
       "collectionfactory\u0000CONSTANT\u0000collectionfactory.STATUS_LOADED\u0000": "const STATUS_LOADED: number & { readonly __brand: \"collectionfactory.STATUS_LOADED\" };",
       "collectionfactory\u0000CONSTANT\u0000collectionfactory.STATUS_LOADING\u0000": "const STATUS_LOADING: number & { readonly __brand: \"collectionfactory.STATUS_LOADING\" };",
       "collectionfactory\u0000CONSTANT\u0000collectionfactory.STATUS_UNLOADED\u0000": "const STATUS_UNLOADED: number & { readonly __brand: \"collectionfactory.STATUS_UNLOADED\" };",
@@ -2479,7 +2479,7 @@
       "sprite\u0000FUNCTION\u0000sprite.set_vflip\u0000[{\"types\":[\"hash\",\"string\",\"url\"],\"isOptional\":false},{\"types\":[\"boolean\"],\"isOptional\":false}]->[]": "function set_vflip(url: string | Hash | Url, flip: boolean): void;",
       "sprite\u0000PROPERTY\u0000animation\u0000": "animation: Hash;",
       "sprite\u0000PROPERTY\u0000cursor\u0000": "cursor: number;",
-      "sprite\u0000PROPERTY\u0000frame_count\u0000": "frame_count: Hash;",
+      "sprite\u0000PROPERTY\u0000frame_count\u0000": "frame_count: number;",
       "sprite\u0000PROPERTY\u0000image\u0000": "image: Hash;",
       "sprite\u0000PROPERTY\u0000material\u0000": "material: Hash;",
       "sprite\u0000PROPERTY\u0000playback_rate\u0000": "playback_rate: number;",
@@ -3489,7 +3489,7 @@
       "sprite\u0000FUNCTION\u0000sprite.set_vflip\u0000[{\"types\":[\"hash\",\"string\",\"url\"],\"isOptional\":false},{\"types\":[\"boolean\"],\"isOptional\":false}]->[]": "function set_vflip(url: string | Hash | Url, flip: boolean): void;",
       "sprite\u0000PROPERTY\u0000animation\u0000": "animation: Hash;",
       "sprite\u0000PROPERTY\u0000cursor\u0000": "cursor: number;",
-      "sprite\u0000PROPERTY\u0000frame_count\u0000": "frame_count: Hash;",
+      "sprite\u0000PROPERTY\u0000frame_count\u0000": "frame_count: number;",
       "sprite\u0000PROPERTY\u0000image\u0000": "image: Hash;",
       "sprite\u0000PROPERTY\u0000material\u0000": "material: Hash;",
       "sprite\u0000PROPERTY\u0000playback_rate\u0000": "playback_rate: number;",

package/generated/camera.d.ts

@@ -257,44 +257,44 @@ declare global {
        * projection of a perspective camera.
        * The type of the property is number.
        */
-      aspect_ratio: unknown;
+      aspect_ratio: number;
       /**
        * Camera frustum far plane.
        * The type of the property is float.
        */
-      far_z: unknown;
+      far_z: number;
       /**
        * Vertical field of view of the camera.
        * The type of the property is float.
        */
-      fov: unknown;
+      fov: number;
       /**
        * Camera frustum near plane.
        * The type of the property is float.
        */
-      near_z: unknown;
+      near_z: number;
       /**
        * READ ONLY The zoom calculated from the current window and project dimensions
        * in auto fit and auto cover modes. The value is 1.0 in fixed mode.
        * The type of the property is float.
        */
-      orthographic_auto_zoom: unknown;
+      orthographic_auto_zoom: number;
       /**
        * Positive zoom multiplier when using an orthographic projection. In auto fit and auto cover
        * modes, this value is multiplied with the calculated orthographic_auto_zoom value.
        * The type of the property is float.
        */
-      orthographic_zoom: unknown;
+      orthographic_zoom: number;
       /**
        * READ ONLY The calculated projection matrix of the camera.
        * The type of the property is matrix4.
        */
-      projection: unknown;
+      projection: Matrix4;
       /**
        * READ ONLY The calculated view matrix of the camera.
        * The type of the property is matrix4.
        */
-      view: unknown;
+      view: Matrix4;
     }
   }
 }

package/generated/kinds/gui-script.d.ts

@@ -44,6 +44,7 @@ import "../vmath";
 import "../webview";
 import "../window";
 import "../zlib";
+import "../../src/custom-messages";
 import "../../src/engine-globals";
 import "../../src/go-overloads";
 import "../../src/message-guard";

package/generated/kinds/render-script.d.ts

@@ -44,6 +44,7 @@ import "../vmath";
 import "../webview";
 import "../window";
 import "../zlib";
+import "../../src/custom-messages";
 import "../../src/engine-globals";
 import "../../src/go-overloads";
 import "../../src/message-guard";

package/generated/kinds/script.d.ts

@@ -44,6 +44,7 @@ import "../vmath";
 import "../webview";
 import "../window";
 import "../zlib";
+import "../../src/custom-messages";
 import "../../src/engine-globals";
 import "../../src/go-overloads";
 import "../../src/message-guard";

package/generated/sprite.d.ts

@@ -120,7 +120,7 @@ declare global {
       /**
        * READ ONLY The frame count of the currently playing animation.
        */
-      frame_count: Hash;
+      frame_count: number;
       /**
        * The image used when rendering the sprite. The type of the property is hash.
        */

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

@@ -106,7 +106,7 @@ declare global {
       /**
        * READ ONLY The frame count of the currently playing animation.
        */
-      frame_count: Hash;
+      frame_count: number;
       /**
        * The image used when rendering the sprite. The type of the property is hash.
        */

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

@@ -257,44 +257,44 @@ declare global {
        * projection of a perspective camera.
        * The type of the property is number.
        */
-      aspect_ratio: unknown;
+      aspect_ratio: number;
       /**
        * Camera frustum far plane.
        * The type of the property is float.
        */
-      far_z: unknown;
+      far_z: number;
       /**
        * Vertical field of view of the camera.
        * The type of the property is float.
        */
-      fov: unknown;
+      fov: number;
       /**
        * Camera frustum near plane.
        * The type of the property is float.
        */
-      near_z: unknown;
+      near_z: number;
       /**
        * READ ONLY The zoom calculated from the current window and project dimensions
        * in auto fit and auto cover modes. The value is 1.0 in fixed mode.
        * The type of the property is float.
        */
-      orthographic_auto_zoom: unknown;
+      orthographic_auto_zoom: number;
       /**
        * Positive zoom multiplier when using an orthographic projection. In auto fit and auto cover
        * modes, this value is multiplied with the calculated orthographic_auto_zoom value.
        * The type of the property is float.
        */
-      orthographic_zoom: unknown;
+      orthographic_zoom: number;
       /**
        * READ ONLY The calculated projection matrix of the camera.
        * The type of the property is matrix4.
        */
-      projection: unknown;
+      projection: Matrix4;
       /**
        * READ ONLY The calculated view matrix of the camera.
        * The type of the property is matrix4.
        */
-      view: unknown;
+      view: Matrix4;
     }
   }
 }

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

@@ -120,7 +120,7 @@ declare global {
       /**
        * READ ONLY The frame count of the currently playing animation.
        */
-      frame_count: Hash;
+      frame_count: number;
       /**
        * The image used when rendering the sprite. The type of the property is hash.
        */

package/index.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="lua-types/5.1" />
 /// <reference types="lua-types/special/jit-only" />
 import "./generated/builtin-messages";
+import "./src/custom-messages";
 import "./src/msg-overloads";
 import "./src/message-guard";
 import "./src/window-event-guard";

package/package.json

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

package/scripts/regen.ts

@@ -546,6 +546,7 @@ export function kindStdlibReferences(entry: KindManifestEntry): string {
 
 const UNIVERSAL_EXTRA_IMPORTS: readonly string[] = [
   "../builtin-messages",
+  "../../src/custom-messages",
   "../../src/engine-globals",
   "../../src/msg-overloads",
   "../../src/message-guard",

package/src/core-types.ts

@@ -152,8 +152,7 @@ declare const OpaqueBrand: unique symbol;
  * The handle kinds modeled today:
  * - GUI & rendering: `Opaque<"node">`, `Opaque<"texture">`,
  *   `Opaque<"render_target">`, `Opaque<"constant">`, `Opaque<"constant_buffer">`
- * - Resources & buffers: `Opaque<"resource">`, `Opaque<"buffer">`,
- *   `Opaque<"bufferstream">`
+ * - Buffers: `Opaque<"buffer">`, `Opaque<"bufferstream">`
  * - Sockets: `Opaque<"client">`, `Opaque<"server">`, `Opaque<"master">`,
  *   `Opaque<"connected">`, `Opaque<"unconnected">`
  * - Box2D physics: `Opaque<"b2Body">`, `Opaque<"b2World">`
@@ -193,6 +192,7 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   number: "number",
   int: "number",
   integer: "number",
+  float: "number",
   string: "string",
   boolean: "boolean",
   table: "Record<string | number, unknown>",
@@ -218,6 +218,9 @@ export const DEFOLD_TYPE_MAP: Readonly<Record<string, string>> = {
   buffer: 'Opaque<"buffer">',
   bufferstream: 'Opaque<"bufferstream"> & { [index: number]: number }',
   userdata: 'Opaque<"userdata">',
+  // Vocabulary, not a shipped brand: no current ref-doc fixture types a slot
+  // `resource`, so nothing hand-written may name `Opaque<"resource">`. Kept so a
+  // future upstream slot carrying the token emits a handle rather than `unknown`.
   resource: 'Opaque<"resource">',
   b2World: 'Opaque<"b2World">',
   b2Body: 'Opaque<"b2Body">',

package/src/custom-messages.d.ts

@@ -0,0 +1,54 @@
+/** @noSelfInFile */
+
+declare global {
+  /**
+   * A project's own message ids, mapped to the payload each carries. Empty as
+   * shipped and extended by declaration merging in your own code:
+   *
+   * ```ts
+   * declare global {
+   *   interface CustomMessages {
+   *     spawn_wave: { count: number; boss?: boolean };
+   *   }
+   * }
+   *
+   * export {};
+   * ```
+   *
+   * The `export {};` makes the file a module, which `declare global` requires;
+   * drop it only in a file that already imports or exports something.
+   *
+   * Once declared, an id is checked on `msg.post` and narrowed by `isMessage`
+   * and `onMessage` exactly like a built-in one. Augment this interface rather
+   * than `BuiltinMessages`, which is regenerated from the Defold reference docs
+   * and reserved for the ids the engine itself defines.
+   */
+  interface CustomMessages {}
+
+  /**
+   * Every message id with a declared payload: the engine's, plus your own.
+   *
+   * The custom half is intersected with `string` because a numeric key is one
+   * the lowering cannot emit — `onMessage`'s handler names become `hash(...)`
+   * comparisons, and only an identifier or a string literal survives that — so
+   * offering it would type-check a handler that silently never runs.
+   */
+  type MessageId = BuiltinMessageId | (keyof CustomMessages & string);
+
+  // A built-in id is tested first, so a `CustomMessages` key shadowing one is
+  // inert rather than silently re-typing an engine message. Resolving to the
+  // intersection instead would yield an unsatisfiable payload and point the
+  // diagnostic at the call site rather than the declaration.
+  /**
+   * The payload declared for a message id: its `BuiltinMessages` entry, else
+   * its `CustomMessages` entry, else the open record an undeclared id keeps.
+   * An id declared in both resolves to the built-in payload.
+   */
+  type MessagePayload<K> = K extends BuiltinMessageId
+    ? BuiltinMessages[K]
+    : K extends keyof CustomMessages
+      ? CustomMessages[K]
+      : Record<string | number, unknown>;
+}
+
+export {};

package/src/emit-dts.ts

@@ -240,6 +240,54 @@ export const RETURN_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
   ["editor.tx.add", 'Opaque<"transaction_step">'],
 ]);
 
+// 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
+// records that token and `property-correction-provenance.test.ts` pins it
+// against every vendored ref-doc. The day upstream corrects a span the suite
+// reds and the entry is deleted rather than silently overriding a value that
+// had since become right.
+//
+// Demonstrated errors only. A property whose declared type is merely imprecise
+// — every `resource.*` path hash, say — is not a correction candidate.
+export interface PropertyTypeCorrection {
+  readonly ts: string;
+  readonly upstream: string;
+  readonly reason: string;
+}
+
+// Keyed `<namespace>.<property>`, so a same-named property in another catalog
+// is untouched.
+export const PROPERTY_TYPE_CORRECTIONS: ReadonlyMap<string, PropertyTypeCorrection> = new Map([
+  [
+    "sprite.frame_count",
+    {
+      ts: "number",
+      upstream: "hash",
+      reason:
+        "a count of animation frames, which the prose confirms; `hash` is a copy-paste of the sibling animation-id spans",
+    },
+  ],
+  [
+    "camera.projection",
+    {
+      ts: "Matrix4",
+      upstream: "float",
+      reason:
+        "the prose in the same element says matrix4; every camera property carries the same blanket `float` span",
+    },
+  ],
+  [
+    "camera.view",
+    {
+      ts: "Matrix4",
+      upstream: "float",
+      reason:
+        "the prose in the same element says matrix4; every camera property carries the same blanket `float` span",
+    },
+  ],
+]);
+
 // FQN-keyed allowlist of the `types.is_*` checks that genuinely narrow their
 // argument, mapped to the `DEFOLD_TYPE_MAP` token whose interface they prove.
 // Emitting these as user-defined type guards (`var_ is Vector3`) is the only way
@@ -1641,7 +1689,7 @@ export function emitDeclarations(module: ApiModule, options?: EmitOptions): stri
       for (const docLine of summaryDocLines(p.brief, p.description, `${INDENT}${INDENT}`)) {
         lines.push(docLine);
       }
-      lines.push(`${INDENT}${INDENT}${emitPropertyMember(p, mapType)}`);
+      lines.push(`${INDENT}${INDENT}${emitPropertyMember(p, mapType, module.namespace)}`);
     }
     lines.push(`${INDENT}}`);
   }
@@ -1759,7 +1807,7 @@ export function emitSymbolSignatures(module: ApiModule, options?: EmitOptions):
   for (const p of module.properties) {
     out.push({
       identity: { namespace: module.namespace, kind: "PROPERTY", name: p.name, signature: "" },
-      tsSignature: emitPropertyMember(p, mapType),
+      tsSignature: emitPropertyMember(p, mapType, module.namespace),
     });
   }
 
@@ -2224,9 +2272,19 @@ function emitReturn(
   return { type: ts, trailing: "" };
 }
 
-function emitPropertyMember(p: ApiProperty, mapType: (t: string) => string): string {
+function emitPropertyMember(
+  p: ApiProperty,
+  mapType: (t: string) => string,
+  namespace: string,
+): string {
   const key = TS_IDENTIFIER.test(p.name) ? p.name : JSON.stringify(p.name);
-  const ts = p.types.length > 0 ? unionFromTokens(p.types, mapType) : "unknown";
+  const correction = PROPERTY_TYPE_CORRECTIONS.get(`${namespace}.${p.name}`);
+  const ts =
+    correction !== undefined
+      ? correction.ts
+      : p.types.length > 0
+        ? unionFromTokens(p.types, mapType)
+        : "unknown";
   return `${key}: ${ts};`;
 }
 

package/src/engine-globals.d.ts

@@ -26,9 +26,9 @@ declare global {
    * that lives only in the type system and is erased at transpile; because the
    * symbol is not exported, consumer code cannot fabricate one. The kinds
    * modeled: `node`, `texture`, `render_target`, `constant`, `constant_buffer`,
-   * `resource`, `buffer`, `bufferstream`, `client`, `server`, `master`,
-   * `connected`, `unconnected`, `b2Body`, `b2World`, `userdata`. You obtain them
-   * from the engine, e.g. `gui.get_node("id")`, `render.render_target(...)`,
+   * `buffer`, `bufferstream`, `client`, `server`, `master`, `connected`,
+   * `unconnected`, `b2Body`, `b2World`, `userdata`. You obtain them from the
+   * engine, e.g. `gui.get_node("id")`, `render.render_target(...)`,
    * `render.constant_buffer()`, `resource.load_buffer(path)`, `b2d.get_world()`,
    * or `socket.tcp()`. See {@link Core.Opaque} for the full explanation, the per
    * -kind obtain examples, and the contrast with a `LuaTable` alias.

package/src/go-overloads.d.ts

@@ -1,6 +1,6 @@
 /** @noSelfInFile */
 
-import type { Hash, Opaque, Quaternion, Url, Vector3, Vector4 } from "./core-types";
+import type { Hash, Quaternion, Url, Vector3, Vector4 } from "./core-types";
 
 interface ScriptProperty<TValue> {
   readonly __defoldScriptProperty: TValue;
@@ -46,7 +46,7 @@ declare global {
       url: SceneAddress | Hash | Url,
       property: string | Hash,
       options?: GoPropertyOptions,
-    ): number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource">;
+    ): number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion;
     /**
      * sets a named property of the specified game object or component, or a material constant
      *
@@ -80,7 +80,7 @@ declare global {
     function set(
       url: SceneAddress | Hash | Url,
       property: string | Hash,
-      value: number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource">,
+      value: number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion,
       options?: GoPropertyOptions,
     ): void;
     /**
@@ -119,7 +119,5 @@ declare global {
     function property(name: string, value: Vector4): ScriptProperty<Vector4>;
     /** @deprecated Declare quaternions via the `defineScript({ properties })` field. */
     function property(name: string, value: Quaternion): ScriptProperty<Quaternion>;
-    /** @deprecated Declare resources via the `defineScript({ properties })` field. */
-    function property(name: string, value: Opaque<"resource">): ScriptProperty<Opaque<"resource">>;
   }
 }

package/src/index.ts

@@ -100,6 +100,8 @@ export {
   collectUrlParameterSlots,
   parameterTypesSatisfyClass,
   REQUIRED_TYPES,
+  type SocketScope,
+  slotAcceptsForeignSocket,
   type UrlParameterClass,
   type UrlParameterEntry,
   type UrlParameterSlot,

package/src/message-dispatch.d.ts

@@ -33,7 +33,7 @@ declare global {
    */
   function onMessage<TSelf = Record<never, never>>(
     handlers: Partial<{
-      [K in BuiltinMessageId]: (self: TSelf, message: BuiltinMessages[K], sender: Url) => void;
+      [K in MessageId]: (self: TSelf, message: MessagePayload<K>, sender: Url) => void;
     }>,
   ): (
     self: TSelf,

package/src/message-guard.d.ts

@@ -27,9 +27,9 @@ declare global {
    * }
    * ```
    */
-  function isMessage<K extends BuiltinMessageId>(
+  function isMessage<K extends MessageId>(
     message_id: Hash,
     message: Record<string | number, unknown>,
     expected: K,
-  ): message is BuiltinMessages[K];
+  ): message is MessagePayload<K>;
 }

package/src/msg-overloads.d.ts

@@ -1,10 +1,6 @@
 /** @noSelfInFile */
 import type { Hash, Url } from "./core-types";
 
-type MsgPostPayload<K> = K extends BuiltinMessageId
-  ? BuiltinMessages[K]
-  : Record<string | number, unknown>;
-
 declare global {
   namespace msg {
     /**
@@ -33,7 +29,7 @@ declare global {
     function post<K extends string>(
       receiver: SceneAddress | Url | Hash,
       message_id: K,
-      message?: MsgPostPayload<K>,
+      message?: MessagePayload<K>,
     ): void;
     function post(
       receiver: SceneAddress | Url | Hash,

package/src/url-parameters.ts

@@ -6,8 +6,10 @@ import type { ApiModule } from "./api-doc";
 // naming a mesh inside the model asset), so a slot is classified only
 // deliberately. The first three address the scene graph; `gui-node` names a node
 // inside the one `.gui` that owns the script, which is not an address at all;
-// `animation` names a block inside the atlas of a component a *sibling*
-// argument addresses, which is why it is the one class needing a companion;
+// `animation` names a block inside an atlas reached through a *companion*
+// parameter of the same call — the sibling literal addressing a sprite
+// component, or the gui node whose scene declares its textures — which is why
+// it is the one class needing a companion;
 // `resource-path` names a project file outright, so it is scoped by the
 // extensions its entry declares rather than by anything in the scene graph;
 // `config-key` names a `<section>.<key>` entry in the project's own
@@ -28,6 +30,13 @@ export type UrlParameterClass =
   | "config-key"
   | "action-id";
 
+// Whether an address slot resolves its literal through the message bus, which
+// crosses collection-proxy worlds, or through an instance/component handle,
+// which does not. `msg.post("mylevel:/hero#script", ...)` is the documented
+// proxy idiom; `go.get_position("mylevel:/hero")` fails in the engine's
+// instance resolution.
+export type SocketScope = "same-world" | "cross-world";
+
 export interface UrlParameterEntry {
   fqn: string;
   parameter: string;
@@ -38,6 +47,12 @@ export interface UrlParameterEntry {
   // shape would fan the table's one interface out into a union for a single
   // optional field.
   addressParameter?: string;
+  // The alternative to `addressParameter`: the parameter naming the gui node
+  // this call animates, which scopes the candidates to the `.gui` scene owning
+  // the script rather than to a component a sibling literal addresses. An
+  // `animation` entry declares exactly one of the two, enforced by the same
+  // drift guard and for the same reason.
+  nodeParameter?: string;
   // The file extensions this slot's literal may name, each written with its
   // leading dot. Required for `resource-path` and absent otherwise — enforced by
   // the drift guard for the same reason `addressParameter` is. Recorded per
@@ -51,6 +66,14 @@ export interface UrlParameterEntry {
   // is. Unlike `addressParameter` this names a parameter of the surrounding
   // *hook*, not of the classified function.
   comparedParameter?: string;
+  // Whether this slot accepts a socket-qualified address naming another world.
+  // Required for `game-object`, `component` and `either` and absent otherwise —
+  // enforced by the drift guard rather than the type, for the same reason
+  // `addressParameter` is. Never defaulted: a slot whose behaviour cannot be
+  // established from the engine is `cross-world`, because a wrong `same-world`
+  // is a false warning about correct code while a wrong `cross-world` only
+  // loses a finding.
+  socketScope?: SocketScope;
   // `"generated"` for a slot the emitter derives from the ref-doc, otherwise a
   // package-relative path to the hand-authored `.d.ts` that declares it,
   // resolved against the `packages/types` package root. Not repo-relative: the
@@ -172,3 +195,19 @@ export function classifyUrlParameter(
   }
   return "none";
 }
+
+// Whether a socket-qualified address naming a foreign world is legal in this
+// slot. Fails open — an unclassified slot, and a classified one carrying no
+// judgment, both accept — so nothing is reported on a slot nobody judged.
+export function slotAcceptsForeignSocket(
+  table: UrlParameterTable,
+  fqn: string,
+  parameter: string,
+): boolean {
+  for (const entry of table) {
+    if (entry.fqn === fqn && entry.parameter === parameter) {
+      return entry.socketScope !== "same-world";
+    }
+  }
+  return true;
+}

package/url-parameters.json

@@ -3,6 +3,7 @@
     "fqn": "go.get_position",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to get the position for"
   },
@@ -10,6 +11,7 @@
     "fqn": "go.get_rotation",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to get the rotation for"
   },
@@ -17,6 +19,7 @@
     "fqn": "go.get_scale",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to get the scale for"
   },
@@ -24,6 +27,7 @@
     "fqn": "go.get_scale_uniform",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to get the uniform scale for"
   },
@@ -31,6 +35,7 @@
     "fqn": "go.set_position",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to set the position for"
   },
@@ -38,6 +43,7 @@
     "fqn": "go.set_rotation",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to get the rotation for"
   },
@@ -45,6 +51,7 @@
     "fqn": "go.set_scale",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to get the scale for"
   },
@@ -52,6 +59,7 @@
     "fqn": "go.set_scale_xy",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to get the scale for"
   },
@@ -59,6 +67,7 @@
     "fqn": "go.set_parent",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to set parent for"
   },
@@ -66,6 +75,7 @@
     "fqn": "go.set_parent",
     "parameter": "parent_id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the new parent game object"
   },
@@ -73,6 +83,7 @@
     "fqn": "go.get_parent",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to get parent for"
   },
@@ -80,6 +91,7 @@
     "fqn": "go.get_world_position",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to get the world position for"
   },
@@ -87,6 +99,7 @@
     "fqn": "go.get_world_rotation",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to get the world rotation for"
   },
@@ -94,6 +107,7 @@
     "fqn": "go.get_world_scale",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to get the world scale for"
   },
@@ -101,6 +115,7 @@
     "fqn": "go.get_world_scale_uniform",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to get the world scale for"
   },
@@ -108,6 +123,7 @@
     "fqn": "go.get_world_transform",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to get the world transform for"
   },
@@ -115,6 +131,7 @@
     "fqn": "go.update_world_transform",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id of the game object instance to update"
   },
@@ -122,6 +139,7 @@
     "fqn": "go.delete",
     "parameter": "id",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "id or table of id's of the instance(s) to delete"
   },
@@ -129,6 +147,7 @@
     "fqn": "go.exists",
     "parameter": "url",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "url of the game object to check"
   },
@@ -136,6 +155,7 @@
     "fqn": "go.world_to_local_position",
     "parameter": "url",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "url of the game object which coordinate system convert to"
   },
@@ -143,6 +163,7 @@
     "fqn": "go.world_to_local_transform",
     "parameter": "url",
     "class": "game-object",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "url of the game object which coordinate system convert to"
   },
@@ -150,6 +171,7 @@
     "fqn": "go.animate",
     "parameter": "url",
     "class": "either",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "url of the game object or component having the property"
   },
@@ -157,6 +179,7 @@
     "fqn": "go.cancel_animations",
     "parameter": "url",
     "class": "either",
+    "socketScope": "same-world",
     "source": "generated",
     "evidence": "url of the game object or component"
   },
@@ -164,24 +187,28 @@
     "fqn": "go.get",
     "parameter": "url",
     "class": "either",
+    "socketScope": "same-world",
     "source": "src/go-overloads.d.ts"
   },
   {
     "fqn": "go.set",
     "parameter": "url",
     "class": "either",
+    "socketScope": "same-world",
     "source": "src/go-overloads.d.ts"
   },
   {
     "fqn": "msg.post",
     "parameter": "receiver",
     "class": "either",
+    "socketScope": "cross-world",
     "source": "src/msg-overloads.d.ts"
   },
   {
     "fqn": "msg.url",
     "parameter": "urlstring",
     "class": "either",
+    "socketScope": "cross-world",
     "source": "src/msg-overloads.d.ts"
   },
   {
@@ -199,6 +226,22 @@
     "source": "generated",
     "evidence": "hashed id of the animation to play"
   },
+  {
+    "fqn": "gui.play_flipbook",
+    "parameter": "animation",
+    "class": "animation",
+    "nodeParameter": "node",
+    "source": "generated",
+    "evidence": "animation id"
+  },
+  {
+    "fqn": "model.play_anim",
+    "parameter": "anim_id",
+    "class": "animation",
+    "addressParameter": "url",
+    "source": "generated",
+    "evidence": "id of the animation to play"
+  },
   {
     "fqn": "resource.atlas",
     "parameter": "path",