api.document

The file's name, or its full path when the desktop wrote it.

Why the game did not start, when it was asked to.

"Placed units", "String table", …

How the game combines repeated occurrences.

The fixed buffer the game reads the section into, for this map's size; null when the length varies.

The record length of a list section, or null.

The shortest copy the game takes, for a "last" or "first" section; shorter ones are passed over. Null when any length is taken.

Whether the editor decodes the section into its model and re-encodes it on save.

Position in the file's section list — what the byte-level calls take.

The four characters as stored ("VER " keeps its space); junk in a protected map.

Byte offset of the eight-byte chunk header within the CHK.

Payload length.

The length field as written; differs from size only when the file ended early.

Which occurrence of this name it is, 0-based, and how many the file has.

Whether the editor has unsaved changes it will encode into this section on save.

The registry entry, or null for a section the editor has never heard of.

COLR index 0–15 (playable slots).

A CRGB custom colour, or null to go back to the palette colour (playable slots).

0-based force (playable slots).

The whole flag word, applied before the booleans.

0-based playable slots the force should contain (others keep theirs); moves them from their forces.

Explicitly back to (or off) the dat defaults; setting any number below turns it off.

Custom name; "" restores the default.

PUNI: player 0-based or "default" (the default column); value true / false, or "default" to follow the default column again.

player 0-based or "default"; useDefault: true puts a player back on the default column.

player 0-based or "default"; useDefault: true puts a player back on the default column.

True when ISOM was reconstructed from the tiles; false when it is the flat fill's lattice.

null leaves the field at the unit's default (clears its valid bit); a number sets it and the bit.

null leaves the state alone; a boolean forces it.

How every archive member is compressed; ignored for a bare .chk.

Encrypt the members as StarEdit does. Every StarCraft build reads it.

Archive members left out of the file, by name.

Leave out ISOM, TILE and DD2: the terrain-editing data the game never reads.

Leave out IVER, IVE2, IOWN, UPUS, SWNM and WAV: editor bookkeeping the game never reads.

Leave out sections whose names the format reference does not know.

Collapse a section that occurs more than once into the bytes the game would act on.

Drop bytes after the last section header the file could parse.

plugin id/step id.

The step's label when it ran, for a notice about a step that is no longer there.

Overlay sprites that belonged to the dropped doodads.

Per player (0-based), where the start location landed, or null when nothing within reach fit.

ERA as stored (the tileset is era & 7).

CHK VER: 59 original, 63 hybrid, 205 Brood War, 206 Remastered.

Open to look at only (OpenDocumentOptions.viewOnly): every write throws and it is never saved.

The container: the open file's (else scx) — scx / scm archives, chk the bare scenario.

The file's name; defaults to the open file's, or the scenario name plus the format.

Compression, encryption and what is left out: over the options Save last used for this map (or its defaults — PKWARE and encryption for a new map, the way it was opened for an opened one), so the bytes are what Save would write unless you say otherwise.

False gives the map without its build steps (document.buildSteps): the scenario as the editor holds it. By default the file is the one Save would write, steps run — except from inside a step, where it is always the map without them.

Write a copy: the document keeps its own name, handle and clean state.

ISOM id of the terrain the map is refilled with; the tileset's default when omitted.

