@scm-js/plugin-api 1.36.0 → 1.38.0

package/index.d.ts

@@ -1209,7 +1209,7 @@ export interface StackedLine {
 	pieces: number;
 }
 /** Every built-in dialog, by the id `openDialogAtom` takes; `DialogHost` maps each to its component. */
-export type DialogId = "newMap" | "openMap" | "saveAs" | "exportImage" | "mapProperties" | "resizeMap" | "mapRevision" | "playerSettings" | "forceSettings" | "playerColors" | "unitSettings" | "upgradeSettings" | "techSettings" | "stringEditor" | "soundEditor" | "switches" | "locationList" | "unitProperties" | "locationProperties" | "spriteProperties" | "triggerEditor" | "missionBriefing" | "cuwpEditor" | "replaceTerrain" | "autoStarts" | "testMap" | "symmetry" | "gridSettings" | "preferences" | "shortcuts" | "validateMap" | "statistics" | "importTriggers" | "exportTriggers" | "importStrings" | "exportStrings" | "find" | "about" | "confirmClose" | "plugins" | "confirmPlugin" | "pluginDialog" | "gameData" | "update";
+export type DialogId = "newMap" | "openMap" | "saveAs" | "exportImage" | "mapProperties" | "resizeMap" | "mapRevision" | "playerSettings" | "forceSettings" | "playerColors" | "unitSettings" | "upgradeSettings" | "techSettings" | "stringEditor" | "soundEditor" | "switches" | "locationList" | "unitProperties" | "locationProperties" | "spriteProperties" | "triggerEditor" | "missionBriefing" | "cuwpEditor" | "replaceTerrain" | "autoStarts" | "testMap" | "symmetry" | "gridSettings" | "preferences" | "shortcuts" | "validateMap" | "statistics" | "importTriggers" | "exportTriggers" | "importStrings" | "exportStrings" | "find" | "about" | "confirmClose" | "recovery" | "previousVersions" | "plugins" | "confirmPlugin" | "pluginDialog" | "gameData" | "update";
 export interface MapImageOptions {
 	/** Output pixels per map tile. 32 matches the game's art 1:1; 1 is a minimap. */
 	pixelsPerTile: number;
@@ -1327,6 +1327,80 @@ export interface TextTrigger {
 	/** 1-based line the `Trigger(` header starts on. */
 	line: number;
 }
+/** Every kind of thing a condition or action can refer to. */
+export type TriggerRefKind = 
+/** A switch; `id` is its 0-based number. */
+"switch"
+/** A death counter; `id` is the unit id, `players` the slots whose cell it is. */
+ | "deaths"
+/** A death counter out of range — an EUD read or write; `address` is the dword it reaches, `id` the unit value as written. */
+ | "memory"
+/** A location; `id` is its 0-based slot (63 is Anywhere). */
+ | "location"
+/** The countdown timer; `id` is 0. */
+ | "timer"
+/** A player's ore or gas; `id` is the `ResourceType`. */
+ | "resources"
+/** A player's score; `id` is the `ScoreType`. */
+ | "score"
+/** Units of a type; `id` is the unit id (a class id for *Any unit*, *Men*, …). */
+ | "units"
+/** Victory, Defeat or Draw; `id` is the action type, `players` the trigger's owners. */
+ | "outcome"
+/** A string of the map's string table; `id` is the 1-based string index. */
+ | "string"
+/** A sound; `id` is the string index of its file name. */
+ | "wav"
+/** A Run AI Script code (four characters as a little-endian u32). */
+ | "aiScript"
+/** A Create Unit with Properties slot, 0-based. */
+ | "cuwp";
+/**
+ * `read`: a condition tests it. `write`: an action changes it. `use`: an action names it
+ * without changing it — the location units appear at, the text a message shows.
+ */
+export type TriggerRefAccess = "read" | "write" | "use";
+export interface TriggerRef {
+	kind: TriggerRefKind;
+	access: TriggerRefAccess;
+	/** Whether a condition or an action refers to it. */
+	part: "condition" | "action";
+	/** The condition's or action's position in the trigger. */
+	slot: number;
+	/** The condition or action type. */
+	type: number;
+	id: number;
+	/**
+	 * The 0-based player slots it is about, for the kinds that belong to a player
+	 * (`deaths`, `resources`, `score`, `units`, `outcome`); empty for the rest, and for a
+	 * condition such as *Command the Most* that compares every player.
+	 */
+	players: number[];
+	/** The player group as the record stores it, where the record has one. */
+	group?: number;
+	/**
+	 * The group resolves only while the game runs (*Foes*, *Allies*, *Neutral Players*,
+	 * *Non Allied Victory Players*), so `players` is every slot it could name.
+	 */
+	approximate?: boolean;
+	/** `memory`: the address reached (rounded down to a dword). */
+	address?: number;
+	/** `memory`: the bits a masked record reaches (its `location` field), when the record is masked. */
+	mask?: number;
+	/** The condition or action is switched off (its Disabled flag); the game skips it. */
+	disabled?: boolean;
+}
+export interface TriggerRefs {
+	/** The trigger's index in the list. */
+	index: number;
+	/** The 0-based slots the trigger runs for. */
+	owners: number[];
+	/** The player groups ticked in the trigger, as stored. */
+	groups: number[];
+	/** Set by the Disabled flag, or no player owns it: the game never runs it. */
+	inert: boolean;
+	refs: TriggerRef[];
+}
 export type IssueLevel = "error" | "warn" | "info";
 export type IssueTarget = {
 	kind: "location";
@@ -1992,11 +2066,25 @@ export interface Preferences {
 	 * What the Save dialog starts from: the options the file was opened with
 	 * (`"asOpened"`, the default), or one of its presets. `compression` is for a map with
 	 * no origin — new, or opened from a bare .chk — where there is nothing to follow;
-	 * `"asOpened"` there means StarEdit's PKWARE.
+	 * `"asOpened"` there means StarEdit's PKWARE. `backup` keeps the file a save writes
+	 * over: `<name>.bak` beside it in the desktop app, the browser's storage otherwise
+	 * (`services/previousVersions.ts`).
 	 */
 	save: {
 		start: "asOpened" | "everything" | "smallest";
 		compression: "asOpened" | ArchiveCompression;
+		backup: boolean;
+	};
+	/**
+	 * Recovery copies (`hooks/useRecovery.ts`): while a map has unsaved changes, a copy of
+	 * it is kept in the browser's storage every `minutes` and when the editor goes to the
+	 * background, and dropped when the map is saved or closed. What a session that ended
+	 * without saving left behind is offered back at the next start. Off stops the copies
+	 * and drops this session's; copies left by earlier sessions are still offered.
+	 */
+	recovery: {
+		enabled: boolean;
+		minutes: number;
 	};
 	/** How many edits Undo keeps per map (SCMDraft keeps 200). */
 	undoLevels: number;
@@ -3147,6 +3235,39 @@ export interface TriggersApi {
 		][];
 		switches: number[];
 	};
+	/**
+	 * 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.
+	 *
+	 * @example
+	 * // 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))];
+	 */
+	references(list?: TriggerRecord[], options?: {
+		briefing?: boolean;
+	}): TriggerRefs[];
+	/**
+	 * 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.
+	 */
+	resolvePlayers(group: number, owners?: number[]): {
+		players: number[];
+		approximate: boolean;
+	};
 	/**
 	 * 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
@@ -3275,6 +3396,12 @@ export type GoTo = {
 } | {
 	kind: "location";
 	index: number;
+}
+/** Opens the Trigger Editor (or, with `briefing`, the Mission Briefing) on that trigger. */
+ | {
+	kind: "trigger";
+	index: number;
+	briefing?: boolean;
 };
 /**
  * The map view: where the viewport is looking, how far in, and what it draws over the
@@ -3579,6 +3706,13 @@ export interface GameDataApi {
 	select(id: string): Promise<GameDataSource>;
 	/** Remove a data set's copy (never the game's bundled files). True when there was one. */
 	remove(id: string): Promise<boolean>;
+	/**
+	 * One file of the data set in use, by its path in the extracted copy: the archive path in
+	 * lower case with forward slashes (`arr/units.dat`, `tileset/jungle.cv5`,
+	 * `unit/zerg/drone.grp`). `tileset/manifest.json` and `unit/manifest.json` list what was
+	 * extracted. Null when the copy has no such file, or there is no game data.
+	 */
+	read(path: string): Promise<Uint8Array | null>;
 }
 /**
  * The constants a plugin needs to *write* a record rather than read one: the bit masks in
@@ -4266,7 +4400,12 @@ export interface MapButtonHandle {
  * not yet applied to the map — so a slot's button can fill it in and leave OK to them.
  *
  * - `mapProperties`: `name`, `description`.
- * - `triggerEditor`, `stringEditor`, `playerSettings`, `missionBriefing`: no fields, a slot only.
+ * - `triggerEditor`, `missionBriefing`: `selected`, the selected row's index in the list
+ *   as text (`""` for none). Setting it selects that row. The index is into the dialog's
+ *   working copy, which matches `triggers.list()` until the person inserts or removes rows.
+ *   And `modified`, `"1"` while that working copy has changes not yet applied (read only):
+ *   `close()` discards them, so ask before closing when it is set.
+ * - `stringEditor`, `playerSettings`: no fields, a slot only.
  *
  * A plugin's own dialog can offer a slot too (`DialogSpec.slot`), under an id of its
  * choosing — `"trigedit.text"` is the Text Trigger Editor's, lending `text` with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scm-js/plugin-api",
-  "version": "1.36.0",
+  "version": "1.38.0",
   "description": "Type declarations for the scmJS plugin API",
   "license": "MIT",
   "types": "index.d.ts",