@defold-typescript/types 0.5.4 → 0.6.0

package/src/lifecycle.ts

@@ -39,12 +39,32 @@ export interface InputAction {
   marked_text?: string;
 }
 
-export interface ScriptHooks<TSelf> {
+/**
+ * Phantom type carried by `go.property()` descriptors.
+ *
+ * @deprecated Declare properties with the value-keyed `properties` field inside
+ * `defineScript({ properties })` — that form types them onto `self` directly and
+ * needs no descriptor. The `go.property` escape hatch still returns this for
+ * backward compatibility.
+ */
+export interface ScriptProperty<TValue> {
+  readonly __defoldScriptProperty: TValue;
+}
+
+/**
+ * @deprecated Use the value-keyed `properties` field of `defineScript`; the
+ * descriptor-plus-`ScriptProperties` extraction is no longer needed.
+ */
+export type ScriptProperties<T extends Record<string, ScriptProperty<unknown>>> = {
+  [K in keyof T]: T[K] extends ScriptProperty<infer TValue> ? TValue : never;
+};
+
+export interface ScriptHooks<TSelf, TInitState = TSelf> {
   // `init` returns the script's initial state; it is the sole site TypeScript
-  // solves `TSelf` from. The engine owns `self` (a userdata-backed table), so
-  // every other hook wraps it in `NoInfer<TSelf>` — otherwise their `self`
+  // solves `TInitState` from. The engine owns `self` (a userdata-backed table),
+  // so every other hook wraps it in `NoInfer<TSelf>` — otherwise their `self`
   // competes as a second inference site and `TSelf` collapses to `{}`.
-  init?(): TSelf;
+  init?(): TInitState;
   update?(self: NoInfer<TSelf>, dt: number): void;
   fixed_update?(self: NoInfer<TSelf>, dt: number): void;
   late_update?(self: NoInfer<TSelf>, dt: number): void;
@@ -84,27 +104,148 @@ type Equal<A, B> =
   (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
 
 // drift-pin: SCRIPT_HOOK_NAMES must list exactly the ScriptHooks members
-const _hookNamesPinnedToInterface: Equal<ScriptHookName, keyof ScriptHooks<unknown>> = true;
+const _hookNamesPinnedToInterface: Equal<ScriptHookName, keyof ScriptHooks<unknown, unknown>> =
+  true;
 void _hookNamesPinnedToInterface;
 
-export type GuiScriptHooks<TSelf> = ScriptHooks<TSelf>;
+export type GuiScriptHooks<TSelf, TInitState = TSelf> = ScriptHooks<TSelf, TInitState>;
+
+export type RenderScriptHooks<TSelf, TInitState = TSelf> = Omit<
+  ScriptHooks<TSelf, TInitState>,
+  "on_input"
+>;
+
+// The factory hook table plus the value-keyed `properties` field. `TProps` is
+// the property channel (raw default values), `TSelf` the merged `self` the
+// callbacks see (`NoInfer`-wrapped inside the hook set), and `TInitState` what
+// `init` returns. `ScriptHooks` itself stays callback-only so the
+// `SCRIPT_HOOK_NAMES` drift pin remains valid.
+export type ScriptHooksWithProperties<TProps, TSelf, TInitState> = ScriptHooks<
+  TSelf,
+  TInitState
+> & {
+  properties?: TProps;
+};
+
+export type GuiScriptHooksWithProperties<TProps, TSelf, TInitState> = GuiScriptHooks<
+  TSelf,
+  TInitState
+> & {
+  properties?: TProps;
+};
 
-export type RenderScriptHooks<TSelf> = Omit<ScriptHooks<TSelf>, "on_input">;
+export type RenderScriptHooksWithProperties<TProps, TSelf, TInitState> = RenderScriptHooks<
+  TSelf,
+  TInitState
+> & {
+  properties?: TProps;
+};
 
-export function defineScript<TSelf = Record<never, never>>(
-  hooks: ScriptHooks<TSelf>,
-): ScriptHooks<TSelf> {
+/**
+ * Type a `.script` component's hook table. At runtime this is an identity
+ * function — it returns `hooks` unchanged; its only job is typing. It infers
+ * `TSelf` from `init`'s return so every other hook's `self` is typed. Declare
+ * editor properties with the value-keyed `properties` field — the key is the
+ * property name and the value its default, so the value's type threads onto
+ * `self` alongside `init`'s state. The transpiler's `lifecycle-erasure` pass
+ * rewrites the top-level call into the flat `function init(self) … end` Defold
+ * chunk shape and synthesizes the `go.property(...)` registrations — zero
+ * runtime cost, nothing the engine sees changes.
+ *
+ * Accepts the full `ScriptHooks` set, all optional: `init`, `update`,
+ * `fixed_update`, `late_update`, `on_message`, `on_input`, `final`,
+ * `on_reload`.
+ *
+ * Scaffold it with the `defold-script` / `defold-script-typed` VSCode snippets
+ * from `defold-typescript init`.
+ *
+ * @param hooks - the `.script` lifecycle hook table to type and return.
+ * @returns the same `hooks` object, now typed (identity at runtime).
+ * @example
+ * ```ts
+ * export default defineScript({
+ *   init() {
+ *     return { hits: 0 };
+ *   },
+ *   update(self, dt) {
+ *     self.hits += 1;
+ *   },
+ * });
+ * ```
+ */
+export function defineScript<TProps extends object = Record<never, never>, TInitState = TProps>(
+  hooks: ScriptHooksWithProperties<TProps, TProps & TInitState, TInitState>,
+): ScriptHooksWithProperties<TProps, TProps & TInitState, TInitState> {
   return hooks;
 }
 
-export function defineGuiScript<TSelf = Record<never, never>>(
-  hooks: GuiScriptHooks<TSelf>,
-): GuiScriptHooks<TSelf> {
+/**
+ * Type a `.gui_script` component's hook table. Like {@link defineScript} it is
+ * an identity function at runtime, infers `TSelf` from `init`'s return by
+ * default, accepts the same value-keyed `properties` field as
+ * {@link defineScript}, and is erased by the transpiler's `lifecycle-erasure`
+ * pass into the flat Defold chunk shape.
+ *
+ * `GuiScriptHooks` is an alias of the `.script` hook set, so it accepts the same
+ * full set, all optional: `init`, `update`, `fixed_update`, `late_update`,
+ * `on_message`, `on_input`, `final`, `on_reload`.
+ *
+ * Scaffold it with the `defold-gui` / `defold-gui-typed` VSCode snippets from
+ * `defold-typescript init`.
+ *
+ * @param hooks - the `.gui_script` lifecycle hook table to type and return.
+ * @returns the same `hooks` object, now typed (identity at runtime).
+ * @example
+ * ```ts
+ * export default defineGuiScript({
+ *   init() {
+ *     return { node: gui.get_node("score") };
+ *   },
+ *   on_input(self, action_id, action) {
+ *     return false;
+ *   },
+ * });
+ * ```
+ */
+export function defineGuiScript<TProps extends object = Record<never, never>, TInitState = TProps>(
+  hooks: GuiScriptHooksWithProperties<TProps, TProps & TInitState, TInitState>,
+): GuiScriptHooksWithProperties<TProps, TProps & TInitState, TInitState> {
   return hooks;
 }
 
-export function defineRenderScript<TSelf = Record<never, never>>(
-  hooks: RenderScriptHooks<TSelf>,
-): RenderScriptHooks<TSelf> {
+/**
+ * Type a `.render_script` component's hook table. Like {@link defineScript} it
+ * is an identity function at runtime, infers `TSelf` from `init`'s return by
+ * default, accepts the same value-keyed `properties` field as
+ * {@link defineScript}, and is erased by the transpiler's `lifecycle-erasure`
+ * pass into the flat Defold chunk shape.
+ *
+ * `RenderScriptHooks` is `Omit<ScriptHooks, "on_input">` — render scripts do not
+ * receive input. It accepts the rest of the set, all optional: `init`,
+ * `update`, `fixed_update`, `late_update`, `on_message`, `final`, `on_reload`.
+ *
+ * Scaffold it with the `defold-render` / `defold-render-typed` VSCode snippets
+ * from `defold-typescript init`.
+ *
+ * @param hooks - the `.render_script` lifecycle hook table to type and return.
+ * @returns the same `hooks` object, now typed (identity at runtime).
+ * @example
+ * ```ts
+ * export default defineRenderScript({
+ *   init() {
+ *     return { clear: vmath.vector4(0, 0, 0, 1) };
+ *   },
+ *   update(self, dt) {
+ *     render.set_render_target(render.RENDER_TARGET_DEFAULT);
+ *   },
+ * });
+ * ```
+ */
+export function defineRenderScript<
+  TProps extends object = Record<never, never>,
+  TInitState = TProps,
+>(
+  hooks: RenderScriptHooksWithProperties<TProps, TProps & TInitState, TInitState>,
+): RenderScriptHooksWithProperties<TProps, TProps & TInitState, TInitState> {
   return hooks;
 }

package/src/message-dispatch.d.ts

@@ -10,6 +10,27 @@ declare global {
   // The transpiler lowers the call to a flat `message_id == hash("...")`
   // if/elseif chain (message-dispatch-lowering.ts), keeping this package free of
   // runtime Lua.
+  /**
+   * Discriminated-union dispatcher for `on_message`: takes a record of per-message
+   * handlers keyed by builtin message id, each receiving its `BuiltinMessages`
+   * payload already narrowed, and returns the `on_message` handler that routes to
+   * them. Reads as `on_message: onMessage<Self>({ ... })`; `self` threads via the
+   * explicit type argument, mirroring `defineScript<Self>`. The transpiler lowers
+   * it to a flat `if/elseif message_id == hash("...")` chain.
+   *
+   * @param handlers - a partial map from builtin message id to its handler; each handler's `message` is narrowed to that id's payload.
+   * @returns the `on_message` lifecycle handler that dispatches to the matching entry.
+   * @example
+   * ```ts
+   * defineScript({
+   *   on_message: onMessage({
+   *     contact_point_response(self, message, sender) {
+   *       print(message.other_group);
+   *     },
+   *   }),
+   * });
+   * ```
+   */
   function onMessage<TSelf = Record<never, never>>(
     handlers: Partial<{
       [K in BuiltinMessageId]: (self: TSelf, message: BuiltinMessages[K], sender: Url) => void;

package/src/message-guard.d.ts

@@ -8,6 +8,25 @@ declare global {
   // untyped `message` record narrow to its `BuiltinMessages` payload. The
   // transpiler lowers the call to `message_id == hash("...")`
   // (message-guard-lowering.ts), keeping this package free of runtime Lua.
+  /**
+   * Type guard for an `on_message` handler: narrows the untyped `message` record
+   * to its `BuiltinMessages` payload when `message_id` matches a known builtin
+   * message id. The engine delivers `message_id` as a pre-hashed `Hash`, so this
+   * guard re-introduces the literal a discriminated union would otherwise need.
+   *
+   * @param message_id - the hashed message id `on_message` received.
+   * @param message - the untyped message record `on_message` received.
+   * @param expected - the builtin message id to test against (e.g. `"contact_point_response"`).
+   * @returns `true` when `message_id` matches `expected`, narrowing `message` to that payload.
+   * @example
+   * ```ts
+   * function on_message(this: void, message_id: Hash, message: object, sender: Url) {
+   *   if (isMessage(message_id, message, "contact_point_response")) {
+   *     print(message.other_group);
+   *   }
+   * }
+   * ```
+   */
   function isMessage<K extends BuiltinMessageId>(
     message_id: Hash,
     message: Record<string | number, unknown>,

package/src/msg-overloads.d.ts

@@ -7,6 +7,26 @@ type MsgPostPayload<K> = K extends BuiltinMessageId
 
 declare global {
   namespace msg {
+    /**
+     * Post a message to a receiving URL. The most common case is to send messages
+     * to a component. If the component part of the receiver is omitted, the message
+     * is broadcast to all components in the game object.
+     * The following receiver shorthands are available:
+     * - `"."` the current game object
+     * - `"#"` the current component
+     * There is a 2 kilobyte limit to the message parameter table size.
+     *
+     * @param receiver - The receiver must be a string in URL-format, a URL object or a hashed string.
+     * @param message_id - The id must be a string or a hashed string.
+     * @param message - a lua table with message parameters to send.
+     * @example
+     * ```ts
+     * msg.post("#collisionobject", "apply_force", {
+     *   force: vmath.vector3(0, 1000, 0),
+     *   position: go.get_world_position(),
+     * });
+     * ```
+     */
     function post<K extends string>(
       receiver: string | Url | Hash,
       message_id: K,

package/src/publish-dts.ts

@@ -20,7 +20,7 @@ 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 inner = opts.emitted.replace(/(^|\n)declare\s+namespace\s+/, "$1namespace ").trimEnd();
   const indented = inner
     .split("\n")
     .map((l) => (l.length === 0 ? l : `  ${l}`))