api.triggers

TriggersApi

Reading triggers, and the pure helpers that make them presentable. Writing goes through document.update.

list
briefing
switchNames
switchUsage
names
defs
text
newTrigger
newCondition
newAction
isPreserved
setPreserved
triggersFor
summarize
comment
claim

Members

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?: 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: TriggerRecord): boolean;

setPreserved

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

triggersFor

triggersFor(list: TriggerRecord[], groups: number[]): number[];

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

summarize

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

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

comment

comment(trigger: TriggerRecord): string | null;

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

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.

Types

Declarations only this group names.

ArgKindtype

type ArgKind = "player" | "unit" | "location" | "switch" | "comparison" | "switchState" | "switchAction" | "modifier" | "unitState" | "order" | "alliance" | "resource" | "score" | "aiScript" | "textFlags" | "text" | "wav" | "number" | "amount" | "count" | "duration" | "percent" | "cuwp" | "slot";

ConditionFieldtype

type ConditionField = keyof ConditionRecord;

ActionFieldtype

type ActionField = keyof ActionRecord;

ArgDefinterface

interface ArgDef

`kind: ArgKind`
`field: F`
`label: string`

ConditionDefinterface

interface ConditionDef

`type: number`
`name: string`
`args: ArgDef<ConditionField>[]`

ActionDefinterface

interface ActionDef

`type: number`
`name: string`
`args: ArgDef<ActionField>[]`
`hasTextFlags?: boolean`	Text / Transmission: the `AlwaysDisplay` flag is an argument of its own.

Choiceinterface

interface Choice

`value: number`
`label: string`
`aliases?: string[]`	Extra spellings the text parser accepts.

TriggerNamesinterface

interface TriggerNames

How the text format names things it cannot know on its own.

`string(index: number): string \| null`	Text of a string-table entry, null when unset.
`intern(text: string): number`	Index for `text` — an existing identical entry or a new one. Only called while parsing.
`location(number: number): string`	Display name of a 1-based location number.
`locationByName(name: string): number \| undefined`	1-based number for a location name (or `Location N` / `Anywhere`), undefined when unknown.
`unit(id: number): string`
`unitByName(name: string): number \| undefined`
`switch(index: number): string`	Display name of a 0-based switch.
`switchByName(name: string): number \| undefined`

TextTriggerinterface

interface TextTrigger

`trigger: TriggerRecord`
`line: number`	1-based line the `Trigger(` header starts on.

TriggerDefsApiinterface

interface TriggerDefsApi

What each condition and action type takes: the argument list in the order StarEdit's TrigEdit shows it, each naming the record field it lives in and the kind of value it is (a player group, a unit id, a location, a comparison, …). Everything that displays or edits a trigger reads this table, the editor's own dialogs included.

`conditions(): ConditionDef[]`
`condition(type: number): ConditionDef \| undefined`
`actions(briefing?: boolean): ActionDef[]`
`action(type: number, briefing?: boolean): ActionDef \| undefined`
`choices(kind: ArgKind): Choice[]`	The values an enumerated argument kind can take, with their labels.
`choiceLabel(kind: ArgKind, value: number): string \| undefined`
`choiceValue(kind: ArgKind, text: string): number \| undefined`	The value behind a label or one of its aliases, for parsing.

TriggerTextApiinterface

interface TriggerTextApi

Printing and parsing the text trigger format (File ▸ Import / Export ▸ Triggers).

`print(triggers: TriggerRecord[], options?: { briefing?: boolean; }): string`
`parse(source: string, options?: { briefing?: boolean; }): TextTrigger[]`	Parse text into records, resolving names against the open map (and interning the strings it mentions). Throws a `TriggerTextError` carrying the line on bad input.
`one(trigger: TriggerRecord, options?: { briefing?: boolean; }): string`	One trigger as its `Trigger(…)` block.

TriggerClaimSpecinterface

interface TriggerClaimSpec

A run of triggers a plugin generates and owns. It is found by content: the editors work on copies of the list with their own unsaved inserts and removals, so locate is asked with whatever list an editor holds and answers where the run is in it — by a hash of the records, say — or null when the records are not there.

`label: string`	What generated the run, in words, as a sentence would use it: `"the trigger script"`.
`badge?: string`	The word on the badge the trigger list shows on each row; the plugin's id by default.
`locate(list: TriggerRecord[]): { start: number; count: number; } \| null`	Where the run sits in `list`, or null when it is not there (edited by hand, or gone).
`describe?(index: number, list: TriggerRecord[]): string`	A sentence about one trigger of the run (its index in `list`), shown in place of the editor's form.
`open?(index: number, list: TriggerRecord[]): void`	Open the plugin's own editor on that trigger — the button under the sentence.
`openLabel?: string`	That button's label; `Open <plugin name>` by default.

TriggerClaimHandleinterface

interface TriggerClaimHandle

`refresh(): void`	The editors ask `locate` again (after a rebuild, or when the run moved).
`remove(): void`

Seen in

Trigger Scriptgenerating a run of triggers and claiming it