The API, group by group

The complete typings are the package's own index.d.ts, and every one of them is generated into a page at docs.scmjs.dev/api; this is the tour. Every method that reads the map returns null / [] / false when no map is open rather than throwing.

Promises, and the one thing that is synchronous#

Everything asynchronous is a promise. There is no completion callback and no (err, result) anywhere in the API: await it and read the answer, or check it for null. That covers opening, saving, exporting and rendering a map (document.open / create / save / saveAs / close / export / renderImage / changeTileset), loading game data (tileset.load, data.load, graphics.load, terrain.checkIsom), and everything that waits for the user (ui.pickArea, pickTile, pickFiles, saveFile, loadImage, readClipboardImage, confirm, alert, prompt, ask). A user who dismisses something resolves the promise with null or false rather than rejecting, so the ordinary path needs no try:

const rect = await api.ui.pickArea({ prompt: "Pick an area to flatten" });
if (!rect) return;                       // Esc, a right-click, or no map
await api.tileset.load();                // the graphics the fill needs
api.document.edit("Flatten", tx => tx.stampTerrain(rect, terrainId));

activate itself may be async — the host awaits it before the plugin counts as loaded — and so may a dialog button's run, which keeps the dialog open until it settles and closes it on anything but false.

The callbacks that remain are the ones that are genuinely callbacks rather than a deferred answer: event listeners (api.events.on(…)), the DOM handlers of ui.widgets, a dialog's or panel's mount, and the pointer and draw hooks of ui.mapTool and ui.overlay. Every one of them returns a Disposable or a cleanup function, so there is no off() to pair up and nothing to unregister at deactivation.

The one exception is a transaction's builder. document.edit(label, build) and document.update(label, build) take a synchronous build: its operations apply as they are called and the commit closes the transaction the moment it returns. An async builder would therefore commit whatever ran before its first await and let the rest mutate the map outside that entry, where undo cannot reach it. TypeScript refuses one, and the host also catches it at runtime — the result's notes and the console say so — for a plugin written in plain JavaScript.

// Wrong: commits at the await, and the placement lands outside the undo entry.
api.document.edit("Place", async tx => {
  await api.data.load();
  tx.placeUnit(0, 0, 128, 128);
});

// Right: await first, then write in one go.
await api.data.load();
api.document.edit("Place", tx => tx.placeUnit(0, 0, 128, 128));

Long work of your own gets a progress panel that does not block the editor; handle.cancelled() is the poll and handle.signal the same answer as an AbortSignal, so anything that takes one stops with the panel:

const job = api.ui.progress("Converting", { cancellable: true });
try {
  for (let i = 0; i < steps; i++) {
    if (job.cancelled()) break;
    job.report(i / steps, `Row ${i}`);
    const data = await fetch(url, { signal: job.signal });
  }
} finally {
  job.done();
}

The three kinds of write#

Everything a plugin can change about the open map goes through one of three, and they differ in what they cost:

They are the editor's own three: a stroke, a dialog's OK, and a raw file edit. Both transactions apply their operations as they are called, so later ones see earlier ones' results, and both commit once at the end — which is why the builder is synchronous (above).

api.document#

api.document.sections#

The CHK as a list of sections, the way the game reads it and Save writes it, with unsaved edits already encoded: list() gives every occurrence in file order as a SectionInfo (index, the four-character name, offset, size, declaredSize / truncated for a file that ended early, occurrence / occurrences for a repeated name, dirty when the editor holds changes it will encode there, and spec — what the registry knows: what, the combine mode on repeat, the fixed size the game reads for this map or null, the record stride of a list, and modelled, whether the editor decodes it). bytes(index) is a copy of one occurrence's payload, combined(name) the bytes the game acts on with repeats folded the way the registry says, file() the whole CHK, spec(name) / known() the registry.

The writes — write(index, bytes), rename(index, name), insert(index, name, bytes), remove(index), move(from, to) and replaceFile(bytes) — are a different kind of transaction from edit: the edited file is parsed again from scratch and installed as the open document, so the change reaches every part of the editor whether or not it models the section, and, as with Resize, the undo history is dropped and every selection cleared. The map is marked modified and "document" fires. Each returns { warnings }, what the parser said of the result; a bad index or a name longer than four characters throws, and so does any write without a map. Indices shift when a section is inserted or removed before them, so take a fresh list() after every edit. Section Explorer is the worked example.