Keep the tile numbers and change only ERA (what SCMDraft's switch does).

The map as Save would write it without the steps, or the step before this one's output: an .scx / .scm archive, the archive extras inside.

Aborted when the user chooses to save without waiting.

Unique within the plugin; the file remembers plugin id/id.

What the notice says is running: "eudplib".

Whether the open map has anything for this step. Cheap and synchronous; false leaves Save exactly as it was.

Build. Return an archive (or a bare scenario) — the editor takes the scenario and any new members from it and lays the final file out with the user's save options; the map's own members are written as they were. Throw an Error whose message says what is wrong in the user's terms.

Unique within the plugin.

What a failure notice names: "TrigScript".

Whether there is anything to do for the open map. Cheap and synchronous; every save asks. Always, when omitted.

May be asynchronous and may write to the document. A throw does not stop the save: the map is written as it stands and a notice shows the error's message, so word it for the user. Inside it document.export() answers the map as it stands, without running anything.

Run spec.run before the map's bytes are produced, every time the map leaves the editor.

The steps behind the file the open map came from or was last saved to; null for a plain map.

Add or replace a member; marks the map modified.

Remove a member; true when there was one.

Label of the entry Undo would take back; null with nothing to undo.

3 × 3 grid, row-major: 0 top-left … 4 centre … 8 bottom-right. Default 4.

ISOM id of the terrain for the new area (a TerrainType.id); the tileset's default when omitted.

Pull locations that hang past the new edge back inside; default true.

Open the map to look at, not to change — a replay's map, a preview. It always opens beside the open map (into is ignored), so nothing is replaced and nothing is asked. Panning, zooming, the layers and selecting work; every tool, menu and dialog that would change it is off, and every write throws — edit, update, sections (except replaceFile(…, { asOpened: true }), a reading of the file rather than an edit), resize, changeTileset, extras, the clipboard's cut and paste, save and saveAs unless as a copy, sync.start. It is never kept in Open Recent, and closing it asks nothing. File ▸ Edit a Copy opens an ordinary copy. label is what the tab and the status bar call it ("Replay"); true is the plain "View only".

Stable for the map's life in this session; never reused.

The scenario's name.

Open to look at only; see OpenDocumentOptions.viewOnly.

Untitled Scenario when omitted.

Beside the open map or in place of it; see OpenInto.

ISOM id of the terrain to fill with; the tileset's default ground when omitted.

Start locations to lay down for players 1..N, as tx.placeStartLocations would. Part of making the map, so a fresh scenario has no history to undo them from.

Warnings from parsing the edited file (a truncated section, no usable DIM, …); empty when it read cleanly.

Take the bytes as the file that was opened rather than as an edit: the map stays unmodified, so closing it does not ask to save, while Save writes the bytes as given. For a plugin that repairs a map as it opens — nothing the user did changed it. Use it only right after an "open", or to put back what was opened; anything else would hide a change from the user. The history is dropped either way.

Every occurrence in file order; empty without a map.

A copy of one occurrence's payload.

The bytes the game acts on for a name — repeated occurrences combined the way the game combines them (SectionKnowledge.mode) — or null when the file has none.

The whole CHK as Save would write it (the archive extras are document.extras).

What the editor knows about a section name, sized for the open map; null for an unknown name.

Every section the editor knows, sized for the open map.

Replace one occurrence's payload.

Rename one occurrence (four characters; shorter names are padded with spaces).

Insert a section before index (list().length appends).

Move the occurrence at from so that it sits at to.

Replace the whole CHK, the way File ▸ Open reads one. The map is marked modified, unless asOpened says the bytes are a reading of the file as it was opened.

The CHK inside a map file — an .scx / .scm archive's staredit\scenario.chk, or the bytes themselves for a bare CHK — the way File ▸ Open reads it, for replaceFile. Reads only; rejects with the reason for a file it cannot read.

Bytes after the last chunk the reader could parse — what follows a chunk header with a negative length, say. Save writes them back as they are; a replaceFile without them drops them. Null when the file ends cleanly.

The sections a file of the open map's revision must carry to load, as Check Map tests them (STRx in place of STR on a Remastered file).

The bytes File ▸ New would write for a section on a map of this size, tileset and revision — StarEdit's defaults for a settings table, the fixed VCOD, an empty list, null terrain. Null for a section the editor cannot produce: one it does not model, or an optional one a new map has no value for (CRGB, SWNM).

Re-encode sections from the editor's model, the way Save writes a dirty one, and install the result like any other raw edit. This is what turns a protected file back into a plain one: repeated occurrences collapse into one, a truncated or oversized section comes back at the size the model encodes to, a string table whose offsets point nowhere is rewritten with every string the editor could read. Names the editor does not model, and modelled ones whose model is absent (no ISOM, no settings table), are left as they are and missing from rebuilt; omit names for every modelled section the map has a model for.

The map had no usable ISOM, so one was created.

Lattice values that changed (every one of a created section).

Diamonds the rebuild resolved from the tiles.

Diamonds it had to guess — under doodads or off the edge.

MTXM (what the game draws) at a cell.

TILE (the ground without doodads) at a cell.

One tile into both sections.

Many tiles into both sections; returns how many changed.

The Rect brush: flat left/right pairs by column parity, one random variation per pair (variation pins it). Needs the tileset graphics; returns tiles changed.

Lay terrain the way a new map is laid over rect, ISOM lattice included when the map has one.

The isometric brush on one diamond: sets its ISOM value and regenerates the tiles around it, cliffs and shores included. Needs ISOM and the tileset; returns whether the terrain could be painted there.

Reconstruct the ISOM section from the tiles — for a map that arrived without one, or whose lattice no longer matches after Rect / Tile edits: exact for terrain that was laid down isometrically, a best guess under doodads and for hand-placed tiles. A missing or wrongly sized ISOM is created (undo removes it again); an existing one gets only the diamonds that differ. Needs the tileset graphics; null without them.

A StarEdit-style unit record (fresh serial, valid/used masks) centred on map pixels.

A unit the way the Units palette places one: a building snaps its placement box to the tile grid (when the palette's Snap to grid is on), anything else lands where you say, and nothing leaves the map. No placement checks — ask canPlaceUnit first if you want them. Returns the record's index.

Whether the Units palette's placement checks, with its current options, allow a unit of this type centred there.

makeSprite + addSprites in one, kept on the map; returns the record's index.

Stamp a doodad (a dddata.bin id) at a tile; returns its record index, or -1 when unknown or off the map.

Make doodads plain terrain: their records go, their tiles stay (in TILE as well as MTXM, so the cells are ground to every tool from here on) and an overlay stays as an ordinary sprite. The way to touch up a ramp or a cliff piece tile by tile. Returns records converted.

Stamp a Clip with its top-left tile at (tx, ty) inside this transaction — the clipboard's paste without the clipboard: the clip can come from anywhere (clipboard.copy, a library, a file), the user's own clip is left alone, and several stamps, or a stamp and the strokes around it, make one undo step. Every part the clip carries is laid down unless parts says otherwise; mode is "merge" unless given. Terrain and doodads from another tileset are refused, as a paste refuses them, and anything off the map is skipped, both said in the result's notes.

A location in the lowest free slot (pixel bounds); returns the slot, or -1 when the table is full.

Set ("fog") or clear the players bits (bit n = player n + 1) over cells; creates MASK on first use.

Tools ▸ Replace Terrain: every tile matching from (a flat terrain by ISOM id, or one exact tile) becomes to, over rect or the whole map; pairs are laid as the Rect brush lays them. Returns tiles changed. Terrain picks need the graphics.

The bucket fill: the 4-connected area around (x, y) of the same terrain type (match: "terrain", the Rect fill) or the same exact tile ("tile"), laid with terrainId as the Rect brush would, or set to tileId. Returns tiles changed.

The Blend brush: id goes on the cell beside the anchor tile on side (terrain.blendCandidates ranks what fits). Returns whether the cell was on the map.

What StarEdit does after an isometric edit: regenerate every tile from the ISOM lattice (the reverse of rebuildIsom). Needs ISOM and the graphics; returns tiles changed, or null without them.

The cells and their images under the symmetry mode (Tools ▸ Symmetry…), each once — what the built-in brushes paint over. With the mode off, the cells as given.

A map pixel and its images under the symmetry mode, the original first.

Shift units by a pixel delta; buildings re-snap to the grid when snap (the palette's option when omitted). Returns records changed.

Tools ▸ Auto-place Start Locations: one per player on a ring or in the corners, each moved to the nearest spot the placement checks accept; replace removes the existing ones first. Players count from 1.

Shift sprites by a pixel delta, clamped to the map. Returns records changed.

Change a doodad's owner or disabled flag (its tiles stay). Returns records changed.

Put Anywhere (slot 63) back to the whole map; returns whether it had to move.

Flip every tile's fog bit for players; returns tiles changed.

Copy one player's fog (0-based) onto the players in the to bit mask (bit n = player n + 1); returns tiles changed.

Fog or clear the connected area around (x, y) that shares player's fog state, for players; returns tiles changed.

A line for the status bar, appended to the label.

The list as it stands, cloned.

Replace the whole list.

Insert one (at the end without at); returns its index.

Replace one record; false when there is none at index.

Parse the text format (triggers.text.print's inverse) and append the result, or replace the list with replace: true. Strings the text names are interned as it parses. Throws with the line number when the text does not parse.

The index of text: an identical entry when there is one, else a new one. 0 for "".

Overwrite one slot.

Install a whole table; unreferenced trailing blanks are dropped, other indices keep their place.

File ▸ Import ▸ Strings: index<TAB>text lines (exchange.formatStrings writes them) set in place, indices past the end appended. Returns how many were replaced and added.

Name a switch (0-based); "" clears the name. Creates SWNM on the first one.

TRIG.

MBRF, the mission briefing's own list of the same records.

SWNM.

SPRP: the scenario's name and description ("" restores the file-name default).

OWNR / SIDE / COLR / CRGB / FORC: the Player Settings and Player Colors dialogs.

FORC: the Force Settings dialog.

UNIS / UNIx and PUNI: the Unit Settings dialog.

UPGS / UPGx and UPGR / PUPx: the Upgrade Settings dialog.

TECS / TECx and PTEC / PTEx: the Technology Settings dialog.

WAV and the archive's sound files: the Sound Editor.

UPRP / UPUS: the Create Unit with Properties slots (Triggers ▸ Unit Properties Slots…).

Scenario ▸ Map Revision: VER / TYPE and, moving to or from Remastered, the string table's width.

Scenario ▸ Map Revision: how the string table's text is written to bytes. A map's file carries no note of it; the editor guesses on open (document.version().textEncoding) and this is the correction. The strings are unchanged; the table is re-encoded on save.

A line for the status bar, appended to the label.

All 12 slots, 0-based, with the effective colour and force.

Patch one slot; colours and forces apply to the eight playable slots only.

The effective row for a units.dat id — the dat's numbers where the type is on "use default".

Patch one type. Setting any number turns "use default" off for it (seeding the untouched columns from the dat, as the dialog does); useDefault: true puts it back. Hit points are whole points. name is the custom name ("" restores the default); available edits PUNI.

The 512 WAV slots in use, joined with the archive (present says whether the file is there).

Put path (staredit\wav\name.wav, or just name.wav) in the first free slot — the existing slot when it is already listed — and, with bytes, store the file in the archive. Returns the slot, or -1 when all 512 are taken.

Clear a slot; with deleteFile, remove the archive member too.

Patch one slot: a number sets the field and its "applied" bit, null clears the bit; a boolean forces a special state, null leaves it to the unit. used is StarEdit's "in use" tick, on by itself once the slot sets anything.

Back to an empty, unticked slot.