@scm-js/plugin-api 1.21.0 → 1.23.0

package/index.d.ts

@@ -1051,6 +1051,12 @@ export interface Toast {
  * default colour, so a string written before the remaster can render differently now —
  * `bleedingLines` finds exactly that case, and the Repair plugin turns it into a finding
  * offering to write the reset the old game supplied for free.
+ *
+ * `runsOf` is a modern renderer in the other way too: it takes one alignment for a whole
+ * line, where 1.16.1 obeyed every alignment code on it and stacked the pieces between
+ * them in one place. `stackedLines` finds the lines that were drawn that way and
+ * `flattenStacks` lays them out left to right — the one rewrite here that loses something
+ * (where each piece sat), which is why the Repair plugin offers it unticked.
  */
 /** What a control byte does. Colours carry an `rgb`; the rest are layout or visibility. */
 export type CodeEffect = "color" | "mimic" | "invisible" | "align" | "clip" | "nothing" | "space";
@@ -1095,6 +1101,23 @@ export interface BleedingLine {
 	/** The code Remastered carries onto it — the whole entry, so a caller can name it. */
 	carried: TextCode;
 }
+/**
+ * A line the game draws in more than one place at once. 0x12 and 0x13 move the text that
+ * follows them to the right or the centre of the line they are on, and 1.16.1 honoured
+ * every one of them: `Name<12>by Author` drew `Name` at the left and `by Author` at the
+ * right of the same line. Lobby names, unit names and briefings were built out of that —
+ * the "stacked" text a classic map shows and a renderer that takes one alignment for the
+ * whole line does not.
+ *
+ * `runsOf` is one of those renderers: `TextLine.align` holds a single alignment, the last
+ * one the line set, so every piece before it lands somewhere its author did not choose.
+ */
+export interface StackedLine {
+	/** 0-based index of the line within the string. */
+	line: number;
+	/** How many pieces of text the line draws, each at its own alignment. */
+	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 interface MapImageOptions {
@@ -2781,6 +2804,36 @@ export interface TriggersApi {
 	};
 	/** A trigger's `Comment` action text, when it has one. */
 	comment(trigger: TriggerRecord): string | null;
+	/**
+	 * 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.
+	 */
+	epd(address: 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. */
+	addressOf(player: number, unitId?: number): number;
+	/**
+	 * 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.
+	 */
+	fingerprint(trigger: TriggerRecord): string;
+	/**
+	 * 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.
+	 */
+	usage(list?: TriggerRecord[]): {
+		cells: [
+			player: number,
+			unit: number
+		][];
+		switches: number[];
+	};
 	/**
 	 * 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
@@ -3359,9 +3412,16 @@ export interface TriggerConsts {
 	readonly triggerFlags: typeof TriggerFlag;
 	/**
 	 * The address of the game's death table, which is the base an EUD player value is
-	 * counted from: `epd = (address - deathsTable) / 4 + 0x2000`.
+	 * counted from: `epd = (address - deathsTable) / 4` (`triggers.epd` does the sum).
 	 */
 	readonly deathsTable: number;
+	/**
+	 * The value of a condition's or action's trailing `mask` word that makes it a *masked*
+	 * record: the game then reads or writes only the bits set in the record's `location`
+	 * field, which is how one byte, one word or one bit of a dword is reached. StarCraft:
+	 * Remastered only; 1.16.1 ignores the word.
+	 */
+	readonly maskedRecord: 17235;
 }
 export interface ActiveBrush {
 	mode: TerrainMode;
@@ -3684,6 +3744,11 @@ export interface NamesApi {
  * remaster can draw in colours its author never chose — `bleedingLines` finds exactly
  * those lines and `fixBleeding` writes the reset the old game supplied. Pass
  * `resetPerLine` to `runs` to see the old rendering.
+ *
+ * The other thing the old game did and a modern renderer does not is honour every
+ * alignment code on a line, stacking the pieces between them in one place: `stackedLines`
+ * finds those lines and `flattenStacks` lays them out left to right. `runs` is one of the
+ * renderers that cannot show them — `TextLine.align` is one alignment for the whole line.
  */
 export interface TextApi {
 	/** Every byte the game gives a meaning, in order; `rgb` is set for the colours only. */
@@ -3710,6 +3775,19 @@ export interface TextApi {
 	 * games draw it alike. Idempotent, and never changes what the string says.
 	 */
 	fixBleeding(text: string): string;
+	/**
+	 * The lines of `text` that 1.16.1 drew at more than one alignment at once — the
+	 * "stacked" lobby and unit names a classic map is built with. A line whose only
+	 * alignment code sits at its head is not one: that code places the line.
+	 */
+	stackedLines(text: string): StackedLine[];
+	/**
+	 * `text` with every stacked line laid out left to right: the alignment codes that split
+	 * it dropped and its pieces joined in writing order, a space between two that would
+	 * otherwise run together. Colours and every other byte survive, so nothing the string
+	 * says is lost — only where each piece sat. Idempotent.
+	 */
+	flattenStacks(text: string): string;
 }
 export type DialogSize = "sm" | "md" | "lg" | "xl" | "full";
 export interface DialogButton {

package/package.json

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