@scm-js/plugin-api 1.4.0 → 1.6.0

package/index.d.ts

@@ -902,6 +902,8 @@ export interface ImagesDat {
 	lo: Uint32Array[];
 }
 export interface WeaponsDat {
+	/** The weapon's name: a 1-based `stat_txt.tbl` index, 0 for none. */
+	label: Uint16Array;
 	damage: Uint16Array;
 	/** Added per upgrade level. */
 	bonus: Uint16Array;
@@ -920,6 +922,8 @@ export interface UpgradesDat {
 	maxRepeats: Uint8Array;
 	/** 1 for upgrades only Brood War has. */
 	broodWar: Uint8Array;
+	/** The upgrade's name: a 1-based `stat_txt.tbl` index, 0 for none. */
+	label: Uint16Array;
 }
 /** The columns Technology Settings shows as defaults. */
 export interface TechdataDat {
@@ -930,6 +934,8 @@ export interface TechdataDat {
 	energyCost: Uint16Array;
 	/** 1 for abilities only Brood War has. */
 	broodWar: Uint8Array;
+	/** The technology's name: a 1-based `stat_txt.tbl` index, 0 for none. */
+	label: Uint16Array;
 }
 export interface SpriteGroup {
 	label: string;
@@ -1910,6 +1916,8 @@ export interface PluginApi {
 	readonly text: TextApi;
 	readonly query: QueryApi;
 	readonly data: DataApi;
+	/** Which set of game files the editor draws from — the game's own or a mod's — and installing, switching and removing sets. */
+	readonly gameData: GameDataApi;
 	/** Bit masks, special unit ids and the pixels-per-tile every record is written in. */
 	readonly consts: ConstsApi;
 	readonly graphics: GraphicsApi;
@@ -2737,6 +2745,16 @@ export interface ViewApi {
 	/** Grid spacing in map pixels (32 = one tile). */
 	gridSize(): number;
 	setGridSize(size: 8 | 16 | 32 | 64 | 128): void;
+	/**
+	 * Highlight something on the map for a moment: the rect an edit filled, the units it
+	 * placed, the location it moved. Fades by itself; several may run at once. Nothing to
+	 * clean up.
+	 *
+	 * @example
+	 * const r = api.document.edit("Fill", (tx) => tx.fillFlat(rect, terrain));
+	 * if (r.changed) api.view.flash({ rect });
+	 */
+	flash(target: FlashTarget): void;
 }
 export interface CommandSpec {
 	/**
@@ -2844,6 +2862,89 @@ export interface DataApi {
 	/** The GRP path an image id draws from, relative to `unit\`. */
 	imagePath(imageId: number): string | null;
 }
+/**
+ * A data set: one set of game files the editor draws from. The default is the game's
+ * own; any other is a mod's, installed under an id of its own, the same formats and
+ * table sizes with some of the files replaced.
+ */
+export interface GameDataProfile {
+	/** Lower-case letters, digits and hyphens, up to 40 characters. */
+	id: string;
+	/** What the dialog and the status line call it. */
+	name: string;
+}
+/** Where the session's game data comes from. */
+export interface GameDataSource {
+	/** `bundled` (this build's own files, or the desktop app's extraction), `stored` (a copy kept in the browser), or `none`. */
+	kind: "bundled" | "stored" | "none";
+	/** One line, as Help ▸ Game Data… shows it. */
+	label: string;
+	/** The data set the files belong to. */
+	profile: GameDataProfile;
+	/** Set when the desktop app extracted the files from a StarCraft installation. */
+	desktop: boolean;
+}
+/** Bytes for an install: a `File` / `Blob`, or already an array. */
+export type GameDataBytes = Blob | Uint8Array;
+/** What a data set is installed from. */
+export interface GameDataFiles {
+	/**
+	 * The archives, `StarDat.mpq` and `BrooDat.mpq` among them — a mod replaces files, it
+	 * does not bring the rest. The game's own are read first, then the others in the order
+	 * given, later ones winning as in the game.
+	 */
+	archives: readonly {
+		name: string;
+		data: GameDataBytes;
+	}[];
+	/** Loose files by member path (`arr/units.dat`, `unit/terran/marine.grp`), read before any archive. */
+	files?: readonly {
+		path: string;
+		data: GameDataBytes;
+	}[];
+}
+/**
+ * The game data as a whole: which set of files the editor draws from, and installing,
+ * switching and removing sets — the plugin side of Help ▸ Game Data…. What is *in* the
+ * files is `data` (the tables), `tileset` (the graphics), `graphics` (the pictures) and
+ * `names` (the labels, which follow the loaded set: a unit, weapon, upgrade or
+ * technology a mod renamed shows its new name, and the rest keep StarEdit's).
+ *
+ * A data set is a name over files in the game's own formats; a mod that extends the
+ * tables past the game's sizes is not covered. Installing needs the game's two archives
+ * every time, since a mod's files are laid over them the way its loader lays them.
+ *
+ * @example
+ * // A mod plugin: install its files once, then draw with them.
+ * const sets = await api.gameData.profiles();
+ * if (!sets.some((p) => p.id === "my-mod")) {
+ *   const files = await api.ui.pickFiles({ multiple: true });
+ *   if (files) await api.gameData.install({ id: "my-mod", name: "My Mod" }, { archives: files.map((f) => ({ name: f.name, data: f })) });
+ * }
+ * await api.gameData.select("my-mod");
+ */
+export interface GameDataApi {
+	/** The session's source, or null while it is still being resolved at startup. */
+	source(): GameDataSource | null;
+	/** The data set in use — the game's own until another is selected. */
+	profile(): GameDataProfile;
+	/** Every data set with a copy here, the game's own first. */
+	profiles(): Promise<GameDataProfile[]>;
+	/**
+	 * Extract a data set from its files, store it under `profile.id` and switch to it. The
+	 * archives must include the game's own two; the promise rejects with the reason when
+	 * they do not or the extraction fails. `progress` is 0–1 with a label, as the dialog's bar.
+	 */
+	install(profile: GameDataProfile, files: GameDataFiles, progress?: (fraction: number, label: string) => void): Promise<GameDataSource>;
+	/**
+	 * Switch to a data set. Everything decoded from the previous one is dropped and the
+	 * viewport redraws from the new files; a set with no copy here falls back to the game's
+	 * own. Resolves with the source in use afterwards.
+	 */
+	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>;
+}
 /**
  * The constants a plugin needs to *write* a record rather than read one: the bit masks in
  * a UNIT / THG2 / MRGN record, the condition, action and argument numbers of a TRIG /
@@ -3364,8 +3465,19 @@ export interface DialogHandle {
  */
 export interface PanelSpec {
 	title: string;
-	/** In CSS pixels; 260 by default. The panel is as tall as its content, up to the map's height. */
+	/** In CSS pixels; 260 by default. The panel is as tall as its content, up to the map's height. Ignored when docked. */
 	width?: number;
+	/**
+	 * Where the panel lives. `"float"` (the default) is a frame over the map the user drags
+	 * about. `"right"` puts it in the right dock as a panel of its own, under Minimap, Layers
+	 * and Properties, with the same head and hide button the built-in panels have — the
+	 * choice for anything the user keeps open while working, such as an assistant or a
+	 * readout. A docked panel shows the dock even when the user has hidden every built-in
+	 * panel in it.
+	 */
+	dock?: "float" | "right";
+	/** A docked panel that takes the dock's spare height (a transcript, a long list); off by default. */
+	grow?: boolean;
 	/** Fill `body` (an empty `<div>` inside the panel); return a cleanup if you need one. */
 	mount(body: HTMLElement, panel: PanelHandle): void | (() => void);
 	/** The panel closed, whichever way. */
@@ -3376,6 +3488,85 @@ export interface PanelHandle {
 	isOpen(): boolean;
 	setTitle(title: string): void;
 }
+/**
+ * One cell in the status bar (`ui.statusItem`): a line of text with the plugin's icon,
+ * a spinner while `busy`, and a click. It is how a plugin that works in the background
+ * stays visible without a panel — "AI · working 12 s", "3 problems", "Synced".
+ */
+export interface StatusItemSpec {
+	text: string;
+	/** The tooltip. */
+	title?: string;
+	/** Show a spinner in the cell. */
+	busy?: boolean;
+	/** Paint the cell as a warning. */
+	warn?: boolean;
+	onClick?: () => void;
+}
+export interface StatusItemHandle {
+	/** Change any of the fields; the cell redraws. */
+	set(patch: Partial<StatusItemSpec>): void;
+	remove(): void;
+	isShown(): boolean;
+}
+/**
+ * The dialogs a plugin may add to (`ui.dialogSlot`), and the fields each one exposes to
+ * the slot. A field is the dialog's *working copy* — what the person sees in the form,
+ * not yet applied to the map — so a slot's button can fill it in and leave OK to them.
+ *
+ * - `mapProperties`: `name`, `description`.
+ * - `textTriggerEditor`: `text` (the whole editor); `payload.briefing` says which list.
+ * - `triggerEditor`, `stringEditor`, `playerSettings`, `missionBriefing`: no fields, a slot only.
+ */
+export type SlottedDialogId = "mapProperties" | "textTriggerEditor" | "triggerEditor" | "stringEditor" | "playerSettings" | "missionBriefing";
+/** A form field a dialog lends to a slot: read it, set it, hear it change. */
+export interface DialogField {
+	get(): string;
+	set(value: string): void;
+}
+/** What a slot's `mount` is handed: which dialog, its payload, its fields, and a way to close it. */
+export interface DialogSlotHost {
+	readonly dialog: SlottedDialogId;
+	readonly payload: Readonly<Record<string, unknown>>;
+	readonly fields: Readonly<Record<string, DialogField>>;
+	close(): void;
+}
+/**
+ * Something a plugin mounts *inside* a built-in dialog — a button in Map Properties
+ * that suggests a name, one in the Text Trigger Editor that explains the text. The slot
+ * is a row at the left of the dialog's footer; fill it with the widgets, and it looks like
+ * part of the dialog. `mount` runs every time the dialog opens, with a cleanup on close.
+ */
+export interface DialogSlotSpec {
+	mount(body: HTMLElement, host: DialogSlotHost): void | (() => void);
+}
+/**
+ * What `view.flash` highlights: a tile rect, or units / locations by index. The
+ * highlight fades over `ms` (600 by default) and never blocks or takes the pointer; it is
+ * the shared way to say "this just changed" or "look here", so every plugin's flash looks
+ * the same. `kind` picks the colour: `"change"` (gold, the default) or `"attention"` (teal).
+ */
+export type FlashTarget = {
+	rect: Rect;
+	kind?: FlashKind;
+	ms?: number;
+} | {
+	units: number[];
+	kind?: FlashKind;
+	ms?: number;
+} | {
+	locations: number[];
+	kind?: FlashKind;
+	ms?: number;
+} | {
+	tiles: {
+		x: number;
+		y: number;
+	}[];
+	kind?: FlashKind;
+	ms?: number;
+};
+export type FlashKind = "change" | "attention";
 /** The pointer over the map, in the map's own units. A tile is 32 × 32 pixels. */
 export interface MapPointer {
 	/** Map pixels. Kept inside the map while a button is held, as the built-in brushes do. */
@@ -3519,8 +3710,33 @@ export interface UiApi {
 		fileName: string;
 	} | null>;
 	dialog(spec: DialogSpec): DialogHandle;
-	/** Open a floating panel over the map. As many as you like; each closes with the plugin. */
+	/**
+	 * Open a panel: floating over the map, or docked at the right with the built-in panels
+	 * (`spec.dock`). As many as you like; each closes with the plugin.
+	 */
 	panel(spec: PanelSpec): PanelHandle;
+	/**
+	 * A cell of your own in the status bar. One line of text beside the plugin's icon, a
+	 * spinner while `busy`, a click. Keep the handle and `set` it as things move; it
+	 * leaves with `remove()` or the plugin.
+	 */
+	statusItem(spec: StatusItemSpec): StatusItemHandle;
+	/**
+	 * Add to a built-in dialog. `mount` runs in a row at the left of the dialog's footer each
+	 * time that dialog opens, with the dialog's working-copy fields to read and fill
+	 * (`SlottedDialogId` lists which dialogs and fields). Returns the registration; it
+	 * leaves with `dispose()` or the plugin.
+	 *
+	 * @example
+	 * api.ui.dialogSlot("mapProperties", {
+	 *   mount(body, dlg) {
+	 *     body.append(api.ui.widgets.button("Suggest a name", { onClick: async () => {
+	 *       dlg.fields.name.set(await suggestName(dlg.fields.description.get()));
+	 *     } }));
+	 *   },
+	 * });
+	 */
+	dialogSlot(dialog: SlottedDialogId, spec: DialogSlotSpec): Disposable;
 	/**
 	 * Take over the pointer on the map until `stop()`, Esc, a right-click, a map change
 	 * or another tool. One tool runs at a time — starting one stops the previous — and a
@@ -3814,7 +4030,9 @@ export type PluginEvent =
 /** The document's file changed: its name or handle after a Save, the save options, the archive extras, the recent list. */
  | "file"
 /** A plugin registered or removed a command — how a plugin learns that one it calls by id has arrived. */
- | "commands";
+ | "commands"
+/** The game data source changed: installed, switched to another data set, or a copy removed. `gameData.source()` says what it is now. */
+ | "gameData";
 /** Why the document changed. */
 export type DocumentChangeReason = 
 /** File ▸ Open, drag-and-drop, `document.open`: a file the user chose. */

package/package.json

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