@defold-typescript/types 0.30.0 → 0.31.0

package/package.json

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

package/src/index.ts

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

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",