A library plugin for scmJS, the browser-based StarCraft 1 / Brood War map editor. It connects the editor to scm-sim, the game engine behind the site's play page at scmjs.dev/play.
It adds two commands: Test in Browser, which plays the open map on the play page in a tab of its own, and Debug Triggers in Browser, which plays it under the map and shows what its triggers do. Everything else is for other plugins. They use it to:
- play a replay to its end without showing it, and get back what happened in it;
- start a map on the play page;
- work out a map's pathing as the game walks it;
- measure groups through chokes and each base's mining;
- play a replay's fights again;
- show a replay inside the editor with the game's own graphics.
The plugin holds no engine. The engine is a separate program served beside the editor, and the plugin talks to it by message inside your browser. A replay or a map handed over is not stored and not sent anywhere.
scm-sim comes with the editor and starts on. If you removed it, open Plugins ▸ Manage Plugins…, paste
https://github.com/scm-js/plugin-scm-sim
and press Add. A plugin that needs scm-sim names it in its own manifest, and the editor installs both together:
{ "requires": ["github:scm-js/plugin-scm-sim"] }It works only where the editor is served beside the play page: at scmjs.dev/editor, or on a stand-in for the site on your own machine. In the desktop app, or an editor hosted somewhere else, the service is there but says it is not present. A plugin that uses it should then fall back to what it can do without it.
The engine runs the game from your own copy of StarCraft. If the browser has none, give the site your game on the Game Data page. Edit ▸ Preferences ▸ Plugins ▸ scm-sim says whether the engine can run a game now.
Tools ▸ Test in Browser plays the open map on the play page, as Save would write it. Testing again sends the new version to the same tab. On Edit ▸ Preferences ▸ Testing, Send the map to chooses between this and StarCraft for Tools ▸ Test Map, Ctrl+F5 and the toolbar's Test button; at scmjs.dev it is this one until you choose. How the map is played is set on the same page:
- Game type: From the map (the default), Use Map Settings, Melee, or Choose on the play page. From the map plays Use Map Settings when the map has computer players or units placed beyond the start locations, and melee otherwise.
- Your race, and your slot for Use Map Settings.
- For melee, the number of computer players and their race.
The user guide has more on each setting. An editor from before 0.8.6 has no Send the map to: there the item is Tools ▸ Test Map in Browser, and its settings are under Edit ▸ Preferences ▸ Plugins ▸ scm-sim.
Tools ▸ Debug Triggers in Browser plays the open map, as Save would write it, in a panel under the map, always with Use Map Settings (a melee game runs the game's own melee triggers, not the map's). You play it there as on the play page. Beside the game:
- Pause / Play, Step Frame, Next Pass (on to the next time the game runs the triggers) and Previous Pass (back to the one before). Going back replays your own orders, so stepping forward again comes to the same game; giving a new order after going back plays on from there instead.
- A timeline with a column for each pass of the triggers: how many fired (green), were held at an action such as a Wait (amber), or stopped at a condition (grey). Click a column to see that pass.
- The triggers of the selected pass, each with what happened to it: fired, held at action 2 (Wait), condition 3 did not hold (Bring), went on from an earlier pass and finished. The game stops asking a trigger's conditions at the first that does not hold, so that is the one named. Click one to open it in the Trigger Editor. Triggers a build step added, such as a TrigScript program's, are listed but have no row of their own to open.
Run the command again to rebuild the map and start over in the same panel. It needs a play page from the same release or later; an older one plays the map and sends nothing back, and the panel says so.
Copy contract.d.ts into your plugin and import it as types only. It has
every type and option, with comments. This section is an overview.
import type { ScmSimService } from "./vendor/scm-sim";
api.services.watch<ScmSimService>("scm-sim.engine", (sim) => {
if (!sim?.present) return; // no engine beside this editor: do without
button.onclick = async () => {
const status = await sim.status();
if (!status.available) { api.ui.status(status.reason ?? ""); return; }
const timeline = await sim.analyse(replayBytes, {
onProgress: (p) => bar.set(p.frames ? p.frame / p.frames : 0),
signal: controller.signal,
});
// timeline.events, timeline.samples, timeline.positions
};
});Some methods came in later versions of the plugin or need a newer play page. Each section below says what to check before offering one.
Asks the engine whether it can run a game now. available is false, with a reason in
words, when the browser has no copy of StarCraft or the engine's page did not answer.
features (since 0.17.0) lists what the site's play page does that a page from before did
not, as its pages say it: "replayDoor" (a replay's mod is read from the file and played,
switched to or asked for) and "liveSwitch" (a replay of a mod whose code ran loads the page
again with ?lift=live instead of refusing). From the analysis page it can also hold
"modAnalysis" (since 0.18.0): analyse and fights play a replay of a mod with that mod.
"modFiles" (since 0.19.0) means the pages say which mods the browser keeps (mods: the
hashes it keeps, and the one it plays), take a mod's files with a replay when they do not keep
it, and say why they could not do something in a word as well as a sentence (see
Mods the engine has not got). "races" (since 0.20.0) means a
race is a number to the pages and a mod may name the races it adds: see
Races a mod adds. It is empty for an older page.
replay is a whole .rep file. A twenty-minute game takes about ten to fifteen seconds. One
replay runs at a time, and further calls wait their turn. The engine uses about a gigabyte of
memory while it runs and gives it back when the replay ends.
If the engine's page loads again before it answers (since 0.19.2), the replay is handed to the
new page and its progress starts over at starting. When the page loads again more than twice
with it waiting, the promise rejects with a sentence that says so. The same goes for
pathing, measure, test, testCopies and fights. A debugger's session whose game was on
that page is over, as if closed.
The answer is a ReplayTimeline:
| Field | What it holds |
|---|---|
events |
One entry each time a unit is born, done (finished), morphs into another type, is given to another player, or died. Each has the frame, the unit's number, its type, owner and place in pixels. A died event also names the unit credited with the kill (by, byType, byOwner, byX, byY) where the game credited one. |
research |
Upgrades and technologies as they finish, per player. |
samples |
Every 48 frames by default (two seconds at Fastest): each player's minerals, gas, supply used and available, finished workers, army size, army cost and finished buildings. |
positions |
At the same frames, where every unit stood. Buildings and units inside a transport or bunker are left out. Typed arrays: start[i] to start[i + 1] are the rows of sample i. |
sight |
When each player could see each unit of the other players, as the game decides it: fog hides a unit, and a cloaked or burrowed unit is seen only by players who detect it. Each row is one stretch: a unit, the player who saw it, the frames from and to, and by, the player's unit nearest to having it in sight (or 0xFFFFFFFF). The game does not record which unit sees what, so by is the likeliest seer. Typed arrays. From timeline version 5 (scm-sim 0.11.0). |
players, map, frames, total, ended |
The players as the replay names them, the map's size in tiles, how far the game was played and how it stopped. |
check |
Whether the game the engine played stayed the game in the replay. parted is null when it did. Otherwise it is the frame from which the timeline no longer matches what happened. See Replays it can play. |
sampleEvery and positionsEvery change the two intervals. positionsEvery: 0 leaves the
positions out.
A replay of a mod (since 0.18.0, when status().features has "modAnalysis"): the engine
plays it with the mod, as the play page does. A replay the play page saved names its mod
itself, and the page reads that first. For one that does not, pass the mod as
options.dataSet, the same { hash, name?, url?, live? } that playReplay takes (files is
never sent). The page plays it with the mod this browser keeps under that hash, which a
person adds once on the play page (Game Menu ▸ Mods ▸ Add a Mod…), and runs the mod's
plugins where the replay's game ran them. The timeline's mod then says what it played
with: { hash, name, plugins, lifter }, the plugins by file name in the order they loaded.
When the browser has not got the mod, or keeps another version of it, the promise rejects
with a sentence that names the mod, its hash and its makers' page. A replay of a mod whose
plugins run takes about 17 seconds to start, then plays at 30 to 40 game frames a second (a
twenty-minute game takes over ten minutes), and uses about 2 GB of memory, given back when
the replay ends. A page from before 0.18.0's engine plays such a replay with the game's own
files or refuses it, so check features first. Since 0.19.0 the mod's files go with the
replay when the page has not got the mod and they can be found, and the page keeps them
first: see Mods the engine has not got.
A unit's number is the timeline's own. It is counted from 0 in the order units appear and stays with the unit for its whole life. When reading the events:
- A Zerg unit is a chain of morphs: a larva is born, morphs into an egg, the egg morphs into the unit, and then it is done. A drone morphs into the building it becomes.
- A refinery, extractor or assimilator is a morph of the geyser it stands on.
- A player who leaves gives every unit to a neutral player. These are
givenevents. - A kill is the game's own credit: a reaver gets its scarab's kills, a carrier its interceptors'. Scarabs and spider mines that go off are deaths with no killer, and so is what a spider mine killed. When several units fall in the same instant, the pairing of killer and victim is the likeliest one.
Starts a map on the play page in a tab of its own. The next call uses the same tab. Leave
map out to play the open map as Save would write it. It is played as the plugin's
preferences say. With Choose on the play page, it resolves when the map is on the setup
screen. Otherwise it resolves when the game is on the page.
Call it from the click that asks for it, because a browser only lets a click open a tab.
Opens a replay on the play page, in the same tab as play, at frame at.frame and through
the eyes of at.player (a replay player's slot). The page pauses there with its Watch Replay
menu open, so the person can play on from that moment: alone, against a community bot, or
with others. replay is a whole .rep file. It resolves when the replay is on the page.
Added in 0.15.0, so check that it is there before offering it. A play page from before it
answers "No map came with the request."
replay.dataSet (since 0.16.0) names the mod the replay was played with: { hash, name?, url?, files? }, with hash the 16 hex digits the play page names the mod by, url its
makers' page and files the mod's files under the game's paths ({ path, bytes }), when
the editor has them. A replay saved on the play page says its mod itself, in an SCMJ
section (Replay.mod in @scm-js/replay), and the page reads that first, so dataSet
matters for a replay whose file does not say. The page then:
- plays it with the mod it keeps under that hash, switching to it (the page loads again, and is handed the replay again);
- keeps
filesas a dropped mod and plays it with that, when it has not got the mod; - otherwise says which mod the replay needs and where
urlpublishes it.
A mod of the same name kept under another hash is refused, with both hashes: the replay is
never played with other files than its own. null means the game's own data. A play page
from before 0.16.0 ignores the field.
replay.dataSet.live (since 0.17.0) says the mod's code ran in the replay's game: its
plugins ran, or its FireGraft project's exe edits were written. The play page runs those only
with ?lift=live in its address, so the tab opens there (a tab already open without it is
sent there first, its other parameters kept). For a replay saved on the play page, set it when
the SCMJ tag's plugins is not empty, or when it names a firegraft project and its
engine.lifter is not "shipped". A play page from scm-sim's R2b on also loads itself again
with ?lift=live when a replay needs it and live was not said; an older one refuses in a
sentence.
Call it from the click that asks for it.
Since 0.7.0. Check that pathing exists and that status().pathing is a number (it is null
on an older play page).
The game's own pathing for a map. Leave scenario out for the open map, or pass a bare
scenario (.chk bytes). Nothing is shown and nobody plays. The engine starts the map on a
copy made for the purpose, with a neutral Nexus on every start location, the test units and
none of the map's triggers, and gives the units move orders. A StarEdit copy of the game is
enough for it.
The answer is a PathingResult:
| Field | What it holds |
|---|---|
regions |
The regions the game divides the map into when it loads it, which it plans ground routes over. grid holds a region id for every 8 × 8 px cell. Per region: whether it is walkable, its group (ground of one group is joined), its centre, its size in tiles and its neighbours. Typed arrays. |
walks |
One per unit and pair of places: the unit type, from and to (and the start locations' slots), the outcome, the frames it took (24 a second at Fastest), the pixels it travelled, how far from to it ended, how many regions it crossed, and its route (x, y every every frames). |
starts, map |
The map's start locations and its size in tiles. |
outcome is one of:
arrived.stopped: it stopped short. The game found no way all the way there, or gave up on a long route.stuck: it stood still for ten seconds while still meaning to move.limit: still walking whenlimitran out.apart: not walked, because the two places are on ground that does not join.unmoved.
By default it walks a Probe, Zergling, Dragoon, Siege Tank and Ultralisk from each start location to every later one. Each start location walked from is a game of its own, a few seconds each. A 4-player map takes about eight seconds, an 8-player map about forty. Options:
units: other ground units (units.dat ids).directed: walk both ways between two start locations.fromandto: walk between your own points instead of the start locations.regions: false: leave the regions out.limitandevery: the frames a walk may take, and how often its position is kept.signalandonProgress: as foranalyse.
Since 0.8.0. Check that measure exists and that status().measure is a number.
Measures of a map taken by the game itself. Leave scenario out for the open map, or pass a
bare scenario. As with pathing, nothing is shown, nobody plays, and a StarEdit copy of the
game is enough.
- Groups (
groups):countunits of a type (at most 12, one selection) are made atfrom. The one nearesttowalks there alone, then the whole group walks there together. Each is timed as it gets through: two tiles past the middle of the way, which is the choke whenfromandtoare its two ends. You get the frames for the one alone (alone), for the first and last of the group (first,last), and how many got through or got stuck.last − aloneis the time the group spent queueing. Groups near each other run in separate games, so an idle group never blocks another. - Bases (
bases, andstarts: truefor every start location): a Nexus on the hall spot and 24 Probes a few tiles away. For each worker count (workers, default 8, 16 and 24), that many Probes go to the base's mineral fields, nearest first. After 25 seconds, the minerals taken from the base's own fields are counted for two game minutes. The result isperMinuteat each count. A spot the game will not take a Nexus on is reported (hallMade: false). Gas is not measured, because a trigger cannot build an Assimilator.
A 4-player map's start locations plus two groups take about ten seconds.
Since 0.13.0, and only where the play page answers them: check status().tests and
status().copies. TrigScript uses these to run a script's tests in the game itself.
test starts the map as Save builds it (a whole .scx) in the game, with EUD allowed and
nothing drawn. It then imports module, the text of an ES module, and calls its
runGameTests(game, payload). The promise resolves with what that returns. The module
runs with the play page's rights, so the page takes it only from an editor on the same
site.
testCopies is for a test of several players. It runs one copy of the game for each slot
in options.players, each copy seated as that player. The copies are kept in step as in a
real multiplayer game: each frame, every copy's commands reach all of them. Each copy
calls the module's drive(game, payload). Through game.copy, a test can read what every
player was shown, and can find the frame at which the copies stopped agreeing (a desync),
with the lines that caused it when options.triggers gives the build's map of triggers.
You get back one answer per copy, in the order of players. Each copy uses about a
gigabyte of memory. The copies share memory with each other, which Chrome and Edge allow on
the play page from version 137. On other browsers status().copies is null.
Since 0.11.0. Check that fights exists and that status().fights is a number.
Plays a replay's fights again in the game, from just before each. Pass the whole replay
file, and for each fight its frames (from, the first loss, and to, the last) and the box
around what fell, in pixels, as your own analysis found them. Each fight is played in two
versions, measured the same way so they compare:
played: the replay's own commands, as recorded.attackMove: the units that can attack, and the Medics, attack-move to the middle of the box. Nobody gives any other command anywhere until the fight ends. Production already queued finishes and walks to its rally point, and nothing new is started.
Ask for versions: ["played", "attackMove", "handsOff"] to add a version with no commands
at all.
The game decides which units took part: every unit of the sides that came into the box while the fight was played, wherever it stood at the start. For each side you get:
- those units and their cost;
- the ones dead at the end, and their cost;
- the cost of what the side has inside the box at the end, units that arrived later included.
The replay is played once from its start and stops at each fight. That takes about as long
as analyse takes to reach the last fight, plus a second or two per fight. Two fights late
in a 22-minute game take about eleven seconds.
A replay of a mod is played with its mod as analyse plays it (since 0.18.0): pass the same
options.dataSet, and the answer's mod says what it played with. While the mod's plugins
run, the page rejects fights in a sentence: playing a fight again puts the game back to an
earlier moment, which the engine cannot do yet with a mod's plugins.
Since 0.5.0. Check that view exists before calling it.
The game itself, drawn inside an element of yours and filling it. It plays a replay with the
game's own graphics (Remastered's, where the person's copy has them), and you drive it. The
engine takes about a gigabyte of memory, so keep one view and load replays into it in turn.
Inside the editor, put the element in api.ui.mapView. That element is never moved, so the
game does not restart when the person switches to the map and back.
const view = sim.view(element);
const ready = await view.ready; // { files, reason, features }: reason says why when files is null
const replay = await view.load(bytes, "game.rep"); // paused at frame 0
const modded = await view.load(bytes, "mod.rep", { hash: "ac3f86533e4b5a31", live: true }); // a mod's replay (0.17.0)
view.speed(4); view.play(true);
view.onFrame(({ frame, playing }) => timeline.move(frame));
view.onCamera(({ x, y, byUser }) => { if (byUser) stopFollowing(); });
view.seek(12000); // quick backwards too, when replay.rewinds
await view.options({ remastered: true, lighting: false, fog: false });
view.dispose();A replay of a mod (since 0.17.0): pass the mod as load's third argument, as playReplay
takes it (hash and live are used). The view's page plays a mod only when its address names
it, and never switches to another, so the view loads at ?view&mod=<hash> (with
&lift=live when live) before the replay goes in, and back at ?view for a replay with no
mod. The page plays the mod it keeps under that hash. Older pages ignore the mod.
Since 0.19.0, when the page has not got the mod, its files go with the replay (the data set's
own files, or the mod registered under its hash with provideMod). The page keeps them,
which takes a minute or two for a large mod with plugins (onKeeping gives its progress
lines to show meanwhile), loads itself again on the mod and plays the replay. With no files to
hand, the load rejects with reason "mod-missing": the view never plays such a replay with
StarCraft's own data instead.
The rest of the view, in short (contract.d.ts has the details):
camera(x, y, height?)looks at a point of the map, in pixels.height(since 0.6.0) is how much of the map shows top to bottom, from 240 to 1920 pixels (960 before 0.9.0). It works only while the console is hidden, which it is unless you ask foroptions({ console: true }).loadanswers with the replay'sname,frames,playersandmap, itslooks,followsandrewinds(whether a seek back is quick). Since 0.19.2 it also saysslow: truefor a replay that runs ahead slowly because a mod's plugins run (about 60 frames a second): even a seek back takes a while there, so send a drag's seeks sparingly, one when it ends.- Since 0.20.0,
loadalso saysraceswhere the replay's mod declares races of its own (see Races a mod adds). A player'sraceis always the byte the replay holds. onFramegives the frame shown, whether it plays, and while a seek runs,seeking. Since 0.19.2 it also givestarget, the frame a seek (or a restart's run) is going to, while one is under way; a page from before leaves it out.follow(track)(since 0.6.0) moves the camera along a path for the whole game, in step with the frames the game draws. Use it for a smooth camera: frame reports come only ten times a second. Checkfollowson the loaded replay first.player(slot)picks whose eyes the fog is drawn through.onUnitsgives the squares the game's minimap would draw, up to eight times a second, and with the fog on, the fog per tile (0 never seen, 1 seen before, 2 seen now).onHover(since 0.6.0) gives the unit under the pointer, for a tooltip of your own.onKeygives the keys the game does not use (all but the arrows). Each is also pressed again on the editor's window, so the editor's and other plugins' hotkeys still work.onWheel(since 0.9.0) gives the wheel over the view. Hand it to the editor's map view (view.wheel(w)) and the game zooms the way the map does.onPointer(since 0.10.0) gives the map pixel under the pointer, for the editor's status bar (view.setPointer(p)).
With a page whose ready features have "ownScreen", the view can show the game's whole
screen as the game draws it: its map, console, minimap and replay panel, and a mod's own
interface, at the mod's own size, fitted into the element with bars. The page offers it where
the replay's game runs the game's own code, which a replay of a mod whose code ran always does,
and turns it on by itself for such a replay.
- The looks (
load's, and every answer tooptions) sayownScreen, whether the replay loaded can be shown so, andownScreenOn, whether it is. A page from before says neither. onLookshears every looks the page says, including the ones it says by itself when the game's own screen stops. Check that it exists: older versions of this plugin lack it.options({ ownScreen: false })goes back to the page's own drawing,trueasks for the game's own screen, andnullleaves it to the page again. The choice holds for the replays loaded after it, and the view tells it again to the page whenever the page loads again.
While it is on, the pointer and the wheel over the view are the game's; the keys are still
handed back (onKey). onHover and onPointer say null and onWheel says nothing. The
fog and player change nothing in the picture, the height of camera waits until it is
off, and onCamera's width and height are the map the game's screen shows at one to one (a
mod that draws the world at its own scale shows less of it). Anything drawn over the view at
map positions lands in the wrong place. Play, speed, seek, the camera, tracks, the minimap's
squares, sounds and music work as before.
Since 0.19.0, with a page whose features has "modFiles".
A plugin that has a mod open registers it once, under the hash the editor's data set names it
by, and everything that plays with that hash finds its files there: the game view,
playReplay, Test in Browser, analyse and fights.
const sim = api.services.get<ScmSimService>("scm-sim", "engine");
const provided = sim?.provideMod?.(hash, {
name: "Cosmonarchy BW",
files: async () => gatherFiles(), // [{ path, file }] or [{ path, bytes }]
});
// when the mod closes, or before registering again under a new hash:
provided?.dispose();files is called only when a page says it does not keep the mod, because gathering a large
mod's files is not free. Paths are the game's (arr/units.dat), or the paths inside the mod's
folder (Cosmonarchy/mpq/arr/units.dat, Cosmonarchy/plugins/gptp.qdp): the page reads a
folder's layout as it reads a folder dropped on it. The page keeps the mod as it keeps a
dropped one, under the hash it works out itself, and also answers to the hash it was handed
it by when the two differ. Every page of the site keeps mods in the same place, so a mod is
kept once: while one page keeps it, another request for it waits, then goes without files.
The wait is for the keeping alone (since 0.19.1): an analysis that keeps the mod goes on to
play the whole replay, and the game view of the same replay loads as soon as the mod is kept,
not when the analysis ends. While it waits, the view says how far the keeping is
(onKeeping), as it does when it keeps the mod itself.
A caller's own dataSet.files (a list, or a function returning one) come before the
registered mod.
When a page cannot do something, the promise rejects with an Error worded for the person.
From 0.19.0 it may also carry reason (ScmSimError in contract.d.ts):
reason |
What it means |
|---|---|
"mod-missing" |
It is to be played with a mod this browser does not keep, and no files came. hash names the mod. |
"mod-terrain" |
The map is on terrain StarCraft has not got, neither 1.16.1 nor Remastered. It was made for a mod and plays with that mod's files, or the mod played lacks it too (another mod, or another version of it). |
"remastered-terrain" |
The map is on terrain only StarCraft: Remastered has. A copy of the game made from a Remastered installation plays it. |
A page from before says no reason.
Since 0.20.0, with a page whose features has "races".
A race is a number. 0 to 7 are the game's own (0 Zerg, 1 Terran, 2 Protoss, 6 Random, and so
on); a mod may add others, such as a fourth playable race whose players' records hold 69. The
pages pass that byte through unchanged: a replay's players say 69, and a race nothing names
reads "Race 69".
A data set may name the races it adds, beside its name and never in its hashed files, so naming
a race does not change the mod's hash. Pass them as races on any dataSet (analyse,
fights, view().load, playReplay, and the mod of scm-sim.live's play), and the Test in
Browser hand-over passes the editor's data set's own (what the editor keeps for it, or
GameDataProfile.races, where the editor has them):
await sim.analyse(bytes, {
dataSet: { hash, live: true, races: [{ id: 69, name: "Askosi", letter: "a", like: 1 }] },
});id is 8 to 255, name 1 to 40 characters; letter is the letter of the race's own files
(game\aconsole.pcx) and like the game's race it plays as (0, 1 or 2), each where known. A
row that is not valid is left out, not refused. The page keeps the table with the mod, names
the players of the view's list by it, and says it back: the loaded replay's races, and
ReplayTimeline.mod.races. A page from before ignores it.
Since 0.20.1, an empty list is passed on as it is: it says the data set adds no races, so a page
that kept names for the mod from before can drop them (a page that does not read it yet keeps
them, as it does when nothing is said). No races at all says nothing about them. The Test in
Browser hand-over sends an empty list when the editor keeps race names for its data set and has
none (the names were cleared, say), and no field from an editor that cannot keep race names.
A second service, for a mod changed while a test game runs (the Mod Editor uses it). Its shape is ScmSimLiveService
in contract.d.ts; reach it with api.services.watch<ScmSimLiveService>("scm-sim.live", …).
play({ map, mod: { name, hash, files }, useMapSettings? })hands the mod's files (those that differ from the game's, by the game's paths) and a map to the play page's tab — the same tabplayuses. The page keeps the files as a mod dropped on it would be, loads again with it and starts the map. Withmapnull it only shows the mod. Call it from a click.playing()says whether a game played alone runs in the tab now;state()says more (the frame, the mod, the files waiting for a start), andonState(listener)hears it whenever a game starts there.patch(fields, files)sends changes into the running game. A field is{ table, id, field, part?, value }in PyMS's names, as the file stores it (hit points in 256ths); a file is{ path, bytes }by the game's path. The answer lists each item asapplied(written into the game between two turns, a picture loaded and drawn, a graft's buttons or requirements written),deferred(kept, and taken at the next start: animation scripts, the sound table, strings and everything else the game reads once) or inerrorswith the reason. A game between people refuses every item.grafts()reads the running game's button sets and requirement lists as.graftfiles, for a mod that has none.
The engine runs StarCraft 1.16.1's own game code. A replay written by 1.16.1 is played as it is. A replay written by 1.18 or StarCraft: Remastered is first rewritten in 1.16.1's form, inside the browser, and then played the same way.
Two kinds of Remastered game cannot be played, and analyse rejects with a message that
says which:
- A map on Remastered's terrain, with a copy of StarCraft from 1.16.1. Remastered added tiles to seven of the eight tilesets, and its ladder maps use them. Such a replay plays only when the browser's copy of StarCraft was made from a Remastered installation.
- A game that held more than 1,700 units at once. Remastered raised that limit, and 1.16.1's game has no room for the rest.
A replay holds only the players' commands, with no record of the game to compare against.
So the engine checks each command as it runs. A command for a unit the game has not made yet
means the game being played has drifted from the one recorded. check.parted is the frame
of the first such command, or null. It has been null to the last frame in every 1.16.1 and
Remastered replay tried so far. A game that passes one of 1.16.1's other limits (100 bullets
in the air, 2,500 sprites) would drift there, and parted shows where.
npm install
npm run typecheck
npm test
npm run build # dist/plugin.js, the bundle the editor loads
The messages exchanged with the engine's pages are listed at the top of src/bridge.ts
(replay analysis) and src/play.ts (playing a map). The timeline types in contract.d.ts
are a copy of the engine's own. ReplayTimeline.version says which form a timeline has.
MIT. The engine itself is not part of this repository.