@scm-js/core 0.13.1 → 0.13.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/index.d.ts +99 -1
  2. package/dist/index.mjs +3832 -3600
  3. package/package.json +1 -1
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @scm-js/core 0.13.1 — StarCraft maps as the scmJS editor reads and writes them.
2
+ * @scm-js/core 0.13.3 — StarCraft maps as the scmJS editor reads and writes them.
3
3
  * Generated by `npm run build:core` in github.com/scm-js/scm-js from core/src/index.ts; the guide is docs/core.md.
4
4
  */
5
5
  import { Archive, HashEntry, StoredMember } from 'mopaq';
@@ -3290,6 +3290,28 @@ export declare const SYSTEM_FILES: {
3290
3290
  };
3291
3291
  /** Whether a path (either slash, any case) is one of `SYSTEM_FILES`: by its file name, or by a folder it is under. */
3292
3292
  export declare function isSystemFile(path: string): boolean;
3293
+ /** The game's own archives, by file name (lower case): what a 1.16.1 installation holds beside its program. */
3294
+ export declare const GAME_ARCHIVES: readonly [
3295
+ "stardat.mpq",
3296
+ "broodat.mpq",
3297
+ "patch_rt.mpq",
3298
+ "starcraft.mpq",
3299
+ "broodwar.mpq"
3300
+ ];
3301
+ /**
3302
+ * The files among `paths` (forward slashes) that are a copy of the game's own and so no part of a mod: in every folder
3303
+ * that holds a `StarDat.mpq`, that folder's `GAME_ARCHIVES` and every file under its `Maps` folder.
3304
+ *
3305
+ * A copy of the game in what was handed over is not the mod. A person hands over a folder that holds the mod's release
3306
+ * and, beside it, the whole game the mod runs on (Cosmonarchy's download: `Release/` and `Starcraft/`); laid as layers
3307
+ * of the mod, the game's archives became "the mod's" files, and in Windows' folder order `StarDat.mpq` came last and
3308
+ * carried original StarCraft's tables and iscript over Brood War's. A copy's `Maps` folder is the person's maps folder:
3309
+ nothing under it is a mod's (Cosmonarchy's copy keeps campaigns at `Maps/CMBW-Root/CMBW-maps/campaign/…`, and
3310
+ `campaign` is one of the game's folders, so they were taken for a mod's root). Apply it to each list a walk is given (a folder's
3311
+ * files, a zip's members), never to a single file the person names: some old mods ship as a replaced `patch_rt.mpq`.
3312
+ * The same rule is in the play page and the Mod Editor plugin: change them together.
3313
+ */
3314
+ export declare function gameCopyFiles(paths: readonly string[]): Set<string>;
3293
3315
  /**
3294
3316
  * The folder of a set of paths the game's paths start in: the one that holds `arr/`, else the one holding the most
3295
3317
  * files under the game's folders, the shallower on a tie; "" is the root. Paths use forward slashes. At any depth, as
@@ -3431,6 +3453,76 @@ export declare function modHash(input: {
3431
3453
  * game; this does not, so the set never depends on a copy.)
3432
3454
  */
3433
3455
  export declare function probeNames(read: (name: string) => Uint8Array | null): string[];
