@defold-typescript/types 0.5.5 → 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/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}`))