Plugins

Writing one, the shape of the API, and a tour of the plugins the editor ships with.

scmJS loads third-party code — a plugin — from a public Git repository or any URL, and lets it add menu items, context-menu entries, hotkeys, dialogs, floating panels, map tools and overlays, read the open map and edit it through the same undo model the built-in tools use. This document is the plugin author's guide; Host side (for editor developers) near the end is the editor's half of it, and every call is also generated into a page at docs.scmjs.dev/api.

Nine plugins are written against exactly this API, each in its own repository, and they are the worked examples for everything below — there is a section on each at the end. Nothing about them is privileged: the versions that ship are pinned and compiled into the build, so a fresh install needs no network, but a plugin you write takes the same path through the same loader.

• How a plugin worksA plugin is one TypeScript (or JavaScript) file with an activate(api) export, sitting in a public repository next to a plugin.json.
• Writing a pluginplugin.json:
• The API, group by groupThe 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.
• Host side (for editor developers)Contribution points read the registries: MenuBar merges pluginMenuItemsAtom into its menu model (withPluginItems), MapViewport and TerrainPalette append the matching pluginContextItemsAto…
• Terrain from Imagescm-js/plugin-image-to-terrain, installed by default — File ▸ Import ▸ Terrain from Image…, and on the terrain palette's and the map's context menus *Terrain from Image…* (into the marked…
• Paintscm-js/plugin-paint, a default — Tools ▸ Paint…, Ctrl+Shift+P, or *Paint…* on the map's right-click menu then opens a panel that floats over the map (api.ui.panel).
• scmscx.comscm-js/plugin-scm-scx, a default that starts on, is the editor's one network plugin: File ▸ Find on scmscx.com… searches the StarCraft map archive at scmscx.com and opens the map you pick…
• Section Explorerscm-js/plugin-section-explorer, installed from Plugins ▸ Browse Plugins…, is the worked example for api.document.sections and api.names: Tools ▸ Section Explorer… (Ctrl+Shift+H) is a hex …
• Walkabilityscm-js/plugin-walkability, a default that starts on, is the worked example for a read-only analysis drawn over the map: Tools ▸ Walkability… (Ctrl+Shift+W) reads every tile's sixteen VF4 …
• Melee Wizardscm-js/plugin-melee-wizard, installed from Browse Plugins, is the worked example for placeUnit / canPlaceUnit / updateUnits inside one document.edit, and for a map tool whose press-and-dr…
• Repairscm-js/plugin-repair, a default that starts on, is the worked example for the "document" event's payload, document.sections's defaults / rebuild / trailing / required, and tx.rebuildIsom.
• Trigger Scriptscm-js/plugin-trigger-script, installed from Browse Plugins, is the Script Editor: a TypeScript-subset language kept as a file inside the map (scmjs\triggers.ts, with a build manifest in …
• AIscm-js/plugin-ai, not a default, is the worked example for calling another plugin's commands, api.document.create and a plugin's own submenu, and the first plugin that needs a server: scm…