@scm-js/core 0.9.1 → 0.11.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.
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @scm-js/core 0.9.1 — StarCraft maps as the scmJS editor reads and writes them.
2
+ * @scm-js/core 0.11.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';
@@ -72,6 +72,8 @@ export interface TextEncodingInfo {
72
72
  }
73
73
  export declare const TEXT_ENCODINGS: readonly TextEncodingInfo[];
74
74
  export declare const DEFAULT_TEXT_ENCODING: TextEncoding;
75
+ /** Bytes to text; a sequence the encoding does not define becomes U+FFFD rather than failing. */
76
+ export declare function decodeText(bytes: Uint8Array, encoding: TextEncoding): string;
75
77
  /**
76
78
  * STR/STRx string table.
77
79
  *
@@ -370,6 +372,159 @@ export interface ReadonlyTrigger {
370
372
  readonly players: readonly number[];
371
373
  readonly currentAction: number;
372
374
  }
375
+ export declare const ConditionType: {
376
+ readonly None: 0;
377
+ readonly CountdownTimer: 1;
378
+ readonly Command: 2;
379
+ readonly Bring: 3;
380
+ readonly Accumulate: 4;
381
+ readonly Kill: 5;
382
+ readonly CommandTheMost: 6;
383
+ readonly CommandTheMostAt: 7;
384
+ readonly MostKills: 8;
385
+ readonly HighestScore: 9;
386
+ readonly MostResources: 10;
387
+ readonly Switch: 11;
388
+ readonly ElapsedTime: 12;
389
+ readonly Briefing: 13;
390
+ readonly Opponents: 14;
391
+ readonly Deaths: 15;
392
+ readonly CommandTheLeast: 16;
393
+ readonly CommandTheLeastAt: 17;
394
+ readonly LeastKills: 18;
395
+ readonly LowestScore: 19;
396
+ readonly LeastResources: 20;
397
+ readonly Score: 21;
398
+ readonly Always: 22;
399
+ readonly Never: 23;
400
+ };
401
+ export declare const ActionType: {
402
+ readonly None: 0;
403
+ readonly Victory: 1;
404
+ readonly Defeat: 2;
405
+ readonly PreserveTrigger: 3;
406
+ readonly Wait: 4;
407
+ readonly PauseGame: 5;
408
+ readonly UnpauseGame: 6;
409
+ readonly Transmission: 7;
410
+ readonly PlayWav: 8;
411
+ readonly DisplayText: 9;
412
+ readonly CenterView: 10;
413
+ readonly CreateUnitWithProperties: 11;
414
+ readonly SetMissionObjectives: 12;
415
+ readonly SetSwitch: 13;
416
+ readonly SetCountdownTimer: 14;
417
+ readonly RunAiScript: 15;
418
+ readonly RunAiScriptAt: 16;
419
+ readonly LeaderboardControl: 17;
420
+ readonly LeaderboardControlAt: 18;
421
+ readonly LeaderboardResources: 19;
422
+ readonly LeaderboardKills: 20;
423
+ readonly LeaderboardPoints: 21;
424
+ readonly KillUnit: 22;
425
+ readonly KillUnitAt: 23;
426
+ readonly RemoveUnit: 24;
427
+ readonly RemoveUnitAt: 25;
428
+ readonly SetResources: 26;
429
+ readonly SetScore: 27;
430
+ readonly MinimapPing: 28;
431
+ readonly TalkingPortrait: 29;
432
+ readonly MuteUnitSpeech: 30;
433
+ readonly UnmuteUnitSpeech: 31;
434
+ readonly LeaderboardComputerPlayers: 32;
435
+ readonly LeaderboardGoalControl: 33;
436
+ readonly LeaderboardGoalControlAt: 34;
437
+ readonly LeaderboardGoalResources: 35;
438
+ readonly LeaderboardGoalKills: 36;
439
+ readonly LeaderboardGoalPoints: 37;
440
+ readonly MoveLocation: 38;
441
+ readonly MoveUnit: 39;
442
+ readonly LeaderboardGreed: 40;
443
+ readonly SetNextScenario: 41;
444
+ readonly SetDoodadState: 42;
445
+ readonly SetInvincibility: 43;
446
+ readonly CreateUnit: 44;
447
+ readonly SetDeaths: 45;
448
+ readonly Order: 46;
449
+ readonly Comment: 47;
450
+ readonly GiveUnits: 48;
451
+ readonly ModifyHitPoints: 49;
452
+ readonly ModifyEnergy: 50;
453
+ readonly ModifyShields: 51;
454
+ readonly ModifyResourceAmount: 52;
455
+ readonly ModifyHangarCount: 53;
456
+ readonly PauseTimer: 54;
457
+ readonly UnpauseTimer: 55;
458
+ readonly Draw: 56;
459
+ readonly SetAllianceStatus: 57;
460
+ readonly DisableDebugMode: 58;
461
+ readonly EnableDebugMode: 59;
462
+ };
463
+ /** The 27 player-group slots of a trigger, and the values conditions/actions store. */
464
+ export declare const PlayerGroup: {
465
+ readonly Player1: 0;
466
+ readonly Player2: 1;
467
+ readonly Player3: 2;
468
+ readonly Player4: 3;
469
+ readonly Player5: 4;
470
+ readonly Player6: 5;
471
+ readonly Player7: 6;
472
+ readonly Player8: 7;
473
+ readonly Player9: 8;
474
+ readonly Player10: 9;
475
+ readonly Player11: 10;
476
+ readonly Player12: 11;
477
+ readonly None: 12;
478
+ readonly CurrentPlayer: 13;
479
+ readonly Foes: 14;
480
+ readonly Allies: 15;
481
+ readonly NeutralPlayers: 16;
482
+ readonly AllPlayers: 17;
483
+ readonly Force1: 18;
484
+ readonly Force2: 19;
485
+ readonly Force3: 20;
486
+ readonly Force4: 21;
487
+ readonly Unused1: 22;
488
+ readonly Unused2: 23;
489
+ readonly Unused3: 24;
490
+ readonly Unused4: 25;
491
+ readonly NonAlliedVictoryPlayers: 26;
492
+ };
493
+ export declare const Comparison: {
494
+ readonly AtLeast: 0;
495
+ readonly AtMost: 1;
496
+ readonly Exactly: 10;
497
+ };
498
+ export declare const SwitchState: {
499
+ readonly Set: 2;
500
+ readonly Cleared: 3;
501
+ };
502
+ export declare const SwitchAction: {
503
+ readonly Set: 4;
504
+ readonly Clear: 5;
505
+ readonly Toggle: 6;
506
+ readonly Randomize: 11;
507
+ };
508
+ export declare const SetModifier: {
509
+ readonly SetTo: 7;
510
+ readonly Add: 8;
511
+ readonly Subtract: 9;
512
+ };
513
+ export declare const ResourceType: {
514
+ readonly Ore: 0;
515
+ readonly Gas: 1;
516
+ readonly OreAndGas: 2;
517
+ };
518
+ /**
519
+ * Unit ids beyond units.dat that conditions and actions accept. 228 is "None"; the classes
520
+ * start at 229 — a melee map's own defeat trigger is "commands at most 0 of 231", Buildings.
521
+ */
522
+ export declare const UnitClass: {
523
+ readonly Any: 229;
524
+ readonly Men: 230;
525
+ readonly Buildings: 231;
526
+ readonly Factories: 232;
527
+ };
373
528
  /**
374
529
  * A parsed scenario.
375
530
  *
@@ -493,6 +648,16 @@ export declare function setExtendedStrings(scn: Scenario, extended: boolean): vo
493
648
  * strings themselves are unchanged; the whole table is re-encoded on save.
494
649
  */
