Skip to content

Auto-mining, auto-restore and its right-click toggle (trigscript/workers, spells and card), in one PR - #96

Merged
jeany55 merged 13 commits into
scm-js:mainfrom
mstephenhunt:auto-restore-toggle
Nov 15, 2026
Merged

jeany55 merged 13 commits into
scm-js:mainfrom
mstephenhunt:auto-restore-toggle

Conversation

@mstephenhunt

@mstephenhunt mstephenhunt commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

This branch now carries all of my open TrigScript work in one place, so it can be reviewed and merged as one PR. It includes the commits of #88 (auto-mining), #92 (Brood War research tables), #93 (auto-restore) and #95 (the simulator camera), plus the right-click toggle that is new here. Those PRs are closed in favor of this one; their descriptions have the full detail of each part; this one summarizes them.

Fixes #91. Fixes #94.

Why

I'm building single-player campaign maps, and I want common behaviors to come as one-line TrigScript library calls instead of a program each map maker has to write:

  • Workers that mine on their own when their building is rallied to a mineral field or a gas building. In Brood War a rallied worker walks there and stands idle.
  • Medics that restore on their own, the way they already heal on their own, when Lockdown, Irradiate, Plague, Ensnare, Maelstrom, Acid Spores or Optical Flare lands on their own or an ally's unit.
  • Turning auto-restore off and on by right-clicking the Restore button, the way an auto-cast ability works in StarCraft II. The game has no notion of a right-click on a card button, so this adds a small library piece that detects one.

