@scm-js/plugin-api 1.67.0 → 1.68.0

package/index.d.ts

@@ -905,8 +905,8 @@ export type TerrainPick = {
 	id: number;
 };
 export interface UnitsDat {
-	/** flingy.dat index. */
-	flingy: Uint8Array;
+	/** flingy.dat index (a byte in the game's layout, a word in the extended ones). */
+	flingy: Uint16Array;
 	/** First subunit (turret), or NO_UNIT. */
 	subunit: Uint16Array;
 	/** Starting facing 0–31 (0 = up, 8 = right, 16 = down), or RANDOM_DIRECTION. */
@@ -932,16 +932,16 @@ export interface UnitsDat {
 	buildTime: Uint16Array;
 	armor: Uint8Array;
 	/** weapons.dat ids, or NO_WEAPON. */
-	groundWeapon: Uint8Array;
-	airWeapon: Uint8Array;
+	groundWeapon: Uint16Array;
+	airWeapon: Uint16Array;
 	/** Bit 0 Zerg, 1 Terran, 2 Protoss, 3 men, 4 building, 5 factory, 6 independent, 7 neutral. */
 	groupFlags: Uint8Array;
 	/** StarEdit availability flags; all zero for the legacy layout. */
 	availability: Uint16Array;
 	/**
 	 * The unit's voice, as sfxdata.dat ids (0 for none): the one it says when trained, and
-	 * first–last ranges for a click, repeated clicks and an order. Only the first
-	 * `VOICED_UNITS` have ready / annoyed / yes sounds; every unit has a "what".
+	 * first–last ranges for a click, repeated clicks and an order. In the game's layout only
+	 * the first `VOICED_UNITS` have ready / annoyed / yes sounds (0 past them); every unit has a "what".
 	 */
 	readySound: Uint16Array;
 	whatSoundStart: Uint16Array;
@@ -1488,7 +1488,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" | "recovery" | "previousVersions" | "plugins" | "confirmPlugin" | "pluginDialog" | "gameData" | "update" | "whatsNew";
+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" | "whatsNew" | "mapDataSet";
 export interface MapImageOptions {
 	/** Output pixels per map tile. 32 matches the game's art 1:1; 1 is a minimap. */
 	pixelsPerTile: number;
@@ -4220,8 +4220,10 @@ export interface GraphicsApi {
 	 * The game's own button picture for a unit type, an upgrade or a technology — the icon
 	 * its command card shows — 36 × 34 at most and transparent round the edges. `look`
 	 * colours it as the game does: `"normal"` yellow (the default), `"disabled"` grey,
-	 * `"selected"` white. It does not depend on the map or its tileset. Null for an id with
-	 * no picture (a unit type past 227, a turret) and until `requestIcons` has the pictures;
+	 * `"selected"` white. It does not depend on the map or its tileset. A unit type past 227
+	 * has a picture only where the data set carries a sheet for every type
+	 * (`unit\cmdbtns\uniticons.grp`). Null for an id with no picture (a turret, a type past
+	 * 227 without that sheet) and until `requestIcons` has the pictures;
 	 * null for good from a game data copy made before the editor kept them (installing the
 	 * game data again brings them). The canvas is the editor's own cached one: draw from it.
 	 *
@@ -4248,6 +4250,39 @@ export interface GraphicsApi {
 	requestIcons(): boolean;
 	/** A GRP finished loading: anything drawn from one may look different now. */
 	onImageLoaded(listener: () => void): Disposable;
+	/**
+	 * Draw one frame of a GRP you hold — a mod's picture, one you made — the way the editor
+	 * draws a unit's: through a tileset's palette, with the team colour slots in a player's
+	 * colour, index 0 transparent. Either kind of GRP is read (the run-length one units use,
+	 * and the uncompressed one of the interface pictures). The canvas is the GRP's whole box,
+	 * as `unitImage`'s is. Resolves null when the bytes are no GRP, the frame is past its
+	 * last, or there is no game data to take the palette from. A GRP drawn through
+	 * `remapping` (fire, sparks) or Remastered's pictures are not drawn here.
+	 *
+	 * @example
+	 * const grp = await api.gameData.read("unit/terran/marine.grp");
+	 * const pic = grp && (await api.graphics.grpImage(grp, 0, { palette: "jungle", teamColor: 1 }));
+	 * if (pic) panelBody.append(pic.image);
+	 */
+	grpImage(grp: Uint8Array, frame: number, options?: GrpImageOptions): Promise<PluginImage | null>;
+}
+/** How `graphics.grpImage` draws a GRP. */
+export interface GrpImageOptions {
+	/**
+	 * The tileset whose palette the picture is drawn through, by its file name: `badlands`,
+	 * `platform`, `install`, `ashworld`, `jungle`, `desert`, `ice` or `twilight`. The open
+	 * map's by default.
+	 */
+	palette?: string;
+	/**
+	 * The player whose colour the team slots (indices 8–15) take, as the open map colours
+	 * its players; 0 by default. Null leaves them the palette's own.
+	 */
+	teamColor?: number | null;
+	/** Mirrored left to right, as a unit facing the other way is drawn. */
+	flipped?: boolean;
+	/** As a shadow: a half-transparent black silhouette. */
+	shadow?: boolean;
 }
 /**
  * The game's own tables, as the editor decoded them: `units.dat` and its neighbours.
@@ -4283,25 +4318,46 @@ export interface DataApi {
 }
 /**
  * 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.
+ * own; any other is installed under an id of its own, the same formats with some of the
+ * files replaced — its tables at any width (the game's, DatExtend's expanded layout or
+ * GPTP's `.datex`), its tilesets at any size.
  */
 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 data set's makers publish it, an `http(s)` address. A map saved with the data
+	 * set records it, and someone who opens that map without the data set is told it. The
+	 * editor never fetches it.
+	 */
+	url?: 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";
+	/**
+	 * `bundled` (this build's own files, or the desktop app's extraction), `stored` (a copy kept in the browser),
+	 * `reader` (a data set read through a function in memory, `gameData.attach`), or `none`.
+	 */
+	kind: "bundled" | "stored" | "reader" | "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;
+	/**
+	 * The data set's hash, where one is known: what a map saved with it records. Sixteen hex
+	 * digits over the files of the set that differ from the game's, by the rule `scmjs mod
+	 * play` hands the play page (`docs/cli.md`, "Playing a mod on the play page").
+	 */
+	hash?: string;
+	/**
+	 * The data set this one was laid over, when it was: `GameDataFiles.base` for an installed
+	 * set, and for a set in memory (`kind: "reader"`) the set in use when it was attached.
+	 */
+	base?: string;
 }
 /** Bytes for an install: a `File` / `Blob`, or already an array. */
 export type GameDataBytes = Blob | Uint8Array;
@@ -4316,11 +4372,58 @@ export interface GameDataFiles {
 		name: string;
 		data: GameDataBytes;
 	}[];
-	/** Loose files by member path (`arr/units.dat`, `unit/terran/marine.grp`), read before any archive. */
+	/** Loose files by member path (`arr/units.dat`, `arr/units.datex`, `unit/terran/marine.grp`), read before any archive. */
 	files?: readonly {
 		path: string;
 		data: GameDataBytes;
 	}[];
+	/**
+	 * Lay the files over the copy of this data set (an id from `profiles()`; the game's own is
+	 * `"starcraft"`) instead of over the game's archives, which `archives` then need not hold.
+	 * A copy the play page has used (one made with the game's files for playing) has every
+	 * picture the tables name; an older one has only what its own units show.
+	 */
+	base?: string;
+}
+/**
+ * What a `GameDataReader` is told beside the path it is asked for.
+ */
+export interface GameDataReadContext {
+	/**
+	 * The file as the game's archives name it, in lower case with backslashes:
+	 * `arr\units.dat` for `arr/units.dat`, `rez\stat_txt.tbl` for `tileset/stat_txt.tbl`,
+	 * `tileset\jungle\ofire.pcx` for `tileset/jungle.ofire.pcx`. A mod keeps its files under
+	 * these names, so a reader can look the file up without knowing the copy's layout. Null
+	 * for `unit/manifest.json` and `tileset/manifest.json`, the extraction's own lists.
+	 */
+	member: string | null;
+	/**
+	 * A file of the data set the reader was attached over, by its path in the extracted copy:
+	 * the game's own file beneath a mod's, to compare with or to answer from. Null when that
+	 * set has no such file. The same as `gameData.read(path, { under: true })`.
+	 */
+	under(path: string): Promise<Uint8Array | null>;
+}
+/**
+ * A data set that is a function in memory (`gameData.attach`): asked for a file by its path
+ * in the extracted copy (`arr/units.dat`, `unit/zerg/drone.grp`), it answers the bytes, or
+ * null to leave the file to the data set underneath. It may answer at once or with a promise.
+ * `file` names the same file as the game does and reads the set underneath.
+ *
+ * It need not answer `unit/manifest.json`: when it answers null the editor takes the list
+ * of the set underneath and works out from the reader's own files which tables are in
+ * GPTP's `.datex` layout and whether it brings unit names (`rez/unitnames.tbl`) and command
+ * card pictures (`unit/cmdbtns/uniticons.grp`). A reader that answers one is taken at its word.
+ */
+export type GameDataReader = (path: string, file: GameDataReadContext) => Uint8Array | null | undefined | Promise<Uint8Array | null | undefined>;
+/** How `gameData.read` reads. */
+export interface GameDataReadOptions {
+	/**
+	 * Read the data set under the one in use: when a set in memory is attached
+	 * (`gameData.attach`), the set it was attached over — the game's own file beneath a mod's,
+	 * without the reader being asked. The set in use when none is attached.
+	 */
+	under?: boolean;
 }
 /**
  * The game data as a whole: which set of files the editor draws from, and installing,
@@ -4329,9 +4432,11 @@ export interface GameDataFiles {
  * `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.
+ * A data set is a name over files in the game's own formats, at whatever width they
+ * have: a units.dat of more than 228 types gives the palette more types (named by
+ * `rez\unitnames.tbl` and pictured by `unit\cmdbtns\uniticons.grp` where the data set has
+ * them), a tileset of more than 2,048 groups draws its extended tiles. Installing lays the
+ * files over the game's two archives, as a loader does, or over a copy already here (`base`).
  *
  * @example
  * // A mod plugin: install its files once, then draw with them.
@@ -4368,8 +4473,59 @@ export interface GameDataApi {
 	 * 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.
+	 *
+	 * @example
+	 * // A mod's units.dat against the game's beneath it, while the mod is attached.
+	 * const mine = await api.gameData.read("arr/units.dat");
+	 * const theirs = await api.gameData.read("arr/units.dat", { under: true });
+	 */
+	read(path: string, options?: GameDataReadOptions): Promise<Uint8Array | null>;
+	/**
+	 * Where a copy keeps a file the game's archives name `member` — the path `read` and a
+	 * `GameDataReader` take: `arr\units.dat` is `arr/units.dat`, `rez\stat_txt.tbl` is
+	 * `tileset/stat_txt.tbl`, `tileset\jungle\ofire.pcx` is `tileset/jungle.ofire.pcx`. Any case,
+	 * either slash.
+	 */
+	storedPath(member: string): string;
+	/**
+	 * Draw from a data set that is a function in memory: every file is asked of `read` first,
+	 * and what it leaves (null) comes from the data set in use now. Nothing is stored and the
+	 * choice is not remembered — `select`, `install` or a reload leave it. The table and
+	 * picture editor's loop: change a file, `reload()`, see the map drawn with it. Units'
+	 * Remastered pictures are not drawn from such a data set (what it changed is not known).
+	 * `options.hash` is what a map saved with the set records and Test Map hands on (sixteen
+	 * hex digits by the rule of `GameDataSource.hash`); it can follow later with `rehash`.
+	 * Attaching reads everything again, even with the same profile and function.
+	 * Resolves with the source in use afterwards.
+	 *
+	 * @example
+	 * // Try a units.dat edit on the open map without installing anything.
+	 * const edited = new Map<string, Uint8Array>([["arr/units.dat", myUnitsDat]]);
+	 * await api.gameData.attach({ id: "draft", name: "Draft" }, (path) => edited.get(path) ?? null);
+	 * // … later, after changing the bytes in `edited`:
+	 * api.gameData.reload();
+	 */
+	attach(profile: GameDataProfile, read: GameDataReader, options?: {
+		hash?: string;
+	}): Promise<GameDataSource>;
+	/**
+	 * Read the data set in use afresh: everything decoded from it (tables, tilesets, pictures,
+	 * names) is dropped and the map is drawn again — after the files behind `attach` changed.
+	 */
+	reload(): void;
+	/**
+	 * Give the set in memory in use (`attach`) a new hash, or none with null, without reading
+	 * anything again: for a hash worked out after the files were attached or redrawn. What a
+	 * map saved from then on records and what Test Map hands on change; nothing is decoded
+	 * afresh. The `"gameData"` event fires. Returns the source, or null (and nothing
+	 * changes) when no set in memory is in use.
+	 *
+	 * @example
+	 * // Draw from the edit at once, and name it when its digest is ready.
+	 * api.gameData.reload();
+	 * api.gameData.rehash(await digestOfChangedFiles());
 	 */
-	read(path: string): Promise<Uint8Array | null>;
+	rehash(hash: string | null): GameDataSource | null;
 }
 /**
  * The constants a plugin needs to *write* a record rather than read one: the bit masks in
@@ -5154,9 +5310,34 @@ export interface PanelSpec {
 export interface FileTypeSpec {
 	/** What the files are, for File ▸ Open's list of types ("StarCraft replay"). */
 	name: string;
-	/** With the dot, any case: `[".rep"]`. */
+	/** With the dot, any case: `[".rep"]`. May be empty for a type that only opens folders (`openFolder`). */
 	extensions: string[];
 	open(files: File[]): void | Promise<void>;
+	/**
+	 * A folder dropped on the editor, as its files with their paths. Each folder of a drop is
+	 * offered on its own to the plugins that have `openFolder`, in the order they registered;
+	 * the first whose `acceptsFolder` passes (or that has none) takes it. A folder none
+	 * takes is left alone. Without `openFolder` a plugin is never offered a folder.
+	 *
+	 * @example
+	 * api.ui.fileType({
+	 *   name: "StarCraft mod", extensions: [".mpq"], open: openArchives,
+	 *   acceptsFolder: (paths) => paths.some((p) => /(^|\/)arr\/units\.dat(ex)?$/i.test(p)),
+	 *   openFolder: (files) => openLooseFiles(files),
+	 * });
+	 */
+	openFolder?(files: FolderFile[]): void | Promise<void>;
+	/** Whether a dropped folder is one `openFolder` opens, by its files' paths (`FolderFile.path`). */
+	acceptsFolder?(paths: readonly string[]): boolean;
+}
+/**
+ * One file of a folder the user picked or dropped, with where it is in the folder:
+ * `path` runs from the folder's parent with forward slashes, the folder's own name first
+ * (`My Mod/arr/units.dat`), as the browser's `webkitRelativePath` has it.
+ */
+export interface FolderFile {
+	path: string;
+	file: File;
 }
 /**
  * Another way to look at a map, shown where the map is drawn (`ui.mapView`): a replay's
@@ -5521,6 +5702,17 @@ export interface TestMapFile {
 	bytes: Uint8Array;
 	/** The file name the game would list, `.scx` or `.scm`. */
 	name: string;
