llms.txt

TD Reference for LLMs

You are writing TD -- a TypeScript DSL that compiles to WeiDU D dialog files.
Files use the .td extension. Functions are dialog states, method chains are transitions.
Everything resolves at compile time into standard WeiDU D code.

=== CORE MODEL ===

D files contain: states (NPC text + transitions), transitions (player choices),
and constructs (BEGIN, APPEND, EXTEND, CHAIN, INTERJECT, patches).

Functions with NO parameters = state functions (name becomes state label).
Functions WITH parameters = helpers (inlined at call sites).

=== DIALOG OPERATIONS ===

begin(dialog, [state1, state2, ...])     Create new DLG file
begin(dialog, state1, state2)            Rest args form
append(dialog, [states])                 Add states to existing DLG
appendEarly(dialog, states)              Add states early (for INTERJECT targets)
extendTop(dialog, state, () => {...})    Add transitions to top
extendBottom(dialog, state, () => {...}) Add transitions to bottom
extendBottom(dialog, state, {position: N}, () => {...})  At specific index
replaceState(dialog, N, () => {...})     Replace state by index
replace(dialog, {0: () => {...}, 3: () => {...}})  Replace multiple states

=== STATE FUNCTIONS ===

function myState() {
    say(tra(1));                           // NPC says @1
    say(tra(1), tra(2), tra(3));           // Multisay (random)
    weight(5);                             // State priority (lower = first)
    copyTrans("DLG", "state");             // Copy transitions from another state
    copyTrans("DLG", "state", {safe: true});
}

=== TRANSITIONS (chain form) ===

reply(text).goTo(target)                   Player reply -> goto state
reply(text).exit()                         Player reply -> end conversation
reply(text).extern("DLG", "state")         Player reply -> state in other DLG
reply(text).action(act1, act2).goTo(t)     Reply + actions + goto
reply(text).journal(text).goTo(t)          Reply + journal entry + goto
reply(text).solvedJournal(text).exit()     Reply + solved journal + exit
reply(text).unsolvedJournal(text).exit()   Reply + unsolved journal + exit
reply(text).flags(0x100).exit()            Reply + flags + exit
action(act).exit()                         No-reply action transition
action(act).goTo(t)                        No-reply action goto
reply(text).copyTransLate("DLG", "state")  Copy transitions (late binding)
reply(text).extern("DLG", "st", {ifFileExists: true})

=== TRANSITIONS (statement form) ===

reply(tra(1));           // Start new transition
action(SetGlobal(...));  // Modify last transition
goTo(nextState);         // Set destination
exit();                  // End conversation
extern("DLG", "state"); // Go to other DLG

=== CONDITIONAL TRANSITIONS ===

if (Global("quest", "GLOBAL", 0)) {
    reply(tra(2)).action(SetGlobal("quest", "GLOBAL", 1)).goTo(next);
}
// Output: IF ~Global("quest","GLOBAL",0)~ THEN reply...

State-level if: single if wrapping entire body (including say()) becomes state trigger.
if (cond) { say(tra(1)); exit(); } -> IF ~cond~ label SAY @1 ... END

=== TEXT REFERENCES ===

tra(N)                    -> @N (translation reference)
tra(N, {sound: "SND"})   -> @N [SND]
tlk(N)                    -> #N (TLK string reference)
tlkForced(N, text)        -> !N (forced TLK)
"string literal"          -> ~string literal~
{male: tra(1), female: tra(2)}  -> @1 @2 (gender variants)

=== CHAIN DIALOGS ===

Multi-speaker conversations (PC says nothing).

New form (recommended):
chain("SPEAKER1", "label", () => {
    say(tra(1));
    from("SPEAKER2");           // Switch speaker
    say(tra(2));
    fromWhen("SPEAKER1", cond); // Conditional speaker switch
    say(tra(3));
    exit();
});

With entry trigger:
chain(Global("x", "GLOBAL", 1), "SPEAKER1", "label", () => {
    say(tra(1));
    from("SPEAKER2");
    say(tra(2));
    exit();
});

Old form: chain(function name() { say("SPEAKER1", tra(1)); say("SPEAKER2", tra(2)); exit(); });

=== INTERJECT ===

interject("DLG", "state", "GlobalVar", () => {
    from("SPEAKER"); say(tra(1));
}, "EXITDLG", "exitState");

interjectCopyTrans("DLG", "state", "GlobalVar", () => {
    from("SPEAKER"); say(tra(1));
});

