api.triggers

list

list(): TriggerRecord[];

TRIG, cloned.

briefing

briefing(): TriggerRecord[];

MBRF, cloned.

switchNames

switchNames(): string[];

SWNM as names, StarEdit's Switch N where there is none.

switchUsage

switchUsage(): number[];

How many conditions and actions mention each switch.

names

names(): TriggerNames;

The name context the text format resolves against: the map's locations, units, switches and strings.

defs

readonly defs: TriggerDefsApi;

text

readonly text: TriggerTextApi;

newTrigger

newTrigger(players?: readonly number[]): TriggerRecord;

An empty trigger owned by the given player groups (All Players by default).

newCondition

newCondition(type: number): ConditionRecord;

A condition of a type, with StarEdit's defaults for its arguments.

newAction

newAction(type: number, briefing?: boolean): ActionRecord;

isPreserved

isPreserved(trigger: ReadonlyTrigger): boolean;

setPreserved

setPreserved(trigger: ReadonlyTrigger, on: boolean): TriggerRecord;

triggersFor

triggersFor(list: readonly ReadonlyTrigger[], groups: readonly number[]): number[];

The indices of the triggers any of these player groups own.

summarize

summarize(trigger: ReadonlyTrigger, briefing?: boolean): { players: string; conditions: string; actions: string; };

The three lines the trigger list shows: players, conditions, actions.

for (const trigger of api.triggers.list()) {
  const line = api.triggers.summarize(trigger);
  api.log(`${line.players}: ${line.conditions} → ${line.actions}`);
}

comment

comment(trigger: ReadonlyTrigger): string | null;

A trigger's Comment action text, when it has one.

epd

epd(address: number): number;

EUD: the player value that reaches a memory address through the deaths table ((address − consts.triggers.deathsTable) / 4, the address rounded down to a dword) — what a Deaths condition or Set Deaths action stores in player with unitId 0 to read or write that dword.

addressOf

addressOf(player: number, unitId?: number): number;

EUD: the address a record's player and unitId reach through the deaths table — epd's inverse, and a plain death counter's cell as an address.

fingerprint

fingerprint(trigger: ReadonlyTrigger): string;

A content fingerprint of a trigger: the same wherever it sits in the list and whatever the game's bookkeeping bits say. What a plugin that generates triggers finds its run by (TriggerClaimSpec.locate), and what an editor keeps a selection by across a list that changed under it.

usage

usage(list?: readonly ReadonlyTrigger[]): { cells: [ player: number, unit: number ][]; switches: number[]; };

Every death-counter cell ([player, unit]) and switch the triggers read or write — TRIG when list is omitted. A player group counts as every slot it can resolve to (Current Player as the trigger's owners); a class unit (Any unit, Men, …) counts for nothing, and an EUD player is an address, not a cell. What a plugin that allocates counters or switches of its own must keep clear of.

// A switch no trigger touches, for a plugin that needs one of its own.
const taken = new Set(api.triggers.usage().switches);
const free = Array.from({ length: 256 }, (_, i) => i).find((i) => !taken.has(i));
api.log(free === undefined ? "every switch is in use" : `${api.names.switch(free)} is free`);

references

references(list?: readonly ReadonlyTrigger[], options?: { briefing?: boolean; }): TriggerRefs[];

What each trigger reads, writes and names — TRIG when list is omitted, one entry per trigger in list order. A condition reads (a switch, a death counter, the timer, a player's ore, units at a location); an action writes (Set Switch, Set Deaths, Create Unit, Move Location's target, Victory) or uses something without changing it (the location units appear at, the text a message shows, a sound). Player groups are resolved to slots against the map's forces, Current Player as the trigger's owners; a Deaths record past the counters is a memory reference with its address.

What a plugin needs to draw how triggers depend on each other, find a switch that is set and never tested, or answer "which triggers can end the game". With briefing, MBRF, where only strings and sounds are referred to.

// Switches something tests that nothing ever sets.
const refs = api.triggers.references().flatMap((t) => t.refs).filter((r) => r.kind === "switch");
const set = new Set(refs.filter((r) => r.access === "write").map((r) => r.id));
const never = [...new Set(refs.filter((r) => r.access === "read" && !set.has(r.id)).map((r) => r.id))];

resolvePlayers

resolvePlayers(group: number, owners?: readonly number[]): { players: readonly number[]; approximate: boolean; };

The 0-based player slots a player group names on the open map: a slot itself, the members of a force, players 1–8 for All Players, and for Current Player the slots of owners (the groups a trigger is ticked for). approximate when the group is only settled while the game runs (Foes, Allies, Neutral Players, Non Allied Victory Players); players is then every slot it could name.

claim

claim(spec: TriggerClaimSpec): TriggerClaimHandle;

Tell the editor that a run of the trigger list is generated by this plugin. The Trigger Editor badges those rows, locks them and offers the plugin's own editor in place of the form; the Text Trigger Editor fences them in comments; Import Triggers says what a replace would remove. The claim lives until remove() or the plugin's deactivation; call refresh() after a rebuild so the editors ask locate again.

// Fingerprints of the triggers this plugin generated, kept as it generates them.
const mine = new Set<string>();
const isMine = (t: Parameters<typeof api.triggers.fingerprint>[0]) => mine.has(api.triggers.fingerprint(t));
const claim = api.triggers.claim({
  label: "the wave generator",
  badge: "waves",
  locate(list) {
    const start = list.findIndex(isMine);
    if (start < 0) return null;
    let count = 1;
    while (start + count < list.length && isMine(list[start + count])) count++;
    return { start, count };
  },
  describe: () => "Made by the wave generator. Change the waves there, not here.",
});
// After regenerating: update `mine`, then
claim.refresh();

claims

claims(list?: readonly ReadonlyTrigger[]): TriggerClaimRange[];

Every plugin's claims as located in list (TRIG as it stands, when omitted), first run first — what an editor of the trigger list needs to fence or lock the generated runs. A claim whose locate finds nothing, or throws, is left out.