+	/**
+	 * The data set the map is being made with, when it is not the game's own: its id and
+	 * name as `gameData.profile()` gives them, and the digest of its files (empty when none
+	 * is known). A target that plays the map should play it with those files — the site's
+	 * play page is handed it as `dataSet` in its `scmjs.play` message.
+	 */
+	dataSet?: {
+		id: string;
+		name: string;
+		hash: string;
+	};
 }
 /** What a preferences page's `mount` is handed. */
 export interface PreferencesPageHost {
@@ -5717,9 +5909,15 @@ export interface PickedObject {
 	index: number;
 }
 export interface PickFilesOptions {
-	/** `accept` for the file input, e.g. `"image/*"` or `".png,.jpg"`. */
+	/** `accept` for the file input, e.g. `"image/*"` or `".png,.jpg"`. Not used for a folder. */
 	accept?: string;
 	multiple?: boolean;
+	/**
+	 * Pick a folder rather than files: `pickFiles` then resolves with every file in it and
+	 * its subfolders as `FolderFile`s, with their paths. The browser's folder picker where it
+	 * has one, else the file input's folder mode; an empty list when the user cancels.
+	 */
+	directory?: boolean;
 }
 export interface UiApi {
 	/**
@@ -5834,8 +6032,21 @@ export interface UiApi {
 	 * hears the pointer, but never takes it. As many as you like; they go with the plugin.
 	 */
 	overlay(spec: OverlaySpec): OverlayHandle;
-	/** The browser's file picker; resolves with an empty list on cancel. */
-	pickFiles(options?: PickFilesOptions): Promise<File[]>;
+	/**
+	 * The browser's file picker; resolves with an empty list on cancel. With `directory: true`
+	 * the folder picker, resolving with the folder's files and their paths.
+	 *
+	 * @example
+	 * const files = await api.ui.pickFiles({ directory: true });
+	 * for (const { path, file } of files) api.log(`${path}: ${file.size} bytes`); // "My Mod/arr/units.dat: 19876 bytes"
+	 */
+	pickFiles(options: PickFilesOptions & {
+		directory: true;
+	}): Promise<FolderFile[]>;
+	pickFiles(options?: PickFilesOptions & {
+		directory?: false;
+	}): Promise<File[]>;
+	pickFiles(options?: PickFilesOptions): Promise<File[] | FolderFile[]>;
 	/**
 	 * Let the user drag a rectangle on the map. The viewport switches to a crosshair, draws
 	 * the marquee and takes the gesture ahead of the active layer's tools; resolves with

package/package.json

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