interjectCopyTrans2("DLG", "state", "GlobalVar", () => {...});

=== PATCH OPERATIONS ===

alterTrans("DLG", [stateNums], [transNums], {trigger?, action?, reply?})
addStateTrigger("DLG", state, trigger)
addStateTrigger("DLG", [states], trigger)
addTransTrigger("DLG", [states], trigger, {trans?: [nums]})
addTransAction("DLG", [states], [transNums], action)
replaceTransTrigger("DLG", [states], [transNums], "old", "new")
replaceTransAction("DLG", [states], [transNums], "old", "new")
replaceTriggerText("DLG", "old", "new")
replaceActionText(["DLG1", "DLG2"], "old", "new")
setWeight("DLG", "state", N)
replaceSay("DLG", "state", tra(N))
replaceStateTrigger("DLG", [states], trigger)

=== goTo() TARGETS ===

goTo(functionRef)   Function reference -> automatically included in the dialog
goTo("label")       String label
goTo(5)             Numeric state index

=== POINT ARGUMENTS ===

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

  reply(tra(1)).action(CreateCreature("ccguard2", [2791, 831], 6)).exit();
  // -> DO ~CreateCreature("ccguard2",[2791.831],6)~ EXIT

Negative coordinates supported: [-1, -1] -> [-1.-1]
Only two-element numeric arrays are converted. [1, 2, 3] and [PC] are unchanged.

=== AUTOMATIC STATE COLLECTION ===

Only list root states in begin()/append(). The transpiler follows goTo(functionRef)
and automatically includes reachable state functions.

begin("DLG", [start]);  // middle and ending auto-included via goTo chain
function start() { say(tra(1)); goTo(middle); }
function middle() { say(tra(2)); goTo(ending); }
function ending() { say(tra(3)); exit(); }

If two constructs share a goTo target, the first one processed claims it.
List shared states explicitly in both constructs to avoid surprises.
Functions with parameters are skipped (helpers, not states).

=== VARIABLES ===

All variables are compile-time. Substituted textually.
const DIALOG = "MYDLG";  // Substituted wherever DIALOG appears

=== HELPER FUNCTIONS ===

Functions with params are helpers (inlined, not emitted as states):
function setQuest(stage: number) { action(SetGlobal("q", "GLOBAL", stage)); goTo(next); }

=== LOOPS (compile-time) ===

for (const x of array) {...}           Unrolled at compile time
for (const [a, b] of pairs) {...}      Destructuring supported
for (let i = 0; i < N; i++) {...}      Numeric loop unrolled
Max 1000 iterations.

=== SCOPE CONSTANTS ===

GLOBAL, LOCALS, MYAREA are auto-quoted. Don't double-quote them.

=== @TRA TAG ===

/** @tra my_dialog.tra */  -> emitted in D header

=== IMPORTS ===

import { tra, tlk, obj } from "@bgforge/iets";            // text/object helpers
import { Global, SetGlobal } from "@bgforge/iets/trig.d";  // engine triggers/actions
import { helper } from "./my-lib";                  // local files

=== ORPHAN DETECTION ===

The transpiler warns about state functions (no params) that are not in any
begin/append and not reachable via goTo. These are likely mistakes -- states
you forgot to include. Unreferenced functions are also removed from the output.

=== GOTCHAS ===

1. Unreferenced state functions are removed and warned about.
2. If two constructs share a goTo target, the first one claims it. List shared states explicitly.
3. Variables must be compile-time primitives (strings/numbers only).
4. copyTrans (state-level, early) vs copyTransLate (transition-level, late).
5. Single if wrapping entire body = state trigger, not transition trigger.
6. No-param functions = states. With-param functions = helpers. No override.
7. GLOBAL/LOCALS/MYAREA auto-quoted.

=== EXAMPLE ===

/** @tra my_mod.tra */
import { tra, obj } from "@bgforge/iets";
import { Global, SetGlobal, See, InParty } from "@bgforge/iets/triggers.d";

function greeting() {
    say(tra(1));
    if (Global("quest", "GLOBAL", 0)) {
        reply(tra(2)).action(SetGlobal("quest", "GLOBAL", 1)).goTo(questStart);
    }
    reply(tra(3)).exit();
}

function questStart() {
    say(tra(4));
    reply(tra(5)).goTo(questMiddle);
}

function questMiddle() {
    say(tra(6));
    exit();
}

begin("MYDLG", [greeting]);

=== COMPILATION ===

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