Repository navigation
trigscript/workers buildAutoMiningProgram(), on u.gather(target) - #88
mstephenhunt wants to merge 4 commits into
Conversation
…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>
jeany55
left a comment
There was a problem hiding this comment.
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.
| * 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; |
There was a problem hiding this comment.
"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.
| * 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() { |
There was a problem hiding this comment.
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.
| 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]; |
There was a problem hiding this comment.
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.
| 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)); } |
There was a problem hiding this comment.
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.
|
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. |
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: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.orderTargetYare 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 ofworkers.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
gatheron a mineral field and on a gas building, and standard-library tests forbuildAutoMiningProgram(), including a second call in the same file or another file, and two builds in a row.scmjs map trace, with the test map's script being exactly the two lines above:on.orderlisteners, both top-level and insideprogram(), still fire besidebuildAutoMiningProgram().Related
While checking what happens when
buildAutoMiningProgram()is called insideprogram()or a listener, I found that a script's own function containingprogram()ortrigger(), called from a program, builds with no error and takes effect from the start of the game. The library case fails with errors located inworkers.tsfor 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.