495
650
  export declare function setTextEncoding(scn: Scenario, encoding: TextEncoding): void;
651
+ /** UNIS and/or UNIx. */
652
+ export declare const unitSettingsSections: (scn: Scenario) => ("TYPE" | "VER " | "IOWN" | "OWNR" | "ERA " | "DIM " | "SIDE" | "MTXM" | "PUNI" | "UPGR" | "PTEC" | "UNIT" | "ISOM" | "TILE" | "DD2 " | "THG2" | "MASK" | "STR " | "UPRP" | "UPUS" | "MRGN" | "TRIG" | "MBRF" | "SPRP" | "FORC" | "WAV " | "UNIS" | "UPGS" | "TECS" | "SWNM" | "COLR" | "PUPx" | "PTEx" | "UNIx" | "UPGx" | "TECx" | "STRx" | "CRGB")[];
653
+ /** UPGS and/or UPGx. */
654
+ export declare const upgradeSettingsSections: (scn: Scenario) => ("TYPE" | "VER " | "IOWN" | "OWNR" | "ERA " | "DIM " | "SIDE" | "MTXM" | "PUNI" | "UPGR" | "PTEC" | "UNIT" | "ISOM" | "TILE" | "DD2 " | "THG2" | "MASK" | "STR " | "UPRP" | "UPUS" | "MRGN" | "TRIG" | "MBRF" | "SPRP" | "FORC" | "WAV " | "UNIS" | "UPGS" | "TECS" | "SWNM" | "COLR" | "PUPx" | "PTEx" | "UNIx" | "UPGx" | "TECx" | "STRx" | "CRGB")[];
655
+ /** UPGR and/or PUPx. */
656
+ export declare const upgradeRestrictionSections: (scn: Scenario) => ("TYPE" | "VER " | "IOWN" | "OWNR" | "ERA " | "DIM " | "SIDE" | "MTXM" | "PUNI" | "UPGR" | "PTEC" | "UNIT" | "ISOM" | "TILE" | "DD2 " | "THG2" | "MASK" | "STR " | "UPRP" | "UPUS" | "MRGN" | "TRIG" | "MBRF" | "SPRP" | "FORC" | "WAV " | "UNIS" | "UPGS" | "TECS" | "SWNM" | "COLR" | "PUPx" | "PTEx" | "UNIx" | "UPGx" | "TECx" | "STRx" | "CRGB")[];
657
+ /** TECS and/or TECx. */
658
+ export declare const techSettingsSections: (scn: Scenario) => ("TYPE" | "VER " | "IOWN" | "OWNR" | "ERA " | "DIM " | "SIDE" | "MTXM" | "PUNI" | "UPGR" | "PTEC" | "UNIT" | "ISOM" | "TILE" | "DD2 " | "THG2" | "MASK" | "STR " | "UPRP" | "UPUS" | "MRGN" | "TRIG" | "MBRF" | "SPRP" | "FORC" | "WAV " | "UNIS" | "UPGS" | "TECS" | "SWNM" | "COLR" | "PUPx" | "PTEx" | "UNIx" | "UPGx" | "TECx" | "STRx" | "CRGB")[];
659
+ /** PTEC and/or PTEx. */
660
+ export declare const techRestrictionSections: (scn: Scenario) => ("TYPE" | "VER " | "IOWN" | "OWNR" | "ERA " | "DIM " | "SIDE" | "MTXM" | "PUNI" | "UPGR" | "PTEC" | "UNIT" | "ISOM" | "TILE" | "DD2 " | "THG2" | "MASK" | "STR " | "UPRP" | "UPUS" | "MRGN" | "TRIG" | "MBRF" | "SPRP" | "FORC" | "WAV " | "UNIS" | "UPGS" | "TECS" | "SWNM" | "COLR" | "PUPx" | "PTEx" | "UNIx" | "UPGx" | "TECx" | "STRx" | "CRGB")[];
496
661
  export declare function parseScenario(bytes: Uint8Array): Scenario;
