Skip to content

trigscript/workers buildAutoMiningProgram(), on u.gather(target) - #88

Closed
mstephenhunt wants to merge 4 commits into
scm-js:mainfrom
mstephenhunt:worker-auto-mining
Closed

mstephenhunt wants to merge 4 commits into
scm-js:mainfrom
mstephenhunt:worker-auto-mining

Conversation

@mstephenhunt

@mstephenhunt mstephenhunt commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Why

I wanted newly built workers to start mining on their own when their building is rallied to a mineral patch or a gas building, and I wanted a map maker to get that with one line instead of writing the detection logic themselves. In Brood War a rallied worker walks there and stands idle, and the Order action can only move, patrol or attack. So a map has no way to give a worker a gather order without writing it into the unit's memory.

What changes

trigscript/workers: buildAutoMiningProgram(). A map maker writes:

import { buildAutoMiningProgram } from "trigscript/workers";
buildAutoMiningProgram();

From then on, 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 the worker's own player. Anything else (ground, a bare geyser, an unfinished or another player's gas building) is left as the game leaves it. It acts once, as the worker comes out, so an order the player gives afterwards stands.

The library is written in TrigScript, on two additions to the language:

  • u.gather(target) gives a worker the order a right-click would: MoveToMinerals for a mineral field, MoveToGas for a gas building. It writes the order id, order state 0 and the order target.
  • u.orderTarget, u.orderTargetX, u.orderTargetY are new read-only fields. A just-trained worker rallied onto a patch has a Move order to the patch's centre and no target unit. One rallied onto its own player's gas building has Follow with that building as the target. The library tells those cases apart with these fields.

Also: ledger rows, docs/ir.md, emitter tests and standard-library tests.

Calling it more than once. buildAutoMiningProgram() keeps a flag at the top of workers.ts, and 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.

Testing

  • Typecheck, build and the test suite pass, including emitter tests for gather on a mineral field and on a gas building, and standard-library tests for buildAutoMiningProgram(), including a second call in the same file or another file, and two builds in a row.
  • In scmjs map trace, with the test map's script being exactly the two lines above:
    • Staged SCVs, Probes and Drones reach MiningMinerals or HarvestGas, and their owner's ore or gas rises. Without the library they never do.
    • Rallies on ground, on an unfinished gas building, on another player's gas building, and on a bare geyser leave the worker alone.
    • A map maker's own on.order listeners, both top-level and inside program(), still fire beside buildAutoMiningProgram().
  • Played in StarCraft: Remastered with the same logic written as a map script, before it became a library, on a map where one human player owns a base of each race. Rallied workers of all three races mine minerals and gather gas. Rallies on ground or on an unfinished Refinery behave normally. A worker given another order as it comes out obeys it. No EUD error.
  • The library form, the two lines above, is built and loads cleanly in the editor; I haven't played it in Remastered yet.

Related

While checking what happens when buildAutoMiningProgram() is called inside program() or a listener, I found that a script's own function containing program() or trigger(), called from a program, builds with no error and takes effect from the start of the game. The library case fails with errors located in workers.ts for the same reason. That's a separate compiler gap, filed as #89.

The map-maker docs for this are drafted in scm-js/scm-js#224, which waits on a TrigScript release that includes this PR.

mstephenhunt and others added 2 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>
mstephenhunt and others added 2 commits November 11, 2026 10:32
…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>
@mstephenhunt mstephenhunt changed the title trigscript/workers autoMining(), on u.gather(target) trigscript/workers buildAutoMiningProgram(), on u.gather(target) Nov 11, 2026
@mstephenhunt
mstephenhunt marked this pull request as ready for review November 11, 2026 16:07

@jeany55 jeany55 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this, and for #89. The auto-mining works the way a map maker would want it, and the notes on what was traced and what was played made it quick to check.

I ran the type-check and the full suite locally at 4c051b9 and both are clean. I read the unit offsets, the order ids and the unit ids against the game's unit structure and they are right.

#89 is fixed in #90, now on main. A function that reaches program() or trigger() is refused at the caller's line, through imports and the standard library too. I tried it on top of this branch: buildAutoMiningProgram() inside program() or a listener gives one error in main.ts, and your standard-library tests pass unchanged.

Two things I'd like settled before this merges, since both are public once released. They are on the lines below: what gather() does to a worker a right-click would refuse, and the function's name. The other two comments are small.

When you rebase on main, a test that the call inside program() is refused at the caller's line would be a good addition to the workers tests.

For the release: once this is in I'll tag TrigScript 4.5.0 and move the pin in scm-js, so scm-js#224 only needs a rebase after that. No need to bump the pin there yourself.

Comment thread compiler/declarations.ts
* Send an SCV, Probe or Drone to mine a mineral field or harvest a Refinery, Extractor or Assimilator, as a right-click
* on it does. Anything else, either way round, is left as it is.
*/
gather(target: Unit): void;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"As a right-click on it does" promises more than the lowering does. A right-click goes through the game's command, which refuses some workers; this writes the order, its state and its target into the unit whatever state it is in.

The library only calls it on a worker just out of production, so that use is fine. A map maker can call it on any worker, though. Could you trace two cases: a burrowed Drone, and an SCV inside a Dropship? A right-click does nothing for either. If the written order makes them misbehave, I'd guard them in the lowering (burrowed and inTransport are already among the flags it reads) and add them to the emitter test. If they turn out harmless, say here what it is: the order written to the unit, with those cases named.

Comment thread stdlib/workers.ts
* to a mineral patch or the player's own finished gas building starts gathering from it. Called at the top of a
* script, as programs are made when the map is built; a call after the first adds nothing.
*/
export function buildAutoMiningProgram() {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd go back to autoMining(). The rest of the standard library names what a thing does for the map (every, after, choose, say), and this name describes how it is built. I take it the rename was to say "top of the script only"; with #90 the compiler says that itself, at the caller's line, so the name no longer has to.

That changes the name in the docs PR too.

Comment thread compiler/orders.ts
export const ORDER_OF_VERB: Readonly<Record<"move" | "patrol" | "attack", number>> = { move: 6, patrol: 152, attack: 14 };

/** The workers `u.gather(…)` sends: SCV, Drone, Probe. */
export const GATHER_WORKERS: readonly number[] = [7, 41, 64];

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not for this PR, noting it for later: the mineral and gas ids are fixed in the game itself, so those are right for any mod, but the game decides who is a worker from the unit's flags in units.dat. A mod with a worker of its own gets nothing from gather() or from the library. A follow-up could read the flag.

Comment thread compiler/gameSim.ts
get hasTarget() { return this.read("hasTarget", () => this.m.getUint32(this.at + 0x5c, true) !== 0); }
get inTransport() { return this.read("inTransport", () => this.flag(0x00000040)); }
get orderTargetX() { return this.read("orderTargetX", () => this.m.getUint16(this.at + 0x58, true)); }
get orderTargetY() { return this.read("orderTargetY", () => this.m.getUint16(this.at + 0x5a, true)); }

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

orderTarget is missing here beside the two positions, so a test run in the lifted game reads nothing for u.orderTarget where the game has a unit. The pointer at +0x5c to a slot, as hasTarget reads it, would do.

@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.

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.

2 participants