api.events

EventsApi

Listeners are notifications: they run after the change, in the order the plugins were activated, and cannot veto or reorder one another. A listener that rewrites the map in response (through document.sections) simply raises a fresh "document" event with reason "replace", which every other listener sees in turn.

Members

on

on(event: "document", listener: (event: DocumentEvent) => void): Disposable;

// Notifications, in activation order; a listener never intercepts what it hears.
api.events.on("document", (e) => {
  if (e.reason === "open") check(e.fileName);
});
api.events.on("terrain", () => redraw());

on

on(event: PluginEvent, listener: () => void): Disposable;

Types

Declarations only this group names.

Preferencesinterface

interface Preferences

`splash: boolean`	Show the splash while the game data loads; off starts straight on the editor.
`confirmClose: boolean`	Ask before closing or replacing a map with unsaved changes.
`newMap: { tileset: TilesetId; width: number; height: number; }`	What File ▸ New and the startup map start with.
`animateWater: boolean`	Initial View ▸ Animate Water / Animate Units.
`animateUnits: boolean`
`animateWaterSpeed: number`	How fast the two animations run, as a multiple of the game's own speed (1 = the game's "Fastest"). One of `ANIMATION_SPEEDS`; applied live, not just at startup.
`animateUnitsSpeed: number`
`classicText: boolean`	Preview the `<XX>` colour codes in strings the way 1.16.1 drew them: the colour resets at every line break. Off is Remastered's rule, which carries a colour onto the next line — see `editor/textColors.ts`. It changes only what the editor draws, never the map, and every preview in the chrome reads it.
`testMap: { launch: boolean; dir: string; }`	Tools ▸ Test Map: whether to start the game after writing the map (desktop build), and the game folder to use when the desktop build should not search ("" = search). The browser's folder is a handle in IndexedDB (`services/handleStore.ts`), not here.
`updates: { checkOnStart: boolean; nightly: boolean; }`	The desktop build's in-app updates (`editor/updates.ts`, `desktop/updater.ts`); the browser build shows none of this, having nothing to update. `checkOnStart` asks GitHub for a newer version a few seconds after launch and raises a toast when there is one. `nightly` follows the nightly channel instead of the numbered releases — one-way in practice, since going back to a stable release is a downgrade the updater will not offer.

PluginEventtype

type PluginEvent = 
/** A map was opened, closed or replaced. */
"document"
/** Any committed edit (every `document.edit`, stroke, undo and redo bumps it, terrain or not), and a fog edit. */
 | "terrain" | "units" | "doodads" | "locations" | "settings" | "triggers" | "layer"
/** THG2 sprites — the same bump doodad edits make. */
 | "sprites" | "selection"
/** The marked area or the clip on the clipboard changed. */
 | "clipboard"
/** The viewport scrolled, zoomed, or a View menu tick moved. */
 | "view"
/** A map tool or a map pick started or stopped. */
 | "tool"
/** The map's unsaved-changes flag changed. */
 | "modified"
/** A palette's pick changed: terrain brush, unit and owner, sprite, doodad, fog players. */
 | "palette"
/** An editing option moved: symmetry, placement rules, doodad rules, location snap, the fog view player, clip parts and paste mode, locked layers, the grid look, Preferences. */
 | "options"
/** The document's file changed: its name or handle after a Save, the save options, the archive extras, the recent list. */
 | "file"
/** A plugin registered or removed a command — how a plugin learns that one it calls by id has arrived. */
 | "commands";

DocumentChangeReasontype

type DocumentChangeReason = 
/** File ▸ Open, drag-and-drop, `document.open`: a file the user chose. */
"open"
/** File ▸ New (the startup map included). */
 | "new"
/** File ▸ Close: `document.isOpen()` is now false. */
 | "close"
/** The open map parsed again from edited bytes — a `document.sections` write, by any plugin. */
 | "replace";

Why the document changed.

DocumentEventinterface

interface DocumentEvent

`reason: DocumentChangeReason`
`fileName: string \| null`

Seen in

Repairchecking a file on open and repairing it