3456
+ /** A race a data set adds to the game's own. */
3457
+ export interface DataSetRace {
3458
+ /** The race byte: 8–255. (0–7 are the game's and cannot be declared.) */
3459
+ id: number;
3460
+ /** What it is called, 40 characters at most, trimmed, not empty. */
3461
+ name: string;
3462
+ /** The lower-case letter its per-race files go by (`game\<letter>console.pcx`, `rez\statbtn<letter>.bin`), when it has them. */
3463
+ letter?: string;
3464
+ /** The game's race it plays as, where only the game's three are known: 0, 1 or 2. Absent: not declared. */
3465
+ like?: 0 | 1 | 2;
3466
+ }
3467
+ /** The first race byte a data set may declare; 0–7 are the game's. */
3468
+ export declare const FIRST_DATASET_RACE = 8;
3469
+ /** The longest name a declared race may have. */
3470
+ export declare const RACE_NAME_MAX = 40;
3471
+ /**
3472
+ * The game's own eight races by their byte (0 Zerg … 7 Inactive), English as the editor's tables have them (shown
3473
+ * through `translate`).
3474
+ */
3475
+ export declare const GAME_RACE_NAMES: readonly string[];
3476
+ /**
3477
+ * A table of declared races as every carrier keeps it: each row's `id` an integer 8–255, its `name` trimmed, not empty
3478
+ * and at most 40 characters, `letter` one letter a–z (lower-cased) and `like` 0, 1 or 2 when present and valid (an
3479
+ * invalid one is left off the row). A row without a usable id or name is dropped, and so is a later row with an id an
3480
+ * earlier one has. Sorted by id. Fields a row has beyond these are kept. Anything that is not an array is an empty
3481
+ * table; nothing here throws.
3482
+ */
3483
+ export declare function normalizeRaces(value: unknown): DataSetRace[];
3484
+ /** Whether two tables say the same (after `normalizeRaces`): the same ids, names, letters and `like`s, in order. */
3485
+ export declare function sameRaces(a: readonly DataSetRace[], b: readonly DataSetRace[]): boolean;
3486
+ /**
3487
+ * A race by its byte: the game's own name (English, as `playerRaceLabel` gives it), else the name `races` declares,
3488
+ * else `Race {id}`. With no table it is `playerRaceLabel`.
3489
+ */
3490
+ export declare function raceLabel(id: number, races?: readonly DataSetRace[]): string;
3491
+ /** The races to offer for a choice: the game's eight in StarEdit's order, then the declared ones by id. */
3492
+ export declare function raceChoices(races?: readonly DataSetRace[]): {
3493
+ value: number;
3494
+ label: string;
3495
+ }[];
3496
+ /** How many entries the game's own `rez\network.tbl` has (1.16.1's, the same in Remastered): a mod's past it are its own. */
3497
+ export declare const GAME_NETWORK_TBL_ENTRIES = 168;
3498
+ /** What a mod's files suggest about the races it adds: hints for a person naming them, never names in themselves. */
3499
+ export interface RaceCandidates {
3500
+ /** Strings the mod's `rez\network.tbl` has past the game's own table, with their index there (0-based). */
3501
+ names: {
3502
+ index: number;
3503
+ name: string;
3504
+ }[];
3505
+ /** Letters other than z, t, p and n that have `game\<x>console.pcx` or `rez\statbtn<x>.bin`, sorted. */
3506
+ letters: string[];
3507
+ }
3508
+ /**
3509
+ * The hints a mod's files give about the races it adds. `network` is the mod's `rez\network.tbl` (null when it has
3510
+ * none); `gameNetwork` the game's own, from a copy of the game (its length is `GAME_NETWORK_TBL_ENTRIES` without one);
3511
+ * `paths` the mod's files by any spelling of their game names. A race's name must never be filled in from these alone.
3512
+ */
3513
+ export declare function raceCandidates(files: {
3514
+ network?: Uint8Array | null;
3515
+ gameNetwork?: Uint8Array | null;
3516
+ paths: Iterable<string>;
3517
+ }): RaceCandidates;
3518
+ /** Whether there is anything in `RaceCandidates` to offer. */
3519
+ export declare const hasRaceCandidates: (c: RaceCandidates) => boolean;
3520
+ /**
3521
+ * Which of the game's three races a player plays as, from the units they build or own: the Zerg, Terran or Protoss
3522
+ * group flag (units.dat's StarEdit group flags, bits 0–2) most of `unitIds` carry. Null when none carries one, when two
3523
+ * are carried by as many, or with no units: unknown, not guessed. A unit counts once per flag it carries.
3524
+ */
3525
+ export declare function racePlaysAs(unitIds: Iterable<number>, units: Pick<UnitsDat, "groupFlags">): 0 | 1 | 2 | null;
3434
3526
  /** The manifest's file name, at the folder's root. */
3435
3527
  export declare const MOD_MANIFEST = "mod.json";
3436
3528
  /** The folder format's version, `scmjs` in the manifest. */
@@ -3502,6 +3594,12 @@ export interface ModManifest {
3502
3594
  }[];
3503
3595
  /** Anything else a person should know about the folder (raw bytes in a text, …). */
3504
3596
  notes: string[];
3597
+ /**
3598
+ * The races the mod adds to the game's own (race bytes 8–255), when the person who made the folder declared them: no
3599
+ * file of a mod says what its races are called. Absent when none are declared. `mod.json` is no file of the mod, so
3600
+ * declaring a race leaves the mod's hash as it was.
3601
+ */
3602
+ races?: DataSetRace[];
3505
3603
  }
3506
3604
  export declare function emptyManifest(name?: string): ModManifest;
3507
3605
  /** A manifest as read from `mod.json`, every field filled; null when it is not one of ours. */