@defold-typescript/types 0.33.0 → 0.33.1

package/generated/resource.d.ts

@@ -526,7 +526,7 @@ declare global {
      * });
      * ```
      */
-    function create_texture(path: string, table: { type?: number; width?: number; height?: number; depth?: number; format?: number; flags?: number; max_mipmaps?: number; compression_type?: number }, buffer: Opaque<"buffer">): Hash;
+    function create_texture(path: string, table: { type?: number; width?: number; height?: number; depth?: number; format?: number; flags?: number; max_mipmaps?: number; compression_type?: number }, buffer?: Opaque<"buffer">): Hash;
     /**
      * Creates a new texture resource that can be used in the same way as any texture created during build time.
      * The path used for creating the texture must be unique, trying to create a resource at a path that is already
@@ -715,7 +715,7 @@ declare global {
      * });
      * ```
      */
-    function create_texture_async(path: string | Hash, table: { type?: number; width?: number; height?: number; depth?: number; format?: number; flags?: number; max_mipmaps?: number; compression_type?: number }, buffer: Opaque<"buffer">, callback: (...args: unknown[]) => unknown): LuaMultiReturn<[Hash, number]>;
+    function create_texture_async(path: string | Hash, table: { type?: number; width?: number; height?: number; depth?: number; format?: number; flags?: number; max_mipmaps?: number; compression_type?: number }, buffer?: Opaque<"buffer">, callback?: (...args: unknown[]) => unknown): LuaMultiReturn<[Hash, number]>;
     /**
      * Constructor-like function with two purposes:
      *

package/generated/sys.d.ts

@@ -607,7 +607,7 @@ declare global {
      * sys.set_engine_throttle(true, 1.5);
      * ```
      */
-    function set_engine_throttle(enable: boolean, cooldown: number): void;
+    function set_engine_throttle(enable: boolean, cooldown?: number): void;
     /**
      * Set the Lua error handler function.
      * The error handler is a function which is called whenever a lua runtime error occurs.

package/generated/versions/defold-1.12.4/gui.d.ts

@@ -1366,7 +1366,7 @@ declare global {
      * gui.set_texture(n, path);
      * ```
      */
-    function new_texture(texture_id: string | Hash, width: number, height: number, type: string | Opaque<"constant">, buffer: string, flip: boolean): LuaMultiReturn<[boolean, number]>;
+    function new_texture(texture_id: string | Hash, width: number, height: number, type: string | Opaque<"constant">, buffer: string, flip?: boolean): LuaMultiReturn<[boolean, number]>;
     /**
      * This is a callback-function, which is called by the engine when user input is sent to the instance of the gui component.
      * It can be used to take action on the input, e.g. modify the gui according to the input.
@@ -2229,7 +2229,7 @@ declare global {
      * });
      * ```
      */
-    function set_texture_data(texture: string | Hash, width: number, height: number, type: string | Opaque<"constant">, buffer: string, flip: boolean): boolean;
+    function set_texture_data(texture: string | Hash, width: number, height: number, type: string | Opaque<"constant">, buffer: string, flip?: boolean): boolean;
     /**
      * Sets the tracking value of a text node. This value is used to
      * adjust the vertical spacing of characters in the text.

package/generated/versions/defold-1.12.4/iap.d.ts

@@ -18,7 +18,7 @@ declare global {
      * @param id - product to buy
      * @param options - optional parameters as properties. The following parameters can be set
      */
-    function buy(id: string, options: { request_id?: string; token?: string }): void;
+    function buy(id: string, options?: { request_id?: string; token?: string }): void;
     /**
      * Explicitly finish a product transaction. [icon:attention] Calling iap.finish is required on a successful transaction if `auto_finish_transactions` is disabled in project settings. Calling this function with `auto_finish_transactions` set will be ignored and a warning is printed. The `transaction.state` field must equal `iap.TRANS_STATE_PURCHASED`.
      *

package/generated/versions/defold-1.12.4/resource.d.ts

@@ -526,7 +526,7 @@ declare global {
      * });
      * ```
      */