Around them, what a repair needs: trailing() is the bytes after the last chunk the reader could act on (what follows a header with a negative length, say — Save writes them back as they are; a replaceFile without them drops them), required() the names 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), defaults(name) 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 name the editor cannot produce), and rebuild(names?) re-encodes sections from the editor's model the way Save writes a dirty one and installs the result like any other raw edit — 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 alone and missing from the result's rebuilt; omit names for every modelled section the map has a model for. Repair is the worked example for these.

EditTransaction#

tx applies each operation immediately, so a later operation sees the state the previous one left (a tileAt after a setTile reads the new tile). When build returns, the transaction lifts doodads the terrain edit broke, removes units the new ground cannot hold (when Remove stranded units is on, as for a stroke), commits, and repaints.

UpdateTransaction#

The second kind of write. Operations apply immediately — a string interned on one line is in the table for the trigger added on the next — and the commit at the end marks the map modified and tells the chrome to re-read. The result is { changed, sections, notes }: which CHK sections were actually touched (["TRIG", "STR "]), so changed is false when every operation was a no-op.

Ids are the game's: units.dat ids for unitTypes, upgrades.dat / techdata.dat ids for the other two (api.names.units() / upgrades() / techs() list them with their names). Players are 0-based here, as in the records; the chrome shows slot + 1.

const { condition, action, comparison, player } = api.consts.triggers;

api.document.update("Add a countdown", (tx) => {
  const trigger = api.triggers.newTrigger([player.Player1]);
  const timer = api.triggers.newCondition(condition.CountdownTimer);
  timer.comparison = comparison.AtMost;
  timer.amount = 30;
  trigger.conditions[0] = timer;

  const say = api.triggers.newAction(action.DisplayText);
  say.text = tx.strings.intern("30 seconds remaining");   // interned above, readable here
  trigger.actions[0] = say;
  trigger.actions[1] = api.triggers.newAction(action.PreserveTrigger);
  tx.triggers.add(trigger);
});

There is no undo entry, so a plugin that wants one keeps its own copy of what it replaced (api.triggers.list() before, tx.triggers.set(...) to put it back).

api.settings#

The same views without a transaction, for reading: players() / player(slot), forces(), unitType(id) / unitTypes() (every type with a name), upgrade(id) / upgrades(), tech(id) / techs(), sounds(), unitAvailable(player, unitId) (PUNI resolved against its default), cuwpSlots() / cuwpSlot(index), version() ({ version, label, fileVersion, type, extendedStrings, extension }). Empty lists and nulls with no map. Writing goes through document.update.

api.triggers#

Reading triggers, and everything needed to show one. Writing is document.update.

Generating triggers. There is no fluent builder here on purpose: tx.triggers.fromText already is one, and it is a better one. A record is 16 conditions and 64 actions of bare numbers, so building one field by field means knowing which field each argument lives in (defs.action(type).args will tell you, but you have to ask); writing the trigger in the text format instead means writing what the map maker would read in the Text Trigger Editor, and getting the names resolved against the open map for free.

const source = `
Trigger("Player 1"){
Conditions:
  Bring("Current Player", "Any unit", "Beacon Alpha", At least, 1);
Actions:
  Display Text Message(Always Display, "You found it!");
  Preserve Trigger();
}`;
api.document.update("Add the beacon trigger", (tx) => {
  tx.triggers.fromText(source);      // throws with the line number when it does not parse
});

fromText is the whole of it — it parses, interns the strings the text names, resolves "Beacon Alpha" against the map's own locations, and appends (or replaces the list with { replace: true }). triggers.text.parse is the same parse without the write, for a plugin that wants the records first; text.print goes back the other way, so a plugin can read what it wrote. Reach for newTrigger / newCondition / newAction when you are editing one field of an existing record, not when you are producing a run of them.

api.query#

Reading the open map: what is where, and the analyses the editor already does. Nothing here writes, and everything answers empty without a map.

A linter plugin is validate() plus find() plus view.goTo and nothing else.

api.view#

Where the viewport is looking. A plugin that finds something needs this to show the user where it is.

