@defold-typescript/types 0.50.1 → 0.52.0

package/src/emit-messages.ts

@@ -137,6 +137,295 @@ export function applyMessageFieldCorrections(
   return { entries };
 }
 
+// What only the engine states about a message the catalog mirrors from the
+// reference: proto optionality, a field the handler reads or the sender fills,
+// a message a component handles or posts, or the shape of a field the reference
+// types only as `table`. `evidence` names `<path>:<symbol>` in the 1.14.0 engine
+// source. Each kind throws once the catalog already states its fact, since that
+// means upstream fixed the reference and the entry is deleted; a `retype` throws
+// once the catalog stops declaring its pinned `upstream` types, since upstream
+// retyped the field and the entry is re-verified against what it now says.
+export type MessageEngineCorrection = {
+  readonly origin: string;
+  readonly name: string;
+  readonly evidence: string;
+} & (
+  | { readonly kind: "optional" | "required"; readonly fields: readonly string[] }
+  | { readonly kind: "add-field"; readonly fields: readonly MessageField[] }
+  | {
+      readonly kind: "add-message";
+      readonly description: string;
+      readonly fields: readonly MessageField[];
+    }
+  | {
+      readonly kind: "retype";
+      readonly fields: readonly string[];
+      readonly tsType: string;
+      readonly upstream: readonly string[];
+    }
+);
+
+const SCRIPT_DDF_DEFAULTS =
+  "script/src/script_ddf.cpp:DoLuaTableToDDF fills an omitted optional field with its default";
+const SOUND_EVENT =
+  "gamesys/src/gamesys/components/comp_sound.cpp:DispatchSoundEvent always sets play_id, and HandleEntryFinishedPlaying sends the event only for a play_sound that supplied one";
+
+function optionalField(name: string, types: string[], doc: string): MessageField {
+  return { name, types, optional: true, doc };
+}
+
+function requiredField(name: string, types: string[], doc: string): MessageField {
+  return { name, types, optional: false, doc };
+}
+
+// The listener and `on_message` paths agree: the DDF the message carries
+// declares the same sub-message fields the listener push sets.
+function physicsBody(message: string): string {
+  return `gamesys/proto/gamesys/physics_ddf.proto:${message} declares the same required fields for the on_message payload`;
+}
+
+function otherGroupField(): MessageField {
+  return {
+    name: "group",
+    types: ["hash"],
+    optional: false,
+    doc: "Collision group of the other object, equal to other_group.",
+  };
+}
+
+export const MESSAGE_ENGINE_CORRECTIONS: readonly MessageEngineCorrection[] = [
+  {
+    kind: "optional",
+    origin: "camera",
+    name: "set_camera",
+    fields: ["orthographic_projection", "orthographic_zoom", "orthographic_mode"],
+    evidence: `gamesys/proto/gamesys/camera_ddf.proto:SetCamera declares them optional with defaults, CompCameraOnMessage handles it, and ${SCRIPT_DDF_DEFAULTS}`,
+  },
+  {
+    kind: "optional",
+    origin: "sys",
+    name: "reboot",
+    fields: ["arg1", "arg2", "arg3", "arg4", "arg5", "arg6"],
+    evidence: `script/src/script/sys_ddf.proto:Reboot declares every argument optional, engine/src/engine.cpp:Dispatch handles it, and ${SCRIPT_DDF_DEFAULTS}`,
+  },
+  {
+    kind: "optional",
+    origin: "sys",
+    name: "start_record",
+    fields: ["frame_period", "fps"],
+    evidence: `script/src/script/sys_ddf.proto:StartRecord declares both optional with defaults 2 and 30, engine/src/engine.cpp:Dispatch handles it, and ${SCRIPT_DDF_DEFAULTS}`,
+  },
+  {
+    kind: "optional",
+    origin: "sprite",
+    name: "play_animation",
+    fields: ["offset", "playback_rate"],
+    evidence: `gamesys/proto/gamesys/sprite_ddf.proto:PlayAnimation declares both optional with defaults 0 and 1, comp_sprite.cpp:CompSpriteOnMessage passes both to PlayAnimation, and ${SCRIPT_DDF_DEFAULTS}`,
+  },
+  {
+    kind: "optional",
+    origin: "go",
+    name: "set_parent",
+    fields: ["parent_id", "keep_world_transform"],
+    evidence: `gameobject/proto/gameobject/gameobject_ddf.proto:SetParent declares both optional with defaults 0 and 1, gameobject.cpp:DispatchMessagesFunction handles it, and ${SCRIPT_DDF_DEFAULTS}`,
+  },
+  {
+    kind: "required",
+    origin: "sound",
+    name: "sound_done",
+    fields: ["play_id"],
+    evidence: SOUND_EVENT,
+  },
+  {
+    kind: "required",
+    origin: "sound",
+    name: "sound_stopped",
+    fields: ["play_id"],
+    evidence: SOUND_EVENT,
+  },
+  {
+    kind: "add-field",
+    origin: "sound",
+    name: "play_sound",
+    fields: [
+      optionalField("pan", ["number"], "Pan between -1 and 1, added to the component's pan."),
+      optionalField("speed", ["number"], "Speed factor, multiplied with the component's speed."),
+    ],
+    evidence:
+      "gamesys/proto/gamesys/gamesys_ddf.proto:PlaySound declares pan and speed, and comp_sound.cpp:CompSoundOnMessage applies both to the voice",
+  },
+  {
+    kind: "add-field",
+    origin: "sound",
+    name: "stop_sound",
+    fields: [
+      optionalField(
+        "play_id",
+        ["number"],
+        "Id passed to play_sound; stops only that voice. Omit to stop every voice.",
+      ),
+    ],
+    evidence:
+      "gamesys/proto/gamesys/gamesys_ddf.proto:StopSound declares play_id, and comp_sound.cpp:CompSoundOnMessage stops only the voice that matches it",
+  },
+  {
+    kind: "add-message",
+    origin: "sound",
+    name: "pause_sound",
+    description: "Pause or resume every voice the receiving sound component plays.",
+    fields: [optionalField("pause", ["boolean"], "true (default) to pause, false to resume.")],
+    evidence:
+      "gamesys/proto/gamesys/gamesys_ddf.proto:PauseSound declares pause, and comp_sound.cpp:CompSoundOnMessage pauses every voice of the component",
+  },
+  {
+    kind: "add-message",
+    origin: "sound",
+    name: "set_pan",
+    description: "Set the pan on the receiving sound component.",
+    fields: [optionalField("pan", ["number"], "Pan between -1 and 1, default 0.")],
+    evidence:
+      "gamesys/proto/gamesys/gamesys_ddf.proto:SetPan declares pan, and comp_sound.cpp:CompSoundOnMessage sets the component's pan",
+  },
+  {
+    kind: "add-message",
+    origin: "render",
+    name: "set_view_projection",
+    description:
+      "Posted automatically by camera components to the render script with the active view and projection matrices.",
+    fields: [
+      requiredField("id", ["hash"], "Id of the camera component that posted the matrices."),
+      requiredField("view", ["matrix4"], "View matrix of the camera."),
+      requiredField("projection", ["matrix4"], "Projection matrix of the camera."),
+    ],
+    evidence:
+      "gamesys/proto/gamesys/gamesys_ddf.proto:SetViewProjection declares id, view and projection required, and comp_camera.cpp:PostRenderScriptSetViewProjectionMsg posts it to the render socket on every camera update",
+  },
+  {
+    kind: "add-field",
+    origin: "physics",
+    name: "collision_response",
+    fields: [otherGroupField()],
+    evidence:
+      "gamesys/proto/gamesys/physics_ddf.proto:CollisionResponse declares a required group, and comp_collision_object.cpp:CollisionCallback sets it to the other object's group",
+  },
+  {
+    kind: "add-field",
+    origin: "physics",
+    name: "contact_point_response",
+    fields: [otherGroupField()],
+    evidence:
+      "gamesys/proto/gamesys/physics_ddf.proto:ContactPointResponse declares a required group, and comp_collision_object.cpp:ContactPointCallback sets it to the other object's group",
+  },
+  {
+    kind: "add-field",
+    origin: "physics",
+    name: "trigger_response",
+    fields: [otherGroupField()],
+    evidence:
+      "gamesys/proto/gamesys/physics_ddf.proto:TriggerResponse declares a required group, and comp_collision_object.cpp:TriggerEnteredCallback sets it to the other object's group",
+  },
+  {
+    kind: "retype",
+    origin: "physics",
+    name: "contact_point_event",
+    fields: ["a", "b"],
+    tsType:
+      "{ position: Vector3; instance_position: Vector3; normal: Vector3; relative_velocity: Vector3; mass: number; id: Hash; group: Hash }",
+    upstream: ["table"],
+    evidence: `gamesys/src/gamesys/scripts/script_physics.cpp:PushContactPoint sets these seven fields on each body, and ${physicsBody("ContactPoint")}`,
+  },
+  {
+    kind: "retype",
+    origin: "physics",
+    name: "collision_event",
+    fields: ["a", "b"],
+    tsType: "{ position: Vector3; id: Hash; group: Hash }",
+    upstream: ["table"],
+    evidence: `gamesys/src/gamesys/scripts/script_physics.cpp:PushCollision sets these three fields on each body, and ${physicsBody("Collision")}`,
+  },
+  {
+    kind: "retype",
+    origin: "physics",
+    name: "trigger_event",
+    fields: ["a", "b"],
+    tsType: "{ id: Hash; group: Hash }",
+    upstream: ["table"],
+    evidence: `gamesys/src/gamesys/scripts/script_physics.cpp:PushTrigger sets these two fields on each body, and ${physicsBody("Trigger")}`,
+  },
+];
+
+export function applyMessageEngineCorrections(
+  catalog: MessageCatalog,
+  overlay: readonly MessageEngineCorrection[] = MESSAGE_ENGINE_CORRECTIONS,
+): MessageCatalog {
+  const entries = catalog.entries.map((entry) => ({
+    ...entry,
+    payload: entry.payload.map((field) => ({ ...field })),
+  }));
+  for (const correction of overlay) {
+    const identity = `(origin=${correction.origin}, name=${correction.name})`;
+    const stale = (fact: string) =>
+      new Error(
+        `applyMessageEngineCorrections: the catalog ${fact} for ${identity}; delete the correction`,
+      );
+    const entry = entries.find(
+      (candidate) => candidate.origin === correction.origin && candidate.name === correction.name,
+    );
+    if (correction.kind === "add-message") {
+      if (entry) throw stale("already declares message");
+      entries.push({
+        name: correction.name,
+        origin: correction.origin,
+        description: correction.description,
+        payload: correction.fields.map((field) => ({ ...field, types: [...field.types] })),
+      });
+      continue;
+    }
+    if (!entry) {
+      throw new Error(`applyMessageEngineCorrections: no catalog message matches ${identity}`);
+    }
+    if (correction.kind === "add-field") {
+      for (const field of correction.fields) {
+        if (entry.payload.some((candidate) => candidate.name === field.name)) {
+          throw stale(`already declares field ${field.name}`);
+        }
+        entry.payload.push({ ...field, types: [...field.types] });
+      }
+      continue;
+    }
+    for (const name of correction.fields) {
+      const field = entry.payload.find((candidate) => candidate.name === name);
+      if (!field) {
+        throw new Error(
+          `applyMessageEngineCorrections: no catalog field matches ${identity} field=${name}`,
+        );
+      }
+      if (correction.kind === "retype") {
+        if (field.types.join("|") !== correction.upstream.join("|")) {
+          throw new Error(
+            `applyMessageEngineCorrections: the catalog now declares ${field.types.join("|")} for field ${name} of ${identity}, not the pinned ${correction.upstream.join("|")}; re-verify the correction`,
+          );
+        }
+        field.types = [correction.tsType];
+        continue;
+      }
+      const optional = correction.kind === "optional";
+      if (field.optional === optional) throw stale(`field ${name} is already ${correction.kind}`);
+      field.optional = optional;
+    }
+  }
+  return { entries };
+}
+
+// The built-in message surface is the catalog plus these overlays. Every reader
+// of it goes through here, so a message the engine overlay adds is never missing
+// from one of them.
+export function applyMessageOverlays(catalog: MessageCatalog): MessageCatalog {
+  return applyMessageEngineCorrections(
+    applyMessageFieldCorrections(applyMessageDeprecations(catalog)),
+  );
+}
+
 const TS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 const ENGINE_TYPES = [
   "Hash",

package/src/engine-globals.d.ts

@@ -4,12 +4,16 @@ import type * as Core from "./core-types";
 // Hand-maintained surface: Defold ships no machine-readable export for the
 // prefixless globals, so add or remove entries here from the Defold API
 // reference and mirror the change in fixtures/globals_doc.json — the
-// engine-globals test fails if the two fall out of sync.
+// engine-globals test fails if the two fall out of sync. That canonical file
+// seeds each new target on release import; also mirror the change into every
+// committed fixtures/defold-*/globals_doc.json, which the API reference reads.
 declare global {
   /** An opaque, branded handle to a hashed name; see {@link Core.Hash}. */
   type Hash<S extends string = string> = Core.Hash<S>;
   /** Hash a string into the engine's `Hash` handle. */
   function hash<S extends string>(s: S): Core.Hash<S>;
+  /** Return a `Hash` unchanged. */
+  function hash<S extends string>(h: Core.Hash<S>): Core.Hash<S>;
   /** Render a `Hash` handle as its hexadecimal string. */
   function hash_to_hex(h: Core.Hash): string;
   /** Pretty-print any values to the console for debugging. */
@@ -36,7 +40,7 @@ declare global {
   type Opaque<Name extends string> = Core.Opaque<Name>;
   /** A message-passing address with `socket`, `path`, and `fragment`; see {@link Core.Url}. */
   type Url = Core.Url;
-  /** A read-only numeric vector accessed by index; see {@link Core.Vector}. */
+  /** A numeric vector read and written by 1-based index; see {@link Core.Vector}. */
   type Vector = Core.Vector;
   /** A three-component vector with `x`, `y`, `z`; see {@link Core.Vector3}. */
   type Vector3 = Core.Vector3;
@@ -46,4 +50,6 @@ declare global {
   type Quaternion = Core.Quaternion;
   /** A 4x4 transformation matrix; see {@link Core.Matrix4}. */
   type Matrix4 = Core.Matrix4;
+  /** An array constant read back from a constant buffer, 1-based with no length; see {@link Core.ConstantArray}. */
+  type ConstantArray<T> = Core.ConstantArray<T>;
 }

package/src/go-overloads.d.ts

@@ -1,6 +1,6 @@
 /** @noSelfInFile */
 
-import type { Hash, Quaternion, Url, Vector3, Vector4 } from "./core-types";
+import type { Hash, Matrix4, Quaternion, Url, Vector3, Vector4 } from "./core-types";
 
 interface ScriptProperty<TValue> {
   readonly __defoldScriptProperty: TValue;
@@ -21,12 +21,17 @@ type WritableKey<P> = {
 
 declare global {
   namespace go {
-    interface GoPropertyOptions {
-      /** **⚠️ 1-based index into an array property; passed to Defold unchanged.** */
-      index?: number;
-      key?: Hash | string;
-      keys?: (Hash | string)[];
-    }
+    // LuaToPropertyOptions raises when more than one of the three is non-nil, and
+    // reads a nil one as absent.
+    type GoPropertyOptions =
+      | {
+          /** **⚠️ 1-based index into an array property; passed to Defold unchanged.** */
+          index?: number;
+          key?: undefined;
+          keys?: undefined;
+        }
+      | { index?: undefined; key?: Hash | string; keys?: undefined }
+      | { index?: undefined; key?: undefined; keys?: (Hash | string)[] };
 
     /**
      * gets a named property of the specified game object or component
@@ -39,6 +44,8 @@ declare global {
      * - keys array of hashes or strings identifying internal component resources (e.g. a particle fx emitter, see examples below)
      * @returns the value of the specified property
      * A `string` value is a text property, which needs Defold 1.13.2 or later.
+     * An array material constant read without `index` returns every element as a
+     * `Vector4[]`.
      * @example
      * ```ts
      * const position = go.get("#sprite", "position");
@@ -50,18 +57,46 @@ declare global {
     function get<P>(): <K extends keyof P>(
       url: SceneAddress | Hash | Url,
       property: K,
-      options?: GoPropertyOptions,
+      ...options: [] | [GoPropertyOptions]
     ) => P[K];
     function get<K extends keyof go.properties>(
       url: SceneAddress | Hash | Url,
       property: K,
-      options?: GoPropertyOptions,
+    ): go.properties[K];
+    function get<K extends keyof go.properties>(
+      url: SceneAddress | Hash | Url,
+      property: K,
+      options: GoPropertyOptions,
     ): go.properties[K];
     function get(
       url: SceneAddress | Hash | Url,
       property: string | Hash,
-      options?: GoPropertyOptions,
-    ): number | boolean | string | Hash | Url | Vector3 | Vector4 | Quaternion;
+    ):
+      | number
+      | boolean
+      | string
+      | Hash
+      | Url
+      | Vector3
+      | Vector4
+      | Quaternion
+      | Matrix4
+      | Vector4[];
+    function get(
+      url: SceneAddress | Hash | Url,
+      property: string | Hash,
+      options: GoPropertyOptions,
+    ):
+      | number
+      | boolean
+      | string
+      | Hash
+      | Url
+      | Vector3
+      | Vector4
+      | Quaternion
+      | Matrix4
+      | Vector4[];
     /**
      * sets a named property of the specified game object or component, or a material constant
      *
@@ -86,19 +121,49 @@ declare global {
       url: SceneAddress | Hash | Url,
       property: K,
       value: P[K],
-      options?: GoPropertyOptions,
+      ...options: [] | [GoPropertyOptions]
     ) => void;
     function set<K extends keyof go.properties>(
       url: SceneAddress | Hash | Url,
       property: K,
       value: go.properties[K],
-      options?: GoPropertyOptions,
+    ): void;
+    function set<K extends keyof go.properties>(
+      url: SceneAddress | Hash | Url,
+      property: K,
+      value: go.properties[K],
+      options: GoPropertyOptions,
+    ): void;
+    function set(
+      url: SceneAddress | Hash | Url,
+      property: string | Hash,
+      value:
+        | number
+        | boolean
+        | string
+        | Hash
+        | Url
+        | Vector3
+        | Vector4
+        | Quaternion
+        | Matrix4
+        | Vector4[],
     ): void;
     function set(
       url: SceneAddress | Hash | Url,
       property: string | Hash,
-      value: number | boolean | string | Hash | Url | Vector3 | Vector4 | Quaternion | Vector4[],
-      options?: GoPropertyOptions,
+      value:
+        | number
+        | boolean
+        | string
+        | Hash
+        | Url
+        | Vector3
+        | Vector4
+        | Quaternion
+        | Matrix4
+        | Vector4[],
+      options: GoPropertyOptions,
     ): void;
     /**
      * Registers a script property, which the Defold editor exposes on every game