@defold-typescript/types 0.1.0

package/src/emit-messages.ts

@@ -0,0 +1,148 @@
+import { DEFOLD_TYPE_MAP } from "./core-types";
+
+export interface MessageField {
+  name: string;
+  types: string[];
+  optional: boolean;
+  doc: string;
+}
+
+export interface MessageEntry {
+  name: string;
+  origin: string;
+  description: string;
+  payload: MessageField[];
+}
+
+export interface MessageCatalog {
+  entries: MessageEntry[];
+}
+
+const TS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const ENGINE_TYPES = [
+  "Hash",
+  "Matrix4",
+  "Quaternion",
+  "Url",
+  "Vector",
+  "Vector3",
+  "Vector4",
+] as const;
+
+export function parseMessagesDoc(raw: unknown): MessageCatalog {
+  if (!isRecord(raw)) {
+    throw new Error(`parseMessagesDoc: expected object, got ${describeKind(raw)}`);
+  }
+  const rawMessages = raw.messages;
+  if (!Array.isArray(rawMessages)) {
+    throw new Error(`parseMessagesDoc: missing or invalid "messages" array`);
+  }
+  const entries: MessageEntry[] = [];
+  for (const item of rawMessages) {
+    if (!isRecord(item)) continue;
+    const name = stringOr(item.name, "");
+    if (name === "") continue;
+    entries.push({
+      name,
+      origin: stringOr(item.origin, ""),
+      description: stringOr(item.description, ""),
+      payload: parsePayload(item.payload),
+    });
+  }
+  return { entries };
+}
+
+function parsePayload(raw: unknown): MessageField[] {
+  if (!Array.isArray(raw)) return [];
+  const fields: MessageField[] = [];
+  for (const item of raw) {
+    if (!isRecord(item)) continue;
+    const name = stringOr(item.name, "");
+    if (name === "") continue;
+    const typesRaw = item.types;
+    const types = Array.isArray(typesRaw)
+      ? typesRaw.filter((t): t is string => typeof t === "string")
+      : [];
+    fields.push({
+      name,
+      types,
+      optional: item.optional === true,
+      doc: stringOr(item.doc, ""),
+    });
+  }
+  return fields;
+}
+
+export function emitBuiltinMessages(catalog: MessageCatalog): string {
+  const entries = [...catalog.entries].sort((a, b) => a.name.localeCompare(b.name));
+  const body = entries.map(emitEntry).join("\n");
+  const inner = [
+    "declare global {",
+    "  interface BuiltinMessages {",
+    body,
+    "  }",
+    "  type BuiltinMessageId = keyof BuiltinMessages;",
+    "}",
+    "",
+    "export {};",
+    "",
+  ].join("\n");
+  const used = collectEngineTypes(inner);
+  const importLine =
+    used.length === 0 ? "" : `import type { ${used.join(", ")} } from "../src/core-types";\n\n`;
+  return `${importLine}${inner}`;
+}
+
+function emitEntry(entry: MessageEntry): string {
+  const key = TS_IDENTIFIER.test(entry.name) ? entry.name : JSON.stringify(entry.name);
+  if (entry.payload.length === 0) {
+    return `    ${key}: Record<string, never>;`;
+  }
+  const fields = entry.payload.map(emitField).join("; ");
+  return `    ${key}: { ${fields} };`;
+}
+
+function emitField(field: MessageField): string {
+  const name = TS_IDENTIFIER.test(field.name) ? field.name : JSON.stringify(field.name);
+  const optional = field.optional ? "?" : "";
+  const ts = field.types.length === 0 ? "unknown" : unionFromTokens(field.types);
+  return `${name}${optional}: ${ts}`;
+}
+
+function unionFromTokens(tokens: readonly string[]): string {
+  const seen = new Set<string>();
+  const mapped: string[] = [];
+  for (const token of tokens) {
+    const ts = mapToken(token);
+    if (seen.has(ts)) continue;
+    seen.add(ts);
+    mapped.push(ts);
+  }
+  return mapped.join(" | ");
+}
+
+function mapToken(token: string): string {
+  if (Object.hasOwn(DEFOLD_TYPE_MAP, token)) {
+    const mapped = DEFOLD_TYPE_MAP[token];
+    if (typeof mapped === "string") return mapped;
+  }
+  return token;
+}
+
+function collectEngineTypes(emitted: string): string[] {
+  return ENGINE_TYPES.filter((t) => new RegExp(`\\b${t}\\b`).test(emitted));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringOr(value: unknown, fallback: string): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function describeKind(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}

package/src/go-overloads.d.ts

@@ -0,0 +1,35 @@
+/** @noSelfInFile */
+import type { Hash, Opaque, Quaternion, Url, Vector3, Vector4 } from "./core-types";
+
+declare global {
+  namespace go {
+    interface GoPropertyOptions {
+      index?: number;
+      key?: Hash;
+      keys?: Record<string | number, unknown>;
+    }
+
+    function get<K extends keyof go.properties>(
+      url: string | Hash | Url,
+      property: K,
+      options?: GoPropertyOptions,
+    ): go.properties[K];
+    function get(
+      url: string | Hash | Url,
+      property: string | Hash,
+      options?: GoPropertyOptions,
+    ): number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource">;
+    function set<K extends keyof go.properties>(
+      url: string | Hash | Url,
+      property: K,
+      value: go.properties[K],
+      options?: GoPropertyOptions,
+    ): void;
+    function set(
+      url: string | Hash | Url,
+      property: string | Hash,
+      value: number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource">,
+      options?: GoPropertyOptions,
+    ): void;
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+export type { ApiFunction, ApiModule, ApiParameter, ApiVariable } from "./api-doc";
+export { parseDefoldApiDoc } from "./api-doc";
+export {
+  DEFOLD_TYPE_MAP,
+  type Hash,
+  type Matrix4,
+  type Quaternion,
+  type Url,
+  type Vector,
+  type Vector3,
+  type Vector4,
+} from "./core-types";
+export { type EmitOptions, emitDeclarations } from "./emit-dts";
+export {
+  defineGuiScript,
+  defineRenderScript,
+  defineScript,
+  type GuiScriptHooks,
+  type InputAction,
+  type InputTouch,
+  type RenderScriptHooks,
+  type ScriptHooks,
+} from "./lifecycle";
+export { type WrapOptions, wrapAsAmbientGlobal } from "./publish-dts";

package/src/lifecycle.ts

@@ -0,0 +1,81 @@
+import type { Hash, Url } from "./core-types";
+
+type OnMessagePayload<K> = K extends BuiltinMessageId
+  ? BuiltinMessages[K]
+  : Record<string | number, unknown>;
+
+export interface InputTouch {
+  id?: number;
+  pressed?: boolean;
+  released?: boolean;
+  tap_count?: number;
+  x?: number;
+  y?: number;
+  dx?: number;
+  dy?: number;
+  acc_x?: number;
+  acc_y?: number;
+  acc_z?: number;
+}
+
+export interface InputAction {
+  value?: number;
+  pressed?: boolean;
+  released?: boolean;
+  repeated?: boolean;
+  x?: number;
+  y?: number;
+  screen_x?: number;
+  screen_y?: number;
+  dx?: number;
+  dy?: number;
+  screen_dx?: number;
+  screen_dy?: number;
+  gamepad?: number;
+  userid?: number;
+  gamepad_unknown?: boolean;
+  gamepad_name?: string;
+  gamepad_axis?: number[];
+  gamepadhats?: number[];
+  gamepad_buttons?: number[];
+  touch?: InputTouch[];
+  text?: string;
+  marked_text?: string;
+}
+
+export interface ScriptHooks<TSelf> {
+  init?(self: TSelf): void;
+  update?(self: TSelf, dt: number): void;
+  on_message?<K extends string>(
+    self: TSelf,
+    message_id: K,
+    message: OnMessagePayload<K>,
+    sender: Url,
+  ): void;
+  on_input?(
+    self: TSelf,
+    action_id: Hash | undefined,
+    action: InputAction,
+    // biome-ignore lint/suspicious/noConfusingVoidType: Defold lets handlers omit the return; `void` is the right shape for "may return boolean or nothing".
+  ): boolean | void;
+  final?(self: TSelf): void;
+  on_reload?(self: TSelf): void;
+}
+
+export type GuiScriptHooks<TSelf> = ScriptHooks<TSelf>;
+
+export type RenderScriptHooks<TSelf> = Omit<ScriptHooks<TSelf>, "on_input">;
+
+export function defineScript<TSelf>(hooks: ScriptHooks<TSelf>): ScriptHooks<TSelf> {
+  return hooks;
+}
+
+export function defineGuiScript<TSelf>(hooks: GuiScriptHooks<TSelf>): GuiScriptHooks<TSelf> {
+  return hooks;
+}
+
+export function defineRenderScript<TSelf>(
+  hooks: RenderScriptHooks<TSelf>,
+): RenderScriptHooks<TSelf> {
+  return hooks;
+}

package/src/msg-overloads.d.ts

@@ -0,0 +1,21 @@
+/** @noSelfInFile */
+import type { Hash, Url } from "./core-types";
+
+type MsgPostPayload<K> = K extends BuiltinMessageId
+  ? BuiltinMessages[K]
+  : Record<string | number, unknown>;
+
+declare global {
+  namespace msg {
+    function post<K extends string>(
+      receiver: string | Url | Hash,
+      message_id: K,
+      message?: MsgPostPayload<K>,
+    ): void;
+    function post(
+      receiver: string | Url | Hash,
+      message_id: Hash,
+      message?: Record<string | number, unknown>,
+    ): void;
+  }
+}

package/src/publish-dts.ts

@@ -0,0 +1,33 @@
+const ENGINE_TYPES = [
+  "Hash",
+  "Matrix4",
+  "Opaque",
+  "Quaternion",
+  "Url",
+  "Vector",
+  "Vector3",
+  "Vector4",
+] as const;
+type EngineType = (typeof ENGINE_TYPES)[number];
+
+export interface WrapOptions {
+  namespace: string;
+  emitted: string;
+  importsFrom: string;
+}
+
+export function wrapAsAmbientGlobal(opts: WrapOptions): string {
+  const used = collectEngineTypes(opts.emitted);
+  const importLine =
+    used.length === 0 ? "" : `import type { ${used.join(", ")} } from "${opts.importsFrom}";\n\n`;
+  const inner = opts.emitted.replace(/^declare\s+namespace\s+/, "namespace ").trimEnd();
+  const indented = inner
+    .split("\n")
+    .map((l) => (l.length === 0 ? l : `  ${l}`))
+    .join("\n");
+  return `/** @noSelfInFile */\n${importLine}declare global {\n${indented}\n}\n\nexport {};\n`;
+}
+
+function collectEngineTypes(emitted: string): EngineType[] {
+  return ENGINE_TYPES.filter((t) => new RegExp(`\\b${t}\\b`).test(emitted));
+}

package/src/script-api.ts

@@ -0,0 +1,95 @@
+import { parse } from "yaml";
+
+export interface RefDocParameter {
+  name: string;
+  doc: string;
+  types: string[];
+}
+
+export interface RefDocElement {
+  type: "FUNCTION";
+  name: string;
+  description: string;
+  parameters: RefDocParameter[];
+  returnvalues: RefDocParameter[];
+}
+
+export interface RefDoc {
+  info: { namespace: string; brief: string; description: string };
+  elements: RefDocElement[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringOr(value: unknown, fallback: string): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function mapParameters(raw: unknown): RefDocParameter[] {
+  if (!Array.isArray(raw)) return [];
+  const out: RefDocParameter[] = [];
+  for (const item of raw) {
+    if (!isRecord(item)) continue;
+    const name = stringOr(item.name, "");
+    // The script_api lists the implicit `self` the engine passes; the emitter
+    // stamps @noSelfInFile, so generated signatures must not declare it.
+    if (name === "self") continue;
+    const type = item.type;
+    out.push({
+      name,
+      doc: stringOr(item.desc, ""),
+      types: typeof type === "string" ? [type] : [],
+    });
+  }
+  return out;
+}
+
+/**
+ * Convert a parsed Defold extension `.script_api` document into the core
+ * ref-doc JSON object shape that `parseDefoldApiDoc` consumes. Only
+ * `type: function` members are carried; scalar members (constants) are
+ * dropped, matching the core ref-doc pipeline where non-function elements
+ * never reach the emitter.
+ */
+export function scriptApiToRefDoc(parsed: unknown): RefDoc {
+  if (!Array.isArray(parsed)) {
+    throw new Error("scriptApiToRefDoc: expected a top-level YAML list");
+  }
+  const tables = parsed.filter(
+    (e): e is Record<string, unknown> => isRecord(e) && e.type === "table",
+  );
+  if (tables.length === 0) {
+    throw new Error("scriptApiToRefDoc: no top-level `type: table` namespace entry found");
+  }
+  if (tables.length > 1) {
+    throw new Error("scriptApiToRefDoc: expected exactly one top-level table, found multiple");
+  }
+  const table = tables[0] as Record<string, unknown>;
+  const namespace = stringOr(table.name, "");
+  if (namespace.length === 0) {
+    throw new Error("scriptApiToRefDoc: top-level table is missing a `name`");
+  }
+  const members = Array.isArray(table.members) ? table.members : [];
+  const elements: RefDocElement[] = [];
+  for (const member of members) {
+    if (!isRecord(member) || member.type !== "function") continue;
+    elements.push({
+      type: "FUNCTION",
+      name: `${namespace}.${stringOr(member.name, "")}`,
+      description: stringOr(member.desc, ""),
+      parameters: mapParameters(member.parameters),
+      returnvalues: mapParameters(member.returns),
+    });
+  }
+  const doc: RefDoc = {
+    info: { namespace, brief: stringOr(table.desc, ""), description: stringOr(table.desc, "") },
+    elements,
+  };
+  return doc;
+}
+
+export function parseScriptApi(yamlText: string): RefDoc {
+  return scriptApiToRefDoc(parse(yamlText));
+}