-    function create_texture(path: string, table: { type?: number; width?: number; height?: number; depth?: number; format?: number; flags?: number; max_mipmaps?: number; compression_type?: number }, buffer: Opaque<"buffer">): Hash;
+    function create_texture(path: string, table: { type?: number; width?: number; height?: number; depth?: number; format?: number; flags?: number; max_mipmaps?: number; compression_type?: number }, buffer?: Opaque<"buffer">): Hash;
     /**
      * Creates a new texture resource that can be used in the same way as any texture created during build time.
      * The path used for creating the texture must be unique, trying to create a resource at a path that is already
@@ -715,7 +715,7 @@ declare global {
      * });
      * ```
      */
-    function create_texture_async(path: string | Hash, table: { type?: number; width?: number; height?: number; depth?: number; format?: number; flags?: number; max_mipmaps?: number; compression_type?: number }, buffer: Opaque<"buffer">, callback: (...args: unknown[]) => unknown): LuaMultiReturn<[Hash, number]>;
+    function create_texture_async(path: string | Hash, table: { type?: number; width?: number; height?: number; depth?: number; format?: number; flags?: number; max_mipmaps?: number; compression_type?: number }, buffer?: Opaque<"buffer">, callback?: (...args: unknown[]) => unknown): LuaMultiReturn<[Hash, number]>;
     /**
      * Constructor-like function with two purposes:
      *

package/generated/versions/defold-1.12.4/sys.d.ts

@@ -607,7 +607,7 @@ declare global {
      * sys.set_engine_throttle(true, 1.5);
      * ```
      */
-    function set_engine_throttle(enable: boolean, cooldown: number): void;
+    function set_engine_throttle(enable: boolean, cooldown?: number): void;
     /**
      * Set the Lua error handler function.
      * The error handler is a function which is called whenever a lua runtime error occurs.

package/generated/versions/defold-1.13.0/b2d_fixture.d.ts

@@ -140,7 +140,7 @@ declare global {
      * b2d.fixture.set_shape(body, 2, { type: b2d.shape.SHAPE_TYPE_EDGE, v1: vmath.vector3(-32, 0, 0), v2: vmath.vector3(32, 0, 0) });
      * ```
      */
-    function set_shape(body: Opaque<"b2Body">, fixture_index: number, shape: { type?: number; radius?: number; center?: Vector3; v0?: Vector3; v1?: Vector3; v2?: Vector3; v3?: Vector3; vertices?: Vector3[]; hx?: number; hy?: number; angle?: number; loop?: boolean; prev_vertex?: Vector3; next_vertex?: Vector3 }, update_mass: boolean): void;
+    function set_shape(body: Opaque<"b2Body">, fixture_index: number, shape: { type?: number; radius?: number; center?: Vector3; v0?: Vector3; v1?: Vector3; v2?: Vector3; v3?: Vector3; vertices?: Vector3[]; hx?: number; hy?: number; angle?: number; loop?: boolean; prev_vertex?: Vector3; next_vertex?: Vector3 }, update_mass?: boolean): void;
     /**
      * Test a point against a fixture.
      *

package/generated/versions/defold-1.13.0/b2d_joint.d.ts

@@ -83,7 +83,7 @@ declare global {
      * @param definition - optional definition with `local_anchor_a`, `local_anchor_b`, `length`, `frequency`, `damping_ratio`, and `collide_connected`
      * @returns created joint
      */