api.data#

The game's own tables as the editor decoded them — units.dat and its neighbours — for the numbers api.names only labels: hit points, costs, build times, armour, weapons, flags, the sprite and image each unit draws through. ready(), load(), then units(), weapons(), upgrades(), techs(), sprites(), flingy(), images(), plus race(unitId) and imagePath(imageId). Everything is null until the tables are loaded, and stays null when the game data was never extracted — degrade, do not throw.

api.consts#

The numbers a record is written in, so a plugin does not carry the hex itself. These are the editor's own tables — the very objects its codec encodes with, handed over at run time, not copies that can drift from them.

consts.triggers. A trigger record is sixteen conditions and sixty-four actions of plain numbers, and triggers.defs only says which field each argument lives in. This says what to put in it: condition and action (and briefingAction, where the same byte means something else) are the type numbers, player the 27 player-group values — which are also the indices of a trigger's own players array — and the rest are the enumerated arguments: comparison, switchState, switchAction, modifier, unitState (Set Doodad State / Set Invincibility), order, alliance, resource, score, and unitClass for the four ids past units.dat (Any unit, Men, Buildings, Factories). conditionFlags, actionFlags and triggerFlags are the flag bits, and deathsTable is the address an EUD player value is counted from (epd = (address - deathsTable) / 4 + 0x2000).

Those argument keys are ArgDef.kind, so a generic argument editor can look one up with the kind the def handed it:

const arg = api.triggers.defs.action(record.type).args[0];
const values = api.consts.triggers[arg.kind];      // e.g. { AtLeast: 0, AtMost: 1, Exactly: 10 }

For generating a run of triggers, tx.triggers.fromText is still the better tool — it resolves location and unit names against the open map, which no constant can. These are for editing a field of an existing record, and for reading one back (record.type === api.consts.triggers.condition.Bring).

Why this is on api and not in the npm package: @scm-js/plugin-api is types only, and import type is erased before the loader sees the specifier — which is exactly what lets a plugin depend on a package at all. A value imported from it type-checks and is then undefined at run time. Anything you need while the plugin runs has to arrive on api.

api.graphics#

The pictures the viewport draws, for a plugin's own lists and previews. Nothing is rendered anew: a unit or sprite frame comes out of the same cache the viewport blits from, so listing five hundred units costs about what the Units palette costs.

api.commands#

Named things a plugin can do, so a menu item, a hotkey, a context entry and another plugin all reach the same one.

api.commands.register({ id: "convert", title: "Convert Image…", run: () => open() });
api.menu.add("Tools", { label: "Convert Image…", command: "convert" });
api.hotkeys.add("Ctrl+Shift+I", { command: "convert" });

register(spec) returns a Disposable; run(id, ...args) runs one, whoever registered it (undefined when there is no such command or its enabled() says no); has(id) and list() ({ id, title, pluginId, enabled }[]) see every plugin's. An id without a dot is namespaced under the plugin ("convert" → "image-to-terrain.convert"); one with a dot is taken as it is, so a plugin can publish a stable name for others to call.

api.terrain#

Read-only helpers over the current tileset: types() (paintable flat terrains with name, group, height, buildable), isomTypes() (ids the isometric brush can paint), hasIsom(), tileInfo(id); terrainAt(tx, ty) — the terrain id (as types() lists them) a tile belongs to: its own group when it is flat ground, else what the ISOM lattice says there (under a cliff, one of the two terrains it joins), null when neither tells, color(tileId) (the atlas average, 0xRRGGBB), terrainColor(terrainId) (mean of the pair's common variations), heightOf(terrainId) (0 low / 1 high / 2 higher, null for anything that is not a flat terrain), diamondAt(px, py), isDiamond(d), diamondsIn(rect) (every lattice diamond whose centre tile is in the rect), floodRegion(x, y, match?) (the bucket fill's area, by terrain type or exact tile), blendCandidates(anchorTileId, side, options?) (the Blend palette's ranked list, with the pixel distance of each seam), flatGroupOf(terrainId) (the even CV5 group of a flat pair), active() / setActive(...) for the palette's brush, terrain, tile, size and Rect variation, and the symmetry mode: symmetry() / setSymmetry(mode) ("none", "h", "v", "hv", "rot180", "rot90", "diag", "adiag"), symmetryAvailable(mode) (the last three need a square map), mirror(cells) and mirrorPoint(px, py) — the images the built-in brushes paint and the palettes place on, so a plugin edit can honour the user's setting the way tx.fillArea does by itself. checkIsom() is asynchronous: it waits for the tileset graphics (rejecting when they are missing) and resolves with how well the ISOM describes the tiles — rects measured, mismatched among them, stale when the share is past what the palette warns at — or null when the map has no ISOM or no map is open.

api.tileset#

id(), name(), isLoaded(), load() (resolves false when the graphics were never extracted — that is a normal state, degrade), raw() for the decoded LoadedTileset.

api.selection#

markedArea() / markArea(rect | null) — the Cut / Copy / Paste layer's marked rectangle, the editor's one "region" concept; units(), sprites(), doodads(), locations() (indices, copied — sort yours freely), each with a setter (setUnits, setSprites, setDoodads, setLocations); layer() / setLayer(); lockedLayers() / setLayerLocked(layer, on) for the Layers panel's padlocks (a locked layer's tools refuse to change the map).

