Skip to content

trigscript/spells: buildAutoRestoreProgram(), Medics that restore on their own - #93

Closed
mstephenhunt wants to merge 10 commits into
scm-js:mainfrom
mstephenhunt:auto-restore
Closed

mstephenhunt wants to merge 10 commits into
scm-js:mainfrom
mstephenhunt:auto-restore

Conversation

@mstephenhunt

Copy link
Copy Markdown
Contributor

Why

I'm building map features as one-call TrigScript library functions, so a map maker gets a behavior by writing one line instead of a program of their own. This is the second one, after auto-mining: Medics that cast Restoration on their own. A map that gives players Medics can call buildAutoRestoreProgram() and the idle Medics restore their own and their allies' units when Lockdown, Irradiate, Plague, Ensnare, Maelstrom, Acid Spores or Optical Flare lands on them, the way they heal on their own.

A hand-written prototype of the same program passed in map trace and in a game I played in Remastered. This turns it into the library function and the language pieces it needs.

It builds on two open PRs: #88 (u.gather, u.orderTarget and the trigscript/workers library) and #92 (stats(P).researched reading Brood War's own rows, which Restoration is in). This branch merges #92's branch into #88's.

What changes

  • buildAutoRestoreProgram(options?) in a new trigscript/spells module. A human player's Medic that is idle, or healing on its own from idle, casts a real Restoration on the nearest unit of its owner's or an ally's (one way is enough) that is within the spell's range and has one of the seven effects. The owner must have researched Restoration, and the Medic needs the spell's energy plus keepEnergy (default 0). switch names a map switch, typed to the map's own switch names, and auto-restore runs only while it is set. The nearest Medic goes, one Medic to a unit, and a Medic with several afflicted units near restores the nearest first. A Medic on a player command is never used, and a Medic never walks to its target: if the target leaves range before the cast, the Medic is stopped. Parasite alone, stasis, invincible units, hallucinations, the Medic itself and computer players' Medics are left alone. A second call adds nothing.
  • u.cast(tech, target). Gives the cast order a player's command gives: the order target, the order and its state. Restoration (a Medic's CastRestoration) is the only spell in its table, and any other technology is a build error that names it.
  • u.stop(). The Stop button's order. The library uses it to stop a Medic whose target left range.
  • u.distanceTo(other). How far apart two units are, measured as the game measures a weapon's or spell's range: between the units' boxes from units.dat's dimensions, with the game's own length approximation. A Marine 200 px from a Medic centre to centre is 183 px by this measure.
  • Read-only unit fields u.opticalFlare, u.acidSpores, u.orderState and u.queuedOrders. queuedOrders is what tells a Medic healing on its own from one healing during an attack-move or a patrol. All three show MedicHeal, but only the player's commands leave an order waiting in the queue.
  • stats(P).allied[Q]. Read-only: whether P has set Q as an ally, from the alliance table. It sits with researched and upgrades on the player's stats.
  • Docs, ledger, embedded stdlib. docs/ir.md covers the new IR kind, verbs and fields. Every new name has a ledger row, and compiler/generated/stdlib.ts is re-embedded.

Testing

  • npm run typecheck is clean, and npm test passes in full.

  • New emitter tests check each piece in the simulator and against the laid-out payload's memory. cast() writes order 180, state 0 and the target's pointer, and leaves a non-Medic alone. stop() writes order 1, state 0. Another technology is a build error naming it. The fields read +0x123, +0x126, +0x4E and +0x84. The alliance read hits 0x58D634 one way. distanceTo() gives 183, 195, 107 and 0 for boxes placed to give those numbers.

  • New stdlib tests check that the library builds, takes a switch name and keepEnergy, refuses a switch the map doesn't have, and adds nothing on a second call.

  • I ran the spec's acceptance checks in scmjs map trace, with the CLI built against this branch, on a test map with staging programs. They cover:

    • each of the seven effects on our own and an allied unit;
    • every gate: not researched, low energy, keepEnergy, switch clear, self, hallucination, stasis, Parasite only, out of range, enemy, one-way alliance the wrong way, computer Medic;
    • the switch both ways;
    • one Medic per unit, with exactly 50 energy spent by the nearest Medic;
    • nearest target first;
    • Medics on move, attack-move, hold, patrol or a manual cast keep their orders, including while healing along an attack-move or patrol;
    • mid-heal;
    • a target that leaves range.

    Controls show the observers see a failure. With no feature, nothing is restored. With the queue check removed, a Medic healing during an attack-move does cast.

  • scmjs map cost over 3,000 frames: 0.011 ms a frame with the switch clear, 0.23 ms with Restoration researched and nothing afflicted, and 0.67 ms average (4.68 ms peak) with every Marine re-ensnared each second.

  • A playable test map for Remastered is built from the spec's checklist, with F7 toggling the switch. Playing it in Remastered is still to do.

mstephenhunt and others added 10 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>
@mstephenhunt

Copy link
Copy Markdown
Contributor Author

Closing in favor of #96, which now carries this PR's commits along with the rest of the auto-mining, auto-restore and toggle work, so it can be reviewed and merged as one PR.

@mstephenhunt
mstephenhunt deleted the auto-restore branch November 13, 2026 11:29
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.

1 participant