TrigScript 4

.github/workflows/ci.yml

@@ -29,5 +29,5 @@ jobs:
     # `dist/testing.js` and its declarations are what another repository's tests import at
     # a tag to run triggers, so they are held to the same rule.
     with:
-      artifacts: dist/compiler.js dist/testing.js dist/testing.d.ts
+      artifacts: dist/compiler.js dist/testing.js dist/testing.d.ts dist/gametest.js
     secrets: inherit

.gitignore

@@ -2,3 +2,9 @@ node_modules/
 *.tsbuildinfo
 # Blizzard's maps, copied in for the round-trip test; never committed.
 fixtures/
+# Videos a probe imports (probes/bad-apple.ts): not ours, made on the spot with scripts/import-video.mts.
+probes/*.video
+# The halftone probe's pictures and walks: made on the spot by probes/lib/halftone-gen.mts.
+probes/*.image
+# The sound demo's imported sound: made on the spot by probes/lib/sound-demo-gen.mts.
+probes/*.sound

README.md

@@ -277,7 +277,7 @@ import { test, expect, program, keyPressed, chatted, setResources, print, sleep,
 program(() => {
   let shop = false;
   while (true) {
-    if (keyPressed(CurrentPlayer, "F2")) { shop = !shop; print(shop ? "Shop open" : "Shop closed"); }
+    if (keyPressed(CurrentPlayer, "F7")) { shop = !shop; print(shop ? "Shop open" : "Shop closed"); }
     const give = chatted(CurrentPlayer, "-give {n}");
     if (give && shop) setResources(CurrentPlayer, "add", give.n, "ore");
     sleep(frames(1));
@@ -287,7 +287,7 @@ program(() => {
 test("-give pays only while the shop is open", (sim) => {
   sim.type("-give 100").frames(2);
   expect(sim.resources(0 as Player).ore).toBe(0);
-  sim.press("F2").frames(1);
+  sim.press("F7").frames(1);
   expect(sim.program("shop").shop).toBe(true);
   sim.type("-give 100").frames(2);
   expect(sim.resources(0 as Player).ore).toBe(100);
@@ -417,7 +417,7 @@ with a message, never passed over in silence.
 | `boolean` | Same | Assigned with `=` only: no `\|\|=`, `&&=`. |
 | `string` | Mostly | A value with no length to declare. `length`, `s[i]` and `slice` count characters (code points), where JavaScript counts UTF-16 units: they differ only past U+FFFF. A made text holds 1 023 bytes. The methods are a subset: no `split`, `replace`, `trim`, `toUpperCase`, `parseInt`, regular expressions. |
 | `null`, `undefined` | Units only | `Unit \| null` is real (`first(…)`, `if (u)`, `u?.kill()`). A number, a boolean or a text is never either: where JavaScript would give `undefined` — `pop()`, `find()`, `get()`, `at()` — say what it is then (`xs.pop() ?? 0`). No optional fields or parameters (`y?: number`); a parameter's default (`y = 1`) is there. |
-| Operators: `+ - * / %`, comparisons, `&&` `\|\|` `!`, `c ? a : b`, `& \| ^ << >> >>>`, `??`, `?.`, `++` `--`, the compound assignments, the comma | Same | `==` and `===` are one thing, since nothing is coerced. A shift by 32 or more leaves nothing, where JavaScript shifts by the remainder. Missing: `**`, `typeof`, `in`, `delete`. |
+| Operators: `+ - * / %`, comparisons, `&&` `\|\|` `!`, `c ? a : b`, `& \| ^ << >> >>>`, `??`, `?.`, `++` `--`, the compound assignments, the comma | Same | `==` and `===` are one thing, since nothing is coerced. A shift by 32 or more leaves nothing, where JavaScript shifts by the remainder. `typeof x === "…"` and `"key" in x` work where the answer is known when the script is built — a function written for a number or a text is inlined with the side its argument takes — and not as tests in the game. Missing: `**`, `delete`. |
 | `if`, `while`, `do`, `for`, `for…of`, `switch`, `break`, `continue` | Same | A loop runs all its rounds within one frame of the game, so one that never ends must `sleep()` on every path; `while (true)` left only by a `break` needs the sleep too. A `for` over bounds the script knows is unrolled. No `for…in`, no labels. |
 | Functions: declarations, parameters by value, defaults, rest parameters, recursion, generics | Same | The compiler inlines a function or calls it; the meaning is the same. One that calls itself cannot `sleep()` and has a depth limit. A function declared inside another does not see the outer one's locals (it sees the program's). It returns a number, a boolean, a text, a unit or an instance — not a record or an array it made. |
 | Arrow functions, closures, functions as values | Callbacks only | An arrow is written where a method takes it (`xs.map((x) => x + bonus)`), and sees every variable in reach. It cannot be kept: not in a variable, an array, a field or a return value. |
@@ -430,7 +430,7 @@ with a message, never passed over in silence.
 | `try` / `catch` / `throw` | Missing | The game has no exceptions. What is always a mistake — an index past the end, a full heap, a stack overflow — is said in the game in red, or listed by Simulate. |
 | `async` / `await`, promises, generators, timers | Missing | `sleep()` is how a program waits: it gives the frame back and carries on later, and may stand anywhere but in a function that calls itself or a loop over units. Something on its own clock is another `program()`. |
 | Modules | Same | `import` between the script's files and from `"trigscript"`; nothing from npm. A function another file's program calls is made with `game()`. |
-| The standard library | A little | `Math.min`, `Math.max`, `Math.abs` (and the rounding ones, which change nothing), `String(n)`, `n.toString()`, `Array.from`, `new Array(n).fill(v)`. For `console.log` there is `print()`, for `Math.random()` there is `random(n)`. No `JSON`, `Date`, `RegExp`, `Object.*`, and no `Math.sqrt` or `**` on a variable. |
+| The standard library | A little | `Math.min`, `Math.max`, `Math.abs` (and the rounding ones, which change nothing), `String(n)`, `n.toString()`, `Array.from`, `new Array(n).fill(v)`. For `console.log` there is `print()`, for `Math.random()` there is `random(n)`. Inside a program `Math.random()`, `Date.now()` and `new Date()` are refused, since they would be worked out once when the map is built; game time is `elapsed()` or `memory.game.frame`. No `JSON`, `Date`, `RegExp`, `Object.*`, and no `Math.sqrt` or `**` on a variable. |
 | — | Added | What TypeScript has no word for: `sleep`, `rose` and `once`, reads of the game (`minerals(p)`), `Unit` objects and loops over units, `stats()`, `keyPressed` / `clicked` / `mouse` / `chatted`, `shared()`, per-player programs. |
 
 The sections below say each of these in full, and [What a program does not
@@ -1197,8 +1197,11 @@ if (target) target.order("move", locations.Exit);
 `randomUnit(filter?)` pick one unit or `null`, and TypeScript wants the `if (target)` before
 the unit is used (or `target?.kill()`). A filter is `{ type, owner, at }`, every part known
 when you build; `units.Men`, `units.Buildings` and `units.Factories` work as a type, and
-`CurrentPlayer` as an owner. Units come in the order of the game's unit table; a dying unit
-is passed over, so `first()` after a `kill()` is the next one.
+`CurrentPlayer` as an owner. Units come oldest first: the game's unit table in the order the
+game hands its places out (slot 0, then 1699 downwards), the walk stopping once it has met
+every unit in use, so a loop costs what the map holds. A unit made in the place of one that
+died, once the game has freed it, comes where the dead one did. A dying unit is passed over,
+so `first()` after a `kill()` is the next one.
 
 A unit has `hp`, `shields` and `energy` in whole points, `maxHp` / `maxShields` of its
 type, `owner`, `type`, `x`, `y`, `kills`, `orderId`, `cooldown`, `resources` (a mineral
@@ -1292,8 +1295,9 @@ program(() => {
 
 `keyPressed(player, key)` is true when the press arrives — once per press, not while the
 key is held (the game reports no held key), and not while the player is typing a message.
-Keys are the letters and digits, `"F1"` … `"F12"` without `"F6"` (the game keeps it to
-itself and reports no press of it — played and seen — so it is an error to ask), `"Space"`, `"Enter"`, `"Escape"`,
+Keys are the letters and digits, `"F1"`, `"F7"` … `"F12"` (the game keeps F2 to F6 to
+itself and reports no press of them — played and seen; F2 to F4 move the camera — so it is
+an error to ask), `"Space"`, `"Enter"`, `"Escape"`,
 `"Tab"`, `"Shift"`, `"Ctrl"`, `"Alt"`, the arrows (`"Left"` …), `"Backspace"`, `"Delete"`,
 `"Insert"`, `"Home"`, `"End"`, `"PageUp"`, `"PageDown"` and `"Numpad0"` … `"Numpad9"`; the
 game's own use of a key still happens. `clicked(player, "left" | "right" | "middle")` is
@@ -1479,14 +1483,12 @@ a message that says so, none is passed over in silence:
 | --- | --- |
 | Fractions: every number is whole | work in a smaller unit (pixels, frames, hundredths) |
 | `**`, `Math.sqrt`, `Math.sign` and the rest of `Math` on a variable — `min`, `max` and `abs` are there, and the rounding ones around a division | a loop, or a list the script worked out (`const roots = Array.from({ length: 100 }, (_, n) => Math.floor(Math.sqrt(n)))`, then `roots[n]`) |
-| A function kept as a value: `const f = (x: number) => x + k`, a function in an array, one returned | `function f(x: number) { … }` in the program; an arrow is fine where a method takes one |
-| A function that returns a record or an array it made | hand it the record or the array to fill in; an instance of a class is the exception (*Classes*) |
-| `try`, `catch`, `throw` — the game has no exceptions | return a number that says what happened |
-| `async`, generators, `for…in`, a labelled `break`, `typeof` | — |
+| A function that returns an array it made (a record or an instance it made is fine) | hand it the array to fill in |
+| `for…in`, a labelled `break` | `for…of`, a flag tested after the inner loop |
 | An `enum` declared inside the program | declare it above the program: its members are numbers the script has, and a variable holds one |
-| On an array: `shift`, `unshift`, `splice`, `at`, `lastIndexOf`, `join` of numbers | `pop` and `push`, a place kept in a variable, `xs[xs.length - 1]`, a template in a loop |
+| What `splice` takes out, as a value | read it first: `xs.slice(start, end)` |
 | `map` into texts or records | `push` in a `for…of` |
-| On a made text: `split`, `trim`, `replace`, `toUpperCase`, `lastIndexOf`, `parseInt`, regular expressions | keep the number beside the text and make the text from it |
+| On a made text: regular expressions, and `replace` with a function | `replace` / `replaceAll` / `split` with a text |
 | A `Map` whose values are texts or records, or whose keys are texts | the place of a row of an array of records as the value |
 | Writing a unit's position, cloak or tint | the game refuses these itself (*Units*) |
 
@@ -1753,7 +1755,8 @@ stored label. Arithmetic is 32 bits that wrap, and each comparison, division, sh
 right, `min`, `max` and printed number reads them signed or unsigned as `numbers.ts`
 marked it. An array that grows is a block of one heap the programs share — sizes double,
 a block given back serves the next array of its size — and a made text is such a block
-of bytes. A function that is called is one body with its parameters as variables; one
+of bytes; an array's own cells sit beside the heap's bytes, a variable each, so that a
+loop's counter reads and writes them in a few triggers. A function that is called is one body with its parameters as variables; one
 that calls itself keeps what a call would overwrite on a stack of its own, an array
 beside the heap whose depth the script's Settings give. `docs/ir.md` says what each node
 means to both backends. A per-player program loops over the

compile.ts

@@ -41,6 +41,21 @@ export const libUrl = (dist: string = DEFAULT_DIST) => `${dist.replace(/\/+$/, "
 export const compilerUrl = (dist: string = DEFAULT_DIST) =>
   dist === DEFAULT_DIST ? `https://cdn.jsdelivr.net/gh/scm-js/plugin-trigscript@v${VERSION}/dist/compiler.js` : `${dist.replace(/\/+$/, "")}/compiler.js`;
 
+/**
+ * What runs a script's tests beside the lifted game (`dist/gametest.js`, from `compiler/gameTestEntry.ts`), at this
+ * release's own tag like the compiler: its text is handed to the engine's page (TrigScript 4, A2).
+ */
+export const gametestUrl = (dist: string = DEFAULT_DIST) =>
+  dist === DEFAULT_DIST ? `https://cdn.jsdelivr.net/gh/scm-js/plugin-trigscript@v${VERSION}/dist/gametest.js` : `${dist.replace(/\/+$/, "")}/gametest.js`;
+
+/** What Remastered is known to allow (`data/allowlist.json`, copied into `dist/` by the build), for Find EUD Error: fetched only then. */
+export const allowlistUrl = (dist: string = DEFAULT_DIST) =>
+  dist === DEFAULT_DIST ? `https://cdn.jsdelivr.net/gh/scm-js/plugin-trigscript@v${VERSION}/dist/allowlist.json` : `${dist.replace(/\/+$/, "")}/allowlist.json`;
+
+/** The Ogg Vorbis encoder (`compiler/vorbis.ts`, `dist/vorbis.wasm`), at this release's own tag: fetched only by a build that has a long clip to put in the map. */
+export const vorbisUrl = (dist: string = DEFAULT_DIST) =>
+  dist === DEFAULT_DIST ? `https://cdn.jsdelivr.net/gh/scm-js/plugin-trigscript@v${VERSION}/dist/vorbis.wasm` : `${dist.replace(/\/+$/, "")}/vorbis.wasm`;
+
 /**
  * What the worker is told to import. The editor's loader turns a fetched plugin into
  * `blob:` modules, and the compiler's own blob URL is the compiler the main thread would
@@ -51,18 +66,23 @@ export const compilerUrl = (dist: string = DEFAULT_DIST) =>
 export const workerModuleUrl = (dist: string = DEFAULT_DIST) => (ENTRY_URL.startsWith("blob:") && !blobRefused ? ENTRY_URL : compilerUrl(dist));
 
 export const COMPILE_TIMEOUT_MS = 15_000;
+/** A build's compile makes the script's sounds too — a long song mixed and encoded — and gets longer. */
+export const BUILD_TIMEOUT_MS = 60_000;
 
 export interface CompileInput {
   files: ScriptFiles;
   names: ScriptNames;
   /** Run the script's tests after the compile: the world they start from, and which of them. */
   tests?: TestRunOptions;
+  /** Encode the sounds the map is to get (a build): a check leaves an Ogg Vorbis one as its name (`compiler/vorbis.ts`). */
+  sounds?: boolean;
 }
 
 interface CompileRequest extends CompileInput {
   id: number;
   moduleUrl: string;
   libUrl: string;
+  vorbisUrl?: string;
 }
 
 interface CompileResponse {
@@ -78,7 +98,7 @@ importScripts(${JSON.stringify(TS_URL)});
 let loading = null;
 let lib = null;
 self.onmessage = async (e) => {
-  const { id, moduleUrl, libUrl, files, names, tests } = e.data;
+  const { id, moduleUrl, libUrl, vorbisUrl, files, names, tests } = e.data;
   try {
     if (!loading) loading = import(moduleUrl);
     let mod;
@@ -90,7 +110,14 @@ self.onmessage = async (e) => {
       if (!r.ok) throw new Error("Could not load the standard library from " + libUrl + " (" + r.status + ").");
       lib = await r.text();
     }
-    postMessage({ id, result: mod.compileScript(self.ts, files, names, { lib, tests }) });
+    // A check names the script's clips and makes none of them; a build makes them, the long ones encoded below.
+    const result = mod.compileScript(self.ts, files, names, { lib, tests, sounds: Boolean(vorbisUrl) });
+    // A build's long clips encoded as Ogg Vorbis; a check's left as names, their samples not sent.
+    if (typeof mod.finishSounds === "function") {
+      const encoder = vorbisUrl && result.sounds.some((s) => s.vorbis) ? await mod.loadVorbis(vorbisUrl) : null;
+      mod.finishSounds(result.sounds, encoder);
+    }
+    postMessage({ id, result });
   } catch (err) {
     postMessage({ id, error: String((err && err.message) || err) });
   }
@@ -188,14 +215,14 @@ function breakWorker(reason: string) {
 }
 
 /** The script ran too long: drop this worker (the next request starts another) and say so. */
-function timeOut(id: number) {
+function timeOut(id: number, ms: number) {
   const p = pending.get(id);
   if (!p) return;
   pending.delete(id);
   worker?.terminate();
   worker = null;
   rejectAll("The compile was stopped.");
-  p.reject(new Error(`The script did not finish in ${COMPILE_TIMEOUT_MS / 1000} seconds. Is there an endless loop outside program()?`));
+  p.reject(new Error(`The script did not finish in ${ms / 1000} seconds. Is there an endless loop outside program()?`));
 }
 
 /** The worker, started if there is none. Throws `CompilerUnavailable` when one cannot be made, or could not a moment ago. */
@@ -247,8 +274,9 @@ export function compileInBackground(input: CompileInput, dist: string = DEFAULT_
     p.reject(new CompileSuperseded());
   }
   return new Promise<CompileResult>((resolve, reject) => {
-    pending.set(id, { resolve, reject, timer: setTimeout(() => timeOut(id), COMPILE_TIMEOUT_MS) });
-    const req: CompileRequest = { id, moduleUrl: workerModuleUrl(dist), libUrl: libUrl(dist), files: input.files, names: input.names, ...(input.tests ? { tests: input.tests } : {}) };
+    const ms = input.sounds ? BUILD_TIMEOUT_MS : COMPILE_TIMEOUT_MS;
+    pending.set(id, { resolve, reject, timer: setTimeout(() => timeOut(id, ms), ms) });
+    const req: CompileRequest = { id, moduleUrl: workerModuleUrl(dist), libUrl: libUrl(dist), files: input.files, names: input.names, ...(input.tests ? { tests: input.tests } : {}), ...(input.sounds ? { vorbisUrl: vorbisUrl(dist) } : {}) };
     w.postMessage(req);
   }).catch((err: Error) => {
     if (err.message === RETRY) return compileInBackground(input, dist);