@amxts/core 0.2.3 → 0.3.0

package/scripts/leaf-natives.ts

@@ -0,0 +1,84 @@
+/**
+ * The natives that never run a plugin's code while they run - leaf natives -
+ * read from the sources of AMX Mod X 1.10 and its stock modules.
+ *
+ * A native is on the list when nothing it does, directly or through what it
+ * calls, can reach a plugin: it executes no forward and no callback
+ * (ExecuteForward, MF_ExecuteForward, callfunc, a comparator, a parser's
+ * reader), calls no game function (MDLL_*, the game's entity functions,
+ * ReGameDLL) and no engine function that runs the game's code or that a
+ * ReHLDS hookchain, Hamsandwich or ReAPI hooks - no cvar written, no command
+ * executed, no message sent, no entity made or removed, nothing precached.
+ * What it does is read and write its own memory and AMX Mod X's: its
+ * arguments, AMX Mod X's tables (players, tries, arrays, vaults, the
+ * dictionary, the plugin list), entity fields, cvar values, info buffers, a
+ * command's words, files.
+ *
+ * Its one way out is an error: LogError runs the error filter of the AMX it
+ * was called with, and the natives' image sets none.
+ *
+ * Every one reads and writes its arguments with get_amxaddr, get_amxstring
+ * and set_amxstring (no bounds check), and writes none it declares `const`.
+ *
+ * What a leaf native allows:
+ * - its import is marked `@leaf`: a plugin keeps no shadow-stack frame for
+ *   a call to it, as no collection can run while it does;
+ * - a string it takes that is the plugin's static text - a literal, which
+ *   never changes - crosses as cells made once a map and kept in the natives'
+ *   image (the module's KeptText), not converted on every call;
+ * - the text it fills is copied back without asking where the plugin's
+ *   memory is again, as the memory cannot grow while it runs.
+ *
+ * A native left off - one that may call back, such as ExecuteForward,
+ * callfunc_*, set_cvar_*, server_cmd or a Pawn plugin's native - goes the
+ * copy way. A wrong entry would let the collector free what a plugin still
+ * holds, so a native is added only after its source is read.
+ */
+/** The names in `text`, apart by white space. */
+function names(text: string): string[] {
+	return text.split(/\s+/).filter(Boolean);
+}
+
+export const LEAF_NATIVES: ReadonlySet<string> = new Set([
+	// Text and numbers: string.cpp and amxmodx.cpp work on their arguments alone.
+	...names(`add argparse contain containi copy copyc equal equali float_to_str format_time get_char_bytes
+		get_time hash_file hash_string is_string_category mb_strtolower mb_strtotitle mb_strtoupper
+		mb_ucfirst md5 num_to_str num_to_word parse_loguser parse_time replace replace_string
+		replace_stringex setc split_string str_to_float str_to_num strcmp strfind strlen strncmp strtof
+		strtok strtok2 strtol`),
+	// Files, vaults and data packs: the C runtime and the engine's file system.
+	...names(`delete_file dir_exists fgets file_exists file_size fopen fputs GetFileTime LoadFileForMe mkdir
+		next_file open_dir read_dir read_file rename_file rmdir SetFilePermissions unlink write_file
+		get_vaultdata remove_vaultdata set_vaultdata vaultdata_exists nvault_lookup nvault_open
+		nvault_pset nvault_remove nvault_set nvault_touch ReadPackString WritePackString`),
+	// Cvars read, never written: writing one runs Cvar_DirectSet and its hooks.
+	...names(`cvar_exists get_cvar_flags get_cvar_float get_cvar_num get_cvar_pointer get_cvar_string
+		get_pcvar_string`),
+	// The server's and the players' state read: AMX Mod X's player table, info
+	// buffers, a command's words, the message and weapon tables. Not
+	// get_user_authid, nor get_players, which asks for it: the engine finds
+	// the id through ReHLDS's SV_GetIDString hookchain.
+	...names(`get_amxx_verstring get_flags get_localinfo get_mapname get_modname get_user_index get_user_info
+		get_user_ip get_user_msgid get_user_msgname get_user_name get_weaponid get_weaponname
+		get_xvar_id is_map_valid read_args read_argv read_flags read_logargv read_logdata xvar_exists`),
+	// Plugins, modules, libraries and the dictionary: AMX Mod X's own lists.
+	...names(`AddTranslation CreateLangKey find_plugin_byfile GetLangTransKey is_module_loaded
+		is_plugin_loaded lang_exists LibraryExists LookupLangKey module_exists register_dictionary`),
+	// Tries and arrays: AMX Mod X's memory. Not ArraySort or SortCustom*, which call a plugin back.
+	...names(`ArrayFindString ArrayGetString ArrayInsertStringAfter ArrayInsertStringBefore ArrayPushString
+		ArraySetString TrieDeleteKey TrieGetArray TrieGetCell TrieGetString TrieKeyExists TrieSetArray
+		TrieSetCell TrieSetString TrieSnapshotGetKey`),
+	// Entities and game data read: fields, private data, the engine's search
+	// of entities by a field. Not lookup_sequence, which may load a model
+	// through a hookchain, nor cs_find_ent_*, which call the game.
+	...names(`copy_infokey_buffer cs_get_item_id cs_get_translated_item_alias cs_get_user_model eng_get_string
+		entity_get_string find_ent_by_class find_ent_by_model find_ent_by_owner find_ent_by_target
+		find_ent_by_tname find_ent_data_info find_gamerules_info find_sphere_class GameConfGetAddress
+		GameConfGetClassOffset GameConfGetKeyValue GameConfGetOffset get_ent_data_string
+		get_gamerules_string get_global_string get_info_keybuffer get_keyvalue get_pdata_string
+		has_map_ent_class`),
+	// GeoIP: lookups in the databases in memory.
+	...names(`geoip_city geoip_code2 geoip_code2_ex geoip_code3 geoip_code3_ex geoip_continent_code
+		geoip_continent_name geoip_country geoip_country_ex geoip_latitude geoip_longitude
+		geoip_region_code geoip_region_name geoip_timezone`),
+]);

