@defold-typescript/types 0.19.4 → 0.20.0

package/src/emit-messages.ts

@@ -12,12 +12,79 @@ export interface MessageEntry {
   origin: string;
   description: string;
   payload: MessageField[];
+  deprecatedSince?: string;
 }
 
 export interface MessageCatalog {
   entries: MessageEntry[];
 }
 
+export interface MessageDeprecation {
+  origin: string;
+  name: string;
+  deprecatedSince: string;
+}
+
+// Messages sit outside the typed identity surface (no MESSAGE kind in
+// ApiSymbolIdentity / the availability matrix), and the per-version message
+// fixtures are incomplete, so message deprecations cannot be derived like member
+// deprecations. This is the smallest curated overlay: only evidence-backed
+// entries, matched by the stable (origin, name) identity, failing closed.
+export const MESSAGE_DEPRECATIONS: readonly MessageDeprecation[] = [
+  { origin: "camera", name: "acquire_camera_focus", deprecatedSince: "1.13.0" },
+  { origin: "camera", name: "release_camera_focus", deprecatedSince: "1.13.0" },
+];
+
+// Stamp deprecatedSince onto the catalog entries the overlay names, keyed by
+// exact (origin, name). The identity index nests name under origin so origin and
+// name never share a delimiter — no separator byte can forge or collide two
+// distinct identities. A duplicate catalog identity, a duplicate overlay
+// identity, or an overlay entry that matches no catalog message each throws
+// rather than silently overwriting or no-op'ing, so an ambiguous surface or a
+// stale curation cannot pass unnoticed.
+export function applyMessageDeprecations(
+  catalog: MessageCatalog,
+  overlay: readonly MessageDeprecation[] = MESSAGE_DEPRECATIONS,
+): MessageCatalog {
+  const entries = catalog.entries.map((entry) => ({ ...entry }));
+  const byIdentity = new Map<string, Map<string, MessageEntry>>();
+  for (const entry of entries) {
+    let byName = byIdentity.get(entry.origin);
+    if (!byName) {
+      byName = new Map<string, MessageEntry>();
+      byIdentity.set(entry.origin, byName);
+    }
+    if (byName.has(entry.name)) {
+      throw new Error(
+        `applyMessageDeprecations: duplicate catalog message identity (origin=${entry.origin}, name=${entry.name})`,
+      );
+    }
+    byName.set(entry.name, entry);
+  }
+  const seenOverlay = new Map<string, Set<string>>();
+  for (const dep of overlay) {
+    let names = seenOverlay.get(dep.origin);
+    if (!names) {
+      names = new Set<string>();
+      seenOverlay.set(dep.origin, names);
+    }
+    if (names.has(dep.name)) {
+      throw new Error(
+        `applyMessageDeprecations: duplicate overlay message identity (origin=${dep.origin}, name=${dep.name})`,
+      );
+    }
+    names.add(dep.name);
+    const entry = byIdentity.get(dep.origin)?.get(dep.name);
+    if (!entry) {
+      throw new Error(
+        `applyMessageDeprecations: no catalog message matches (origin=${dep.origin}, name=${dep.name})`,
+      );
+    }
+    entry.deprecatedSince = dep.deprecatedSince;
+  }
+  return { entries };
+}
+
 const TS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 const ENGINE_TYPES = [
   "Hash",
@@ -95,11 +162,14 @@ export function emitBuiltinMessages(catalog: MessageCatalog): string {
 
 function emitEntry(entry: MessageEntry): string {
   const key = TS_IDENTIFIER.test(entry.name) ? entry.name : JSON.stringify(entry.name);
+  const prefix = entry.deprecatedSince
+    ? `    /** @deprecated since ${entry.deprecatedSince} */\n`
+    : "";
   if (entry.payload.length === 0) {
-    return `    ${key}: Record<string, never>;`;
+    return `${prefix}    ${key}: Record<string, never>;`;
   }
   const fields = entry.payload.map(emitField).join("; ");
-  return `    ${key}: { ${fields} };`;
+  return `${prefix}    ${key}: { ${fields} };`;
 }
 
 function emitField(field: MessageField): string {

package/src/index.ts

@@ -1,3 +1,23 @@
+export {
+  type ApiAvailability,
+  type ApiMigrationCatalog,
+  type ApiMigrationEntry,
+  type ApiSymbolIdentity,
+  type AvailabilityLabel,
+  type AvailabilityLabelKind,
+  applyMigrationOverlay,
+  availabilityLabel,
+  type Box2dBackend,
+  collectSymbolIdentities,
+  deriveAvailabilityMatrix,
+  groupByLogicalName,
+  isSignatureTransition,
+  type LogicalNameGroup,
+  normalizedFunctionSignature,
+  symbolIdentityKey,
+  type VersionSurface,
+  validateAvailability,
+} from "./api-availability";
 export type { ApiFunction, ApiModule, ApiParameter, ApiVariable } from "./api-doc";
 export { parseDefoldApiDoc } from "./api-doc";
 export {
@@ -17,7 +37,12 @@ export {
   htmlToDocText,
   renderDocComment,
 } from "./doc-comment";
-export { type EmitOptions, emitDeclarations } from "./emit-dts";
+export {
+  type EmitOptions,
+  emitDeclarations,
+  emitSymbolSignatures,
+  type SymbolSignature,
+} from "./emit-dts";
 export {
   hashExampleSource,
   lookupTranslation,

package/src/lifecycle.ts

@@ -112,7 +112,21 @@ export interface InputAction {
    */
   userid?: number;
   /**
-   * True if the inout originated from an unknown/unmapped gamepad.
+   * The guid of the gamepad controller. Only passed with "connected" action.
+   */
+  gamepad_guid?: string;
+  /**
+   * Parsed guid info table. Only passed with "connected" action. See table below.
+   */
+  gamepad_guid_info?: {
+    vendor: number;
+    product: number;
+    bus: number;
+    crc: number;
+    version: number;
+  };
+  /**
+   * True if the input originated from an unknown/unmapped gamepad.
    */
   gamepad_unknown?: boolean;
   /**
@@ -333,8 +347,14 @@ export interface ScriptHooks<TSelf, TInitState = TSelf> {
    * `userid`
    * Id of the user associated with the controller. Usually only relevant on consoles.
    *
+   * `gamepad_guid`
+   * The guid of the gamepad controller. Only passed with "connected" action.
+   *
+   * `gamepad_guid_info`
+   * Parsed guid info table. Only passed with "connected" action. See table below.
+   *
    * `gamepad_unknown`
-   * True if the inout originated from an unknown/unmapped gamepad.
+   * True if the input originated from an unknown/unmapped gamepad.
    *
    * `gamepad_name`
    * Name of the gamepad
@@ -386,6 +406,27 @@ export interface ScriptHooks<TSelf, TInitState = TSelf> {
    * `acc_z`
    * Accelerometer z value (if present).
    *
+   * Guid info table:
+   * This info is only passed with a `connected` action.
+   *
+   * Field
+   * Description
+   *
+   * `vendor`
+   * USB vendor id. E.g. Nintendo 0x057e, Sony 0x054c, or Microsoft 0x045e
+   *
+   * `product`
+   * USB product id
+   *
+   * `bus`
+   * How device is communicating. E.g.0x0003 for USB devices and 0x0005 for Bluetooth devices.
+   *
+   * `crc`
+   * SDL CRC16 signature, typically used when vendor and product ids are unavailable
+   *
+   * `version`
+   * The device or firmware version
+   *
    * @param self - reference to the script state to be used for storing data
    * @param action_id - id of the received input action, as mapped in the input_binding-file
    * @param action - a table containing the input data, see above for a description