@scm-js/core 0.12.1 → 0.13.0

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 +1259 -9
  2. package/dist/index.mjs +9773 -1840
  3. package/package.json +1 -1
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @scm-js/core 0.12.1 — StarCraft maps as the scmJS editor reads and writes them.
2
+ * @scm-js/core 0.13.0 — 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';
@@ -1062,8 +1062,8 @@ export type GameKind = "melee" | "ums";
1062
1062
  */
1063
1063
  export declare function requiredSections(fileVersion: number, game?: GameKind): string[];
1064
1064
  export interface UnitsDat {
1065
- /** flingy.dat index. */
1066
- flingy: Uint8Array;
1065
+ /** flingy.dat index (a byte in the game's layout, a word in the extended ones). */
1066
+ flingy: Uint16Array;
1067
1067
  /** First subunit (turret), or NO_UNIT. */
1068
1068
  subunit: Uint16Array;
1069
1069
  /** Starting facing 0–31 (0 = up, 8 = right, 16 = down), or RANDOM_DIRECTION. */
@@ -1089,16 +1089,16 @@ export interface UnitsDat {
1089
1089
  buildTime: Uint16Array;
1090
1090
  armor: Uint8Array;
1091
1091
  /** weapons.dat ids, or NO_WEAPON. */
1092
- groundWeapon: Uint8Array;
1093
- airWeapon: Uint8Array;
1092
+ groundWeapon: Uint16Array;
1093
+ airWeapon: Uint16Array;
1094
1094
  /** Bit 0 Zerg, 1 Terran, 2 Protoss, 3 men, 4 building, 5 factory, 6 independent, 7 neutral. */
1095
1095
  groupFlags: Uint8Array;
1096
1096
  /** StarEdit availability flags; all zero for the legacy layout. */
1097
1097
  availability: Uint16Array;
1098
1098
  /**
1099
1099
  * The unit's voice, as sfxdata.dat ids (0 for none): the one it says when trained, and
1100
- * first–last ranges for a click, repeated clicks and an order. Only the first
1101
- * `VOICED_UNITS` have ready / annoyed / yes sounds; every unit has a "what".
1100
+ * first–last ranges for a click, repeated clicks and an order. In the game's layout only
1101
+ * the first `VOICED_UNITS` have ready / annoyed / yes sounds (0 past them); every unit has a "what".
1102
1102
  */
1103
1103
  readySound: Uint16Array;
1104
1104
  whatSoundStart: Uint16Array;
@@ -1108,7 +1108,45 @@ export interface UnitsDat {
1108
1108
  yesSoundStart: Uint16Array;
1109
1109
  yesSoundEnd: Uint16Array;
1110
1110
  }
1111
- export declare function decodeUnitsDat(data: Uint8Array): UnitsDat;
1111
+ export interface FlingyDat {
1112
+ /** sprites.dat index. */
1113
+ sprite: Uint16Array;
1114
+ /** The fastest the flingy moves, in 1/256 pixel a frame (a Zergling's 1408 is 5.5 pixels a frame). */
1115
+ topSpeed: Uint32Array;
1116
+ /** How quickly it reaches that speed, in the same units a frame. */
1117
+ acceleration: Uint16Array;
1118
+ /** How far before its goal it starts to slow down, in 1/256 pixel. */
1119
+ haltDistance: Uint32Array;
1120
+ /** How sharply it turns. */
1121
+ turnRadius: Uint8Array;
1122
+ /** 0 flingy.dat's own figures, 1 partially mobile or weapon, 2 iscript.bin's (a unit whose walk is animated). */
1123
+ moveControl: Uint8Array;
1124
+ }
1125
+ export interface SpritesDat {
1126
+ /** images.dat index. */
1127
+ image: Uint16Array;
1128
+ }
1129
+ export interface ImagesDat {
1130
+ /** 1-based images.tbl index of the GRP path, relative to `unit\`. */
1131
+ grp: Uint32Array;
1132
+ /** 1 when the GRP holds 17 frames per facing set (directions 0–16, the rest mirrored). */
1133
+ graphicTurns: Uint8Array;
1134
+ drawFunction: Uint8Array;
1135
+ remapping: Uint8Array;
1136
+ /** iscript.bin id of the image's animation script. */
1137
+ iscript: Uint32Array;
1138
+ /** 1-based images.tbl indices of the overlay position files (0 = none), in LO_KINDS order. */
1139
+ lo: Uint32Array[];
1140
+ }
1141
+ /**
1142
+ * units.dat at any width: the game's 228 types (or the 19192-byte original, whose last two columns read 0),
1143
+ * DatExtend's expanded layout, or GPTP's `.datex` when `fileName` ends so. Throws when the size fits no layout.
1144
+ * Columns a layout stores only for a range of ids (the voices, 0–105) read 0 elsewhere.
1145
+ */
1146
+ export declare function decodeUnitsDat(data: Uint8Array, fileName?: string): UnitsDat;
1147
+ export declare function decodeFlingyDat(data: Uint8Array, fileName?: string): FlingyDat;
1148
+ export declare function decodeSpritesDat(data: Uint8Array, fileName?: string): SpritesDat;
1149
+ export declare function decodeImagesDat(data: Uint8Array, fileName?: string): ImagesDat;
1112
1150
  export declare const MEGATILE_PX = 32;
1113
1151
  export interface Cv5Group {
1114
1152
  /** Doodad groups store 1 here; terrain groups store a group type. */
@@ -1186,6 +1224,12 @@ export interface TilesetFiles {
1186
1224
  }
1187
1225
  /** A .vx4ex file is 64 bytes per megatile where .vx4 is 32; the caller usually knows which. */
1188
1226
  export declare function loadTileset(files: TilesetFiles): Tileset;
1227
+ /**
1228
+ * The CV5 group an MTXM value names, as the game takes it: bit 15 left out — unless the
1229
+ * tileset has more groups than eleven bits reach (`groupCount`), when the group is
1230
+ * `(id >> 4) & 0xFFF`.
1231
+ */
1232
+ export declare function tileGroupOf(tileId: number, groupCount?: number): number;
1189
1233
  /** Resolve an MTXM tile id to a VX4 megatile index, or -1 when the id is out of range. */
1190
1234
  export declare function megatileForTile(tileset: Tileset, tileId: number): number;
1191
1235
  /**
@@ -1311,7 +1355,7 @@ export declare function mapStatistics(scn: Scenario, tileset: Tileset | null, te
1311
1355
  /** The same numbers as plain text, for the clipboard. */
1312
1356
  export declare function statisticsText(s: MapStatistics): string;
1313
1357
  /** Every built-in dialog, by the id `openDialogAtom` takes; `DialogHost` maps each to its component. */
1314
- 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";
1358
+ 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";
1315
1359
  /**
1316
1360
  * The per-tileset tables StarEdit's isometric brush runs on.
1317
1361
  *
@@ -2161,6 +2205,16 @@ export declare function readWavs(scn: Scenario): number[];
2161
2205
  export declare function soundList(scn: Scenario, extras: Extras, wavs?: readonly number[]): SoundRow[];
2162
2206
  /** Install an edited table, creating the section when the file had none. Marks WAV dirty only on a change. */
2163
2207
  export declare function applySounds(scn: Scenario, wavs: readonly number[]): boolean;
2208
+ /** `fmt ` format tags this module knows by name. */
2209
+ export declare const WAV_FORMAT: {
2210
+ readonly pcm: 1;
2211
+ readonly msAdpcm: 2;
2212
+ readonly float: 3;
2213
+ readonly alaw: 6;
2214
+ readonly mulaw: 7;
2215
+ readonly imaAdpcm: 17;
2216
+ readonly extensible: 65534;
2217
+ };
2164
2218
  export interface WavInfo {
2165
2219
  /** The `fmt ` tag; for WAVE_FORMAT_EXTENSIBLE the sub-format's tag (its GUID's first field). */
2166
2220
  format: number;
@@ -2176,12 +2230,45 @@ export interface WavInfo {
2176
2230
  /** The `fmt ` chunk's bytes past the 16 common ones (ADPCM's block parameters and coefficients). */
2177
2231
  extra: Uint8Array;
2178
2232
  }
2233
+ /** Whether Web Audio and the game both play the file as it is: integer PCM, 8 or 16 bits. */
2234
+ export declare function isPlainPcm(info: WavInfo): boolean;
2235
+ /** Whether `decodeWav` reads this encoding. */
2236
+ export declare function canDecodeWav(info: WavInfo): boolean;
2237
+ /** Frames in the data chunk, for any encoding this module knows. */
2238
+ export declare function wavFrames(info: WavInfo): number;
2179
2239
  /** Duration in seconds, from the header — no decoding needed. */
2180
2240
  export declare function wavDuration(info: WavInfo): number;
2181
2241
  /** A short label: `22050 Hz · 16-bit · mono`, with the codec named when it is not plain PCM. */
2182
2242
  export declare function wavFormatLabel(info: WavInfo): string;
2243
+ export declare function wavCodecName(format: number): string | null;
2183
2244
  /** Reads the header of a RIFF/WAVE file; null when the bytes are not one. */
2184
2245
  export declare function parseWavHeader(bytes: Uint8Array): WavInfo | null;
2246
+ export type WavBits = 8 | 16;
2247
+ /**
2248
+ * Writes plain PCM: 8-bit unsigned or 16-bit signed little-endian, channels interleaved.
2249
+ * Samples are floats in -1..1 and are clipped; every channel is taken to be `channels[0]`'s length.
2250
+ */
2251
+ export declare function encodeWav(channels: readonly Float32Array[], sampleRate: number, bits: WavBits): Uint8Array;
2252
+ export interface PcmAudio {
2253
+ sampleRate: number;
2254
+ /** One Float32Array per channel, samples in -1..1. */
2255
+ channels: Float32Array[];
2256
+ }
2257
+ /** Reads plain 8/16-bit PCM back into floats; null for anything else (`decodeWav` takes the rest). */
2258
+ export declare function decodePcmWav(bytes: Uint8Array): PcmAudio | null;
2259
+ /**
2260
+ * Reads any WAV encoding this module knows (`canDecodeWav`) back into floats — the game's
2261
+ * IMA ADPCM sounds included; null for a file that is not a WAV or is in an encoding it
2262
+ * does not know (then Web Audio may still take it).
2263
+ */
2264
+ export declare function decodeWav(bytes: Uint8Array): PcmAudio | null;
2265
+ /**
2266
+ * IMA ADPCM (format 0x11): per block, a 4-byte header per channel — the first sample as a
2267
+ * signed 16-bit value, then the step index — followed by 4-byte words of eight nibbles,
2268
+ * one word per channel in turn, low nibble first. What the game's own sound files are.
2269
+ * `info` is the file's header (`parseWavHeader`); `decodeWav` picks this for format 0x11.
2270
+ */
2271
+ export declare function decodeImaAdpcm(bytes: Uint8Array, info: WavInfo): PcmAudio;
2185
2272
  export interface BaseTerrain {
2186
2273
  /** CV5 group `index`, which is also the ISOM terrain id. */
2187
2274
  id: number;
@@ -2376,6 +2463,33 @@ export declare function checkDoodadPlacement(scn: Scenario, tileset: Tileset | n
2376
2463
  * with the old copy removed). Nothing is applied.
2377
2464
  */
2378
2465
  export declare function placeDoodad(scn: Scenario, def: DoodadDef, tx: number, ty: number, owner: number, tileAt?: (at: number) => number): DoodadEdit;
2466
+ export interface IscriptHeader {
2467
+ id: number;
2468
+ type: number;
2469
+ /** Code offset per animation slot (see `Anim`); 0 when the header has no such animation. */
2470
+ anims: number[];
2471
+ }
2472
+ export interface IscriptBin {
2473
+ data: Uint8Array;
2474
+ headers: Map<number, IscriptHeader>;
2475
+ }
2476
+ /**
2477
+ * The id table and each header's entry points. How many entry points a header has depends
2478
+ * on the compiler that wrote the file: the game's own file and PyMS's give a type the
2479
+ * counts of `ANIM_COUNT_BY_TYPE`, IceCC — which most mods' binaries come from — writes
2480
+ * `type + 1` (`iscriptText.ts#readIscriptHeaders` tells them apart by where the headers sit).
2481
+ */
2482
+ export declare function decodeIscript(data: Uint8Array): IscriptBin;
2483
+ /** The tables a walking speed is read from. */
2484
+ export interface SpeedTables {
2485
+ units: UnitsDat;
2486
+ flingy: FlingyDat;
2487
+ sprites: SpritesDat;
2488
+ images: ImagesDat;
2489
+ iscript: IscriptBin;
2490
+ }
2491
+ /** Pixels a frame a unit walks at its top speed, unupgraded; null when the tables do not say (a building, a bad id). */
2492
+ export declare function walkSpeed(t: SpeedTables, unitId: number): number | null;
2379
2493
  /** OWNR controller bytes as StarEdit's Player Settings lists them, with the rest for maps that use them. */
2380
2494
  export declare const PLAYER_TYPES: {
2381
2495
  value: number;
@@ -2402,6 +2516,1142 @@ export declare function playerColorHex(colors: readonly number[] | null | undefi
2402
2516
  * Remastered custom RGB when the slot is set to one, else its palette entry.
2403
2517
  */
2404
2518
  export declare function displayColorHex(colors: readonly number[] | null | undefined, rgb: PlayerRgb | null | undefined, owner: number): string;
2519
+ /**
2520
+ * Every field of every `arr\*.dat` table, as data: what the game's tables hold, in file order, with the names PyMS
2521
+ * gives them (so a table exported here as PyDAT TXT reads in PyDAT, and the other way round).
2522
+ *
2523
+ * A table is a struct of arrays: field 1 for every entry, then field 2 for every entry, and so on. Three layouts are
2524
+ * in use, and `table.ts` reads all three, taking the width (how many entries) from the file's length:
2525
+ *
2526
+ * - **dat**, the game's own: a fixed count (228 units, 130 weapons, …), and a few columns that exist only for a
2527
+ * range of ids (`first` / `count` below — units.dat's infestation column covers ids 106–201 only, the sounds a unit
2528
+ * says when selected cover 0–105). units.dat from before Brood War also lacks its last two columns (`legacy`).
2529
+ * - **expanded**, DatExtend's as PyMS reads it: any count, every column at the full count, and units.dat's flingy
2530
+ * column widened to u16 (`expanded`). PyMS adds rules for units (a multiple of 12, 250–912, ids 228–250 reserved);
2531
+ * they are not a property of the file, so nothing here enforces them.
2532
+ * - **datex**, GPTP's DatExtend (`*.datex`): no header, every column at the full count, and units.dat's flingy, ground
2533
+ * weapon and air weapon columns and orders.dat's weapon column widened to u16 (`datex`). The count is the file's
2534
+ * size over the entry size (99 bytes a unit). GPTP's own limits (3,000 units, …) are its build's, not the file's.
2535
+ *
2536
+ * The schema is plain JSON-able data (`JSON.stringify(DAT_SCHEMAS)`), so it can be published and read by other tools.
2537
+ * Field meanings and pointers follow PyMS (`FileFormats/DAT/*.py`, Help/Files/DAT) and GPTP's DatExtend sources; the
2538
+ * code of neither is included here. Sources and licenses: ../../../ATTRIBUTION.md
2539
+ */
2540
+ export type DatValueType = "u8" | "u16" | "u32";
2541
+ /** How PyDAT TXT writes a value that is not a plain number. */
2542
+ export type DatTextCoder =
2543
+ /** 0 → False, 1 → True, anything else as the number. */
2544
+ {
2545
+ kind: "bool";
2546
+ }
2547
+ /** One line a bit: `field.name True|False`; `names[bit]` names it, "" for `flag_0xNN`. */
2548
+ | {
2549
+ kind: "flags";
2550
+ bits: number;
2551
+ names: readonly string[];
2552
+ }
2553
+ /** `whole` = value >> 8, `fraction` = value & 0xFF (units.dat hit points are 24.8 fixed point). */
2554
+ | {
2555
+ kind: "hitPoints";
2556
+ }
2557
+ /** `whole` = value >> 1, `half` = value & 1 (supply is counted in halves). */
2558
+ | {
2559
+ kind: "supply";
2560
+ };
2561
+ export interface DatField {
2562
+ /** PyDAT TXT's name for the field; also the column's key. */
2563
+ name: string;
2564
+ /** The value's width in the standard layout. */
2565
+ type: DatValueType;
2566
+ /** A small struct of `type` values an entry (placement box, extents): the part names, in file order. */
2567
+ parts?: readonly string[];
2568
+ /** Standard layout only: the field is stored for ids `first` to `first + count - 1` and nothing else. */
2569
+ first?: number;
2570
+ count?: number;
2571
+ /** The width in DatExtend's expanded layout (PyMS), when it differs. */
2572
+ expanded?: DatValueType;
2573
+ /** The width in GPTP's `.datex`, when it differs. */
2574
+ datex?: DatValueType;
2575
+ /** How PyDAT TXT writes it, when not as a plain number. */
2576
+ text?: DatTextCoder;
2577
+ /** PyDAT TXT's dotted name when it is not `name` (portdata's `idle.portrait_file`). */
2578
+ textName?: string;
2579
+ /** What the value points at: a table (`flingy`, …), a string table (`stat_txt.tbl`), `iscript.bin`, `cmdicons.grp`. */
2580
+ ref?: string;
2581
+ /** Absent from the original (pre-Brood War) game's units.dat. */
2582
+ broodWar?: true;
2583
+ }
2584
+ export type DatTableName = "units" | "weapons" | "flingy" | "sprites" | "images" | "upgrades" | "techdata" | "orders" | "sfxdata" | "portdata" | "mapdata";
2585
+ export interface DatSchema {
2586
+ table: DatTableName;
2587
+ /** The file's name in the game's archives. */
2588
+ file: string;
2589
+ /** Entries in the game's own file. */
2590
+ entries: number;
2591
+ /** The entry header PyDAT TXT writes: `Unit(0):`. */
2592
+ textType: string;
2593
+ fields: readonly DatField[];
2594
+ /** PyMS's rules for an expanded file of this table; informational (see the module comment). */
2595
+ expandedRules?: {
2596
+ min?: number;
2597
+ max?: number;
2598
+ multiple?: number;
2599
+ reserved?: readonly [
2600
+ number,
2601
+ number
2602
+ ];
2603
+ };
2604
+ /** GPTP DatExtend's id limit for the table (`dat_limits.h`); informational — the width is always the file's. */
2605
+ datexLimit?: number;
2606
+ /** PyDAT TXT's line order when it is not field order (portdata groups idle and talking). */
2607
+ textOrder?: readonly string[];
2608
+ }
2609
+ /** The eleven tables, by name. */
2610
+ export declare const DAT_SCHEMAS: Readonly<Record<DatTableName, DatSchema>>;
2611
+ export declare const DAT_TABLES: DatTableName[];
2612
+ /** The table a file name is for (`units.dat`, `arr\units.datex`, `UNITS.DAT`), or null. */
2613
+ export declare function datTableOf(fileName: string): DatTableName | null;
2614
+ export type DatLayout = "dat" | "expanded" | "datex";
2615
+ export type Column = Uint8Array | Uint16Array | Uint32Array;
2616
+ export interface DatFile {
2617
+ table: DatTableName;
2618
+ layout: DatLayout;
2619
+ /** Entries in the file. */
2620
+ count: number;
2621
+ /** units.dat from before Brood War: no `broodwar_unit_flag` / `staredit_availability_flags` columns. */
2622
+ legacy: boolean;
2623
+ /**
2624
+ * One array a field, `count × parts` long (parts entry by entry: width, height, width, …). In the standard layout an
2625
+ * entry outside a field's stored range reads 0 and is not written.
2626
+ */
2627
+ columns: Record<string, Column>;
2628
+ }
2629
+ /** A row: plain fields as numbers, struct fields (`unit_extents`) as `{ left, up, right, down }`. A field the entry does not store is absent. */
2630
+ export type DatRow = Record<string, number | Record<string, number>>;
2631
+ /** The field's width in a layout. */
2632
+ export declare function fieldType(field: DatField, layout: DatLayout): DatValueType;
2633
+ /** The ids a field stores in a layout: [first, end). */
2634
+ export declare function storedRange(field: DatField, layout: DatLayout, count: number): [
2635
+ number,
2636
+ number
2637
+ ];
2638
+ /** Bytes an entry takes when every column is at the full count (the expanded and `.datex` layouts). */
2639
+ export declare function datEntrySize(table: DatTableName | DatSchema, layout: "expanded" | "datex"): number;
2640
+ /** The game's own file size for the table (19876 for units.dat; 19192 with `legacy`). */
2641
+ export declare function datStandardSize(table: DatTableName | DatSchema, legacy?: boolean): number;
2642
+ export interface DatShape {
2643
+ layout: DatLayout;
2644
+ count: number;
2645
+ legacy: boolean;
2646
+ }
2647
+ /**
2648
+ * The layout and width a file of `size` bytes has. A `.datex` name means GPTP's layout; otherwise the game's size is
2649
+ * the standard layout, and any other multiple of an entry is DatExtend's expanded one (PyMS's reading), else `.datex`'s.
2650
+ * Null when the size fits none.
2651
+ */
2652
+ export declare function datShape(table: DatTableName | DatSchema, size: number, fileName?: string): DatShape | null;
2653
+ /** An empty table of `count` entries (all zeros). */
2654
+ export declare function emptyDat(table: DatTableName, count?: number, layout?: DatLayout): DatFile;
2655
+ export interface DecodeDatOptions {
2656
+ /** The file's name (`units.datex`): a `.datex` name picks GPTP's layout. */
2657
+ fileName?: string;
2658
+ /** Read as this layout, the count from the size. */
2659
+ layout?: DatLayout;
2660
+ }
2661
+ /** A whole table. Throws when the size fits no layout of the table. */
2662
+ export declare function decodeDat(table: DatTableName, data: Uint8Array, options?: DecodeDatOptions): DatFile;
2663
+ /** The file's bytes, in its own layout (or `layout`, at the same count). Throws when a value does not fit its column. */
2664
+ export declare function encodeDat(file: DatFile, layout?: DatLayout): Uint8Array;
2665
+ /** Whether entry `id` stores `field` in the file's layout. */
2666
+ export declare function datHas(file: DatFile, field: DatField, id: number): boolean;
2667
+ /** Entry `id` as a row. */
2668
+ export declare function datRow(file: DatFile, id: number): DatRow;
2669
+ /** Every entry as a row. */
2670
+ export declare function datRows(file: DatFile): DatRow[];
2671
+ /** Set the fields a row names on entry `id` (others are left as they are). */
2672
+ export declare function setDatRow(file: DatFile, id: number, row: DatRow): void;
2673
+ /** A table from rows (entry i = rows[i]), in a layout. */
2674
+ export declare function datFromRows(table: DatTableName, rows: readonly DatRow[], layout?: DatLayout): DatFile;
2675
+ export interface DatToTextOptions {
2676
+ /** A name for an entry, written after its header as a comment (`Unit(0): # Terran Marine`), which PyDAT skips. */
2677
+ name?: (id: number) => string | undefined;
2678
+ }
2679
+ /** PyDAT TXT: one block an entry (`Unit(0):`, then a tab-indented `field value` line each), a blank line after each. */
2680
+ export declare function datToText(file: DatFile, ids?: readonly number[] | null, options?: DatToTextOptions): string;
2681
+ export interface DatTextEntry {
2682
+ type: string;
2683
+ id: number;
2684
+ /** Line number (1-based) of the header. */
2685
+ line: number;
2686
+ /** `field` or `field.part` → value; True/False as 1/0. */
2687
+ values: Map<string, {
2688
+ value: number;
2689
+ line: number;
2690
+ }>;
2691
+ }
2692
+ export declare class DatTextError extends Error {
2693
+ readonly line: number;
2694
+ constructor(message: string, line: number);
2695
+ }
2696
+ /** PyDAT TXT's entries, as written (no schema applied). `#` starts a comment. */
2697
+ export declare function parseDatText(text: string): DatTextEntry[];
2698
+ export interface DatFromTextOptions {
2699
+ /** Apply the text over this table (a copy is made); entries and fields the text leaves out keep its values. */
2700
+ base?: DatFile;
2701
+ /** Without a base: the layout of the new table (the game's when the entries are its count, else expanded). */
2702
+ layout?: DatLayout;
2703
+ /** Without a base: the entry count (default: the highest id in the text + 1, at least the game's count). */
2704
+ count?: number;
2705
+ }
2706
+ /** A table from PyDAT TXT. */
2707
+ export declare function datFromText(table: DatTableName, text: string, options?: DatFromTextOptions): DatFile;
2708
+ export interface TblFile {
2709
+ /** Whole entries, NULs included. */
2710
+ strings: string[];
2711
+ encoding: TextEncoding;
2712
+ }
2713
+ export declare function decodeTblFile(data: Uint8Array, encoding?: TextEncoding): TblFile;
2714
+ /** The bytes PyTBL writes: entries in order, each with a NUL added when it lacks one. */
2715
+ export declare function encodeTblFile(file: TblFile): Uint8Array;
2716
+ /** One entry as a PyTBL line. */
2717
+ export declare function tblEscape(s: string): string;
2718
+ /** A PyTBL line's entry: `<N>` (0–255) is that character. */
2719
+ export declare function tblUnescape(s: string): string;
2720
+ /** PyTBL text: a line an entry. */
2721
+ export declare function tblToText(strings: readonly string[]): string;
2722
+ /** The entries of PyTBL text. A line beginning with `#` is a comment; everything after a `#` elsewhere is too. */
2723
+ export declare function tblFromText(text: string): string[];
2724
+ /**
2725
+ * GRP sprite sheets as pictures, and written back. `grp.ts` draws straight from the file; this module turns a GRP
2726
+ * into its frames' pixels (palette indices, 0 = transparent) and encodes frames into a GRP the way the game's own
2727
+ * files are encoded, so that the game's GRPs decode and encode to the same bytes.
2728
+ *
2729
+ * header u16 frames, u16 width, u16 height
2730
+ * frame table u8 x, u8 y, u8 width, u8 height, u32 offset (8 bytes each)
2731
+ * frame data u16 lineOffset[height] (from the frame's start), then each line:
2732
+ * 0x80|n n transparent pixels (n ≤ 127)
2733
+ * 0x40|n the next byte, n times (n ≤ 63)
2734
+ * n the next n bytes (n ≤ 63)
2735
+ *
2736
+ * The game's encoder (as measured on the 838 GRPs of 1.16.1): a run of transparent pixels is always a skip; a run of
2737
+ * four or more equal pixels is a repeat; anything else is copied, at most 63 bytes at a time — and while copying, a
2738
+ * run is measured only as far as the copy has room, so a run that starts near a full copy's end is copied. Trailing
2739
+ * transparency is written like any other. A frame whose bytes equal an earlier frame's points at
2740
+ * that frame's data instead of a copy of it.
2741
+ *
2742
+ * **Uncompressed GRPs.** The game's interface pictures (`dlgs\*.grp`, `glue\…\dlg.grp`, `glue\…\iScore.grp`,
2743
+ * `glue\chatroom\ichat.grp`, `game\icons.grp`) store each frame as its `width × height` palette indices, row by row,
2744
+ * with no line table — the same header and frame table, and the same sharing of equal frames. Nothing in the file says
2745
+ * which kind it is (the code that draws it knows; GPTP calls the two `FrameFormat::Rle` and `Raw`), so a GRP is read
2746
+ * uncompressed only when its lines do not read (an offset outside the file, a line that never ends) and its frames
2747
+ * pack their `width × height` bytes one after another from the end of the frame table to the file's last byte. Both
2748
+ * hold for all 22 of the game's interface GRPs and Cosmonarchy's 37; a GRP whose lines do read stays run-length (a
2749
+ * tiny one can pack both ways: a 4 × 4 frame of one colour is 16 bytes run-length encoded).
2750
+ */
2751
+ /** One frame: its box inside the GRP's shared box, and `width × height` palette indices. */
2752
+ export interface GrpFramePixels {
2753
+ x: number;
2754
+ y: number;
2755
+ width: number;
2756
+ height: number;
2757
+ pixels: Uint8Array;
2758
+ }
2759
+ export interface GrpImage {
2760
+ width: number;
2761
+ height: number;
2762
+ frames: GrpFramePixels[];
2763
+ /** The frames are stored uncompressed (`width × height` bytes each, no line table), as the game's interface GRPs are. */
2764
+ raw?: true;
2765
+ /**
2766
+ * Which frames share their data, when that is not "every frame equal to an earlier one" (the encoder's rule without
2767
+ * it): for each frame, the first frame whose data it points at (its own index when it has data of its own). Only an
2768
+ * uncompressed GRP has it, and only when its maker shared otherwise — the game's `dlgs\*.grp` store one frame twice,
2769
+ * Cosmonarchy's `glue\dlg.grp` shares none. A frame edited since no longer equal to the one named gets its own data.
2770
+ */
2771
+ shares?: number[];
2772
+ }
2773
+ export declare function decodeGrpImage(data: Uint8Array): GrpImage;
2774
+ /** One line's bytes, the way the game's encoder writes them. */
2775
+ export declare function encodeGrpLine(pixels: Uint8Array, out: number[]): void;
2776
+ /** One frame's data: the line table, then the lines. */
2777
+ export declare function encodeGrpFrame(frame: GrpFramePixels): Uint8Array;
2778
+ /**
2779
+ * A GRP's bytes: the frames run-length encoded the game's way, or stored as they are when `image.raw`. A frame equal
2780
+ * to an earlier one points at its data — or, when `image.shares` is given, the frame it names, if still equal.
2781
+ */
2782
+ export declare function encodeGrpImage(image: GrpImage): Uint8Array;
2783
+ /** The smallest box around a frame's opaque pixels, as the game's frames are cut: `{ x, y, width, height }` inside the frame. */
2784
+ export declare function opaqueBox(pixels: Uint8Array, width: number, height: number): {
2785
+ x: number;
2786
+ y: number;
2787
+ width: number;
2788
+ height: number;
2789
+ };
2790
+ /** A whole picture as a frame: the opaque part cut out, with its offset kept (how the game's frames are stored). */
2791
+ export declare function frameFromPicture(pixels: Uint8Array, width: number, height: number): GrpFramePixels;
2792
+ /** A frame drawn into the GRP's full box (`image.width × image.height` indices, 0 outside the frame). */
2793
+ export declare function framePicture(image: GrpImage, index: number): Uint8Array;
2794
+ /**
2795
+ * 8-bit PCX read and written (the game's `game\tunit.pcx`, `tileset\*\ofire.pcx`, …). `pcx.ts` is the editor's
2796
+ * reader; this one keeps the 128-byte header so a file comes back byte for byte, and writes new ones.
2797
+ *
2798
+ * header (128 bytes): 0x0A, version 5, RLE 1, 8 bits, xmin ymin xmax ymax, dpi, 48-byte EGA palette, 0,
2799
+ * 1 plane, bytes per line (even by the standard; game\thpbar.pcx has 19), palette type, screen size, 54 zero bytes
2800
+ * pixels: each line `bytesPerLine` bytes, run-length coded — a byte ≥ 0xC0 is a count (low 6 bits) for the next
2801
+ * byte; any other byte is itself. Runs do not cross lines.
2802
+ * palette: 0x0C, then 256 × RGB.
2803
+ */
2804
+ export interface PcxImage {
2805
+ width: number;
2806
+ height: number;
2807
+ /** `width × height` palette indices, row-major. */
2808
+ pixels: Uint8Array;
2809
+ /** 256 × RGB, or null for none. */
2810
+ palette: Uint8Array | null;
2811
+ /** The file's header as read, reused (with this image's size) when written. */
2812
+ header?: Uint8Array;
2813
+ /** Bytes a line takes in the file (≥ width; even in a standard file, odd in a few of the game's). */
2814
+ bytesPerLine?: number;
2815
+ /** The value a line's padding byte had. */
2816
+ padding?: number;
2817
+ }
2818
+ export declare function decodePcxImage(data: Uint8Array): PcxImage;
2819
+ /** A PCX: the image's own header when it has one (the size set from the image), else a standard one. */
2820
+ export declare function encodePcxImage(image: PcxImage): Uint8Array;
2821
+ /**
2822
+ * `.lo?` overlay offsets (`unit\terran\control.lof`, …) read and written, and PyLO's text form. `lo.ts` is the editor's
2823
+ * reader (offsets in one array, with lookup helpers); this module holds a file as frames of `[x, y]` pairs, the way
2824
+ * PyLO does, and writes it back.
2825
+ *
2826
+ * u32 frames, u32 overlays per frame, u32 offset[frames], then each frame's `overlays × (s8 x, s8 y)`.
2827
+ *
2828
+ * PyLO text: `Frame:` then one ` (x, y)` line an overlay, a blank line after each frame; `#` starts a comment.
2829
+ */
2830
+ export interface LoOverlays {
2831
+ /** frames[frame][overlay] = [x, y], each −128…127. */
2832
+ frames: [
2833
+ number,
2834
+ number
2835
+ ][][];
2836
+ /** Where each frame's pairs were in the file, kept so a file whose frames share data or sit out of order comes back as it was. */
2837
+ offsets?: number[];
2838
+ }
2839
+ export declare function decodeLoFile(data: Uint8Array): LoOverlays;
2840
+ export interface EncodeLoOptions {
2841
+ /** A frame equal to an earlier one points at its pairs instead of a copy (default: PyLO's layout, every frame its own, in order). */
2842
+ share?: boolean;
2843
+ }
2844
+ /** The file's bytes: the read file's own offsets when they still fit the frames, else a fresh layout. */
2845
+ export declare function encodeLoFile(lo: LoOverlays, options?: EncodeLoOptions): Uint8Array;
2846
+ /**
2847
+ * PyLO text. When the file's frames are not laid out the way PyLO writes them (several of the game's share a frame's
2848
+ * pairs), a first comment line `# scmjs: offsets …` keeps where each frame was, so the text comes back to the same
2849
+ * bytes here; PyLO reads it as a comment.
2850
+ */
2851
+ export declare function loToText(lo: LoOverlays): string;
2852
+ /** PyLO text read: every frame must have as many overlays as the first. */
2853
+ export declare function loFromText(text: string): LoOverlays;
2854
+ /**
2855
+ * `scripts\iscript.bin` as text and back, in the PyICE / IceCC dialect:
2856
+ *
2857
+ * .headerstart
2858
+ * IsId 3
2859
+ * Type 1
2860
+ * Init Script3_Init
2861
+ * Death [NONE]
2862
+ * .headerend
2863
+ *
2864
+ * Script3_Init:
2865
+ * playfram 0x00
2866
+ * wait 1
2867
+ * end
2868
+ *
2869
+ * A command's arguments may be written `cmd a b` or `cmd(a, b)`; numbers in decimal or `0x` hex; `#` starts a comment.
2870
+ * Beside PyICE's commands this reads IceCC's raw-data lines — `ub n` (a byte), `uw n` (a word), `pw Label` (a label's
2871
+ * offset as a word) — which mods use to write opcodes a plugin added (Cosmonarchy's `flagjmp` is `ub 62`, `ub flags`,
2872
+ * `pw Label`), and the unknown opcodes' other spellings (`unused_0c` for `__0c`).
2873
+ *
2874
+ * **Layout.** The assembler lays a file out as IceCC does: the table pointer, `00 00 FF FF 00 00`, all the code in
2875
+ * source order, then the headers in source order, then the id table (in header order) and its `FF FF 00 00` end. The
2876
+ * game's own file is laid out differently (headers among the code, 1,364 zero bytes up front, the table in another
2877
+ * order); the disassembler notes such a file's layout in comment lines PyICE ignores —
2878
+ *
2879
+ * # scmjs: preamble 00*1366 … the bytes from offset 2 to the first header or code
2880
+ * # scmjs: headers inline each header block is written where it stands in the text
2881
+ * # scmjs: table 198 199 200 … the id table's order
2882
+ *
2883
+ * — so that any iscript.bin disassembles to text that assembles to the same bytes. Bytes no script reaches are kept
2884
+ * as `ub` lines, so nothing is lost either.
2885
+ *
2886
+ * Opcode names and argument layouts follow PyMS's command reference (Help/Programs/PyICE); its code is not included
2887
+ * here. Sources and licenses: ../../../ATTRIBUTION.md
2888
+ */
2889
+ /** Argument kinds: `b` u8, `s` s8, `w` u16, `f` a frame (u16, written in hex when a frameset), `L` a label (u16 offset), `N` a u8 count and that many u16 sounds. */
2890
+ export type IscriptArgKind = "b" | "s" | "w" | "f" | "L" | "N";
2891
+ export interface IscriptOpcode {
2892
+ op: number;
2893
+ name: string;
2894
+ args: readonly IscriptArgKind[];
2895
+ /** Execution does not continue past it (`goto`, `end`, `return`). */
2896
+ endsFlow?: boolean;
2897
+ }
2898
+ /** The 69 opcodes of 1.16.1, by number. */
2899
+ export declare const ISCRIPT_OPCODES: readonly IscriptOpcode[];
2900
+ /** The header's animation entry points, in header order, as PyICE names them. */
2901
+ export declare const ISCRIPT_ANIMS: readonly [
2902
+ "Init",
2903
+ "Death",
2904
+ "GndAttkInit",
2905
+ "AirAttkInit",
2906
+ "Unused1",
2907
+ "GndAttkRpt",
2908
+ "AirAttkRpt",
2909
+ "CastSpell",
2910
+ "GndAttkToIdle",
2911
+ "AirAttkToIdle",
2912
+ "Unused2",
2913
+ "Walking",
2914
+ "WalkingToIdle",
2915
+ "SpecialState1",
2916
+ "SpecialState2",
2917
+ "AlmostBuilt",
2918
+ "Built",
2919
+ "Landing",
2920
+ "LiftOff",
2921
+ "IsWorking",
2922
+ "WorkingToIdle",
2923
+ "WarpIn",
2924
+ "Unused3",
2925
+ "StarEditInit",
2926
+ "Disable",
2927
+ "Burrow",
2928
+ "UnBurrow",
2929
+ "Enable"
2930
+ ];
2931
+ /** How many entry points a header of each type has, in PyMS's table (the game's own file is laid out this way). */
2932
+ export declare const ISCRIPT_TYPE_ANIMS: Readonly<Record<number, number>>;
2933
+ /**
2934
+ * Header sizes differ between compilers: PyMS (and the game's file) give a type the entry points of PyMS's table; IceCC
2935
+ * writes `type + 1` of them (one fewer for the even types, so a type 0 header holds Init alone), and takes types PyMS
2936
+ * does not know (3, 25). Mods' binaries are mostly IceCC's.
2937
+ */
2938
+ export type IscriptEntryRule = "icecc" | "pyms";
2939
+ /** How many entry points a header of `type` has under a rule, or undefined when the rule has no such type. */
2940
+ export declare function iscriptEntryCount(type: number, rule: IscriptEntryRule): number | undefined;
2941
+ export declare class IscriptTextError extends Error {
2942
+ readonly line: number;
2943
+ constructor(message: string, line: number);
2944
+ }
2945
+ export interface IscriptHeaderInfo {
2946
+ id: number;
2947
+ type: number;
2948
+ offset: number;
2949
+ /** Entry point offsets in header order; 0 = none. */
2950
+ anims: number[];
2951
+ }
2952
+ /**
2953
+ * The id table and the headers it points at, in table order. Without a rule, the one the file was written with: the
2954
+ * rule under which its headers sit packed before the table (IceCC's layout), else PyMS's when it fits, else IceCC's.
2955
+ */
2956
+ export declare function readIscriptHeaders(data: Uint8Array, rule?: IscriptEntryRule): {
2957
+ table: number;
2958
+ headers: IscriptHeaderInfo[];
2959
+ end: number;
2960
+ rule: IscriptEntryRule;
2961
+ };
2962
+ export interface IscriptToTextOptions {
2963
+ /** A comment for a header, written above it (PyICE lists the images.dat entries that use it). */
2964
+ headerComment?: (id: number) => string | undefined;
2965
+ }
2966
+ /** iscript.bin as PyICE text that assembles (with `iscriptFromText`) to the same bytes. */
2967
+ export declare function iscriptToText(data: Uint8Array, options?: IscriptToTextOptions): string;
2968
+ export interface IscriptFromTextOptions {
2969
+ /** Header sizes when the text does not say (`# scmjs: entries …`); default IceCC's, which mods' sources are written for. */
2970
+ entries?: IscriptEntryRule;
2971
+ /** Collects what was dropped (an entry point past its header's size). */
2972
+ warnings?: string[];
2973
+ }
2974
+ /** iscript.bin from PyICE / IceCC text (see the module comment for the layout and the `# scmjs:` notes). */
2975
+ export declare function iscriptFromText(text: string, options?: IscriptFromTextOptions): Uint8Array;
2976
+ /**
2977
+ * `scripts\aiscript.bin` and `scripts\bwscript.bin` as PyAI text and back, aise's commands included.
2978
+ *
2979
+ * script Ter3 {
2980
+ * name_string 1052
2981
+ * bin_file aiscript
2982
+ * broodwar_only 0
2983
+ * staredit_hidden 0
2984
+ * requires_location 0
2985
+ * entry_point Ter3_entry
2986
+ * }
2987
+ *
2988
+ * --Ter3_entry--
2989
+ * start_town()
2990
+ * build(1, 109, 80)
2991
+ * goto(Ter3_entry)
2992
+ *
2993
+ * Blocks are `--Name--` or `:Name`; a command is `name(a, b)` or `name a b`; `#` and `;` start comments; a string is
2994
+ * quoted, with `<N>` for a byte that is not plain text. Units, upgrades and technologies are written as numbers (PyAI
2995
+ * reads those too; names when a table of them is given). `@` directives are read and ignored; `type name = value`
2996
+ * variables are substituted.
2997
+ *
2998
+ * **Files.** aiscript.bin: u32 offset of the headers; the code; the headers (u32 id, u32 code offset — 0 for a script
2999
+ * kept in bwscript.bin — u32 1-based stat_txt.tbl string, u32 flags); a zero u32. bwscript.bin: the same with 8-byte
3000
+ * headers (id, code offset). An **expanded** file (aise; past 64 KB) begins with a table of `goto` trampolines with
3001
+ * u32 targets: a command's short (u16) block argument points at a trampoline, aise's long ones and `goto` take u32.
3002
+ *
3003
+ * **Layout.** The assembler writes code in source order — not in the order a script is reached, as PyAI does — so a
3004
+ * file disassembles to text that assembles to the same bytes. What PyAI text cannot say about a file goes in comment
3005
+ * lines PyAI ignores: `# scmjs: aiscript preamble …` (bytes before the code), `# scmjs: aiscript long-jumps …` (the
3006
+ * trampolines' order), `# scmjs: file bwscript` (the code below belongs to bwscript.bin), `# scmjs: bwscript order …`.
3007
+ * Without them, code reached only from bwscript scripts goes to bwscript.bin, and a file is expanded when it must be.
3008
+ *
3009
+ * Command names and argument layouts follow PyMS's PyAI (Help/Programs/PyAI, its AISE command list); its code is not
3010
+ * included here. Sources and licenses: ../../../ATTRIBUTION.md
3011
+ */
3012
+ export type AiArgKind = "byte" | "word" | "dword" | "block" | "long_block" | "unit" | "unit_id" | "unit_group" | "upgrade" | "technology" | "string" | "point" | "build_at_point" | "area" | "idle_order_flags" | `enum:${string}` | `flags:${string}`;
3013
+ export interface AiOpcode {
3014
+ op: number;
3015
+ name: string;
3016
+ args: readonly AiArgKind[];
3017
+ endsFlow?: boolean;
3018
+ /** One of aise's commands (needs the aise plugin in the game). */
3019
+ aise?: boolean;
3020
+ /**
3021
+ * Not in PyAI or aise: a mod's own command whose layout was read off its files, not from a description. The name is
3022
+ * ours (`op_a6`); PyAI does not know it.
3023
+ */
3024
+ inferred?: boolean;
3025
+ }
3026
+ /** The opcodes, the game's 0–112 and aise's from 113. */
3027
+ export declare const AI_OPCODES: readonly AiOpcode[];
3028
+ /** Named values of the enumerated argument types (a value without a name is written as its number). */
3029
+ export declare const AI_ENUMS: Readonly<Record<string, Readonly<Record<string, number>>>>;
3030
+ /** Flag names of the flag argument types, and their width. */
3031
+ export declare const AI_FLAGS: Readonly<Record<string, {
3032
+ bytes: 2 | 4;
3033
+ names: Readonly<Record<string, number>>;
3034
+ }>>;
3035
+ /** Script header flag bits. */
3036
+ export declare const AI_SCRIPT_FLAGS: {
3037
+ readonly requires_location: 1;
3038
+ readonly staredit_hidden: 2;
3039
+ readonly broodwar_only: 4;
3040
+ };
3041
+ export declare class AiScriptTextError extends Error {
3042
+ readonly line: number;
3043
+ constructor(message: string, line: number);
3044
+ }
3045
+ /** Names for units, upgrades and technologies (stat_txt.tbl's), to write and read them by name. */
3046
+ export interface AiNames {
3047
+ units?: readonly string[];
3048
+ upgrades?: readonly string[];
3049
+ technologies?: readonly string[];
3050
+ }
3051
+ /** A C string as PyAI writes it: quoted, `<N>` for control bytes, `#`, `<`, `>`, quotes and bytes that are not UTF-8. */
3052
+ export declare function aiStringText(bytes: Uint8Array): string;
3053
+ export interface AiScriptToTextOptions {
3054
+ names?: AiNames;
3055
+ }
3056
+ /** aiscript.bin (and bwscript.bin, when its scripts are kept there) as PyAI text that assembles to the same bytes. */
3057
+ export declare function aiscriptToText(aiscript: Uint8Array, bwscript?: Uint8Array | null, options?: AiScriptToTextOptions): string;
3058
+ export interface AiScriptFromTextOptions {
3059
+ names?: AiNames;
3060
+ }
3061
+ export interface AiScriptFiles {
3062
+ aiscript: Uint8Array;
3063
+ /** Null when no script is kept in bwscript.bin. */
3064
+ bwscript: Uint8Array | null;
3065
+ }
3066
+ /** aiscript.bin and bwscript.bin from PyAI text (see the module comment for the layout and the `# scmjs:` notes). */
3067
+ export declare function aiscriptFromText(text: string, options?: AiScriptFromTextOptions): AiScriptFiles;
3068
+ /**
3069
+ * `.graft` files (GPTP's grafting, the successor of a Firegraft `.fgp`): requirements and buttons as data the game
3070
+ * loads from `datreq\*.graft`, as binary and as the text the CMBW editor's `graftc` reads and writes.
3071
+ *
3072
+ * **Requirements** (`units.graft`, `upgrades.graft`, `research.graft`, `tech.graft`, `orders.graft`) are the game's
3073
+ * own requirement script, a stream of u16: a leading 0, then each entry — its id, its opcodes (0xFF00 and up) and
3074
+ * their parameters, ended by 0xFFFF (an upgrade's levels each end with one: 0xFF1F … 0xFFFF 0xFF20 … 0xFFFF) — and a
3075
+ * last 0xFFFF. Text:
3076
+ *
3077
+ * #DAT REQ:
3078
+ * 1:
3079
+ * 0xFF02
3080
+ * 111
3081
+ * 0xFFFF
3082
+ *
3083
+ * **Buttons** (`buttons.graft`): u32 button count, u32 unit count, u32 status-entry count; the buttons (u16 position,
3084
+ * u16 icon, u32 condition, u32 action, u16 condition parameter, u16 action parameter, u16 enabled string, u16
3085
+ * disabled string — conditions and actions by index into GPTP's tables); a set a unit (u32 button count, u32 first
3086
+ * button index, u32 connected unit); a status entry a unit (u32 unit id, u32 status function, u32 display function).
3087
+ * Text:
3088
+ *
3089
+ * #BUTTONS:
3090
+ * 1:
3091
+ * 1, 130, 1, 2, 0, 0, 373, 0 position, icon, condition, action, condition and action parameters, strings
3092
+ * Unit 1: 1, 65535, 2, 1 button set[, connected unit[, status function, display function]]
3093
+ * Unit 4: -1 no buttons
3094
+ *
3095
+ * What graftc's text cannot say about a file (a nonzero leading word, a status entry for another unit) goes in
3096
+ * `# scmjs:` comment lines, so a file comes back byte for byte. The layouts are read off GPTP's loader
3097
+ * (`hooks/grafting/grafting.cpp`) and the files Cosmonarchy ships; graftc's own code is not included here.
3098
+ */
3099
+ export declare class GraftTextError extends Error {
3100
+ readonly line: number;
3101
+ constructor(message: string, line: number);
3102
+ }
3103
+ export interface ReqGraft {
3104
+ /** The leading word (0 in every file seen). */
3105
+ start: number;
3106
+ /** Entries in file order: the id, then every word up to and including the entry's last 0xFFFF. */
3107
+ entries: {
3108
+ id: number;
3109
+ words: number[];
3110
+ }[];
3111
+ }
3112
+ export declare function decodeReqGraft(data: Uint8Array): ReqGraft;
3113
+ export declare function encodeReqGraft(graft: ReqGraft): Uint8Array;
3114
+ export declare function reqGraftToText(graft: ReqGraft): string;
3115
+ export declare function reqGraftFromText(text: string): ReqGraft;
3116
+ export interface GraftButton {
3117
+ position: number;
3118
+ icon: number;
3119
+ condition: number;
3120
+ action: number;
3121
+ conditionParam: number;
3122
+ actionParam: number;
3123
+ enabledString: number;
3124
+ disabledString: number;
3125
+ }
3126
+ export interface ButtonGraft {
3127
+ buttons: GraftButton[];
3128
+ /** A set a unit: how many buttons, from which, and the connected unit (0xFFFF none). */
3129
+ sets: {
3130
+ count: number;
3131
+ first: number;
3132
+ connected: number;
3133
+ }[];
3134
+ /** A status entry a unit: [unit id, status function, display function]. */
3135
+ status: [
3136
+ number,
3137
+ number,
3138
+ number
3139
+ ][];
3140
+ }
3141
+ export declare function decodeButtonGraft(data: Uint8Array): ButtonGraft;
3142
+ export declare function encodeButtonGraft(g: ButtonGraft): Uint8Array;
3143
+ /**
3144
+ * graftc's text. The buttons are cut into sets at every place a unit's set starts or ends, so each unit names one set
3145
+ * and buttons no unit uses are kept as sets of their own; a unit's status entry is written on its line when it is the
3146
+ * unit's own (`[unit, …]`), and with a note otherwise.
3147
+ */
3148
+ export declare function buttonGraftToText(g: ButtonGraft): string;
3149
+ export declare function buttonGraftFromText(text: string): ButtonGraft;
3150
+ /**
3151
+ * PNG read and written with nothing but the platform: zlib is the `CompressionStream` / `DecompressionStream`
3152
+ * ("deflate") every browser and Node 18+ has, so this works in the editor, the command line and a worker alike, and
3153
+ * is async for that reason.
3154
+ *
3155
+ * Read: 8-bit (and 16-bit, kept to the high byte) greyscale, RGB, palette (1/2/4/8-bit), grey+alpha and RGBA, not
3156
+ * interlaced; `tRNS` honoured. Written: RGBA, or palette images with their PLTE/tRNS. `tEXt` chunks both ways.
3157
+ */
3158
+ export interface PngImage {
3159
+ width: number;
3160
+ height: number;
3161
+ /** `width × height × 4` RGBA. */
3162
+ rgba: Uint8Array;
3163
+ /** For a palette image: its indices and palette (256 × RGBA at most), as stored. */
3164
+ indexed?: {
3165
+ indices: Uint8Array;
3166
+ palette: Uint8Array;
3167
+ };
3168
+ /** tEXt chunks. */
3169
+ text: Record<string, string>;
3170
+ }
3171
+ /** zlib (RFC 1950) inflate and deflate, by the platform. */
3172
+ export declare const inflate: (data: Uint8Array) => Promise<Uint8Array<ArrayBufferLike>>;
3173
+ export declare const deflate: (data: Uint8Array) => Promise<Uint8Array<ArrayBufferLike>>;
3174
+ export declare function isPng(data: Uint8Array): boolean;
3175
+ export declare function decodePng(data: Uint8Array): Promise<PngImage>;
3176
+ export interface EncodePngInput {
3177
+ width: number;
3178
+ height: number;
3179
+ /** RGBA pixels, or palette indices with `palette`. */
3180
+ rgba?: Uint8Array;
3181
+ indices?: Uint8Array;
3182
+ /** 256 × RGB or × RGBA (an index whose alpha is below 255 gets a tRNS entry). */
3183
+ palette?: Uint8Array;
3184
+ text?: Record<string, string>;
3185
+ }
3186
+ export declare function encodePng(image: EncodePngInput): Promise<Uint8Array>;
3187
+ export interface NamedPalette {
3188
+ /** What the palette is (`units`, `tileset\\badlands.wpe`, …), written into the PNG and checked on the way back. */
3189
+ name: string;
3190
+ /** 256 × RGB (768 bytes; a `.wpe` is 256 × RGBX, 1024 bytes, also taken). */
3191
+ colours: Uint8Array;
3192
+ }
3193
+ /** The default number of cells a row: 17 for a GRP of facings, else about square. */
3194
+ export declare function sheetColumns(frames: number): number;
3195
+ export interface GrpToPngOptions {
3196
+ /** Cells a row (default `sheetColumns`). */
3197
+ columns?: number;
3198
+ /** More `tEXt` chunks to write (Latin-1), beside `scmjs:grp`: what the sheet is, for a person or another tool. */
3199
+ text?: Record<string, string>;
3200
+ }
3201
+ export declare function grpToPng(grpBytes: Uint8Array | GrpImage, palette: NamedPalette, options?: GrpToPngOptions): Promise<Uint8Array>;
3202
+ export interface PngToGrpOptions {
3203
+ /** The frame size when the PNG was not written by `grpToPng` (it says its own). */
3204
+ frameWidth?: number;
3205
+ frameHeight?: number;
3206
+ /** How many frames (default: every cell of the sheet). */
3207
+ frames?: number;
3208
+ }
3209
+ export interface QuantiseReport {
3210
+ /** Distinct colours (`#rrggbb`) that are not in the palette, with how many pixels had each and the colour they became. */
3211
+ coloursLost: {
3212
+ colour: string;
3213
+ pixels: number;
3214
+ became: number;
3215
+ }[];
3216
+ /** Opaque pixels whose colour was not exactly a palette colour. */
3217
+ pixelsChanged: number;
3218
+ /** Pixels with partial transparency, made opaque (alpha ≥ 128) or transparent. */
3219
+ pixelsAlphaRounded: number;
3220
+ /** The palette the PNG says it was made with, when that is not the one given. */
3221
+ paletteMismatch?: string;
3222
+ }
3223
+ /** A GRP from a PNG sheet, quantised to `palette`, with a report of what was lost. */
3224
+ export declare function pngToGrp(png: Uint8Array, palette: NamedPalette, options?: PngToGrpOptions): Promise<{
3225
+ grp: Uint8Array;
3226
+ image: GrpImage;
3227
+ report: QuantiseReport;
3228
+ }>;
3229
+ /**
3230
+ * What a mod comes in, opened without running anything: the game's paths inside a folder (at its root or a folder
3231
+ * down), an MPQ, a self-executing exe with an MPQ appended, or a zip of any of these. Pure (no DOM, no Node): the
3232
+ * command line and any page share it.
3233
+ *
3234
+ * - **A zip**: its central directory read, the "stored" and "deflate" members inflated with the platform's own
3235
+ * `DecompressionStream("deflate-raw")`. No zip64 and no encryption; such a zip is refused in words.
3236
+ * - **MPQDraft's self-executing MPQ** (SEMPQ): a small Windows program with the archive appended at a 512-byte boundary
3237
+ * after the program, where storm looks for one.
3238
+ * - **FireGraft's patcher**: the program, then an overlay `"PEGF"`, u32 1, u32 count, and for each plugin u32 id,
3239
+ * u32 size, u32 0; then the plugins' bytes, then the archive. The plugins are recorded, never run.
3240
+ *
3241
+ * Nothing of an exe is run or kept but its archive.
3242
+ */
3243
+ /** The game's own top folders: a mod's files sit under these. */
3244
+ export declare const GAME_FOLDERS: string[];
3245
+ /** A path as the game names it: backslashes, lower case (`arr\units.dat`). Two paths are one file when these agree. */
3246
+ export declare const gameName: (path: string) => string;
3247
+ /**
3248
+ * The folder of a set of paths the game's paths start in: the one that holds `arr/`, else the one holding the most
3249
+ * files under the game's folders, the shallower on a tie; "" is the root. Paths use forward slashes. At any depth, as
3250
+ * the play page looks (a zip's `Mod 1.2/mpq/arr/…`); a game folder's name deeper in a root (`unit/terran/unit/`)
3251
+ * scores fewer files than the root itself, so it does not win.
3252
+ */
3253
+ export declare function modRoot(paths: readonly string[]): string;
3254
+ /** Where a Windows program's own bytes end (after its last section), or null when the bytes are no program. */
3255
+ export declare function programEnd(b: Uint8Array): number | null;
3256
+ export interface ExeArchive {
3257
+ /** The archive, from its header on. */
3258
+ archive: Uint8Array;
3259
+ /** Where in the exe it starts. */
3260
+ at: number;
3261
+ kind: "sempq" | "firegraft";
3262
+ /** FireGraft's plugins in the overlay, by id and size (never run, not kept). */
3263
+ plugins: {
3264
+ id: number;
3265
+ size: number;
3266
+ }[];
3267
+ }
3268
+ /** The mod archive inside a self-executing exe, or null when the exe holds none (a program only). */
3269
+ export declare function exeArchive(b: Uint8Array): ExeArchive | null;
3270
+ /** An MPQ from its first byte (a mod's `.mpq`). */
3271
+ export declare const isMpq: (b: Uint8Array) => boolean;
3272
+ /** A zip, by its first member's local header (or an empty zip's end record). */
3273
+ export declare const isZip: (b: Uint8Array) => boolean;
3274
+ /** A Windows program. */
3275
+ export declare const isExe: (b: Uint8Array) => boolean;
3276
+ export interface ZipMember {
3277
+ /** The member's path in the zip, forward slashes. */
3278
+ path: string;
3279
+ size: number;
3280
+ read(): Promise<Uint8Array>;
3281
+ }
3282
+ export declare class ModSourceError extends Error {
3283
+ }
3284
+ /** The files of a zip (folders left out), read lazily. */
3285
+ export declare function readZip(b: Uint8Array): ZipMember[];
3286
+ /**
3287
+ * The hash of game files alone, by the mod hash's rule (`hash.ts`): a line `name<TAB>sha256` a file (the game's name,
3288
+ * lower case with backslashes), sorted by name, joined with newlines, hashed again; the first sixteen hex digits. A
3289
+ * mod's hash also has lines for its plugins and FireGraft project: `modHash` / `modHashOfDigests` in `hash.ts`; for a
3290
+ * mod without either the two agree.
3291
+ */
3292
+ export declare function dataSetHash(files: readonly {
3293
+ name: string;
3294
+ bytes: Uint8Array;
3295
+ }[]): Promise<string>;
3296
+ /** One file's SHA-256 in hex, as `dataSetHash` takes it: for a caller that hashes a file at a time and lets the bytes go. */
3297
+ export declare const fileDigest: (bytes: Uint8Array) => Promise<string>;
3298
+ /** `dataSetHash` from each file's `fileDigest` rather than its bytes: the same rule, the same hash. */
3299
+ export declare function dataSetHashOfDigests(files: readonly {
3300
+ name: string;
3301
+ sha256: string;
3302
+ }[]): Promise<string>;
3303
+ /** A plugin a mod carries: MPQDraft's `.qdp`, Chaoslauncher's `.bwl`. */
3304
+ export declare const isPluginFile: (name: string) => boolean;
3305
+ /** FireGraft's project, the one FireGraft file the hash has a line for. */
3306
+ export declare const isFiregraftProject: (name: string) => boolean;
3307
+ /** A file of a mod's code rather than the game's: a plugin, FireGraft's project or database. */
3308
+ export declare const isModCode: (name: string) => boolean;
3309
+ /** A plugin's line: `plugins\<file name>`, lower case. */
3310
+ export declare const pluginLine: (name: string, sha256: string) => string;
3311
+ /** The FireGraft project's line: `<file name>.fgp`, lower case. */
3312
+ export declare const firegraftLine: (name: string, sha256: string) => string;
3313
+ /** A game file's line: its game name. */
3314
+ export declare const gameLine: (name: string, sha256: string) => string;
3315
+ /** The hash of lines `name<TAB>sha256` in any order: sorted by name, joined with "\n", SHA-256, sixteen hex digits. */
3316
+ export declare function hashLines(lines: readonly string[]): Promise<string>;
3317
+ /** A file by its name and its bytes' SHA-256 (`fileDigest`). */
3318
+ export interface Digest {
3319
+ name: string;
3320
+ sha256: string;
3321
+ }
3322
+ /** What a mod's hash is made of: its game files by game name, the plugins it carries and its FireGraft files. */
3323
+ export interface ModHashInput {
3324
+ files: readonly Digest[];
3325
+ /** Plugins carried as files (a plugin inside the mod's archive is not one: the play page does not load it). */
3326
+ plugins?: readonly Digest[];
3327
+ /** FireGraft's files; only the project (`.fgp`) has a line. */
3328
+ firegraft?: readonly Digest[];
3329
+ }
3330
+ export interface ModHash {
3331
+ /** The mod's hash: every line. */
3332
+ hash: string;
3333
+ /** The hash without the plugins' lines: what a page that does not run them presents. */
3334
+ withoutPlugins: string;
3335
+ /** The lines without the plugins' (sorted): what `hashLines` makes `withoutPlugins` of. */
3336
+ lines: string[];
3337
+ /** The plugins' lines (sorted). */
3338
+ pluginLines: string[];
3339
+ }
3340
+ /**
3341
+ * The mod's hash and its hash without plugins. Game files are taken once by game name (the last given wins, as a
3342
+ * later layer does in the game); plugins and FireGraft projects once by file name, any case (the first given wins,
3343
+ * as on the play page).
3344
+ */
3345
+ export declare function modHashOfDigests(input: ModHashInput): Promise<ModHash>;
3346
+ /** `modHashOfDigests` from the files' bytes. */
3347
+ export declare function modHash(input: {
3348
+ files: readonly {
3349
+ name: string;
3350
+ bytes: Uint8Array;
3351
+ }[];
3352
+ plugins?: readonly {
3353
+ name: string;
3354
+ bytes: Uint8Array;
3355
+ }[];
3356
+ firegraft?: readonly {
3357
+ name: string;
3358
+ bytes: Uint8Array;
3359
+ }[];
3360
+ }): Promise<ModHash>;
3361
+ /**
3362
+ * The names looked for in a mod's archive that has no list of its files: the play page's list (scm-sim
3363
+ * `web/modDrop.ts#namesToProbe`: what the game reads at its start and for a game, every tileset's files, the eleven
3364
+ * tables in both layouts), and every path the archive's own `arr\images.tbl`, `sfxdata.tbl` and `portdata.tbl` name.
3365
+ * `read` answers a member of the archive, or null. (The play page also reads those three tables from the person's own
3366
+ * game; this does not, so the set never depends on a copy.)
3367
+ */
3368
+ export declare function probeNames(read: (name: string) => Uint8Array | null): string[];
3369
+ /** The manifest's file name, at the folder's root. */
3370
+ export declare const MOD_MANIFEST = "mod.json";
3371
+ /** The folder format's version, `scmjs` in the manifest. */
3372
+ export declare const MOD_FORMAT = 1;
3373
+ /** The palette a GRP's sheet is drawn with when the manifest names none. */
3374
+ export declare const DEFAULT_PALETTE = "jungle";
3375
+ export declare const MOD_FOLDERS: {
3376
+ readonly tables: "tables";
3377
+ readonly strings: "strings";
3378
+ readonly iscript: "iscript";
3379
+ readonly ai: "ai";
3380
+ readonly overlays: "overlays";
3381
+ readonly graphics: "graphics";
3382
+ readonly sounds: "sounds";
3383
+ readonly grafts: "grafts";
3384
+ readonly maps: "maps";
3385
+ readonly plugins: "plugins";
3386
+ readonly firegraft: "Firegraft";
3387
+ readonly files: "files";
3388
+ };
3389
+ /** What form a member takes in the folder. */
3390
+ export type MemberForm = "table" | "strings" | "iscript" | "ai" | "overlay" | "graphics" | "sound" | "graft" | "map" | "plugin" | "firegraft" | "file";
3391
+ export interface ModTable {
3392
+ /** The member: `arr\units.dat`, `arr\units.datex`. */
3393
+ file: string;
3394
+ layout: DatLayout;
3395
+ /** Entries in the file, for a reader (the text says them all). */
3396
+ entries: number;
3397
+ /** units.dat from before Brood War (no Brood War columns). */
3398
+ legacy?: true;
3399
+ }
3400
+ /** A plugin or FireGraft file: kept as it is, never run. `member` when it was a file of the mod's archive. */
3401
+ export interface ModCarried {
3402
+ name: string;
3403
+ bytes: number;
3404
+ file: string;
3405
+ member?: string;
3406
+ }
3407
+ /** `mod.json`. */
3408
+ export interface ModManifest {
3409
+ /** The folder format's version (`MOD_FORMAT`). */
3410
+ scmjs: number;
3411
+ name: string;
3412
+ version: string;
3413
+ authors: string[];
3414
+ licence: string;
3415
+ /** The game the mod is for. */
3416
+ base: string;
3417
+ /** The sources the folder was made from, in load order (a later one's files over an earlier one's). */
3418
+ layers: string[];
3419
+ /** The palette the GRPs' sheets are drawn with: a tileset's name (`tileset\<name>.wpe`, the mod's own first). */
3420
+ palette: string;
3421
+ /** Where the names written beside the tables and in the AI text came from: the mod's string tables, the game's, or none. */
3422
+ names: "mod" | "game" | "none";
3423
+ /** Each table's member and layout, by table. */
3424
+ tables: Partial<Record<DatTableName, ModTable>>;
3425
+ /** Each string table's text encoding, by its file in the folder. */
3426
+ encodings: Record<string, TextEncoding>;
3427
+ /** Folder files whose member the path alone does not name (two for `ai/aiscript.txt`: aiscript, bwscript). */
3428
+ members: Record<string, string | string[]>;
3429
+ plugins: ModCarried[];
3430
+ firegraft: ModCarried[];
3431
+ /** The mod's maps, by member. */
3432
+ maps: string[];
3433
+ /** Members that have a text or picture form but were kept as bytes under `files/`, grouped by why. */
3434
+ kept: {
3435
+ why: string;
3436
+ files: string[];
3437
+ }[];
3438
+ /** Anything else a person should know about the folder (raw bytes in a text, …). */
3439
+ notes: string[];
3440
+ }
3441
+ export declare function emptyManifest(name?: string): ModManifest;
3442
+ /** A manifest as read from `mod.json`, every field filled; null when it is not one of ours. */
3443
+ export declare function readManifest(text: string): ModManifest | null;
3444
+ /** A problem with a file of the folder, said with the file and, when there is one, the line. */
3445
+ export declare class ModFolderError extends Error {
3446
+ readonly file: string;
3447
+ readonly line: number;
3448
+ constructor(message: string, file: string, line: number);
3449
+ }
3450
+ /** A member's path as a folder path: `\` is `/`, and a character a file system may refuse (and `%`) is `%XX`. */
3451
+ export declare function folderPath(member: string): string;
3452
+ /** The member a folder path stands for (`folderPath` undone). */
3453
+ export declare function memberPath(path: string): string;
3454
+ /** The place a member takes in the folder by its name alone, before any check. */
3455
+ export declare function placeOf(member: string): {
3456
+ form: MemberForm;
3457
+ file: string;
3458
+ };
3459
+ /**
3460
+ * The member (or members) a folder file stands for, and its form; null for a file that is no member (the manifest,
3461
+ * a read-me, a plugin that sat beside the archive rather than in it, anything outside the known folders).
3462
+ */
3463
+ export declare function memberOf(file: string, manifest: ModManifest): {
3464
+ form: MemberForm;
3465
+ members: string[];
3466
+ } | null;
3467
+ /** What the entries of the tables are called, for the text's comments and the AI script's arguments. */
3468
+ export interface ModNames {
3469
+ units: string[];
3470
+ weapons: string[];
3471
+ upgrades: string[];
3472
+ technologies: string[];
3473
+ /** A GRP path an image (`unit\…`), for its comment. */
3474
+ images?: string[];
3475
+ /** A WAV path a sound row (`sound\…`), for its comment. */
3476
+ sounds?: string[];
3477
+ }
3478
+ /** The AI script's names: a name used twice, or one that reads as a number, is left out (written as its number). */
3479
+ export declare function aiNames(names: ModNames | null | undefined): AiNames | undefined;
3480
+ export interface RenderContext {
3481
+ names?: ModNames | null;
3482
+ /** The palette GRPs are drawn with; none keeps every GRP as bytes. */
3483
+ palette?: NamedPalette | null;
3484
+ }
3485
+ export interface Rendered {
3486
+ form: MemberForm;
3487
+ /** The folder file. */
3488
+ file: string;
3489
+ data: Uint8Array;
3490
+ /** Set when a member with a text or picture form was kept as bytes: why. */
3491
+ kept?: string;
3492
+ /** A table's layout, for the manifest. */
3493
+ table?: ModTable;
3494
+ /** A string table's encoding, for the manifest. */
3495
+ encoding?: TextEncoding;
3496
+ /** Something the manifest's notes should say. */
3497
+ note?: string;
3498
+ }
3499
+ /**
3500
+ * One member in its folder form, checked by packing the form back: the text (or picture) when the bytes come back
3501
+ * the same, else the bytes under `files/` with why. AI scripts come in a pair: `renderAiScripts`.
3502
+ */
3503
+ export declare function renderMember(member: string, bytes: Uint8Array, ctx?: RenderContext): Promise<Rendered>;
3504
+ /** `scripts\aiscript.bin` and `bwscript.bin` as one PyAI text, checked; either may be absent from the mod. */
3505
+ export declare function renderAiScripts(ai: {
3506
+ member: string;
3507
+ bytes: Uint8Array;
3508
+ } | null, bw: {
3509
+ member: string;
3510
+ bytes: Uint8Array;
3511
+ } | null, ctx?: RenderContext): Rendered[];
3512
+ export interface PackContext {
3513
+ manifest: ModManifest;
3514
+ names?: ModNames | null;
3515
+ /** A palette by name, for a sheet that is no longer in its own palette's colours. */
3516
+ palette?: (name: string) => NamedPalette | null;
3517
+ /** A sound that is not a WAV (`sounds/…/x.ogg`) as a WAV. */
3518
+ convertSound?: (bytes: Uint8Array, file: string) => Promise<Uint8Array>;
3519
+ /** What quantising a picture lost, by file. */
3520
+ quantised?: (file: string, report: QuantiseReport) => void;
3521
+ }
3522
+ /** The members a folder file stands for, with their bytes; none for a file that is no member. */
3523
+ export declare function packFile(file: string, data: Uint8Array, ctx: PackContext): Promise<{
3524
+ member: string;
3525
+ data: Uint8Array;
3526
+ }[]>;
3527
+ /**
3528
+ * Records a rendered member in the manifest: its table layout, encoding, a name the path does not give, why it was
3529
+ * kept as bytes, a note. `layer` is the member's own name as the source spelled it.
3530
+ */
3531
+ export declare function recordRendered(manifest: ModManifest, members: readonly string[], r: Rendered): void;
3532
+ /** Sorts a manifest's lists, so the same folder always writes the same `mod.json`. */
3533
+ export declare function tidyManifest(m: ModManifest): ModManifest;
3534
+ /** A file by the game's name (`arr\units.dat`, any case), or null when there is none. */
3535
+ export type ReadMember = (name: string) => Promise<Uint8Array | null>;
3536
+ export interface ModData {
3537
+ /** Each table as the game would read it: the mod's, else the game's. */
3538
+ tables: Partial<Record<DatTableName, DatFile>>;
3539
+ /** The game's own tables, when a copy was given. */
3540
+ base: Partial<Record<DatTableName, DatFile>>;
3541
+ /** The tables the mod has, by the member they came from. */
3542
+ fromMod: Partial<Record<DatTableName, string>>;
3543
+ /** String tables (whole entries), the mod's else the game's; null where neither has one. */
3544
+ strings: {
3545
+ stat: string[] | null;
3546
+ unitnames: string[] | null;
3547
+ images: string[] | null;
3548
+ sfxdata: string[] | null;
3549
+ portdata: string[] | null;
3550
+ mapdata: string[] | null;
3551
+ };
3552
+ /** Which of those the mod has. */
3553
+ stringsFromMod: Set<string>;
3554
+ /** iscript ids: every header of the mod's iscript files (or the game's), and the game's. */
3555
+ iscriptIds: Set<number> | null;
3556
+ baseIscriptIds: Set<number> | null;
3557
+ /** The mod's iscript files, by member. */
3558
+ iscriptFiles: string[];
3559
+ names: ModNames;
3560
+ /** Files that could not be read as what they are, with why. */
3561
+ problems: string[];
3562
+ }
3563
+ /** A string table's entry as text: up to its first NUL. */
3564
+ export declare const entryText: (s: string | undefined) => string;
3565
+ /**
3566
+ * Reads the mod's data over the game's. `modTables` names the mod's table members by table (`arr\units.datex`);
3567
+ * `iscripts` the mod's iscript members. `base` is the game's own files, or null when no copy was found.
3568
+ */
3569
+ export declare function loadModData(mod: ReadMember, base: ReadMember | null, modTables: Partial<Record<DatTableName, string>>, iscripts?: readonly string[]): Promise<ModData>;
3570
+ /** What each unit, weapon, upgrade, technology, image and sound is called, from the string tables. */
3571
+ export declare function namesOf(tables: ModData["tables"], strings: ModData["strings"]): ModNames;
3572
+ /**
3573
+ * The files a GPTP mod names things in beside the game's string tables:
3574
+ *
3575
+ * - `rez\stat.txt`: PyTBL text the mod's plugin loads as the game's strings (Cosmonarchy's weapons' labels point
3576
+ * past `stat_txt.tbl`'s end, into it).
3577
+ * - `arr\weapons.txt`, `upgrades.txt`, `techdata.txt`: the mod's own name lists, one line an entry, which its makers'
3578
+ * data editors show (Cosmonarchy: "Gauss Rifle (Maverick)", "Lobotomy Grenade (Francisco Goska)").
3579
+ */
3580
+ export declare const NAME_TEXT_FILES: {
3581
+ readonly stat: "rez\\stat.txt";
3582
+ readonly weapons: "arr\\weapons.txt";
3583
+ readonly upgrades: "arr\\upgrades.txt";
3584
+ readonly techdata: "arr\\techdata.txt";
3585
+ };
3586
+ /** A text file's bytes as text: UTF-8 where it is that, else Windows-1252, as the mods' tools write them. */
3587
+ export declare function nameFileText(bytes: Uint8Array): string;
3588
+ /**
3589
+ * `stat_txt.tbl`'s whole entries with `rez\stat.txt` (null: none) filling those the table leaves empty or does not
3590
+ * reach; where both have an entry, the table's stands (the text holds button strings at some of the techs' label
3591
+ * numbers).
3592
+ */
3593
+ export declare function statWithText(table: readonly string[], text: string | null): string[];
3594
+ /** How many of `rez\stat.txt`'s entries have text. */
3595
+ export declare const statTextEntries: (text: string | null) => number;
3596
+ /**
3597
+ * A mod's name list (`arr\upgrades.txt`, …) over a table of `count` entries: one name an entry, `""` where its line is
3598
+ * empty (the label stands there); null when there is no list or it has not exactly a line an entry, which is not one.
3599
+ */
3600
+ export declare function nameList(text: string | null, count: number): string[] | null;
3601
+ /** A row with struct fields spread out (`unit_extents.left`). */
3602
+ export declare function flatRow(file: DatFile, id: number): Record<string, number>;
3603
+ /** The fields an entry has another value in than in `before` (a field one side does not store counts as 0). */
3604
+ export declare function rowChanges(before: DatFile, after: DatFile, id: number): {
3605
+ field: string;
3606
+ before: number;
3607
+ after: number;
3608
+ }[];
3609
+ /** Whether entry `id` of a table is the mod's own: added past the game's, or changed from it. Without the game's table, an entry past the game's count. */
3610
+ export declare function ownEntry(data: ModData, table: DatTableName, id: number): boolean;
3611
+ export interface ModFinding {
3612
+ level: "error" | "warning";
3613
+ /** What kind of finding: `dangling`, `grp-missing`, `iscript-missing`, `iscript-unused`, `weapon-unused`, `sound-missing`, `string-past`, `button-set`, `requirement`, `layout-mix`, `duplicate-name`, `duplicate-file`. */
3614
+ rule: string;
3615
+ /** Where: `units 0 (Terran Marine) ground_weapon`, `images.tbl`, `datreq\units.graft entry 12`. */
3616
+ where: string;
3617
+ why: string;
3618
+ }
3619
+ export interface CheckFiles {
3620
+ /** Whether the mod has a file, by the game's name. */
3621
+ inMod(name: string): boolean;
3622
+ /** Whether the game has it; null when no copy of the game was given (or it does not hold such files). */
3623
+ inBase: ((name: string) => Promise<boolean | null>) | null;
3624
+ /** The mod's `.graft` files. */
3625
+ grafts: {
3626
+ member: string;
3627
+ bytes: Uint8Array;
3628
+ }[];
3629
+ }
3630
+ /** The game's highest iscript id: an id past it is one a mod added (used when no copy of the game was given). */
3631
+ export declare const GAME_ISCRIPT_LAST = 411;
3632
+ export declare function checkMod(data: ModData, files: CheckFiles): Promise<ModFinding[]>;
3633
+ export type ModChangeKind = "table" | "strings" | "iscript" | "ai" | "pictures" | "overlays" | "sounds" | "grafts" | "maps" | "files";
3634
+ export interface ModChange {
3635
+ kind: ModChangeKind;
3636
+ /** The line a person reads. */
3637
+ text: string;
3638
+ /** For a table: which and what. */
3639
+ table?: DatTableName;
3640
+ id?: number;
3641
+ field?: string;
3642
+ before?: number | string | null;
3643
+ after?: number | string | null;
3644
+ /** For a group of files: their names. */
3645
+ files?: string[];
3646
+ }
3647
+ export interface DiffSide {
3648
+ data: ModData;
3649
+ /** A file of this side (the mod's, else the game's), by the game's name. */
3650
+ read(name: string): Promise<Uint8Array | null>;
3651
+ /** The mod's own files, by the game's name (lower case). */
3652
+ names: string[];
3653
+ }
3654
+ export declare function diffMods(a: DiffSide, b: DiffSide): Promise<ModChange[]>;
2405
3655
  /** Unit type catalogue: StarEdit names by units.dat id, and the palette's grouping of them. */
2406
3656
  export type RaceKey = "terran" | "zerg" | "protoss" | "neutral";
2407
3657
  /** StarEdit's display names, indexed by units.dat id (0–227). */