package/scripts/player-fields.ts

@@ -721,7 +721,7 @@ export function playerFieldsSource(fields: PlayerField[]): string {
 			'\t\tconst ids = text.split(",");',
 			'\t\tfor (let i = 0; i < ids.length; i++) {',
 			'\t\t\tconst id = I32.parseInt(unchecked(ids[i]));',
-			'\t\t\tif (id > 0) list.push(new Player(id));',
+			'\t\t\tif (id > 0) list.push(__playerOf(id));',
 			'\t\t}',
 			'\t\treturn list;',
 			'\t}',

package/scripts/plugin-natives.ts

@@ -988,7 +988,7 @@ function crossForwards(sources: any[], contract: Contract | null, problems: stri
 					} else if (type === 'Vector' && param.type !== 'Float') {
 						problems.push(`${where} - argument ${i + 1} is ${pawn} in the include: a Vector is three Floats, Float:${param.name}[3]`);
 					} else if (!param.type || param.type === 'any') {
-						// The host's public takes an untagged array as text (generate-host.ts, kindOf).
+						// An untagged array crosses as text (generate-image.ts, kindOf).
 						problems.push(`${where} - argument ${i + 1} is ${pawn} in the include, without a tag: Pawn passes it as text, and a ${type} would arrive empty; tag it, Float:${param.name}[]`);
 					} else {
 						crossing += param.type === 'Float' ? 'F' : '_';

package/scripts/prebuilt.ts

@@ -22,9 +22,14 @@
 // - the core: the compile's scripts, the patched AssemblyScript and its
 //   Binaryen, the API in as/, the natives table wamrc reads and the WAMR
 //   patch - which also decides whether the server's module loads the .aot.
-//   A package from the registry is its version: what npm has under a
-//   version never changes. A folder on this machine (a checkout) is its
-//   content, so the version and a hash are both kept;
+//   A package from the registry is its ABI (scripts/build-identity.ts): the
+//   .aot is taken under any core of its line on the same ground that has
+//   every import it uses with the same shape, as the server's module of that
+//   line loads it - a core's patch release needs no module released again,
+//   only one that uses what a later patch added. The .aot keeps the facade
+//   of the core it was compiled with, as any plugin built before the patch
+//   does. A folder on this machine (a checkout) is its content too, so the
+//   version, the ABI and a hash are all kept;
 // - every module package the compile reads - the module, and the ones it
 //   imports (menu-core reads config-core for its proxy) - the same way;
 // - the options amxts.config.ts gives them: setup is compiled with them;
@@ -47,12 +52,13 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { join, relative, resolve, sep } from 'node:path';
 import ts from 'typescript';
-import { coreVersion } from './build-identity';
+import { ABI_SECTION, abiIdentity, abiLine, coreVersion, importName, importShapes, releaseLine } from './build-identity';
 import { compileToMachineCode, compileToWasm } from './compile';
 import { codeFiles } from './compile-cache';
 import { includeForward, nativesBeside } from './plugin-natives';
 import { CORE_DIR, CORE_PLUGINS, loadProject, optionsOf, shared, sourcesFor } from './project';
 import { moduleSurface } from './shared-modules';
+import { readSection } from './source-map';
 import { SYSTEM_NAME, SYSTEMS, wamrcPath } from './system';
 import { c, log, since } from './ui';
 
@@ -60,7 +66,7 @@ import { c, log, since } from './ui';
 export const PREBUILT_DIR = 'prebuilt';
 const MANIFEST = 'manifest.json';
 /** Goes up when the manifest changes shape: a build reads only its own. */
-const FORMAT = 1;
+const FORMAT = 2;
 const CORE_NAME = '@amxts/core';
 
 /** A package as a prebuilt module was compiled with it. */
@@ -68,6 +74,8 @@ interface Built {
 	version: string;
 	/** Its content: the code files, TypeScript without comments. */
 	hash: string;
+	/** The core's: the ABI the .aot carries. */
+	abi?: string;
 }
 
 export interface PrebuiltManifest {
@@ -152,9 +160,9 @@ function coreHash(): string {
 }
 
 /** The core or a module package the project has, by name, as a prebuilt module is checked against it. */
-function installed(name: string, sources: Sources): { version: string; dir: string; hash: () => string } | null {
+function installed(name: string, sources: Sources): { version: string; dir: string; hash: () => string; abi?: string } | null {
 	if (name === CORE_NAME) {
-		return { version: coreVersion(), dir: CORE_DIR, hash: coreHash };
+		return { version: coreVersion(), dir: CORE_DIR, hash: coreHash, abi: abiIdentity() };
 	}
 	const pkg = sources.project.packages.find(each => each.name === name);
 	return pkg ? { version: pkg.version, dir: pkg.dir, hash: () => packageHash(pkg) } : null;
@@ -223,7 +231,8 @@ function mismatch(manifest: PrebuiltManifest, pkg: ModulePackage, sources: Sourc
 	for (const [name, built] of Object.entries(manifest.from)) {
 		const have = installed(name, sources);
 		if (!have) return `${named} was built with ${name}, which the project does not have`;
-		if (have.version !== built.version) return `${named} was built for ${name} ${built.version}, the project has ${have.version}`;
+		const other = have.abi ? otherAbi(built.abi ?? '', have.abi) : have.version !== built.version && `${name} ${built.version}, the project has ${have.version}`;
+		if (other) return `${named} was built for ${other}`;
 		if (!fromRegistry(have.dir) && have.hash() !== built.hash) {
 			return `${named} was built from another ${name} ${built.version} than the one in ${posix(relative(sources.project.dir, have.dir)) || '.'}`;
 		}
@@ -235,11 +244,31 @@ function mismatch(manifest: PrebuiltManifest, pkg: ModulePackage, sources: Sourc
 		}
 	}
 	const own = resolve(sources.project.pluginsDir) !== resolve(CORE_PLUGINS);
-	const shadow = own ? manifest.places.find(place => existsSync(join(sources.project.pluginsDir, place))) : undefined;
+	const shadow = own ? manifest.places.find(place => sources.ownFile(place)) : undefined;
 	if (shadow) return `${posix(relative(sources.project.dir, join(sources.project.pluginsDir, shadow)))} takes the place of a file ${named} was built from`;
 	return null;
 }
 
+/**
+ * How the ABI a module was built for (the identity and its imports, as its
+ * .aot carries them) differs from the project's - `amxts 0.2, the project
+ * has 0.3`, both whole within a line, an import of a later patch or of
+ * another shape - or false when the server's module would load it: a module
+ * built by one patch serves every patch of its line that has its imports.
+ */
+function otherAbi(built: string, have: string): string | false {
+	const [identity, ...imports] = built.split('\n');
+	if (abiLine(identity) !== abiLine(have)) {
+		const line = (abi: string) => releaseLine(abi.slice(0, abi.indexOf('+')));
+		return line(identity) === line(have) ? `amxts ${identity}, the project has ${have}` : `amxts ${line(identity)}, the project has ${line(have)}`;
+	}
+	const shapes = importShapes();
+	const misfit = imports.find(shape => shapes.get(importName(shape)) !== shape);
+	if (!misfit) return false;
+	const name = importName(misfit);
+	return shapes.has(name) ? `another shape of ${name}` : `amxts ${identity.slice(0, identity.indexOf('+'))} or later (it uses ${name}), the project has ${coreVersion()}`;
+}
+
 /** The `new Forward<...>("name")` calls of a package whose arguments are not all text: their names. */
 function typedForwards(pkg: ModulePackage): string[] {
 	const names: string[] = [];
@@ -261,6 +290,7 @@ async function prebuild(pkg: ModulePackage, sources: Sources): Promise<string> {
 	rmSync(dir, { recursive: true, force: true });
 	mkdirSync(dir, { recursive: true });
 	const owner = sources.ownerSource(pkg);
+	const core = installed(CORE_NAME, sources)!;
 	const plugin = { source: owner, output: '', root: CORE_PLUGINS, wamrc: wamrcPath(), signatures: join(CORE_DIR, 'runtime/natives.txt'), quick: false };
 	const natives: PluginNative[] = [];
 	const wasm = join(dir, `${pkg.short}.wasm`);
@@ -277,18 +307,19 @@ async function prebuild(pkg: ModulePackage, sources: Sources): Promise<string> {
 		const bytes = readFileSync(output);
 		systems[system] = { file: `${PREBUILT_DIR}/${system}/${pkg.short}.aot`, size: bytes.length, sha256: sha256(bytes) };
 	}
+	// The ABI the .aot carries: the identity, and the imports it uses.
+	const abi = readSection(new Uint8Array(readFileSync(wasm)), ABI_SECTION) ?? undefined;
 	rmSync(wasm, { force: true });
 
 	// What the compile read: its places in the tree, and the packages they are in.
 	const reached = sources.reach(join(CORE_PLUGINS, 'facade.ts'), sources.reach(join(CORE_PLUGINS, sources.entry(owner))));
 	const places = [...reached].map(place => posix(relative(CORE_PLUGINS, place))).sort();
 	const used = sources.project.modules.filter(each => each === pkg || [...reached].some(place => sources.packageOf(sources.real(place) ?? place) === each));
-	const core = installed(CORE_NAME, sources)!;
 	const manifest: PrebuiltManifest = {
 		format: FORMAT,
 		module: pkg.name,
 		version: pkg.version,
-		from: Object.fromEntries([[CORE_NAME, { version: core.version, hash: core.hash() }], ...used.map(each => [each.name, { version: each.version, hash: packageHash(each) }])]),
+		from: Object.fromEntries([[CORE_NAME, { version: core.version, hash: core.hash(), abi }], ...used.map(each => [each.name, { version: each.version, hash: packageHash(each) }])]),
 		options: Object.fromEntries(used.map(each => [each.name, optionsOf(sources.project, each.definition)])),
 		forwards: Object.fromEntries(used.flatMap(typedForwards).map(name => [name, declarationOf(name)])),
 		places,

package/scripts/project.ts

@@ -53,6 +53,7 @@ import { createRequire } from 'node:module';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import ts from 'typescript';
+import { serverFolder } from '../src/system.mjs';
 import { coreImports, importedName, importTable, withAutoImports } from './auto-imports';
 import { includeDirs } from './includes';
 import { existsSync, readdirSync, readFileSync, statSync } from './tracked-fs';
@@ -667,9 +668,56 @@ export function coreEntryOf(place: string): string {
 export function projectPlugins(project: Project): string[] {
 	const core = resolve(project.pluginsDir) === resolve(CORE_PLUGINS);
 	if (core && resolve(project.dir) !== resolve(CORE_DIR)) return [];
+	const stale = new Set(staleCopies(project));
 	return readdirSync(project.pluginsDir)
 		.filter(f => f.endsWith('.ts') && !f.endsWith('.d.ts') && !(core && NOT_PLUGINS.has(f)))
-		.map(f => join(project.pluginsDir, f));
+		.map(f => join(project.pluginsDir, f))
+		.filter(f => !stale.has(f));
+}
+
+/** A server's addons/amxts: the module's files, written over on every start. */
+export const SERVER_FOLDER = /[\\/]addons[\\/]amxts$/i;
+
+/** The server's addons/amxts that AMXTS_SERVER names, or '' when it names none. */
+export function serverDir(): string {
+	try {
+		const dir = serverFolder(process.env.AMXTS_SERVER ?? '');
+		return dir && resolve(dir);
+	} catch {
+		return '';
+	}
+}
+
+/**
+ * Copies of the core's own API at the top of the project's plugins folder,
+ * left there by an older amxts: a file named as one of the core's as/ (or
+ * the editor's imports.d.ts) whose first line is the core's - a generator's
+ * header or that file's own first line. An author's file of the same name
+ * starts otherwise and stays a plugin. A server's addons/amxts/plugins of
+ * an older amxts holds them too: its module wrote them there.
+ */
+export function staleCopies(project: Project): string[] {
+	const dir = resolve(project.pluginsDir);
+	const parent = dirname(dir);
+	if (!existsSync(dir) || dir === resolve(CORE_PLUGINS) || SERVER_FOLDER.test(parent) || parent === serverDir()) return [];
+	coreFirstLines ??= new Map([...readdirSync(CORE_PLUGINS).filter(f => f.endsWith('.ts')).map(f => [f, firstLine(join(CORE_PLUGINS, f))] as const), ['imports.d.ts', '// GENERATED by ']]);
+	const core = coreFirstLines;
+	return readdirSync(dir)
+		.filter((f) => {
+			const header = core.get(f);
+			if (header === undefined) return false;
+			const line = firstLine(join(dir, f));
+			return line.startsWith('// GENERATED by ') || line === header;
+		})
+		.sort()
+		.map(f => join(dir, f));
+}
+
+/** The first line of each file at the top of the core's as/, read once. */
+let coreFirstLines: Map<string, string> | undefined;
+
+function firstLine(path: string): string {
+	return readFileSync(path, 'utf8').split('\n', 1)[0].trimEnd();
 }
 
 /** The modules that run on the server - each in its owner plugin: every one but a library. */
@@ -747,7 +795,12 @@ export class Sources {
 	/** A plugin that imports a module package the config does not list. */
 	readonly problems: string[] = [];
 
-	constructor(readonly root: string, readonly project: Project) {}
+	/** Copies of the core's API an older amxts left in the plugins folder: the core's files are under them. */
+	private readonly stale: Set<string>;
+
+	constructor(readonly root: string, readonly project: Project) {
+		this.stale = new Set(staleCopies(project));
+	}
 
 	/**
 	 * Whether a file is a plugin's code, which auto-imports reach: the
@@ -792,14 +845,20 @@ export class Sources {
 		return this.project.modules.find(pkg => path === pkg.module || path === pkg.natives || ofPackage(pkg, path)) ?? null;
 	}
 
+	/** The project's own file at this place under its plugins folder, or null: an old copy of the core's API is not one. */
+	ownFile(place: string): string | null {
+		const own = join(this.project.pluginsDir, place);
+		return existsSync(own) && !this.stale.has(own) ? own : null;
+	}
+
 	/** The file on disk at this place in the tree, or null. */
 	real(path: string): string | null {
 		const rel = this.rel(path);
 		if (!inside(this.root, resolve(path))) return existsSync(path) ? resolve(path) : null;
 
 		if (this.project.pluginsDir !== resolve(this.root)) {
-			const own = join(this.project.pluginsDir, rel);
-			if (existsSync(own)) return own;
+			const own = this.ownFile(rel);
+			if (own) return own;
 		}
 		const core = resolve(this.root, rel);
 		if (existsSync(core)) return core;

package/scripts/reapi-events.ts

@@ -1,13 +1,13 @@
-// The game events reapi alone delivers - ReGameDLL's and ReHLDS's own
-// functions - and the build's refusal of a listener for one nothing else
+// The game events only ReGameDLL's and ReHLDS's hookchains deliver - their
+// own functions - and the build's refusal of a listener for one nothing else
 // hears, in a project for plain HLDS.
 //
-// A server without reapi hears every other game event through Ham Sandwich
-// (as/hooks.ts picks it once, by hasModule), and many of these through
-// another stock hook (scripts/hlds-events.ts); a listener for one of the rest
-// is only a line in its console. A project whose amxts.config.ts says
-// `target: "hlds"` has said there is no reapi, so the build stops at such a
-// listener instead, with the file and the line.
+// A server without them hears every other game event through the entity's
+// function in its class (as/hooks.ts picks it once), and many of these
+// through another stock hook (scripts/hlds-events.ts); a listener for one of
+// the rest is only a line in its console. A project whose amxts.config.ts
+// says `target: "hlds"` has said there is neither, so the build stops at
+// such a listener instead, with the file and the line.
 import { join } from 'node:path';
 // @ts-ignore - shipped as JavaScript, with types beside it we do not need here
 import * as asc from '../runtime/deps/assemblyscript/dist/assemblyscript.js';
@@ -76,7 +76,7 @@ export function reapiListeners(sources: any[], events = unheardEvents()): string
 			const event = gameEventOf(node);
 			if (event === undefined || !events.has(event)) return;
 			const line = source.text.slice(0, node.range.start).split('\n').length;
-			found.push(`${source.normalizedPath}:${line}: "${event}" needs ReAPI, and amxts.config.ts's target is "hlds" - nothing on plain HLDS hears it. Listen for another event, or set target: "rehlds"`);
+			found.push(`${source.normalizedPath}:${line}: "${event}" is ReGameDLL's or ReHLDS's own, and amxts.config.ts's target is "hlds" - nothing on plain HLDS hears it. Listen for another event, or set target: "rehlds"`);
 		});
 	}
 	return found;

package/scripts/server-env.ts

@@ -0,0 +1,145 @@
+// env(): the settings a plugin reads of the server's environment and of its
+// addons/amxts/.env, and the ones a plugin cannot start without.
+//
+//   const token = env("KZ_MAP_TOKEN");           // required text: the plugin does not start without it
+//   const limit = env("KZ_MAX_RECORDS", 100);    // a number, 100 when the server has none
+//   const debug = env("KZ_DEBUG", false);        // an on/off switch
+//
+// Each call's name, and the kind and value of its default, go into the
+// plugin's .aot as the section amxts.env, a line each: `KZ_MAP_TOKEN` for a
+// required one, `KZ_MAX_RECORDS number 100`, `KZ_DEBUG boolean false`,
+// `KZ_MIRROR string https://...`. The module refuses the plugin while a
+// required one is nowhere or one is there and not of its kind
+// (runtime/src/module.cpp, MissingEnv; envProblems here is the same), and
+// `amxts dev` warns of one the server's .env lacks. The name and the default
+// are written out in the call: the build reads them there. The module reads
+// .env as parseDotenv does.
+import ts from 'typescript';
+
+/** The custom section of a plugin that lists the variables it reads: wamrc copies it into the .aot. */
+export const ENV_SECTION = 'amxts.env';
+
+/** What a plugin imports the facade's env() from, once the build has rewritten its imports. */
+const FACADE = new Set(['~/facade', '@amxts/core']);
+
+/** A number as env() takes one: decimal, a fraction and an exponent allowed. */
+const NUMBER = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i;
+
+/** The words of an on/off switch, in any case. */
+const SWITCH = new Set(['1', '0', 'true', 'false', 'yes', 'no', 'on', 'off']);
+
+/**
+ * A .env file's variables: `KEY=value` lines, `#` comments, a value in
+ * quotes kept as it is - `#` and spaces too - and one without them cut at a
+ * ` #` comment and trimmed. A line without `=` is no variable.
+ */
+export function parseDotenv(text: string): Map<string, string> {
+	const variables = new Map<string, string>();
+	for (const raw of text.split('\n')) {
+		const line = raw.trim();
+		const at = line.indexOf('=');
+		if (line.startsWith('#') || at <= 0) continue;
+		const value = line.slice(at + 1).trim();
+		const quote = value[0];
+		const end = quote === '"' || quote === '\'' ? value.indexOf(quote, 1) : -1;
+		variables.set(line.slice(0, at).trim(), end > 0 ? value.slice(1, end) : value.replace(/\s+#.*$/, ''));
+	}
+	return variables;
+}
+
+/** One call of the facade's env(): its section line - null when its name or default is not written out - and its line in the file. */
+export interface EnvCall {
+	entry: string | null;
+	line: number;
+}
+
+/** A default as the section writes it - `number 100`, `boolean false`, `string text` - or null when it is not written out. */
+function defaultOf(node: ts.Expression): string | null {
+	if (ts.isStringLiteralLike(node)) return `string ${node.text}`;
+	if (ts.isNumericLiteral(node)) return `number ${node.text}`;
+	if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(node.operand)) return `number -${node.operand.text}`;
+	if (node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword) return `boolean ${node.getText()}`;
+	return null;
+}
+
+/** The calls of the facade's env() in a file, by the name it imports env() under. */
+export function envCallsOf(text: string): EnvCall[] {
+	if (!text.includes('env')) return [];
+	const source = ts.createSourceFile('file.ts', text, ts.ScriptTarget.Latest, true);
+	const local = source.statements.flatMap((statement) => {
+		if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier) || !FACADE.has(statement.moduleSpecifier.text)) return [];
+		const bindings = statement.importClause?.namedBindings;
+		return bindings && ts.isNamedImports(bindings) ? bindings.elements.filter(each => (each.propertyName ?? each.name).text === 'env').map(each => each.name.text) : [];
+	})[0];
+	if (!local) return [];
+
+	const calls: EnvCall[] = [];
+	const visit = (node: ts.Node) => {
+		if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === local) {
+			const [name, fallback] = node.arguments;
+			const kind = fallback ? defaultOf(fallback) : '';
+			calls.push({
+				entry: name && ts.isStringLiteralLike(name) && kind !== null ? `${name.text}${kind ? ` ${kind}` : ''}` : null,
+				line: source.getLineAndCharacterOfPosition(node.getStart()).line + 1,
+			});
+		}
+		ts.forEachChild(node, visit);
+	};
+	visit(source);
+	return calls;
+}
+
+/**
+ * One compile's section lines: `read` goes into the compile's readFile with
+ * every file the plugin reaches, `entries` gives them after, one a name, and
+ * `problems` each call whose name or default is not written out; a new one
+ * for every compile.
+ */
+export function envBuild() {
+	const entries = new Map<string, string>();
+	const problems: string[] = [];
+	return {
+		read(file: string, text: string): void {
+			for (const call of envCallsOf(text)) {
+				if (call.entry === null) {
+					problems.push(`${file.replace(/\\/g, '/')}:${call.line}: env() takes its name and its default written out - env("MYPLUGIN_TOKEN"), env("MYPLUGIN_LIMIT", 100), env("MYPLUGIN_DEBUG", false), env("MYPLUGIN_URL", "https://...") - the build reads what a plugin needs from the call`);
+					continue;
+				}
+				const name = call.entry.split(' ', 1)[0];
+				// Required wherever one call has no default.
+				if (!entries.has(name) || call.entry === name) entries.set(name, call.entry);
+			}
+		},
+		entries: () => [...entries.keys()].sort().map(name => entries.get(name)!),
+		problems,
+	};
+}
+
+/**
+ * What the section's lines need that `variables` has not, as the module's
+ * line names it: `KZ_MAP_TOKEN` for a required one missing,
+ * `KZ_MAX_RECORDS as a number` for one there and of another kind.
+ */
+export function envProblems(entries: string[], variables: Map<string, string>): string[] {
+	return entries.flatMap((entry) => {
+		const [name, kind] = entry.split(' ');
+		const value = variables.get(name);
+		if (value === undefined) return kind ? [] : [name];
+		if (kind === 'number' && !NUMBER.test(value)) return [`${name} as a number`];
+		if (kind === 'boolean' && !SWITCH.has(value.toLowerCase())) return [`${name} as a boolean`];
+		return [];
+	});
+}
+
+/** The section of a plugin's .aot by its name, as the module reads it (AotSection); null when it has none. */
+export function aotSection(aot: Uint8Array, wanted: string): string | null {
+	const view = new DataView(aot.buffer, aot.byteOffset, aot.byteLength);
+	const name = new TextEncoder().encode(`${wanted}\0`);
+	for (let at = 8; at + 8 <= aot.length; at = (at + 8 + view.getUint32(at + 4, true) + 3) & ~3) {
+		const length = view.getUint32(at + 4, true);
+		const body = at + 8;
+		if (view.getUint32(at, true) !== 100 || length < 6 + name.length || view.getUint32(body, true) !== 0 || view.getUint16(body + 4, true) !== name.length) continue;
+		if (name.every((byte, i) => aot[body + 6 + i] === byte)) return new TextDecoder().decode(aot.subarray(body + 6 + name.length, body + length));
+	}
+	return null;
+}

package/scripts/shared-modules.ts

@@ -18,7 +18,8 @@
 // What crosses, and how:
 //
 // - number, boolean, string (and a union of string literals, which is a
-//   string), arrays of them, `T | null`;
+//   string), arrays of them, `T | null`, a `Record<string, T>` - its keys
+//   and values in order; a rest parameter as its array;
 // - Player, by its id;
 // - an object the module hands out and takes back - it is returned by one
 //   exported function and taken by another: a config, a section - or hands
@@ -100,6 +101,7 @@ type Wire
 		| { kind: 'player' }
 		| { kind: 'null'; of: Wire }
 		| { kind: 'array'; of: Wire }
+		| { kind: 'dict'; of: Wire }
 		| { kind: 'fn'; params: Wire[]; result: Wire | null; sig: number }
 		| { kind: 'record'; cls: ClassInfo }
 		| { kind: 'handle'; cls: ClassInfo };
@@ -132,6 +134,8 @@ interface ExportedFunction {
 	paramNames: string[];
 	wires: Wire[];
 	result: Wire | null;
+	/** Its last parameter is a rest parameter, `...names: string[]`: the owner spreads the array into it. */
+	rest?: boolean;
 }
 
 export interface ModuleAnalysis {
@@ -434,6 +438,11 @@ function describe(program: any, name: string): ModuleAnalysis {
 				const of = toWire(cls.typeArguments[0], context);
 				return of ? { kind: 'array', of } : null;
 			}
+			// A Record of text keys, `{ KZ_CP: checkpoint }`: its keys and values, in order.
+			if (program.resolver.isRecordClass(cls) && String(cls.typeArguments[0]) === '~lib/string/String') {
+				const of = toWire(cls.typeArguments[1], context);
+				return of ? { kind: 'dict', of } : null;
+			}
 			if (cls.internalName === '~lib/~/facade/Player') return { kind: 'player' };
 			const info = classInfo(cls, context);
 			if (!info) return null;
@@ -459,13 +468,12 @@ function describe(program: any, name: string): ModuleAnalysis {
 		const params: string[] = [];
 		const paramNames: string[] = [];
 		const wires: Wire[] = [];
+		let rest = false;
 		declaration.signature.parameters.forEach((param: any, i: number) => {
 			const paramName = param.name.text;
 			const pcontext = where(`${context} - parameter "${paramName}"`);
-			if (param.parameterKind === as.ParameterKind.Rest) {
-				problems.push(`${pcontext}: a rest parameter cannot cross - take an array`);
-				return;
-			}
+			// A rest parameter crosses as the array it is.
+			if (param.parameterKind === as.ParameterKind.Rest) rest = true;
 			if (param.initializer && !plainDefault(param.initializer)) {
 				problems.push(`${pcontext}: its default is computed - the proxy evaluates it in the other plugin, so it has to be a literal`);
 				return;
@@ -484,7 +492,7 @@ function describe(program: any, name: string): ModuleAnalysis {
 		}
 		const result = returned === 'void' ? null : toWire(returns, where(`${context} - its result`));
 		if (returned !== 'void' && !result) return null;
-		return { name: fnName, params, paramNames, wires, result };
+		return { name: fnName, params, paramNames, wires, result, rest };
 	}
 
 	for (const { name: fnName, element, instance } of exported) {
@@ -573,6 +581,7 @@ function wireKey(wire: Wire): string {
 		case 'player': return 'player';
 		case 'null': return `${wireKey(wire.of)}?`;
 		case 'array': return `${wireKey(wire.of)}[]`;
+		case 'dict': return `{${wireKey(wire.of)}}`;
 		case 'fn': return `(${wire.params.map(wireKey).join(',')})=>${wire.result ? wireKey(wire.result) : 'void'}`;
 		case 'record': return `rec ${wire.cls.internal}`;
 		case 'handle': return `handle ${wire.cls.internal}`;
@@ -609,6 +618,7 @@ class Codec {
 			case 'player': return '__Player';
 			case 'null': return wire.of.kind === 'fn' ? `(${this.type(wire.of)}) | null` : `${this.type(wire.of)} | null`;
 			case 'array': return `Array<${this.type(wire.of)}>`;
+			case 'dict': return `Record<string, ${this.type(wire.of)}>`;
 			case 'fn': return `(${wire.params.map((p, i) => `a${i}: ${this.type(p)}`).join(', ')}) => ${wire.result ? this.type(wire.result) : 'void'}`;
 			case 'record':
 			case 'handle': return this.className(wire.cls);
@@ -677,6 +687,12 @@ class Codec {
 				lines.push(`function __r${n}(r: __Reader): ${T} {\n\tconst count = r.i32();\n\tconst list = new Array<${this.type(wire.of)}>();\n\tfor (let i: i32 = 0; i < count; i++) list.push(__r${inner}(r));\n\treturn list;\n}`);
 				break;
 			}
+			case 'dict': {
+				const inner = this.id(wire.of);
+				lines.push(`function __w${n}(w: __Writer, v: ${T}): void {\n\tconst keys = Object.keys(v);\n\tw.i32(keys.length);\n\tfor (let i: i32 = 0; i < keys.length; i++) {\n\t\tw.str(keys[i]);\n\t\t__w${inner}(w, v[keys[i]]);\n\t}\n}`);
+				lines.push(`function __r${n}(r: __Reader): ${T} {\n\tconst count = r.i32();\n\tconst record: ${T} = {};\n\tfor (let i: i32 = 0; i < count; i++) {\n\t\tconst key = r.str();\n\t\trecord[key] = __r${inner}(r);\n\t}\n\treturn record;\n}`);
+				break;
+			}
 			case 'fn':
 				lines.push(`function __w${n}(w: __Writer, v: ${T}): void { w.i32(__sendFunction(changetype<usize>(v), ${wire.sig}, __invoke)); }`);
 				lines.push(`function __r${n}(r: __Reader): ${T} { return changetype<${T}>(__receiveFunction(r, changetype<usize>(__stub${wire.sig}))); }`);
@@ -875,7 +891,7 @@ export function serveSource(analysis: ModuleAnalysis): string {
 
 	/** A call of `fn` on `target` - the module, or a handle's object read first. */
 	const callCase = (op: number, fn: ExportedFunction, target: string, before: string[]) => {
-		const args = fn.paramNames.map((_, i) => `a${i}`).join(', ');
+		const args = fn.paramNames.map((_, i) => `${fn.rest && i === fn.paramNames.length - 1 ? '...' : ''}a${i}`).join(', ');
 		const lines = [
 			...before,
 			...fn.wires.map((wire, i) => `\t\t\tconst a${i} = ${codec.read(wire, 'r')};`),

package/scripts/system.ts

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'node:url';
 import { executable, MODULE_FILE } from '../src/system.mjs';
 
 export type { ServerSystem, System } from '../src/system.mjs';
-export { describeSystem, detectServerSystem, executable, HOST_SYSTEM, manifestName, MODULE_FILE, moduleVersion, parseSystem, serverFiles, serverFolder, serverImage, serverSystem, SYSTEM_NAME, SYSTEMS, TARGET_ABI, WAMRC_PACKAGE, wamrcPath } from '../src/system.mjs';
+export { describeSystem, detectServerSystem, executable, HOST_SYSTEM, manifestName, MODULE_FILE, moduleAbiOf, moduleVersion, parseSystem, serverFiles, serverFolder, serverImage, serverSystem, SYSTEM_NAME, SYSTEMS, TARGET_ABI, WAMRC_PACKAGE, wamrcPath } from '../src/system.mjs';
 
 const CORE = resolve(fileURLToPath(new URL('..', import.meta.url)));