@scm-js/plugin-api 1.71.0 → 1.73.0

package/index.d.ts

@@ -861,6 +861,11 @@ export interface TerrainType extends TerrainName {
 	group: number;
 	height: 0 | 1 | 2;
 	buildable: boolean;
+	/**
+	 * The name in the user's language, where `name` is not a string of the catalogue's: a pair
+	 * terrain's name is put together ("Mud (mid ground)", "Group 3672"). Shown through `terrainLabel`.
+	 */
+	label?: string;
 }
 export type GroupKind = "terrain" | "edge" | "doodad" | "other";
 export interface TileInfo {
@@ -895,7 +900,11 @@ export interface Rect {
 	x1: number;
 	y1: number;
 }
-/** What Replace Terrain matches or writes: a flat terrain type (by ISOM id) or one exact tile. */
+/**
+ * What Replace Terrain matches or writes: a flat terrain type or one exact tile. A terrain's id
+ * is its ISOM id (the CV5 `index` of the flat pair), or a pair id (`palette.ts#PAIR_TERRAIN`)
+ * for flat ground the tileset does not type — a mod's added pairs.
+ */
 export type TerrainPick = {
 	kind: "terrain";
 	id: number;
@@ -4347,6 +4356,25 @@ export interface GameDataProfile {
 	 * editor never fetches it.
 	 */
 	url?: string;
+	/**
+	 * The races the data set adds to the game's own, when they are declared (no game file says
+	 * what a mod's races are called). Kept with the id: a profile handed to `attach` or
+	 * `install` with races keeps them, and one without gets those kept before for the same id —
+	 * after a new release of the mod (a new hash) as well. `setRaces` changes them. Absent in an
+	 * editor from before races a data set adds (`api.gameData.source()?.profile.races ?? []`).
+	 */
+	races?: DataSetRace[];
+}
+/** A race a data set adds to the game's own. */
+export interface DataSetRace {
+	/** The race byte: 8–255. (0–7 are the game's and cannot be declared.) */
+	id: number;
+	/** What it is called, 40 characters at most, trimmed, not empty. */
+	name: string;
+	/** The lower-case letter its per-race files go by (`game\<letter>console.pcx`, `rez\statbtn<letter>.bin`), when it has them. */
+	letter?: string;
+	/** The game's race it plays as, where only the game's three are known: 0, 1 or 2. Absent: not declared. */
+	like?: 0 | 1 | 2;
 }
 /** Where the session's game data comes from. */
 export interface GameDataSource {
@@ -4541,6 +4569,41 @@ export interface GameDataApi {
 	 * api.gameData.rehash(await modHashOfTheFiles());
 	 */
 	rehash(hash: string | null): GameDataSource | null;
+	/**
+	 * The races the data set in use adds; empty for the game's own or when none is declared.
+	 * Absent in an editor from before races a data set adds: call it as
+	 * `api.gameData.races?.() ?? []`.
+	 */
+	races(): DataSetRace[];
+	/**
+	 * Declare the races a data set adds, replacing its table: the data set in use by default,
+	 * or the profile `id`. Kept with the profile's id (it survives a new release of the mod and
+	 * a re-attach). Rows are normalized: sorted by id, a row with an id outside 8–255, an id an
+	 * earlier row has, or no name (or one over 40 characters) dropped; an empty list forgets
+	 * them. The game's own data set (and a Remastered installation's) takes none: returns null.
+	 * For the set in use, returns its source with the races, and fires what a change of the
+	 * data set fires (the `"gameData"` event), so open panels repaint; for another set, keeps
+	 * them for when it is used and returns null.
+	 *
+	 * @example
+	 * api.gameData.setRaces?.([{ id: 9, name: "Hivemind Remnant", letter: "h", like: 0 }]);
+	 * api.names.race(9); // "Hivemind Remnant"
+	 */
+	setRaces(races: readonly DataSetRace[], id?: string): GameDataSource | null;
+	/**
+	 * What the data set in use suggests about races it adds, for a person naming them: `names`,
+	 * the strings its `rez\network.tbl` has past the game's own table, and `letters`, the
+	 * letters other than z, t, p and n with a `game\<letter>console.pcx` or
+	 * `rez\statbtn<letter>.bin` of its own. Names and letters already declared are left out;
+	 * empty for the game's own data set. These are hints a person confirms, never names to fill
+	 * in. A set in memory (`attach`) is asked through its function; a stored copy keeps none of
+	 * these files, so it gives none. Absent in an editor from before it
+	 * (`api.gameData.raceCandidates?.()`).
+	 */
+	raceCandidates(): Promise<{
+		names: string[];
+		letters: string[];
+	}>;
 }
 /**
  * The constants a plugin needs to *write* a record rather than read one: the bit masks in
@@ -5071,8 +5134,12 @@ export interface NamesApi {
 	/** An OWNR / IOWN controller byte: `Human`, `Computer`, `Neutral`, … */
 	playerType(value: number): string;
 	playerTypes(): NamedValue[];
-	/** A SIDE race byte. */
+	/**
+	 * A SIDE race byte: the game's eight by name, a race the data set in use declares
+	 * (`gameData.races()`) by its name, any other `Race {n}`.
+	 */
 	race(value: number): string;
+	/** The game's eight races in StarEdit's order, then the races the data set in use declares, by id. */
 	races(): NamedValue[];
 	/** One of the 27 trigger player groups (`Player 1` … `Non Allied Victory Players`). */
 	playerGroup(value: number): string;
@@ -5721,12 +5788,14 @@ export interface TestMapFile {
 	 * 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.
+	 * play page is handed it as `dataSet` in its `scmjs.play` message. `races` when the data
+	 * set declares the races it adds (`gameData.races()`), so the target can name them.
 	 */
 	dataSet?: {
 		id: string;
 		name: string;
 		hash: string;
+		races?: DataSetRace[];
 	};
 }
 /** What a preferences page's `mount` is handed. */

package/package.json

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