ts/ielib/index.ts -- new types:

  - CreRef = string & {}
  - Direction = IE<number, "Direction">
  - StrRef = IE<number, "StrRef">
  - Documented why Scope is not narrowed to a union

  scripts/ts-update.ts -- generator updates:
  - TYPE_MAPPING: added areref, creref, strref
  - PARAM_NAME_TYPES: added Face → Direction, removed dead AreRef entry; changed endsWith to exact match
  - PARAM_NAME_TYPES override logic added to trigger parser (was action-only)
  - Both file headers updated with new type imports

  ts/ielib/bg2/spell.ids.ts: import → import type

  ts/ielib/package.json: version bump 0.1.4 → 0.2.0

  scripts/ts-update.test.ts: 3 new tests for PARAM_NAME_TYPES trigger overrides

  ts/ielib/bg2/actions.d.ts, triggers.d.ts: regenerated with all new types

Author: burner1024

scripts/ts-update.test.ts

@@ -88,6 +88,22 @@ describe("parseTriggerParameters", () => {
   it("throws on unknown type", () => {
     expect(() => parseTriggerParameters("Z:Unknown")).toThrow("Unknown type");
   });
+
+  it("overrides type for param named Scope via PARAM_NAME_TYPES", () => {
+    const result = parseTriggerParameters("S:Name*,S:Scope*");
+    expect(result).toBe("name: string, scope: Scope");
+  });
+
+  it("resolves resref type codes (ItmRef, AreRef, SplRef)", () => {
+    expect(parseTriggerParameters("ItmRef:Item*")).toBe("item: ItmRef");
+    expect(parseTriggerParameters("AreRef:Area*")).toBe("area: AreRef");
+    expect(parseTriggerParameters("SplRef:Spell*")).toBe("spell: SplRef");
+  });
+
+  it("does not override non-matching param names", () => {
+    const result = parseTriggerParameters("S:MyScope*");
+    expect(result).toBe("myScope: string");
+  });
 });
 
 describe("extractTriggerBlocks", () => {

scripts/ts-update.ts

@@ -37,11 +37,20 @@ const TYPE_MAPPING: Readonly<Record<string, string>> = {
   i: "number",
   p: "Point",
   a: "Action",
+  areref: "AreRef",
+  creref: "CreRef",
   itmref: "ItmRef",
   splref: "SplRef",
+  strref: "StrRef",
 };
 
-const ACTION_FILE_HEADER = `import type { Action, ObjectPtr, Point, SpellID, SplRef } from "../index";
+/** Maps YAML param names to TypeScript types. Checked before type/ids resolution. */
+const PARAM_NAME_TYPES: Readonly<Record<string, string>> = {
+  Scope: "Scope",
+  Face: "Direction",
+};
+
+const ACTION_FILE_HEADER = `import type { Action, AreRef, CreRef, Direction, ObjectPtr, Point, Scope, SpellID, SplRef, StrRef } from "../index";
 
 import type { Align } from "./align.ids";
 import type { Animate } from "./animate.ids";
@@ -70,7 +79,7 @@ import type { WeatherID } from "./weather.ids";
 
 `;
 
-const TRIGGER_FILE_HEADER = `import type { ObjectPtr, SpellID, ItmRef } from "../index";
+const TRIGGER_FILE_HEADER = `import type { AreRef, ItmRef, ObjectPtr, Scope, SplRef, SpellID } from "../index";
 
 import type { Align } from "./align.ids";
 import type { AreaTypeID as AreaType } from "./areatype.ids";
@@ -229,8 +238,10 @@ function generateTypeScriptDeclaration(yamlFilePath: string): string | null {
     let paramName = param.name.toLowerCase() === "unused" ? `unused${unusedCount++}` : param.name;
     paramName = normalizeParamName(paramName, "lower");
 
+    // Priority: param name exact override > ids field > type code
+    const typeOverride = PARAM_NAME_TYPES[param.name];
     // Use explicit empty-string check: ids may be "" which should fall through to TYPE_MAPPING
-    const paramType = normalizeTypeName(
+    const paramType = typeOverride ?? normalizeTypeName(
       param.ids !== undefined && param.ids !== "" ? param.ids : TYPE_MAPPING[param.type] ?? param.type,
     );
     paramLines.push(`${paramName}: ${paramType}`);
@@ -342,10 +353,11 @@ export function parseTriggerParameters(params: string): string {
       const specificType = parts.length > 1 ? parts[1] : undefined;
       const formattedName = normalizeParamName(name, "camelCase");
 
-      // Use specific IDS type if present and non-empty, otherwise fall through to TYPE_MAPPING
-      const rawType = specificType !== undefined && specificType !== ""
+      // Priority: param name exact override > specific IDS type > base type code
+      const typeOverride = PARAM_NAME_TYPES[name];
+      const rawType = typeOverride ?? (specificType !== undefined && specificType !== ""
         ? specificType
-        : TYPE_MAPPING[type.toLowerCase()];
+        : TYPE_MAPPING[type.toLowerCase()]);
       if (!rawType) {
         throw new Error(`Unknown type: "${type}" or "${specificType}"`);
       }

ts/ielib/README.md

@@ -1,3 +1,19 @@
 ## IElib
 
 Typescript bindings for Infinity Engine BAF.
+
+### Type branding
+
+Numeric IDS types (e.g. `SpellID`, `Align`, `ClassID`, `Slots`) use branded types via `IE<number, "...">` for nominal type safety. This prevents accidentally passing one kind of ID where another is expected. Custom numeric values can be created with a cast:
+
+```typescript
+const mySpell = 42 as SpellID;
+```
+
+String resource reference types (`ResRef`, `SplRef`, `ItmRef`) are intentionally **not** branded. Resrefs are almost always raw string literals, and branding would require a cast on every usage (e.g. `"SWORD01" as ItmRef`). Unlike numeric IDS types, there is no finite set of valid resrefs to provide as pre-typed constants.
+
+Engine action functions return a branded `Action` type, which allows `ActionOverride` to enforce that its argument is an actual action call rather than an arbitrary expression.
+
+### IDS type naming
+
+Some IDS types use a `*ID` suffix (`ClassID`, `GenderID`, `KitID`, etc.) while others use bare names (`Align`, `EA`, `State`, etc.). The suffix exists to avoid name clashes with same-named trigger/action functions (e.g. `Class()` trigger vs `ClassID` type). Types without a same-named function use the bare name.