llms.txt

TBAF Reference for LLMs

You are writing TBAF -- a TypeScript subset that compiles to BAF (Infinity Engine AI scripts).
Files use the .tbaf extension. Everything resolves at compile time. The output is flat
IF/THEN/END blocks. BAF has no runtime variables, loops, or functions.

=== CORE CONCEPT ===

A BAF script is a list of IF/THEN/END blocks. The engine checks them top-to-bottom and
runs the first one whose conditions are true. TBAF lets you write TypeScript that expands
entirely at compile time into those blocks.

Input:
  if (See(Player1)) { Attack(Player1); }

Output:
  IF
    See(Player1)
  THEN
    RESPONSE #100
      Attack(Player1)
  END

=== VARIABLES ===

const and let are compile-time text substitution. No runtime variables exist.

  const TARGET = "Player1";
  if (See(TARGET)) { Attack(TARGET); }
  // becomes: if (See(Player1)) { Attack(Player1); }

=== FUNCTIONS ===

Functions are expanded at every call site. Parameters are substituted.

  function attackIfVisible(target: string) {
      if (See(target)) { Attack(target); }
  }
  attackIfVisible("Player1");
  attackIfVisible("Player2");
  // Produces two IF/THEN/END blocks, one per call

Condition functions: the return expression becomes a condition.

  function isHostile(t: string) { return See(t) && !InParty(t); }
  if (isHostile("Player1")) { Attack(Player1); }
  // -> IF See(Player1) !InParty(Player1) THEN Attack(Player1) END

Constraint: a function used inside an || group must return a single condition.
A function returning A() && B() cannot appear inside ||.

=== IF / ELSE IF / ELSE ===

Each branch becomes a separate IF/THEN/END block. The else branch gets the
negated conditions from all prior branches.

  if (A()) { X(); }
  else if (B()) { Y(); }
  else { Z(); }
  ->
  IF A() THEN X() END
  IF !A() B() THEN Y() END
  IF !A() !B() THEN Z() END

Nested if: conditions accumulate.
  if (A()) { if (B()) { X(); } }
  -> IF A() B() THEN X() END

=== OPERATORS ===

&&   Multiple conditions in the same IF block (AND)
||   OR(n) group
!    Negated condition

  if (A() && B()) { ... }            -> IF A() B() THEN ... END
  if (A() || B()) { ... }            -> IF OR(2) A() B() THEN ... END
  if (A() && (B() || C())) { ... }   -> IF A() OR(2) B() C() THEN ... END
  if (!A()) { ... }                  -> IF !A() THEN ... END

else after if(A && B) -> OR(2) !A !B
else after if(A || B) -> !A !B

Avoid deeply nested negations of complex conditions. If the condition is too
complex to invert, the transpiler will error. Simplify the condition.

=== SWITCH / CASE ===

Each case becomes a separate IF block. The case value is appended as the last
argument to the switch expression.

  const state = Global("state", "LOCALS");
  switch (state) {
      case 0: ActionA(); break;
      case 1: ActionB(); break;
  }
  -> IF Global("state", "LOCALS", 0) THEN ActionA() END
  -> IF Global("state", "LOCALS", 1) THEN ActionB() END

The switch expression must be a function call (like Global()).
No `default` case allowed -- BAF cannot express "none of the above".

=== LOOPS ===

Loops are fully expanded at compile time. Max 1000 iterations.

  for (let i = 0; i < 3; i++) { ... }         -> 3 copies of body
  for (const x of ["a", "b"]) { ... }         -> 2 copies, x substituted
  for (const [a, b] of [[1,2],[3,4]]) { ... } -> destructuring supported

Supported incrementors: i++, i--, i+=N, i-=N
Loop variables are removed after the loop ends.

=== ARRAYS ===

Compile-time only. Spread supported:
  const base = ["a", "b"];
  const all = [...base, "c"];  // ["a", "b", "c"]

=== POINT ARGUMENTS ===

BAF uses [x.y] dot notation for coordinates. In TBAF, use [number, number] tuples:

  CreateCreature("ccguard2", [2791, 831], 6);
  // -> CreateCreature("ccguard2", [2791.831], 6)

Negative coordinates supported: [-1, -1] -> [-1.-1]
Works through variable substitution, function inlining, and loop unrolling.
Only two-element numeric arrays are converted. [1, 2, 3] and [PC] are unchanged.

=== ENUMS ===

  enum Spell { Shield = "WIZARD_SHIELD", Armor = "WIZARD_ARMOR" }
  Spell.Shield -> WIZARD_SHIELD

Enums from iets .d.ts files have their prefix stripped: ClassID.ANKHEG -> ANKHEG

=== IMPORTS ===

Engine builtins come from iets:
  import { See, Attack, Global } from "@bgforge/iets/baf.d";
  import { Player1, Myself } from "@bgforge/iets/objects.d";
  import { ClassID } from "@bgforge/iets/class.ids";

Local files can also be imported:
  import { myHelper } from "./helpers";

=== SCOPE CONSTANTS ===

GLOBAL, LOCALS, MYAREA are automatically quoted in the output:
  SetGlobal("x", LOCALS, 1) -> SetGlobal("x", "LOCALS", 1)
Don't quote them yourself.

=== @TRA TAG ===

/** @tra filename.tra */  -> sets the WeiDU translation file

=== FORBIDDEN ===

default in switch         BAF can't express "none of the above"
Negating complex || groups  Too complex to represent in BAF conditions
Arrow functions () => {}  Not supported
Classes/async/try-catch   No runtime constructs exist in BAF
Template literals         Not supported
Object literals           Not meaningful in BAF

=== GOTCHAS ===

1. Everything is compile-time. Variables don't exist at runtime.
2. Max 1000 loop iterations.
3. GLOBAL/LOCALS/MYAREA auto-quoted -- don't double-quote them.
4. Functions inside || must return exactly 1 condition.
5. Switch expression must be a function call (e.g. Global()).
6. Loop variables are removed after the loop ends.
7. All blocks use RESPONSE #100 (no weighted responses).

=== EXAMPLE ===

/** @tra smarter_mages.tra */
import { See, Attack, Global, SetGlobal, Spell } from "@bgforge/iets/baf.d";
import { Player1, Myself } from "@bgforge/iets/objects.d";

const enemies = ["Player1", "Player2", "Player3"];

function attackEnemy(target: string) {
    if (See(target)) {
        Attack(target);
    }
}

for (const enemy of enemies) {
    attackEnemy(enemy);
}

if (Global("buffed", LOCALS, 0)) {
    Spell(Myself, WIZARD_SHIELD);
    SetGlobal("buffed", LOCALS, 1);
}

=== COMPILATION ===

.tbaf -> transpiler -> .baf -> WeiDU -> game
Press Ctrl+R in VSCode or use the transpile CLI.