Along the way, stats(P).researched turned out to read the wrong row for every Brood War tech (#91), and the simulator's camera never moved on Center View (#94), which the toggle's tests needed.

What changes

Auto-mining (#88)

  • buildAutoMiningProgram() in trigscript/workers. For every human player, a newly trained SCV or Probe, or a Drone hatched from a Larva, starts gathering when its producer's rally point is on a mineral field or on a finished gas building of its own player. Anything else is left as the game leaves it. It acts once, as the worker comes out, so a later order stands. A second call adds nothing.
  • u.gather(target) gives a worker the order a right-click would: MoveToMinerals or MoveToGas.
  • u.orderTarget, u.orderTargetX, u.orderTargetY: new read-only fields the library uses to tell a rally onto a patch from one onto a gas building.

Brood War research tables (#92)

  • stats(P).researched and .upgrades read Brood War's own rows. The game keeps Brood War's techs (ids 24–43) and upgrades (ids 46–60) in separate tables, 0x58F140 and 0x58F32C. stats(P1).researched[techs.Restoration] used to read Player 2's Stim Packs.
  • The simulator keys a table cell by its row's base too, so Restoration and Stim Packs stay separate cells.

Auto-restore (#93)

  • buildAutoRestoreProgram(options?) in a new trigscript/spells module. An idle Medic of a human player, or one healing on its own, casts a real Restoration on the nearest afflicted unit of its owner or an ally within range. The owner must have researched Restoration, and the Medic needs the energy plus keepEnergy (default 0). switch names a map switch that gates the program. One Medic goes to each unit, and a Medic on a player command is never used.
  • New language pieces: u.cast(tech, target) (Restoration only), u.stop(), u.distanceTo(other) measured as the game measures a spell's range, the read-only fields u.opticalFlare, u.acidSpores, u.orderState and u.queuedOrders, and stats(P).allied[Q].

The simulator camera (#95)

  • Center View moves the simulated camera: to the location's center minus 320, 240, snapped down to a multiple of 8 and kept on the map (at most 648 px short of the right edge and 488 short of the bottom, as played in Remastered with Classic graphics).
  • A placed mouse stays on the screen, so local.mouse reads the same before and after.
  • TestWorld.mapSize (tiles) gives the simulator the map's size. Without it the simulator assumes 128 × 128.

The right-click toggle (new in this PR)

  • trigscript/card (new): CardButton(tech, slot) with begin() and rightClicked(), cardSlots (the nine positions plus each ability's default; cardSlots.Restoration is the bottom middle) and cardSetup({ afterCalibration, showMeasurements }). It compares where the mouse was when the right button went down against where the button is drawn, only while the card shows that ability's units' buttons (Medic buttons, set 34, for Restoration). Single-player maps.
  • Which graphics are on: the card sits against the right edge of the drawn game. That edge is 640 wide in Classic graphics and as wide as the display's shape in Remastered graphics, and no readable address says which is on. At the start it centers the view on the map's middle, waits for the camera to settle, reads where it stopped and sends the view back. afterCalibration runs instead of the send-back, for maps that open on a cinematic. Minimap clicks, and the camera going further right than Remastered allows, keep it current after a mid-game switch.
  • Real-game shape: each step runs in its own pass of the caller's loop, and the only awaits are sync()s followed by assignments. In Remastered, a Center View after an await in the same branch, or in a start() task, locked the view.
  • buildAutoRestoreProgram({ allowPlayersToTurnOffAutoCast: true }): a right-click on a Medic's Restore button turns auto-restore off for that player, and another turns it back on, with "Auto-restore off" / "Auto-restore on" shown to that player. It starts on, and while the map's switch is off the right-click is ignored. Without the option, auto-restore behaves as in trigscript/spells: buildAutoRestoreProgram(), Medics that restore on their own #93.
  • Three Local fields: local.mouse.buttons (0x6CDDC0), local.card.buttonSet (0x68C14C) and local.screen.width (0x6CEFF0), with simulator values and ledger scripts.

Testing

  • On the combined branch: npm run typecheck is clean, and npm test passed 1474, with 9 skipped. One earlier run on a loaded machine had 16 failures; the rerun passed in full.
  • Auto-mining: emitter and standard-library tests, including a second call in the same file or another file. In scmjs map trace, staged SCVs, Probes and Drones reach MiningMinerals or HarvestGas, and rallies on ground, an unfinished gas building, another player's gas building or a bare geyser leave the worker alone. Played in Remastered as a hand-written map script before it became a library. The library form itself hasn't been played.
  • Research tables: a new test decodes the Set Deaths each write emits (P1 Restoration → 0x58F140, P12 Restoration → 0x58F140 + 220, P3 Caduceus Reactor → 0x58F32C + 35). It fails on main. The tables haven't been read or written in a played Remastered game yet.
  • Auto-restore: emitter tests for each language piece, standard-library tests, and the spec's acceptance checks in scmjs map trace: the seven effects, every gate, the switch, one Medic per unit, nearest target first, Medics on player commands keeping their orders, mid-heal, and a target leaving range. scmjs map cost over 3,000 frames: 0.011 ms a frame with the switch clear, 0.67 ms average (4.68 ms peak) with every Marine re-ensnared each second. Playing the Remastered test map is still to do.
  • Simulator camera: a new test in tests/testing.test.ts fails on main (middle 0, 0 / corner 0, 0) and passes here.
  • The toggle: new simulator tests for the hit test and the card check, afterCalibration, the toggle turning off and on, the switch being off, and the program without the option. Played in StarCraft: Remastered on a Mac, single player: the startup measurement detected Remastered graphics, right-clicks on Restore toggled it off and on, and right-clicks on Optical Flare didn't. After switching to Classic graphics mid-game, the mode was detected again and Restore toggled at its Classic position. Not played yet: a Marine or mixed selection, the targeting cursor, the switch turned off, and a Medic casting after being turned back on (covered by the simulator tests).

Related

mstephenhunt and others added 12 commits November 11, 2026 06:39
…m a gas building

A right-click's order, written to the worker: MoveToMinerals (85) for a mineral field, MoveToGas (81) for a
gas building, order state 0 and the order target. Three read-only fields go with it, u.orderTarget and
u.orderTargetX / u.orderTargetY, so a program can see where a just-trained worker is headed (a rally on a
patch gives Move to the patch's centre; one on the player's own gas building gives Follow with that target).

Played in StarCraft: Remastered: rallied SCVs, Probes and Drones mine and gather gas.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
import { autoMining } from "trigscript/workers"; autoMining(); at the top of a script. From then on, a human
player's new SCV, Probe or Drone whose producer is rallied to a mineral patch mines it, and one rallied to the
player's own finished gas building gathers from it; anywhere else it walks to the rally as before. It acts once, as
the worker comes out, and leaves computer players' workers and Create Unit's alone. The module is TrigScript, on
u.gather() and u.orderTarget / orderTargetX / orderTargetY.

It is on for the whole game, so it is called once, by its name, as a statement of its own at the top of a script. A
standard-library function tagged @topLevelOnce is held to that when the script is built: every reference to it is
checked, so a call inside program(), a listener, a function or an if, an alias (const f = autoMining) or passing it
as a value, or a second call, is an error at that reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ce check

Drops the compiler check (topLevelOnceErrors in hoist.ts, its call in compiler.ts and its note in docs/compiler.md)
and the @topLevelOnce tag. autoMining() keeps a flag at the top of workers.ts instead: a call after the first returns
without setting up a second listener. The script's modules run fresh on every build, so the flag starts false each
time, and every file of one build shares it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The call makes a program, and programs are made when the map is built, so it belongs at the top of a script; the name
says so. The JSDoc moves from the module's flag onto the function, where an editor's hover finds it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The game keeps Brood War's techs (ids 24-43) and upgrades (ids 46-60) in tables of
their own, 20 and 15 a player wide. stats() had one table for each, 24 and 46 wide,
so P1's Restoration was P2's Stim Packs, and P12's ran past the table. A Brood War
key now lands in its row of techResearchedBW (0x58F140) or currentUpgradeLevelBW
(0x58F32C), the places BWAPI's BWGame.h gives.

The simulator keys a cell by its row's base too, so a Brood War id and the original
id at the same place in the row stay apart, and placeOfAddress names the Brood War
rows.

Fixes scm-js#91.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…P).allied

Four read-only unit fields: u.opticalFlare (+0x123, true while Optical Flare
blinds the unit), u.acidSpores (+0x126, the stacks, 0 to 9), u.orderState
(+0x4E) and u.queuedOrders (+0x84, the orders waiting behind the current one
that the game counts: those with a button). And stats(P).allied[Q], read only:
whether P has set Q as an ally, from the alliance table (0x58D634), one way.

queuedOrders is what tells a Medic healing on its own from one healing on the
way of a player's command. In map trace a Medic healing from idle reads
MedicHeal with 0 queued, its MedicHealToIdle not counted; one that stopped to
heal during an attack-move reads MedicHeal with its HealMove queued (1), and
one on patrol has its two Patrols queued (2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s a range

The game measures a weapon's or a spell's range between the units' boxes, not
their centres (units_distance in OpenBW): each box is the type's dimensions in
units.dat around the unit's centre, the gaps along x and along y are taken, and
xy_length makes them one length, a little over the longer gap once the shorter
is a quarter of it. distanceTo() does the same, reading the dimensions at
0x6617C8 by the units' types, so `a.distanceTo(b) <= 192` is "within
Restoration's range" as the game decides it. 0 when either unit is gone.

Checked in map trace against the game: a Marine 200 px from a Medic centre to
centre is 183 px away by this measure and is restored, and one 212 px away is
195 px and is not.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nd the Stop button

cast() gives the order a player's command gives, written to the caster as
gather() writes a worker's: the order's target (+0x5C), then the order and its
state in one masked write (+0x4D, +0x4E back to 0). The tech-to-order table
holds Restoration alone, a Medic's CastRestoration (180); any other technology
is an error when the script is built, naming it, and a caster of another type
or a target gone is left alone. Nothing checks research or energy: the game's
own spell order drops a cast its caster has no energy for, and walks the
caster into range.

stop() writes the order Stop (1) with its state 0: the unit stops where it
stands and takes up its next queued order, or goes idle.

Played in StarCraft: Remastered (2026-11-11, by a prototype map): the
CastRestoration write is cast, mid-heal too. In map trace, stop() ends a cast
whose target flew out of range before it landed, with no energy spent and the
Medic left where it stood.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…licted unit nearby

import { buildAutoRestoreProgram } from "trigscript/spells";
buildAutoRestoreProgram({ switch: "Medics trained", keepEnergy: 25 });

From then on a human player's Medic that is idle, or healing on its own from
idle, casts Restoration on a unit of its owner's or of a player its owner has
allied (one way is enough) that is within the spell's range and has Lockdown,
Irradiate, Plague, Ensnare, Maelstrom, Acid Spores or Optical Flare. Both
options are optional: `switch` names a switch of the map (typed to the map's
own names), and auto-restore runs only while it is set; `keepEnergy` is the
energy a Medic keeps after the cast, beyond the spell's cost read from
techdata. The owner must have researched Restoration.

Each frame it pairs the eligible Medics with the afflicted units within range,
by u.distanceTo() against weapons.dat's range for Restoration, and sends the
nearest pair first, one Medic to a unit, so the nearest Medic goes and a Medic
with two units near restores the nearer. A unit some Medic is already casting
at is left to it. A Medic it sent whose target leaves range before the cast is
under way is stopped (u.stop()), so it never walks after it. A Medic on any
player command is never used: moving, attack-moving, holding, patrolling and
casting are other orders, and a Medic healing on the way of an attack-move or
a patrol has that order queued (u.queuedOrders), which one healing from idle
does not. Parasite alone, stasis, invincible units, hallucinations and the
Medic itself are left alone, and so are computer players' Medics. A second call
adds nothing, as buildAutoMiningProgram()'s does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
centerView() in a program left local.camera at 0, 0 in a test: the action
was only logged, and only the test's moveCamera() moved the camera. Now Center
View sets the camera of the player whose program ran it, centered on the
location for a 640 x 480 screen, snapped down to 8 pixels, and kept on the
map: 648 pixels short of its right edge and 488 short of its bottom, as played
in Classic graphics. The mouse stays where it is on the screen.

A test world can be given the map's size (mapSize, in tiles), which the build
step fills in from the open map; memory.map.width and .height read it.

Fixes scm-js#94

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…auto-restore's toggle

import { CardButton, cardSlots } from "trigscript/card";
const restore = new CardButton(techs.Restoration, cardSlots.Restoration);
await restore.begin();
while (true) { if (await restore.rightClicked()) { … } … await nextFrame(); }

buildAutoRestoreProgram({ switch: "Medics trained", allowPlayersToTurnOffAutoCast: true });

The game keeps no record of which card button a right-click landed on, so
CardButton tests where the mouse was when the right button went down against
where the button is drawn, while the card shows the ability's units' buttons
(Medic buttons, set 34, for Restoration). The card sits against the right edge
of the drawn game, which is 640 wide in Classic graphics and as wide as the
display's shape in Remastered's, and no address says which is on. So at the
start it centers the view on the map's middle, waits for the camera to settle,
reads where it stopped and sends the view back; minimap clicks and the camera
going further right than Remastered allows keep it current after a graphics
switch. Each step is its own pass of the caller's loop: in Remastered a Center
View after an await in the same branch, or in a task beside the program, locked
the view. Single-player maps.

With allowPlayersToTurnOffAutoCast, a right-click on a Medic's Restore button
turns auto-restore off for the player and another turns it on ("Auto-restore
off" / "Auto-restore on", to that player). It starts on, and while the map's
switch is off the right-click is ignored.

Three Local fields: local.mouse.buttons (0x6CDDC0), local.card.buttonSet
(0x68C14C) and local.screen.width (0x6CEFF0), all played in Remastered.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mstephenhunt mstephenhunt changed the title trigscript/card: a right-click on a command card button, and auto-restore's on/off toggle Auto-mining, auto-restore and its right-click toggle (trigscript/workers, spells and card), in one PR Nov 13, 2026
@jeany55

jeany55 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Thanks for all of this, and for #91 and #94: both were real bugs, and the tests that fail on main made them quick to check. CI is green, and I'd like to merge this as it is rather than ask for another round. It is still marked as a draft, though, so tell me if there is more you mean to push first.

A follow-up PR comes right after the merge, with the changes I'd otherwise have asked for here. So they don't surprise you:

  • Names. buildAutoMiningProgram() and buildAutoRestoreProgram() become autoMining() and autoRestore(), as in the review on trigscript/workers buildAutoMiningProgram(), on u.gather(target) #88. With A function that reaches program() or trigger() is refused where a program calls it #90 the compiler says "call it at the top of the file" itself, at the call, so the name doesn't have to. Both get a test of that error.
  • gather(), cast() and stop() leave a burrowed or loaded unit as it is. They write the order into the unit past everything a command checks, and the player has no command for a burrowed Drone or an SCV in a Dropship. The doc comments say what is written instead of "as a right-click does".
  • autoRestore() passes over a Medic that can't cast (in stasis, under Maelstrom, loaded). Such a Medic could be given the cast and then hold its target, so no other Medic went.
  • The lifted game's test world reads orderTarget, beside the two positions.
  • trigscript/card and the right-click toggle move to a branch, card-right-click, and stay out of the next release. The idea is good and I'd like to have it. What holds it back is that a library module's names are public from the first release, and this one rests on measurements from one computer: the view is sent to the middle of the map and back at the start, and the button positions were read on a Mac. Before it comes back I'd want it played on Windows, on a 4:3 and an ultrawide display, and on a map that isn't square. Two smaller things to fix there: with two people playing, each player's copy handles every human's Medics, so one player's "off" doesn't hold; and importing trigscript/spells reserved the card's location even with the toggle off. local.mouse.buttons, local.card.buttonSet and local.screen.width stay on main.

Not for now, but noted in the plan's open list: the worker and Medic types are fixed ids, so a mod's own worker gets nothing.

Your notes say a few things haven't been played in Remastered yet: autoMining() as the library, the Brood War rows of researched and upgrades in a game, and the auto-restore test map. If you play any of them, say so here or in an issue.

We tag 4.5.0 and move the editor's pin once the follow-up is in. scm-js/scm-js#233 will then need the two new names, and its card and toggle sections held back until that branch lands.

@jeany55
jeany55 marked this pull request as ready for review November 15, 2026 01:24
@jeany55
jeany55 merged commit 07dd21b into scm-js:main Nov 15, 2026
1 check passed
@jeany55

jeany55 commented Nov 15, 2026

Copy link
Copy Markdown
Contributor

Merged. It was still a draft, so I marked it ready myself: it read as finished, CI passed, and I didn't want the two fixes waiting. #91 and #94 are closed with it. If you had more to push, open it as a new PR against main.

The follow-up described above is #97. The card library and the toggle are on the card-right-click branch, one commit on top of #97, with what it waits on written in docs/v4-plan.md. If you can play it on another setup, that branch is the place to build on.

jeany55 added a commit that referenced this pull request Nov 15, 2026
After #96: autoMining() and autoRestore(), guards on the order verbs, the card library on a branch
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Simulator: centerView() doesn't move local.camera stats(P).researched reads the wrong byte for Brood War techs (and upgrades 46+)

2 participants