api.clipboard#

The Cut / Copy / Paste layer, sharing the user's own clip: clip() / setClip(clip | null); copy(source?) and cut(source?), where source is { rect } for a tile rect or { units?, sprites?, doodads?, locations? } for objects by index — omitted, they take what Ctrl+C would: the object layer's selection, else the marked area — with the parts ticked in parts(); paste(tx, ty, { parts?, mode? }), the clip's top-left at a tile, one undo step, the pasted area marked afterwards, returning the PasteResult (counts per list, notes for what was skipped); parts() / setParts(patch), mode() / setMode("merge" | "replace"), pasting() / setPasting(on) (arm the layer so the next click stamps), and summary(clip). A Clip is self-contained — it outlives the map it came from and pastes into another, with terrain and doodads refused across tilesets.

api.exchange#

The file formats behind File ▸ Import / Export: encodeTrg(triggers) / decodeTrg(bytes) for SCMDraft's raw .trg (2400-byte records; string indices are the map's own), and formatStrings() / parseStrings(text) for the index<TAB>text strings file (control bytes as <XX>), which tx.strings.import applies.

api.palette#

What the Units, Sprites, Doodads and Fog of War palettes have picked, and what they list — so a plugin can paint "whatever the user chose" without a picker of its own (Paint does exactly this: switch layers and its brush follows). The Terrain palette's pick is terrain.active().

api.names#

The names behind the numbers a map stores, so a plugin that shows raw values need not carry the game's tables: unit(id) / units() (StarEdit's names, plus Any unit, Men, Buildings, Factories for the trigger classes 228–231), upgrade / upgrades, tech / techs, weapon / weapons, playerType / playerTypes (OWNR controllers), race / races (SIDE), playerGroup / playerGroups (the 27 trigger groups), condition / conditions and action(type, briefing?) / actions(briefing?) (trigger and briefing types), aiScript(code). The list forms return { value, label }[] for a drop-down. The per-map ones read the open scenario and answer a placeholder without one: string(index) (null for 0 or out of range), location(index) (0-based slot; 63 is Anywhere), switch(index), player(slot), and tile(id) — the terrain a MTXM id belongs to, null without the tileset graphics.

api.text#

StarCraft's <XX> text control codes — bytes 0x01–0x1F in a string, which set the colour, move the text or hide it. This is the editor's own table, the one the String Editor's buttons and preview are drawn from, so a plugin that shows or rewrites map text carries no copy of its own. Worth using rather than reimplementing: the numbering is easy to get wrong, and the editor's own table was wrong from 0x12 up until it was checked against the classic player palette.

The Remastered newline change. StarCraft 1.16.1 reset the text colour at every line break; Remastered carries it onto the next line of the same string. So a multi-line string written before the remaster — most map descriptions, objectives and briefing text — can be drawn today in colours its author never chose. runs models Remastered's rule; pass { resetPerLine: true } to see the old rendering. bleedingLines(text) returns the lines that differ ({ line, carried }, carried being the whole TextCode inherited), and fixBleeding(text) writes the default colour at the head of each of them so both games draw the string alike — idempotent, and it never changes what the string says. The Repair plugin's string finding is exactly these two functions over api.query.strings().

