@defold-typescript/types 0.51.0 → 0.53.0

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. */

package/src/engine-type-name.ts

@@ -0,0 +1,33 @@
+// Reference names the rule cannot split into words: the reference writes these
+// as one run of capitals, or runs a number into a word (Bullet spells the joint
+// `btGeneric6DofConstraint`).
+export const ENGINE_TYPE_NAME_OVERRIDES: ReadonlyMap<string, string> = new Map([
+  ["LIVEUPDATE", "LiveUpdate"],
+  ["PIEBOUNDS", "PieBounds"],
+  ["SYSFIELD", "SysField"],
+  ["USERFIELD", "UserField"],
+  ["generic_6dof_params", "Generic6DofParams"],
+  ["generic_6dof_spring_params", "Generic6DofSpringParams"],
+]);
+
+/**
+ * The PascalCase TypeScript name of a reference type leaf (`EASING` ->
+ * `Easing`, `sys_info` -> `SysInfo`, `b2Body` -> `B2Body`). A word written in
+ * one case is capitalized; a mixed-case word keeps its inner capitals.
+ */
+export function engineTypeName(
+  referenceLeaf: string,
+  overrides: ReadonlyMap<string, string> = ENGINE_TYPE_NAME_OVERRIDES,
+): string {
+  const override = overrides.get(referenceLeaf);
+  if (override !== undefined) return override;
+  return referenceLeaf
+    .split("_")
+    .filter((part) => part.length > 0)
+    .map((part) =>
+      part === part.toUpperCase() || part === part.toLowerCase()
+        ? part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()
+        : part.charAt(0).toUpperCase() + part.slice(1),
+    )
+    .join("");
+}

package/src/go-overloads.d.ts

@@ -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,29 +44,59 @@ 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");
      * // Name the target component to read its catalogued property type. The
      * // empty call applies the type argument, then the inner call infers the key:
-     * const animation = go.get<sprite.properties>()("#sprite", "animation"); // Hash
+     * const animation = go.get<sprite.Properties>()("#sprite", "animation"); // Hash
      * ```
      */
     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>(
+    function get<K extends keyof go.Properties>(
       url: SceneAddress | Hash | Url,
       property: K,
-      options?: GoPropertyOptions,
-    ): go.properties[K];
+    ): 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,
+    ):
+      | 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;
+      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
      *
@@ -79,20 +114,40 @@ declare global {
      * // Name the target component to gate the value to its property type. The
      * // empty call applies the type argument, then the inner call infers the key.
      * // A read-only property such as "animation" is not a key it accepts:
-     * go.set<sprite.properties>()("#sprite", "playback_rate", 2);
+     * go.set<sprite.Properties>()("#sprite", "playback_rate", 2);
      * ```
      */
     function set<P>(): <K extends WritableKey<P>>(
       url: SceneAddress | Hash | Url,
       property: K,
       value: P[K],
-      options?: GoPropertyOptions,
+      ...options: [] | [GoPropertyOptions]
     ) => void;
-    function set<K extends keyof go.properties>(
+    function set<K extends keyof go.Properties>(
+      url: SceneAddress | Hash | Url,
+      property: K,
+      value: go.Properties[K],
+    ): void;
+    function set<K extends keyof go.Properties>(
       url: SceneAddress | Hash | Url,
       property: K,
-      value: go.properties[K],
-      options?: GoPropertyOptions,
+      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,
@@ -108,7 +163,7 @@ declare global {
         | Quaternion
         | Matrix4
         | Vector4[],
-      options?: GoPropertyOptions,
+      options: GoPropertyOptions,
     ): void;
     /**
      * Registers a script property, which the Defold editor exposes on every game