-    function create_distance(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition: { local_anchor_a?: Vector3; local_anchor_b?: Vector3; length?: number; frequency?: number; damping_ratio?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
+    function create_distance(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition?: { local_anchor_a?: Vector3; local_anchor_b?: Vector3; length?: number; frequency?: number; damping_ratio?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
     /**
      * Create a filter joint.
      *
@@ -92,7 +92,7 @@ declare global {
      * @param definition - optional definition table
      * @returns created joint
      */
-    function create_filter(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition: Record<string | number, unknown>): Opaque<"b2Joint">;
+    function create_filter(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition?: Record<string | number, unknown>): Opaque<"b2Joint">;
     /**
      * Create a friction joint.
      *
@@ -101,7 +101,7 @@ declare global {
      * @param definition - optional definition with `local_anchor_a`, `local_anchor_b`, `max_force`, `max_torque`, and `collide_connected`
      * @returns created joint
      */
-    function create_friction(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition: { local_anchor_a?: Vector3; local_anchor_b?: Vector3; max_force?: number; max_torque?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
+    function create_friction(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition?: { local_anchor_a?: Vector3; local_anchor_b?: Vector3; max_force?: number; max_torque?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
     /**
      * Create a gear joint.
      *
@@ -110,7 +110,7 @@ declare global {
      * @param definition - optional definition with `ratio`
      * @returns created joint
      */
-    function create_gear(joint1: Opaque<"b2Joint">, joint2: Opaque<"b2Joint">, definition: { ratio?: number }): Opaque<"b2Joint">;
+    function create_gear(joint1: Opaque<"b2Joint">, joint2: Opaque<"b2Joint">, definition?: { ratio?: number }): Opaque<"b2Joint">;
     /**
      * Create a motor joint.
      *
@@ -119,7 +119,7 @@ declare global {
      * @param definition - optional definition with `linear_offset`, `angular_offset`, `max_force`, `max_torque`, `correction_factor`, and `collide_connected`
      * @returns created joint
      */
-    function create_motor(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition: { linear_offset?: Vector3; angular_offset?: number; max_force?: number; max_torque?: number; correction_factor?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
+    function create_motor(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition?: { linear_offset?: Vector3; angular_offset?: number; max_force?: number; max_torque?: number; correction_factor?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
     /**
      * Create a mouse joint.
      *
@@ -128,7 +128,7 @@ declare global {
      * @param definition - optional definition with `target`, `max_force`, `frequency`, `damping_ratio`, and `collide_connected`
      * @returns created joint
      */
-    function create_mouse(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition: { target?: Vector3; max_force?: number; frequency?: number; damping_ratio?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
+    function create_mouse(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition?: { target?: Vector3; max_force?: number; frequency?: number; damping_ratio?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
     /**
      * Create a prismatic joint.
      *
@@ -137,7 +137,7 @@ declare global {
      * @param definition - optional definition with `local_anchor_a`, `local_anchor_b`, `local_axis_a`, `reference_angle`, `enable_limit`, `lower_translation`, `upper_translation`, `enable_motor`, `max_motor_force`, `motor_speed`, and `collide_connected`
      * @returns created joint
      */
-    function create_prismatic(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition: { local_anchor_a?: Vector3; local_anchor_b?: Vector3; local_axis_a?: Vector3; reference_angle?: number; enable_limit?: boolean; lower_translation?: number; upper_translation?: number; enable_motor?: boolean; max_motor_force?: number; motor_speed?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
+    function create_prismatic(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition?: { local_anchor_a?: Vector3; local_anchor_b?: Vector3; local_axis_a?: Vector3; reference_angle?: number; enable_limit?: boolean; lower_translation?: number; upper_translation?: number; enable_motor?: boolean; max_motor_force?: number; motor_speed?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
     /**
      * Create a pulley joint.
      *
@@ -146,7 +146,7 @@ declare global {
      * @param definition - optional definition with `ground_anchor_a`, `ground_anchor_b`, `local_anchor_a`, `local_anchor_b`, `length_a`, `length_b`, `ratio`, and `collide_connected`
      * @returns created joint
      */
-    function create_pulley(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition: { ground_anchor_a?: Vector3; ground_anchor_b?: Vector3; local_anchor_a?: Vector3; local_anchor_b?: Vector3; length_a?: number; length_b?: number; ratio?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
+    function create_pulley(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition?: { ground_anchor_a?: Vector3; ground_anchor_b?: Vector3; local_anchor_a?: Vector3; local_anchor_b?: Vector3; length_a?: number; length_b?: number; ratio?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
     /**
      * Create a revolute joint.
      *
@@ -155,7 +155,7 @@ declare global {
      * @param definition - optional definition with `local_anchor_a`, `local_anchor_b`, `reference_angle`, `enable_limit`, `lower_angle`, `upper_angle`, `enable_motor`, `max_motor_torque`, `motor_speed`, and `collide_connected`
      * @returns created joint
      */
-    function create_revolute(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition: { local_anchor_a?: Vector3; local_anchor_b?: Vector3; reference_angle?: number; enable_limit?: boolean; lower_angle?: number; upper_angle?: number; enable_motor?: boolean; max_motor_torque?: number; motor_speed?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
+    function create_revolute(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition?: { local_anchor_a?: Vector3; local_anchor_b?: Vector3; reference_angle?: number; enable_limit?: boolean; lower_angle?: number; upper_angle?: number; enable_motor?: boolean; max_motor_torque?: number; motor_speed?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
     /**
      * Create a rope joint.
      *
@@ -164,7 +164,7 @@ declare global {
      * @param definition - optional definition with `local_anchor_a`, `local_anchor_b`, `max_length`, and `collide_connected`
      * @returns created joint
      */
-    function create_rope(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition: { local_anchor_a?: Vector3; local_anchor_b?: Vector3; max_length?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
+    function create_rope(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition?: { local_anchor_a?: Vector3; local_anchor_b?: Vector3; max_length?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
     /**
      * Create a weld joint.
      *
@@ -173,7 +173,7 @@ declare global {
      * @param definition - optional definition with `local_anchor_a`, `local_anchor_b`, `reference_angle`, `frequency`, `damping_ratio`, and `collide_connected`
      * @returns created joint
      */
-    function create_weld(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition: { local_anchor_a?: Vector3; local_anchor_b?: Vector3; reference_angle?: number; frequency?: number; damping_ratio?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
+    function create_weld(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition?: { local_anchor_a?: Vector3; local_anchor_b?: Vector3; reference_angle?: number; frequency?: number; damping_ratio?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
     /**
      * Create a wheel joint.
      *
@@ -182,7 +182,7 @@ declare global {
      * @param definition - optional definition with `local_anchor_a`, `local_anchor_b`, `local_axis_a`, `enable_motor`, `max_motor_torque`, `motor_speed`, `frequency`, `damping_ratio`, and `collide_connected`
      * @returns created joint
      */
-    function create_wheel(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition: { local_anchor_a?: Vector3; local_anchor_b?: Vector3; local_axis_a?: Vector3; enable_motor?: boolean; max_motor_torque?: number; motor_speed?: number; frequency?: number; damping_ratio?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
+    function create_wheel(body_a: Opaque<"b2Body">, body_b: Opaque<"b2Body">, definition?: { local_anchor_a?: Vector3; local_anchor_b?: Vector3; local_axis_a?: Vector3; enable_motor?: boolean; max_motor_torque?: number; motor_speed?: number; frequency?: number; damping_ratio?: number; collide_connected?: boolean }): Opaque<"b2Joint">;
     /**
      * Destroy a joint created by `b2d.joint`.
      *

package/generated/versions/defold-1.13.0/b2d_shape.d.ts

@@ -183,7 +183,7 @@ declare global {
      * @param max_fraction - optional maximum translation fraction, defaults to 1
      * @returns hit table with `point`, `normal`, `fraction`, and `iterations`, or nil
      */
-    function ray_cast(shape_id: Opaque<"b2Shape">, origin: Vector3, translation: Vector3, max_fraction: number): { point: Vector3; normal: Vector3; fraction: number; iterations: number };
+    function ray_cast(shape_id: Opaque<"b2Shape">, origin: Vector3, translation: Vector3, max_fraction?: number): { point: Vector3; normal: Vector3; fraction: number; iterations: number };
     /**
      * Set shape material id.
      *

package/generated/versions/defold-1.13.0/gui.d.ts

@@ -1364,7 +1364,7 @@ declare global {
      * gui.set_texture(n, path);
      * ```
      */
-    function new_texture(texture_id: string | Hash, width: number, height: number, type: string | Opaque<"constant">, buffer: string, flip: boolean): LuaMultiReturn<[boolean, number]>;
+    function new_texture(texture_id: string | Hash, width: number, height: number, type: string | Opaque<"constant">, buffer: string, flip?: boolean): LuaMultiReturn<[boolean, number]>;
     /**
      * This is a callback-function, which is called by the engine when user input is sent to the instance of the gui component.
      * It can be used to take action on the input, e.g. modify the gui according to the input.
@@ -2227,7 +2227,7 @@ declare global {
      * });
      * ```
      */
-    function set_texture_data(texture: string | Hash, width: number, height: number, type: string | Opaque<"constant">, buffer: string, flip: boolean): boolean;
+    function set_texture_data(texture: string | Hash, width: number, height: number, type: string | Opaque<"constant">, buffer: string, flip?: boolean): boolean;
     /**
      * Sets the tracking value of a text node. This value is used to
      * adjust the vertical spacing of characters in the text.

package/generated/versions/defold-1.13.0/iap.d.ts

@@ -18,7 +18,7 @@ declare global {
      * @param id - product to buy
      * @param options - optional parameters as properties. The following parameters can be set
      */
-    function buy(id: string, options: { request_id?: string; token?: string }): void;
+    function buy(id: string, options?: { request_id?: string; token?: string }): void;
     /**
      * Explicitly finish a product transaction. [icon:attention] Calling iap.finish is required on a successful transaction if `auto_finish_transactions` is disabled in project settings. Calling this function with `auto_finish_transactions` set will be ignored and a warning is printed. The `transaction.state` field must equal `iap.TRANS_STATE_PURCHASED`.
      *

package/generated/versions/defold-1.13.0/resource.d.ts

@@ -526,7 +526,7 @@ declare global {
      * });
      * ```
      */
-    function create_texture(path: string, table: { type?: number; width?: number; height?: number; depth?: number; format?: number; flags?: number; max_mipmaps?: number; compression_type?: number }, buffer: Opaque<"buffer">): Hash;
+    function create_texture(path: string, table: { type?: number; width?: number; height?: number; depth?: number; format?: number; flags?: number; max_mipmaps?: number; compression_type?: number }, buffer?: Opaque<"buffer">): Hash;
     /**
      * Creates a new texture resource that can be used in the same way as any texture created during build time.
      * The path used for creating the texture must be unique, trying to create a resource at a path that is already
@@ -715,7 +715,7 @@ declare global {
      * });
      * ```
      */
-    function create_texture_async(path: string | Hash, table: { type?: number; width?: number; height?: number; depth?: number; format?: number; flags?: number; max_mipmaps?: number; compression_type?: number }, buffer: Opaque<"buffer">, callback: (...args: unknown[]) => unknown): LuaMultiReturn<[Hash, number]>;
+    function create_texture_async(path: string | Hash, table: { type?: number; width?: number; height?: number; depth?: number; format?: number; flags?: number; max_mipmaps?: number; compression_type?: number }, buffer?: Opaque<"buffer">, callback?: (...args: unknown[]) => unknown): LuaMultiReturn<[Hash, number]>;
     /**
      * Constructor-like function with two purposes:
      *

package/generated/versions/defold-1.13.0/sys.d.ts

@@ -607,7 +607,7 @@ declare global {
      * sys.set_engine_throttle(true, 1.5);
      * ```
      */
-    function set_engine_throttle(enable: boolean, cooldown: number): void;
+    function set_engine_throttle(enable: boolean, cooldown?: number): void;
     /**
      * Set the Lua error handler function.
      * The error handler is a function which is called whenever a lua runtime error occurs.

package/package.json

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

package/scripts/fidelity-audit.ts

@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { type ApiFunction, parseDefoldApiDoc } from "../src/api-doc";
 import { DEFOLD_TYPE_MAP } from "../src/core-types";
 import {
   ARBITRARY_TABLE_SLOT_KEYS,
@@ -8,6 +9,7 @@ import {
   buildTableDocResolver,
   HANDLE_METHOD_LOCAL,
   HOMOGENEOUS_ARRAY_SLOTS,
+  isDocOptional,
   isRecordsCollectionSlot,
   isSlotLevelList,
   MAPPING_TABLE_SLOTS,
@@ -18,6 +20,7 @@ import {
   TABLE_SLOT_CURATIONS,
   type TableSlotCuration,
   TS_IDENTIFIER,
+  trailingOptionalCutoff,
 } from "../src/emit-dts";
 import { parseMessagesDoc } from "../src/emit-messages";
 import {
@@ -87,6 +90,207 @@ export function countDroppedHandleMethods(doc: unknown, namespace: string, emit
   return dropped;
 }
 
+// Upstream ships `examples`, `description` and `brief` as syntax-highlighted HTML
+// — every token in its own span, quotes as entities — so a call site is invisible
+// to any parser until the markup is gone. `&` decodes last so an escaped
+// entity stays literal.
+function plainText(html: string): string {
+  return html
+    .replace(/<[^>]*>/g, "")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&");
+}
+
+// The arguments of the call whose `(` ends just before `start`, split on
+// top-level commas only: a comma inside a nested call, table, index or string
+// literal belongs to that argument. Null when the text ends before the call does.
+function splitArguments(text: string, start: number): string[] | null {
+  const args: string[] = [];
+  let current = "";
+  let depth = 0;
+  let quote: string | null = null;
+  for (let i = start; i < text.length; i += 1) {
+    const ch = text[i] as string;
+    if (quote !== null) {
+      current += ch;
+      if (ch === "\\") {
+        current += text[i + 1] ?? "";
+        i += 1;
+      } else if (ch === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+    } else if (ch === "(" || ch === "{" || ch === "[") {
+      depth += 1;
+    } else if (ch === ")" || ch === "}" || ch === "]") {
+      if (depth === 0) {
+        if (ch !== ")") return null;
+        const last = current.trim();
+        if (last !== "" || args.length > 0) args.push(last);
+        return args;
+      }
+      depth -= 1;
+    } else if (ch === "," && depth === 0) {
+      args.push(current.trim());
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  return null;
+}
+
+// Inline `<code>` in example prose names a function rather than calling it
+// (`<code>gui.set_texture()</code> is sufficient`). A highlighted block's `<code>`
+// always wraps token spans, so only the prose kind is bare text.
+const INLINE_CODE = /<code>[^<]*<\/code>/g;
+
+const exampleCallCache = new WeakMap<ApiFunction, readonly (readonly string[])[]>();
+
+// Every `<fqn>(…)` call in the function's upstream examples, as argument lists.
+function exampleCalls(fn: ApiFunction): readonly (readonly string[])[] {
+  const cached = exampleCallCache.get(fn);
+  if (cached !== undefined) return cached;
+  const text = plainText((fn.examples ?? "").replace(INLINE_CODE, ""));
+  const escaped = fn.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const calls: string[][] = [];
+  for (const match of text.matchAll(new RegExp(`(?<![\\w.:])${escaped}\\s*\\(`, "g"))) {
+    const args = splitArguments(text, match.index + match[0].length);
+    if (args !== null) calls.push(args);
+  }
+  exampleCallCache.set(fn, calls);
+  return calls;
+}
+
+// Whether a call passing `count` arguments fits this declaration's arity, with
+// the emitter's own trailing-optional cutoff as the floor.
+function acceptsArgumentCount(fn: ApiFunction, count: number): boolean {
+  const params = fn.parameters;
+  if (count < trailingOptionalCutoff(params, fn.name)) return false;
+  return count <= params.length || params.some((p) => p.isVararg === true);
+}
+
+// The ref-doc documents an overload as a separate element sharing the name, and
+// an element's examples often call a sibling (`vmath.vector3(2.0)` beside the
+// `x, y, z` form). A call another same-named declaration accepts is that
+// declaration's call, not an omission from this one.
+function ownExampleCalls(
+  fn: ApiFunction,
+  overloads: readonly ApiFunction[],
+): readonly (readonly string[])[] {
+  return exampleCalls(fn).filter(
+    (args) => !overloads.some((other) => other !== fn && acceptsArgumentCount(other, args.length)),
+  );
+}
+
+// A table parameter's `<dl>`/`<ul>` describes its fields, so an optional field
+// there says nothing about whether the argument itself may be omitted.
+const FIELD_LIST = /<(dl|ul|ol|table)\b[\s\S]*?<\/\1>/g;
+const OPENS_OPTIONAL = /^\s*optional\b/i;
+const OMISSION_PHRASE = /\bdefaults? to\b|\b(?:if|when|can be|may be) omitted\b/i;
+
+type OptionalityAxis = (
+  fn: ApiFunction,
+  index: number,
+  overloads: readonly ApiFunction[],
+) => boolean;
+
+// The three ways a ref-doc evidences that a parameter may be omitted, each read
+// from one function element and its same-named overloads. `is_optional` is not
+// among them: a slot upstream marks optional is already emitted omissible, so
+// only the unmarked ones can be lost.
+export const OPTIONALITY_EVIDENCE: Readonly<
+  Record<"prose" | "exampleArity" | "exampleNil", OptionalityAxis>
+> = {
+  // The parameter's own prose opens with "optional", or names a default or an
+  // omission outside any field list.
+  prose: (fn, index) => {
+    const doc = fn.parameters[index]?.doc ?? "";
+    return (
+      OPENS_OPTIONAL.test(plainText(doc)) ||
+      OMISSION_PHRASE.test(plainText(doc.replace(FIELD_LIST, " ")))
+    );
+  },
+  // An upstream example stops before this parameter. A trailing `...` forwards
+  // an unknown number of values, so it proves nothing about arity.
+  exampleArity: (fn, index, overloads) =>
+    ownExampleCalls(fn, overloads).some((args) => args.length <= index && args.at(-1) !== "..."),
+  // An upstream example passes a bare `nil` in this position.
+  exampleNil: (fn, index, overloads) =>
+    ownExampleCalls(fn, overloads).some((args) => args[index] === "nil"),
+};
+
+const ARITY_OVERLOAD_REASON =
+  "the example `vmath.euler_to_quat(v)` passes one vector3 for all three angles: " +
+  "y and z are required in the three-number form, and the one-argument call needs " +
+  "an overload the declaration lacks, not an omissible slot";
+
+// Slots the evidence flags that are genuinely required, keyed like
+// `OPTIONAL_SLOT_CORRECTIONS`. Each value is the recorded reason, so an
+// exemption is a decision someone can re-check rather than a silent skip.
+export const OPTIONALITY_EVIDENCE_EXEMPTIONS: ReadonlyMap<string, string> = new Map([
+  [
+    "render.render_target:param:parameters",
+    "both upstream examples pass the parameters table first, in place of `name`: an " +
+      "argument shifted into another slot rather than this one omitted, which an " +
+      "overload the declaration lacks would express",
+  ],
+  ["vmath.euler_to_quat:param:y", ARITY_OVERLOAD_REASON],
+  ["vmath.euler_to_quat:param:z", ARITY_OVERLOAD_REASON],
+]);
+
+export interface EvidencedSlot {
+  readonly key: string;
+  readonly emittedRequired: boolean;
+}
+
+// Every `<element>:param:<slot>` the ref-doc evidences as omissible, and whether
+// the emitted surface still requires it. A slot is emitted omissible when any
+// same-named declaration makes that position omissible under `isDocOptional`,
+// the emitter's own predicate, corrections included. Skipped functions are
+// hand-authored, so their slots are not the generator's to lose.
+export function evidencedOptionalSlots(
+  entry: Pick<ModuleManifestEntry, "doc" | "skipFunctions">,
+): EvidencedSlot[] {
+  const skipFunctions = new Set(entry.skipFunctions ?? []);
+  const functions = parseDefoldApiDoc(entry.doc).functions;
+  const overloadsByName = new Map<string, ApiFunction[]>();
+  for (const fn of functions) {
+    overloadsByName.set(fn.name, [...(overloadsByName.get(fn.name) ?? []), fn]);
+  }
+  const emittedRequired = new Map<string, boolean>();
+  for (const fn of functions) {
+    if (skipFunctions.has(stripNamespace(fn.name))) continue;
+    const overloads = overloadsByName.get(fn.name) ?? [fn];
+    fn.parameters.forEach((param, index) => {
+      if (param.isVararg === true) return;
+      if (!Object.values(OPTIONALITY_EVIDENCE).some((axis) => axis(fn, index, overloads))) return;
+      const omissible = overloads.some((other) => {
+        const slot = other.parameters[index];
+        return slot?.name === param.name && isDocOptional(slot, other.name);
+      });
+      const key = tableSlotKey(fn.name, "param", param.name);
+      emittedRequired.set(key, (emittedRequired.get(key) ?? false) || !omissible);
+    });
+  }
+  return [...emittedRequired].map(([key, required]) => ({ key, emittedRequired: required }));
+}
+
+// The evidenced slots the emitted declaration still requires, before exemptions.
+export function unmarkedOptionalSlots(
+  entry: Pick<ModuleManifestEntry, "doc" | "skipFunctions">,
+): string[] {
+  return evidencedOptionalSlots(entry)
+    .filter((slot) => slot.emittedRequired)
+    .map((slot) => slot.key);
+}
+
 function auditEntry(
   entry: ModuleManifestEntry,
   knownConstantFqns: ReadonlySet<string>,
@@ -99,9 +303,13 @@ function auditEntry(
   // multiReturn is fully recovered: emitReturn emits LuaMultiReturn<[...]> for
   // every >1-return function, so no documented multi-return is a loss anymore.
   const multiReturn = 0;
-  // optionalAsRequired is fully recovered: emitParameter expresses an interior
-  // doc-optional param as `| undefined`, so no doc-optional param is a loss.
-  const optionalAsRequired = 0;
+  // Every param upstream marks optional is recovered: emitParameter expresses an
+  // interior one as `| undefined` and a trailing one as `?`. What stays lost is a
+  // slot the ref-doc evidences as omissible without marking it, which neither an
+  // OPTIONAL_SLOT_CORRECTIONS entry nor a stated exemption accounts for.
+  const optionalAsRequired = unmarkedOptionalSlots(entry).filter(
+    (key) => !OPTIONALITY_EVIDENCE_EXEMPTIONS.has(key),
+  ).length;
   const unknown = new Set<string>();
 
   const constantFqns = new Set<string>();
@@ -394,7 +602,8 @@ function auditEntry(
       );
       // Interior doc-optional params (a required param follows) are no longer a
       // loss: emitParameter expresses them as `| undefined`, mirroring the
-      // emitted surface. optionalAsRequired stays in the report shape reading 0.
+      // emitted surface. optionalAsRequired counts the unmarked ones instead,
+      // through unmarkedOptionalSlots above.
     });
     for (const ret of returns) {
       const tableSlotCuration =