Text stacking — the 1.16.1 trick of drawing lines on top of each other — is a different thing, and there is nothing here for it: Remastered does not render the overlap at all, and the intended picture was the overlap, so there is nothing to restore it to.

api.ui#

api.menu / api.contextMenu / api.hotkeys#

• menu.add(path, item): path is a top-level menu ("File", "Edit", "View", "Layer", "Scenario", "Triggers", "Tools", "Plugins", "Help") or a submenu by label ("File/Import"). Plugin items appear after a separator at the end of that menu, unless after names a built-in item or submenu (after: "Open Recent"), in which case the item sits directly under it. A last segment that names no submenu gets one of the plugin's own at the end of the menu ("Tools/AI"), so a plugin with many items can keep them together; separator: true on an item draws a line above it (never two in a row). item is { label, shortcut?, icon?, after?, enabled?(), run() }. icon puts a mark in front of the label: "plugin" for the plugin's own icon (the manifest's), or any PluginIcon — use it for items that do something no built-in does, such as reaching a server, so the user can tell at a glance which entries are the plugin's.
• contextMenu.add(surface, item): surfaces are "viewport" (the map) and "terrainPalette". run(ctx), enabled?(ctx) and visible?(ctx) get a ContextMenuContext: the tile and pixel under the pointer (viewport), the active layer, terrain mode and terrain, and the marked area.
• hotkeys.add("Ctrl+Shift+I", run): modifiers in any order, then a key name. Plugin hotkeys are checked before the built-ins and never while typing in a field or while a dialog is open.
• All three take { command: "id" } (or command: on the item) instead of a run of their own — see api.commands. A context item's command is called with the ContextMenuContext as its argument.

api.events#

on(event, fn) for "document" (opened, closed, replaced), "terrain" (every committed edit, stroke, undo and redo bumps it, terrain or not — fog edits included — so it is the "something changed on the map" event), "units", "sprites" (the doodads revision, which THG2 records ride on), "doodads", "locations", "settings" (every settings dialog's OK, Map Properties included), "triggers", "layer", "selection", "clipboard" (the marked area or the clip), "view" (scrolled, zoomed, a View tick moved, or an overlay registered or toggled), "tool" (a map tool or pick started or stopped), "modified" (the unsaved-changes flag), "palette" (a palette's pick changed: terrain brush, unit and owner, sprite, doodad, fog players), "options" (an editing option moved: symmetry, placement and doodad rules, location snap, the fog view player, clip parts and paste mode, locked layers, the grid look, Preferences), "file" (the document's name or handle after a Save, its save options, the archive extras, the recent list) and "commands" (a plugin registered or removed a command — how a plugin that calls another's by id learns it has arrived, since plugins activate in no fixed order; check commands.has in the listener).

The "document" listener is handed a DocumentEvent: reason is "open" (File ▸ Open, a drop, document.open from any plugin), "new" (File ▸ New, the startup map included), "close", or "replace" (the open map parsed again from edited bytes — a document.sections write, by any plugin, yours included), and fileName is the file's name or null. A plugin that acts on maps as they open listens for "open" and lets the rest pass; the other events carry nothing.

Listeners are notifications, not a pipeline: they run after the change, in the order the plugins were activated, and cannot veto, delay or reorder one another. There is no plugin ordering and none is planned — a listener that rewrites the map in response (Repair does, through document.sections) simply raises a fresh "document" event with reason "replace", which every other listener sees in turn, so whatever a plugin computed from the earlier state is recomputed from the later one.

api.storage#

get(key, fallback), set(key, value), remove(key): JSON in localStorage under a per-plugin prefix (scmjs.plugin.<id>.). Safe when storage is unavailable (falls back to memory). The user can see and throw it away — Preferences ▸ General ▸ Browser storage lists your keys as one row under your plugin's id, opening onto the values, with a Clear button of its own, and Clear all data sweeps every scmjs. key — so treat what you store as a convenience, never as the only copy of something, and keep it small and readable.

api.plugin, api.apiVersion, api.log(...)#

Who you are (id, name, source), which API you got, and a console logger with the plugin's name prefixed.