@defold-typescript/types 0.15.2 → 0.16.1

package/package.json

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

package/src/core-types.ts

@@ -1,10 +1,16 @@
 /// <reference types="@typescript-to-lua/language-extensions" />
 
+/**
+ * A read-only numeric vector accessed by index; `length` is its component count.
+ */
 export interface Vector {
   readonly [index: number]: number;
   readonly length: number;
 }
 
+/**
+ * A three-component vector with `x`, `y`, and `z` components.
+ */
 export interface Vector3 {
   x: number;
   y: number;
@@ -22,6 +28,9 @@ export interface Vector3 {
   unm: LuaNegationMethod<Vector3>;
 }
 
+/**
+ * A four-component vector with `x`, `y`, `z`, and `w` components.
+ */
 export interface Vector4 {
   x: number;
   y: number;
@@ -40,6 +49,9 @@ export interface Vector4 {
   unm: LuaNegationMethod<Vector4>;
 }
 
+/**
+ * A rotation quaternion with `x`, `y`, `z`, and `w` components.
+ */
 export interface Quaternion {
   x: number;
   y: number;
@@ -48,6 +60,9 @@ export interface Quaternion {
   mul: LuaMultiplicationMethod<Quaternion, Quaternion>;
 }
 
+/**
+ * A 4x4 transformation matrix.
+ */
 export interface Matrix4 {
   m00: number;
   m01: number;
@@ -73,29 +88,87 @@ export interface Matrix4 {
 }
 
 declare const HashBrand: unique symbol;
+/**
+ * An opaque, branded handle to a *hashed name*: hold it and pass it back to the
+ * engine API, but never inspect or construct it. Defold uses it in place of a
+ * string for game-object and component ids, resource paths, input-action names,
+ * material/animation/constant names, and the `socket`, `path`, and `fragment` of
+ * every {@link Url}; you obtain one from the global `hash(name)` function (or
+ * receive it back from the engine) and pass it straight to the API, never
+ * assembling its bits by hand.
+ *
+ * @remarks
+ * The brand is a phantom `unique symbol` property (`[HashBrand]: "Hash"`) that
+ * exists only in the type system and is erased at transpile — at runtime a
+ * `Hash` is the engine's opaque hash value, not an object carrying that key.
+ * Because the symbol is not exported, consumer code cannot fabricate a `Hash`;
+ * the only sources are `hash()` and the engine. That nominal branding is what
+ * stops a bare `string` or `number` from standing in where the API expects an
+ * already-hashed name. Many engine functions also accept a plain `string` and
+ * hash it for you, but a value already typed `Hash` is passed through as-is.
+ *
+ * Hashing is one-way: the original string cannot be recovered from a `Hash`.
+ * `hash_to_hex(h)` renders it as a hexadecimal string for logging, and `pprint`
+ * shows it as `hash: [0x…]`. Two hashes are equal exactly when they name the
+ * same thing, so a `Hash` is safe to compare, store, and use as a table key.
+ */
 export interface Hash {
   readonly [HashBrand]: "Hash";
 }
 
 declare const OpaqueBrand: unique symbol;
 /**
- * A nominal handle to an engine value you may hold and pass back to the API but
- * must never inspect or construct — a Defold `node`, `texture`, `render_target`,
- * `userdata`, etc. The `Name` parameter mints a distinct, mutually-incompatible
- * brand per kind, so TypeScript's structural typing can't silently swap a
- * `render_target` for a `constant`, and a plain object can't stand in for either.
+ * A nominal, branded handle to a value the engine owns and manages — a GUI node,
+ * a texture, a render target, a physics body, a socket, and so on: hold it and
+ * pass it back to the API, but never inspect or construct it. You get one back
+ * from an engine function, keep it in a variable, and pass it to the other
+ * functions that act on that resource; treat it as an opaque ticket, meaningful
+ * to the engine, not a value you read or assemble yourself.
  *
  * @remarks
- * The brand is a phantom `unique symbol` property: it exists only in the type
- * system (erased at transpile, never present at runtime). Because the symbol is
- * not exported, consumer code cannot fabricate an `Opaque` — the engine API is
- * the only source. Contrast with a `LuaTable` alias, which says the opposite:
- * "inspect freely, the shape just isn't modeled."
+ * Why a dedicated type? Each kind of handle is its own brand, so the compiler
+ * keeps them apart: `Opaque<"node">` and `Opaque<"texture">` are different
+ * types, and passing a texture where a node is expected is a compile error,
+ * exactly as a wrong primitive would be. The brand is a phantom `unique symbol`
+ * property that lives only in the type system and is erased at transpile — at
+ * runtime the value is just the engine's userdata. Because the symbol is never
+ * exported, your code cannot fabricate a handle or inspect or construct one; the
+ * engine API is the only source.
+ *
+ * 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">`
+ * - Sockets: `Opaque<"client">`, `Opaque<"server">`, `Opaque<"master">`,
+ *   `Opaque<"connected">`, `Opaque<"unconnected">`
+ * - Box2D physics: `Opaque<"b2Body">`, `Opaque<"b2World">`
+ * - Generic: `Opaque<"userdata">`
+ *
+ * @example
+ * Handles always come back from the engine — for instance:
+ * ```ts
+ * const node = gui.get_node("button");          // Opaque<"node">
+ * const rt = render.render_target("rt", opts);  // Opaque<"render_target">
+ * const cb = render.constant_buffer();          // Opaque<"constant_buffer">
+ * const buf = resource.load_buffer(path);       // Opaque<"buffer">
+ * const stream = buffer.get_stream(buf, "rgb"); // Opaque<"bufferstream">
+ * const world = b2d.get_world();                // Opaque<"b2World">
+ * const [conn] = socket.tcp();                  // a "master" socket handle
+ * function update(self: ...) {}                 // self is Opaque<"userdata">
+ * ```
+ *
+ * Contrast with a `LuaTable` alias, which says the opposite — "inspect freely,
+ * the shape just isn't modeled." An `Opaque` says "do not look inside; this
+ * value is meaningful only to the engine."
  */
 export interface Opaque<Name extends string> {
   readonly [OpaqueBrand]: Name;
 }
 
+/**
+ * A message-passing address with `socket`, `path`, and `fragment` components.
+ */
 export interface Url {
   readonly socket: Hash;
   readonly path: Hash;

package/src/engine-globals.d.ts

@@ -6,15 +6,44 @@ import type * as Core from "./core-types";
 // reference and mirror the change in fixtures/globals_doc.json — the
 // engine-globals test fails if the two fall out of sync.
 declare global {
+  /** An opaque, branded handle to a hashed name; see {@link Core.Hash}. */
   type Hash = Core.Hash;
+  /** Hash a string into the engine's `Hash` handle. */
   function hash(s: string): Core.Hash;
+  /** Render a `Hash` handle as its hexadecimal string. */
   function hash_to_hex(h: Core.Hash): string;
+  /** Pretty-print any value to the console for debugging. */
   function pprint(v: unknown): void;
+  /**
+   * A typed handle to a resource the engine owns — a GUI node, a texture, a
+   * render target, a physics body, a socket, and so on. You get one back from an
+   * engine function, keep it in a variable, and pass it to the functions that
+   * act on that resource; you never inspect or construct one yourself.
+   *
+   * Each kind of handle is its own brand, so `Opaque<"node">` and
+   * `Opaque<"texture">` are different types and the compiler rejects passing one
+   * where the other is expected. The brand is a phantom `unique symbol` property
+   * 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(...)`,
+   * `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.
+   */
   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}. */
   type Vector = Core.Vector;
+  /** A three-component vector with `x`, `y`, `z`; see {@link Core.Vector3}. */
   type Vector3 = Core.Vector3;
+  /** A four-component vector with `x`, `y`, `z`, `w`; see {@link Core.Vector4}. */
   type Vector4 = Core.Vector4;
+  /** A rotation quaternion with `x`, `y`, `z`, `w`; see {@link Core.Quaternion}. */
   type Quaternion = Core.Quaternion;
+  /** A 4x4 transformation matrix; see {@link Core.Matrix4}. */
   type Matrix4 = Core.Matrix4;
 }