@defold-typescript/types 0.12.1 → 0.14.0

package/api-targets.json

@@ -54,7 +54,7 @@
           "namespace": "msg",
           "fixture": "msg_doc.json",
           "outFile": "msg.d.ts",
-          "skipFunctions": ["post"]
+          "skipFunctions": ["post", "url"]
         },
         {
           "namespace": "particlefx",

package/generated/camera.d.ts

@@ -52,7 +52,7 @@ declare global {
      * }
      * ```
      */
-    function get_cameras(): Record<string | number, unknown>;
+    function get_cameras(): Url[];
     /**
      * get enabled
      *
@@ -175,7 +175,7 @@ declare global {
      * @param camera - camera id
      * @param aspect_ratio - the manual aspect ratio value.
      */
-    function set_aspect_ratio(camera: Url | number, aspect_ratio: number): void;
+    function set_aspect_ratio(camera: Url | number | undefined, aspect_ratio: number): void;
     /**
      * Enables or disables automatic aspect ratio calculation. When enabled (true),
      * the camera automatically calculates aspect ratio from render target dimensions.
@@ -184,42 +184,42 @@ declare global {
      * @param camera - camera id
      * @param auto_aspect_ratio - true to enable auto aspect ratio
      */
-    function set_auto_aspect_ratio(camera: Url | number, auto_aspect_ratio: boolean): void;
+    function set_auto_aspect_ratio(camera: Url | number | undefined, auto_aspect_ratio: boolean): void;
     /**
      * set far z
      *
      * @param camera - camera id
      * @param far_z - the far z.
      */
-    function set_far_z(camera: Url | number, far_z: number): void;
+    function set_far_z(camera: Url | number | undefined, far_z: number): void;
     /**
      * set field of view
      *
      * @param camera - camera id
      * @param fov - the field of view.
      */
-    function set_fov(camera: Url | number, fov: number): void;
+    function set_fov(camera: Url | number | undefined, fov: number): void;
     /**
      * set near z
      *
      * @param camera - camera id
      * @param near_z - the near z.
      */
-    function set_near_z(camera: Url | number, near_z: number): void;
+    function set_near_z(camera: Url | number | undefined, near_z: number): void;
     /**
      * set orthographic zoom mode
      *
      * @param camera - camera id
      * @param mode - camera.ORTHO_MODE_FIXED, camera.ORTHO_MODE_AUTO_FIT or camera.ORTHO_MODE_AUTO_COVER
      */
-    function set_orthographic_mode(camera: Url | number, mode: number): void;
+    function set_orthographic_mode(camera: Url | number | undefined, mode: number): void;
     /**
      * set orthographic zoom
      *
      * @param camera - camera id
      * @param orthographic_zoom - the zoom level when the camera uses orthographic projection.
      */
-    function set_orthographic_zoom(camera: Url | number, orthographic_zoom: number): void;
+    function set_orthographic_zoom(camera: Url | number | undefined, orthographic_zoom: number): void;
     /**
      * Converts a 3D world position to screen-space coordinates with view depth.
      * Returns a vector3 where x and y are in screen pixels and z is the view depth in world units

package/generated/font.d.ts

@@ -36,7 +36,7 @@ declare global {
      * `path_hash`
      * hash The path of the font file
      */
-    function get_info(fontc: string | Hash): { path: Hash; fonts: Record<string | number, unknown>; path: string; path_hash: Hash };
+    function get_info(fontc: string | Hash): { path: Hash; fonts: { path: string; path_hash: Hash }[] };
     /**
      * prepopulates the font glyph cache with rasterised glyphs
      *

package/generated/go.d.ts

@@ -471,7 +471,7 @@ declare global {
      * // Get the world position of the game object the script is attached to:
      * const p = go.get_world_position();
      *
-     * // Get the world position of another game object with id "x":
+     * // Reach a sibling game object by its id — relative addressing, no socket prefix:
      * const p2 = go.get_world_position("x");
      * ```
      */
@@ -868,7 +868,7 @@ declare global {
      * // Set the position of the game object the script is attached to:
      * go.set_position(p);
      *
-     * // Set the position of another game object with id "x":
+     * // Reach a sibling game object by its id — relative addressing, no socket prefix:
      * go.set_position(p, "x");
      * ```
      */

package/generated/msg.d.ts

@@ -1,76 +1,9 @@
 /** @noSelfInFile */
-import type { Hash, Url } from "../src/core-types";
-
 declare global {
   /**
    * Functions for passing messages and constructing URL objects.
    */
   namespace msg {
-    /**
-     * This is equivalent to `msg.url(nil)` or `msg.url("#")`, which creates an url to the current
-     * script component.
-     *
-     * @returns a new URL
-     * @example
-     * ```ts
-     * // Create a new URL which will address the current script:
-     * const my_url = msg.url();
-     * print(my_url); // => url: [current_collection:/my_instance#my_component]
-     * ```
-     */
-    function url(): Url;
-    /**
-     * The format of the string must be `[socket:][path][#fragment]`, which is similar to a HTTP URL.
-     * When addressing instances:
-     *
-     * - `socket` is the name of a valid world (a collection)
-     *
-     * - `path` is the id of the instance, which can either be relative the instance of the calling script or global
-     *
-     * - `fragment` would be the id of the desired component
-     *
-     * In addition, the following shorthands are available:
-     *
-     * - `"."` the current game object
-     *
-     * - `"#"` the current component
-     *
-     * @param urlstring - string to create the url from
-     * @returns a new URL
-     * @example
-     * ```ts
-     * const my_url = msg.url("#my_component");
-     * print(my_url); // => url: [current_collection:/my_instance#my_component]
-     *
-     * const my_collection_url = msg.url("my_collection:/my_sub_collection/my_instance#my_component");
-     * print(my_collection_url); // => url: [my_collection:/my_sub_collection/my_instance#my_component]
-     *
-     * const my_socket_url = msg.url("my_socket:");
-     * print(my_socket_url); // => url: [my_collection:]
-     * ```
-     */
-    function url(urlstring: string): Url;
-    /**
-     * creates a new URL from separate arguments
-     *
-     * @param socket - socket of the URL
-     * @param path - path of the URL
-     * @param fragment - fragment of the URL
-     * @returns a new URL
-     * @example
-     * ```ts
-     * const my_socket = "main"; // specify by valid name
-     * const my_path = hash("/my_collection/my_gameobject"); // specify as string or hash
-     * const my_fragment = "component"; // specify as string or hash
-     * const my_url = msg.url(my_socket, my_path, my_fragment);
-     *
-     * print(my_url); // => url: [main:/my_collection/my_gameobject#component]
-     * print(my_url.socket); // => 786443 (internal numeric value)
-     * print(my_url.path); // => hash: [/my_collection/my_gameobject]
-     * print(my_url.fragment); // => hash: [component]
-     * ```
-     */
-    function url(socket?: string | Hash, path?: string | Hash, fragment?: string | Hash): Url;
   }
 }
 

package/package.json

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

package/scripts/fidelity-audit.ts

@@ -63,20 +63,6 @@ function docString(raw: unknown): string | undefined {
   return typeof raw === "string" ? raw : undefined;
 }
 
-function isDocOptional(param: Record<string, unknown>): boolean {
-  return param.is_optional === "True" || stringArray(param.types).includes("nil");
-}
-
-function trailingOptionalCutoff(params: readonly Record<string, unknown>[]): number {
-  let cutoff = params.length;
-  for (let i = params.length - 1; i >= 0; i -= 1) {
-    const p = params[i];
-    if (p && isDocOptional(p)) cutoff = i;
-    else break;
-  }
-  return cutoff;
-}
-
 // Colon `<receiver>:<method>` FUNCTION elements are emitted as method-bearing
 // interfaces (see emit-dts collectHandleMethodGroups). Before that recovery they
 // emitted nothing yet were never counted as a droppedMembers loss — a blind spot
@@ -109,7 +95,9 @@ function auditEntry(
   // multiReturn is fully recovered: emitReturn emits LuaMultiReturn<[...]> for
   // every >1-return function, so no documented multi-return is a loss anymore.
   const multiReturn = 0;
-  let optionalAsRequired = 0;
+  // optionalAsRequired is fully recovered: emitParameter expresses an interior
+  // doc-optional param as `| undefined`, so no doc-optional param is a loss.
+  const optionalAsRequired = 0;
   const unknown = new Set<string>();
 
   const constantFqns = new Set<string>();
@@ -325,14 +313,13 @@ function auditEntry(
     }
     const params = paramList(element.parameters);
     const returns = paramList(element.returnvalues);
-    const cutoff = trailingOptionalCutoff(params);
     const arbitraryTable =
       typeof element.name === "string" && ARBITRARY_TABLE_SLOTS.has(element.name);
     const mappingSlot =
       typeof element.name === "string" ? MAPPING_TABLE_SLOTS.get(element.name) : undefined;
     const homogeneousElement =
       typeof element.name === "string" ? HOMOGENEOUS_ARRAY_SLOTS.get(element.name) : undefined;
-    params.forEach((param, index) => {
+    params.forEach((param) => {
       const tableSlotCuration =
         typeof element.name === "string" && typeof param.name === "string"
           ? TABLE_SLOT_CURATIONS.get(tableSlotKey(element.name, "param", param.name))
@@ -348,10 +335,9 @@ function auditEntry(
           ? { element: element.name, kind: "param", name: param.name }
           : undefined,
       );
-      // Residual: a doc-optional param the emitter cannot mark `?` because a
-      // required param follows it. The trailing-run cutoff must match
-      // emit-dts so the gate and the emitted surface agree.
-      if (isDocOptional(param) && index < cutoff) optionalAsRequired += 1;
+      // Interior doc-optional params (a required param follows) are no longer a
+      // loss: emitParameter expresses them as `| undefined`, mirroring the
+      // emitted surface. optionalAsRequired stays in the report shape reading 0.
     });
     for (const ret of returns) {
       const tableSlotCuration =

package/scripts/fidelity-baseline.json

@@ -26,10 +26,10 @@
   "camera": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 1,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
-    "optionalAsRequired": 7
+    "optionalAsRequired": 0
   },
   "collectionfactory": {
     "droppedElements": 0,
@@ -66,7 +66,7 @@
   "font": {
     "droppedElements": 0,
     "unknownTokens": [],
-    "recordTables": 1,
+    "recordTables": 0,
     "multiReturn": 0,
     "droppedMembers": 0,
     "optionalAsRequired": 0

package/src/emit-dts.ts

@@ -164,6 +164,9 @@ export const OVERLOAD_COVERED_SKIPS = new Set([
   "go.property",
   // msg-overloads.d.ts supplies the typed msg.post shape.
   "msg.post",
+  // msg-overloads.d.ts supplies the typed msg.url shape (0 / 1-string / 3-arg
+  // arities; the runtime-invalid two-arg form is intentionally omitted).
+  "msg.url",
 ]);
 
 // Element names whose `table` slot is a prose-only `a table mapping X to Y`
@@ -214,6 +217,9 @@ export const HOMOGENEOUS_ARRAY_SLOTS: ReadonlyMap<string, string | readonly stri
   // no brand exists to reference; `number` is the faithful element token for these
   // numeric constants, mirroring the vmath.vector/buffer.* number entries.
   ["push.register", "number"],
+  // camera.get_cameras returns "a table with all camera URLs" (the ref example
+  // iterates it with `pairs`) — a homogeneous list of `url`, emitted `Url[]`.
+  ["camera.get_cameras", "url"],
 ]);
 
 // A `mapping` curation whose value is itself a single-level mapping, emitted
@@ -231,6 +237,30 @@ export const SOCKET_HANDLE_TOKENS = ["client", "master", "unconnected"] as const
 
 export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new Map([
   ["collectionfactory.create:return:ids", { kind: "mapping", key: "hash", value: "hash" }],
+  // font.get_info's `info` return is a `<dl>` with `path: hash` and a nested
+  // `fonts` field whose `<dd>` is itself a `<dl>` (`path: string`, `path_hash:
+  // hash`). parseTableFields flattens the inner `<dl>` to the top level, which
+  // duplicates the `path` key and bares `fonts` to Record; this curation replaces
+  // the whole mis-parsed field list with the faithful shape (a nested isList
+  // object), recovering the array and removing the duplicate key.
+  [
+    "font.get_info:return:info",
+    {
+      kind: "object",
+      fields: [
+        { name: "path", types: ["hash"] },
+        {
+          name: "fonts",
+          types: ["table"],
+          isList: true,
+          fields: [
+            { name: "path", types: ["string"] },
+            { name: "path_hash", types: ["hash"] },
+          ],
+        },
+      ],
+    },
+  ],
   // iap.finish and iap.acknowledge take the same Defold IAP transaction object —
   // the table handed to the iap.set_listener callback. The ref-doc fixture
   // describes it in prose only (no field list), so the shape is curated from the
@@ -1234,7 +1264,12 @@ function emitParameter(
     concrete.length > 0
       ? mapSlotUnion(concrete, p.doc, mapType, true, resolver, elementName, "param", p.name)
       : "unknown";
-  return `${name}${optional ? "?" : ""}: ${ts}`;
+  // An interior doc-optional param (a required param follows, so the trailing-`?`
+  // projection cannot mark it) keeps its optionality as `| undefined` — TSTL
+  // lowers `undefined` to `nil`, the faithful call. Trailing optionals keep the
+  // `?` form; required params are untouched.
+  const interiorOptional = !optional && isDocOptional(p) ? " | undefined" : "";
+  return `${name}${optional ? "?" : ""}: ${ts}${interiorOptional}`;
 }
 
 function emitReturn(

package/src/msg-overloads.d.ts

@@ -40,5 +40,43 @@ declare global {
       message_id: Hash,
       message?: Record<string | number, unknown>,
     ): void;
+    /**
+     * Construct a URL. A URL is `[socket:][path][#fragment]`.
+     *
+     * @remarks
+     * Only the following arities are supported at runtime:
+     *
+     * - `msg.url()` — no-arg.
+     * - `msg.url("[socket:][path][#fragment]")` — one string, the full URL.
+     * - `msg.url(socket, path, fragment)` — three required args.
+     *
+     * The two-arg form `msg.url(socket, path)` is a runtime error.
+     *
+     * In the same world, address a sibling **relatively** — by bare id
+     * (`msg.url("camera")`), absolute path (`msg.url("/camera")`), or
+     * component (`msg.url("#main")`). The `socket:` prefix only crosses
+     * into a collection-proxy-loaded world.
+     *
+     * @example
+     * ```ts
+     * // No-arg, then take the current game object's URL.
+     * const self: Url = msg.url();
+     *
+     * // A sibling in the same world — bare id, no socket prefix.
+     * const sibling: Url = msg.url("camera");
+     *
+     * // An absolute path in the same world.
+     * const absSibling: Url = msg.url("/camera");
+     *
+     * // A component on a sibling.
+     * const comp: Url = msg.url("camera#script");
+     *
+     * // Crossing into a proxy-loaded world — `socket` is the world name.
+     * const proxied: Url = msg.url(hash("level1"), hash("/door"), hash("script"));
+     * ```
+     */
+    function url(): Url;
+    function url(urlstring: string): Url;
+    function url(socket: string | Hash, path: string | Hash, fragment: string | Hash): Url;
   }
 }