497
662
  declare const MODELLED: readonly [
498
663
  "TYPE",
@@ -996,6 +1161,20 @@ export declare function megatileForTile(tileset: Tileset, tileId: number): numbe
996
1161
  * a rotated copy (see cycle.ts).
997
1162
  */
998
1163
  export declare function drawMegatile(tileset: Tileset, megatile: number, dest: Uint8ClampedArray | Uint8Array, destWidth: number, dx: number, dy: number, palette?: Uint8Array): void;
1164
+ export declare function groupBuildable(group: Cv5Group): boolean;
1165
+ export declare const TileFlag: {
1166
+ readonly Walkable: 1;
1167
+ readonly MidGround: 2;
1168
+ readonly HighGround: 4;
1169
+ readonly BlocksView: 8;
1170
+ readonly Ramp: 16;
1171
+ };
1172
+ /**
1173
+ * A megatile's ground height as the game takes it, from its 16 minitiles (the CV5 height
1174
+ * bits are not read): high when at least 12 are high, else mid when high and mid together
1175
+ * are at least 12, else low.
1176
+ */
1177
+ export declare function megatileHeight(tileset: Tileset, megatile: number): 0 | 1 | 2;
999
1178
  /** StarCraft tileset reference data. */
1000
1179
  export type TilesetId = "badlands" | "platform" | "install" | "ashworld" | "jungle" | "desert" | "ice" | "twilight";
1001
1180
  /**
@@ -1099,6 +1278,122 @@ export declare function mapStatistics(scn: Scenario, tileset: Tileset | null, te
1099
1278
  export declare function statisticsText(s: MapStatistics): string;
1100
1279
  /** Every built-in dialog, by the id `openDialogAtom` takes; `DialogHost` maps each to its component. */
1101
1280
  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";
1281
+ /**
1282
+ * The per-tileset tables StarEdit's isometric brush runs on.
1283
+ *
1284
+ * Nothing here can be read off the CV5: it is the numbering StarEdit compiled in, as
1285
+ * reverse-engineered for Chkdraft (src/mapping_core/sc.h, MIT, Justin Forsberg).
1286
+ * Upstream: https://github.com/TheNitesWhoSay/Chkdraft
1287
+ * Full provenance and license notice: ../../ATTRIBUTION.md
1288
+ *
1289
+ * Each
1290
+ * tileset has one row per CV5 terrain type (the `index` field of a tile group):
1291
+ *
1292
+ * - `isomValue` — what the ISOM section stores (shifted left 4) for a diamond of that
1293
+ * type, and the row of the shape-link table the type starts at. Flat terrains
1294
+ * ("solid brushes") take one row; each cliff/edge set takes fourteen (one per shape).
1295
+ * - `linkId` — the identity neighbours are compared by; unrelated to `isomValue`.
1296
+ * - `brush` — position in StarEdit's palette, or -1 for types it does not offer.
1297
+ *
1298
+ * Row 0's `isomValue` is where the shape rows begin. Rows above the half-way point are
1299
+ * edge sets; their `isomValue` is the first of their fourteen shape rows.
1300
+ *
1301
+ * `terrainTypeMap` is the compressed adjacency list: "type A, then the types a search
1302
+ * for a neighbour of A starts at, 0" repeated, ending in 0. See editor/isom.ts.
1303
+ */
1304
+ export interface IsomTerrainType {
1305
+ /** CV5 group `index`. */
1306
+ index: number;
1307
+ isomValue: number;
1308
+ linkId: number;
1309
+ brush: number;
1310
+ }
1311
+ export interface TileChange {
1312
+ /** Flat index into `scenario.tiles`. */
1313
+ at: number;
1314
+ before: number;
1315
+ after: number;
1316
+ /**
1317
+ * What `scenario.editorTiles` (TILE) held before a terrain change, when that differs
1318
+ * from `before` (the cell was under a doodad). Filled in by `applyChanges` the first
1319
+ * time a change is applied, so undo can put the ground back rather than the doodad tile.
1320
+ */
1321
+ under?: number;
1322
+ }
1323
+ /**
1324
+ * Apply a change list, or take it back. Terrain edits (`layer` "terrain") write MTXM and
1325
+ * TILE alike, remembering what TILE held in `under` on first application; doodad edits
1326
+ * ("mtxm") touch only MTXM's contents, leaving TILE as the ground beneath.
1327
+ */
1328
+ export declare function applyChanges(scn: Scenario, changes: readonly TileChange[], direction?: "do" | "undo", layer?: "terrain" | "mtxm"): void;
1329
+ export interface Links {
1330
+ left: number;
1331
+ top: number;
1332
+ right: number;
1333
+ bottom: number;
1334
+ }
1335
+ /** One quadrant of a shape-link row: the two links on its rect sides, and its identity. */
1336
+ export interface QuadLinks extends Links {
1337
+ linkId: number;
1338
+ }
1339
+ export interface ShapeLinks {
1340
+ /** CV5 `index` of the terrain or edge set this row belongs to; 0 for padding rows. */
1341
+ terrainType: number;
1342
+ quads: [
1343
+ QuadLinks,
1344
+ QuadLinks,
1345
+ QuadLinks,
1346
+ QuadLinks
1347
+ ];
1348
+ }
1349
+ export interface IsomTables {
1350
+ era: number;
1351
+ links: ShapeLinks[];
1352
+ terrainTypes: readonly IsomTerrainType[];
1353
+ /** `[a * n + b]`: the terrain to try first when `b` must sit next to `a`. */
1354
+ terrainTypeMap: Uint16Array;
1355
+ /** Link hash of a left-hand CV5 group → the even group indices carrying it. */
1356
+ hashToGroups: Map<number, number[]>;
1357
+ }
1358
+ /** The brush tables for a tileset's graphics, built once per loaded tileset. */
1359
+ export declare function isomTables(tileset: Tileset, era: number): IsomTables;
1360
+ export interface Diamond {
1361
+ x: number;
1362
+ y: number;
1363
+ }
1364
+ /**
1365
+ * The diamond under a map pixel — StarEdit's own arithmetic. Diamond (x, y) is centred
1366
+ * on pixel (64x, 32y) and spans 128x64. The result can be off the map; check bounds.
1367
+ */
1368
+ export declare function diamondAt(px: number, py: number): Diamond;
1369
+ export interface IsomEdit {
1370
+ tiles: TileChange[];
1371
+ /** Changes to `scenario.isom`, indexed by u16. */
1372
+ isom: TileChange[];
1373
+ }
1374
+ /** True when the scenario carries an ISOM section the brush can work on. */
1375
+ export declare function hasIsom(scn: Scenario | null): scn is Scenario & {
1376
+ isom: Uint16Array;
1377
+ };
1378
+ /**
1379
+ * Paint `terrainType` (a CV5 index) with an `extent`-diamond brush centred on `d`.
1380
+ * Mutates `scn.tiles` and `scn.isom`; returns what changed, or null when the terrain is
1381
+ * not one the tileset paints isometrically or `d` is not a diamond.
1382
+ */
1383
+ export declare function paintIsom(scn: Scenario & {
1384
+ isom: Uint16Array;
1385
+ }, tileset: Tileset, d: Diamond, terrainType: number, extent: number, random?: () => number): IsomEdit | null;
1386
+ /**
1387
+ * Paint `terrainType` (a CV5 index) over any set of diamonds in one stroke: each is set to
1388
+ * the terrain, the neighbours they leave are re-picked as `paintIsom` re-picks the edge of
1389
+ * its brush, and the tiles follow. What `scmjs map generate` lays its ground with, a whole
1390
+ * plateau or lake at a time, so the result does not depend on the order of the diamonds.
1391
+ * Diamonds off the lattice or off the map are skipped; null when the terrain is not one
1392
+ * the tileset paints isometrically.
1393
+ */
1394
+ export declare function paintIsomDiamonds(scn: Scenario & {
1395
+ isom: Uint16Array;
1396
+ }, tileset: Tileset, diamonds: readonly Diamond[], terrainType: number, random?: () => number): IsomEdit | null;
1102
1397
  export interface IsomCheck {
1103
1398
  /** Rects that have tiles under them. */
1104
1399
  rects: number;
@@ -1122,6 +1417,10 @@ export interface IsomReport extends IsomCheck {
1122
1417
  /** A rebuild would bring more than `STALE_ISOM_SHARE` of the rects back in step. */
1123
1418
  stale: boolean;
1124
1419
  }
1420
+ /** How well the ISOM section describes the tiles that are actually on the map. */
1421
+ export declare function checkIsom(scn: Scenario & {
1422
+ isom: Uint16Array;
1423
+ }, tileset: Tileset): IsomCheck;
1125
1424
  /**
1126
1425
  * What `useIsomStatus` measured for the open map — whether it can be painted
1127
1426
  * isometrically and how well its lattice describes its tiles. Check Map reads it.
@@ -1319,6 +1618,8 @@ export declare function summarizeTrigger(t: ReadonlyTrigger, names: TriggerNames
1319
1618
  conditions: string;
1320
1619
  actions: string;
1321
1620
  };
1621
+ /** Text of the trigger's Comment action, if it has one. */
1622
+ export declare function triggerComment(t: ReadonlyTrigger, names: TriggerNames): string | null;
1322
1623
  /**
1323
1624
  * A `TriggerNames` over the scenario. `intern` appends to the string table (marking it
1324
1625
  * dirty), so parsing text into a scenario changes it even before the triggers are applied;
@@ -1574,6 +1875,36 @@ export declare function updateUnits(scn: Scenario, indices: readonly number[], p
1574
1875
  * to the map.
1575
1876
  */
1576
1877
  export declare function moveUnits(scn: Scenario, units: UnitsDat | null, indices: readonly number[], dx: number, dy: number, snap?: boolean): UnitChange[];
1878
+ export type SymmetryMode = "none" | "h" | "v" | "hv" | "rot180" | "rot90" | "diag" | "adiag";
1879
+ export interface Point {
1880
+ x: number;
1881
+ y: number;
1882
+ }
1883
+ /**
1884
+ * One image of a mode, as a map from a point to its image over a continuous plane `w` by
1885
+ * `h` (pixels or tiles, whichever the caller measures in), with the same map's linear part
1886
+ * — how a movement turns — and which element of the mode's group it is. The elements are
1887
+ * numbered so that `mirroredOwner` can hand each image a player consistently: for the
1888
+ * reflections 1 is the one flip (and in "hv" 2 is the other, 3 both), for the quarter turn
1889
+ * 1, 2 and 3 are the turns clockwise.
1890
+ */
1891
+ export interface SymmetryImage {
1892
+ element: number;
1893
+ map(x: number, y: number): Point;
1894
+ linear(dx: number, dy: number): Point;
1895
+ }
1896
+ /** The images of `mode` other than the identity; modes that turn the plane need it square and answer nothing otherwise. */
1897
+ export declare function symmetryImages(mode: SymmetryMode, w: number, h: number): SymmetryImage[];
1898
+ /**
1899
+ * The player an image of something `owner` placed belongs to, when Symmetry hands each
1900
+ * copy its own player. The eight players go in groups of as many as the mode has images —
1901
+ * P1–P2, P3–P4, … for the two-way modes, P1–P4 and P5–P8 for the four-way ones — and the
1902
+ * copy takes the player in the same group the image's element leads to, so whichever
1903
+ * player you place for, each corner keeps its own: under "hv" P1 top-left gives P2
1904
+ * top-right, P3 bottom-left and P4 bottom-right, and placing for P3 bottom-left gives the
1905
+ * same four. Neutral and the rescuable players (9–12) are left alone.
1906
+ */
1907
+ export declare function mirroredOwner(mode: SymmetryMode, owner: number, element: number): number;
1577
1908
  /**
1578
1909
  * Something on the map, for finding its mirror images among the others: its centre in
1579
1910
  * pixels and what it is (a unit type, a doodad, a box's size). Moving and deleting under
@@ -1717,6 +2048,27 @@ export interface SoundRow {
1717
2048
  }
1718
2049
  /** The table's filled slots, in slot order. */
1719
2050
  export declare function soundList(scn: Scenario, extras: Extras, wavs?: readonly number[]): SoundRow[];
2051
+ export interface WavInfo {
2052
+ /** The `fmt ` tag; for WAVE_FORMAT_EXTENSIBLE the sub-format's tag (its GUID's first field). */
2053
+ format: number;
2054
+ channels: number;
2055
+ sampleRate: number;
2056
+ bitsPerSample: number;
2057
+ /** Byte length of the `data` chunk, clipped to the file. */
2058
+ dataLength: number;
2059
+ /** Offset of the first sample byte. */
2060
+ dataOffset: number;
2061
+ /** Bytes per frame (PCM) or per block (ADPCM), from the header. */
2062
+ blockAlign: number;
2063
+ /** The `fmt ` chunk's bytes past the 16 common ones (ADPCM's block parameters and coefficients). */
2064
+ extra: Uint8Array;
2065
+ }
2066
+ /** Duration in seconds, from the header — no decoding needed. */
2067
+ export declare function wavDuration(info: WavInfo): number;
2068
+ /** A short label: `22050 Hz · 16-bit · mono`, with the codec named when it is not plain PCM. */
2069
+ export declare function wavFormatLabel(info: WavInfo): string;
2070
+ /** Reads the header of a RIFF/WAVE file; null when the bytes are not one. */
2071
+ export declare function parseWavHeader(bytes: Uint8Array): WavInfo | null;
1720
2072
  export interface BaseTerrain {
1721
2073
  /** CV5 group `index`, which is also the ISOM terrain id. */
1722
2074
  id: number;
@@ -1813,6 +2165,104 @@ export declare function idealStarts(width: number, height: number, players: numb
1813
2165
  * ones placed before it, so they never overlap each other.
1814
2166
  */
1815
2167
  export declare function placeStartLocations(scn: Scenario, tileset: Tileset | null, tables: UnitsDat | null, options: StartPlacementOptions): StartPlacementResult;
2168
+ export interface DoodadDef {
2169
+ /** The `dddata.bin` index, which DD2 records store. */
2170
+ id: number;
2171
+ /** First CV5 group; row `r` is group `group + r`, column `c` is slot `c`. */
2172
+ group: number;
2173
+ width: number;
2174
+ height: number;
2175
+ /** Palette category, from stat_txt.tbl; "Unlisted" for groups without a name. */
2176
+ category: string;
2177
+ /** The first group's CV5 flag word — copied onto the overlay's THG2 record, as StarEdit does. */
2178
+ flags: number;
2179
+ /** The sprite (or unit) drawn over the tiles, or null. */
2180
+ overlay: DoodadOverlay | null;
2181
+ /** MTXM id per cell, row-major; 0 where the doodad leaves the ground alone. */
2182
+ tiles: Uint16Array;
2183
+ /** CV5 group required under each cell, row-major; 0 = no requirement. */
2184
+ required: Uint16Array;
2185
+ /**
2186
+ * Whether any of its minitiles carries the VF4 ramp bit. StarEdit files ramps under the
2187
+ * cliff categories with no name of their own; this is the only way to tell them apart.
2188
+ */
2189
+ ramp: boolean;
2190
+ }
2191
+ export interface DoodadOverlay {
2192
+ kind: "sprite" | "unit";
2193
+ /** sprites.dat or units.dat id. */
2194
+ id: number;
2195
+ flipped: boolean;
2196
+ }
2197
+ export interface DoodadCategory {
2198
+ name: string;
2199
+ doodads: DoodadDef[];
2200
+ }
2201
+ export interface DoodadCatalogue {
2202
+ doodads: DoodadDef[];
2203
+ byId: Map<number, DoodadDef>;
2204
+ /** In first-appearance order, the way StarEdit's category drop-down lists them; "Unlisted" last. */
2205
+ categories: DoodadCategory[];
2206
+ /** Whether dddata.bin was available; without it nothing is ever refused for its ground. */
2207
+ hasPlacementData: boolean;
2208
+ }
2209
+ /**
2210
+ * Read the doodads out of the CV5. `dddata` may be null (no requirements) and `names`
2211
+ * the decoded stat_txt.tbl or null (one anonymous category).
2212
+ */
2213
+ export declare function buildDoodadCatalogue(tileset: Tileset, dddata: Uint8Array | null, names: readonly string[] | null): DoodadCatalogue;
2214
+ export interface SpriteChange {
2215
+ index: number;
2216
+ before: SpriteRecord | null;
2217
+ after: SpriteRecord | null;
2218
+ }
2219
+ export interface DoodadChange {
2220
+ index: number;
2221
+ before: DoodadRecord | null;
2222
+ after: DoodadRecord | null;
2223
+ }
2224
+ /** Everything one doodad edit changes; each list undoes in reverse. */
2225
+ export interface DoodadEdit {
2226
+ /** MTXM-only tile changes (apply with `applyChanges(…, "mtxm")`). */
2227
+ tiles: TileChange[];
2228
+ doodads: DoodadChange[];
2229
+ sprites: SpriteChange[];
2230
+ }
2231
+ export declare function applyDoodadChanges(scn: Scenario, changes: readonly DoodadChange[], direction?: "do" | "undo"): void;
2232
+ export interface DoodadPlacementOptions {
2233
+ /** Skip StarEdit's ground check: any doodad goes on any terrain, even over another doodad. */
2234
+ placeAnywhere: boolean;
2235
+ /** Keep the left column on an even tile, as StarEdit always does. */
2236
+ snapToGrid: boolean;
2237
+ /** Place as plain terrain: the tiles (both sections) and any overlay sprite, no DD2 record — a placement and a conversion in one. */
2238
+ asTerrain: boolean;
2239
+ }
2240
+ export declare const DEFAULT_DOODAD_PLACEMENT: DoodadPlacementOptions;
2241
+ export interface DoodadVerdict {
2242
+ ok: boolean;
2243
+ /** The footprint leaves the map (never allowed). */
2244
+ outOfBounds: boolean;
2245
+ /** Cell indices (row-major) whose ground fails the check, for the ghost to mark red. */
2246
+ bad: number[];
2247
+ }
2248
+ /**
2249
+ * May `def` go with its top-left tile at (tx, ty)? `tileAt` overrides what a cell
2250
+ * currently holds — a move passes the map as it would be with the moving doodads gone.
2251
+ *
2252
+ * A requirement counts only under a cell the doodad draws. Measured against Blizzard's
2253
+ * own maps (Ice Floes, Spring Thaw, Isolation): every ramp and bridge they placed sits
2254
+ * on ground that matches its drawn cells exactly and its undrawn "approach" cells not
2255
+ * at all — an Ice cliff ramp wants two more rows of cliff above it than any cliff has, a
2256
+ * Desert bridge wants dirt where its channel's water is — so StarEdit never looked at
2257
+ * those.
2258
+ */
2259
+ export declare function checkDoodadPlacement(scn: Scenario, tileset: Tileset | null, def: DoodadDef, tx: number, ty: number, opts: DoodadPlacementOptions, tileAt?: (at: number) => number): DoodadVerdict;
2260
+ /**
2261
+ * Stamp `def` at (tx, ty): its tiles into MTXM, a DD2 record and, if it has one, the
2262
+ * overlay sprite. `tileAt` is what the cells hold right now (a move passes the state
2263
+ * with the old copy removed). Nothing is applied.
2264
+ */
2265
+ export declare function placeDoodad(scn: Scenario, def: DoodadDef, tx: number, ty: number, owner: number, tileAt?: (at: number) => number): DoodadEdit;
1816
2266
  /** OWNR controller bytes as StarEdit's Player Settings lists them, with the rest for maps that use them. */
1817
2267
  export declare const PLAYER_TYPES: {
1818
2268
  value: number;