@amxts/core 0.2.3 → 0.3.0

package/scripts/upgrade.ts

@@ -29,14 +29,16 @@ import type { Kind } from './upgrade-names';
 // functions take one object, the menu's context, and an item is one object
 // with its title (scripts/upgrade-menus.ts). What is rewritten no longer
 // matches, so a second run changes nothing.
-import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import ts from 'typescript';
 import { MESSAGE_NAMES } from './client-messages';
-import { CORE_ENTRIES, CORE_PLUGINS, loadProject } from './project';
-import { apiFiles, serverFolder } from './system';
+import { CORE_ENTRIES, CORE_PLUGINS, loadProject, SERVER_FOLDER, serverDir, staleCopies } from './project';
+import { apiFiles } from './system';
+import { parseUsage } from './typed-commands';
 import { c, log } from './ui';
+import { upgradeCalls } from './upgrade-calls';
 import { upgradeMenus } from './upgrade-menus';
 import { COMMON, EVENTS, FLAG_NAMES, GAME_EVENT_FIELDS, HIDDEN, HIDDEN_EVENTS, JOIN_OPTIONS, RENAMED, SERVER_EVENT_CLASSES, SERVER_EVENT_FIELDS, SERVER_EVENTS, SERVER_EVENTS_BY_HAND, SERVER_FIELD_CLASSES, SERVER_GAME_EVENTS } from './upgrade-names';
 
@@ -188,10 +190,13 @@ export function upgradeHandlers(file: string, text: string): { text: string; cha
 		const handler = node.arguments[1];
 		if (!handler) return;
 		const player = method === 'addCommand';
+		// A command without arguments takes a handler of the player as it is.
+		const ofPlayer = player && takesNoArguments(node);
 
 		if (ts.isArrowFunction(handler) || ts.isFunctionExpression(handler)) {
 			const params = handler.parameters;
 			if (params.length === 0 || !ts.isIdentifier(params[0].name)) return;
+			if (ofPlayer && params.length === 1) return;
 			if (!player || readsWords(handler)) {
 				left.push({ file, line: lineOf(handler), why: BY_HAND });
 				return;
@@ -210,7 +215,7 @@ export function upgradeHandlers(file: string, text: string): { text: string; cha
 				left.push({ file, line: lineOf(handler), why: `${handler.getText(source)} is declared elsewhere: if it takes the player, pass ({ player }) => ${handler.getText(source)}(player)` });
 				return;
 			}
-			if (fn.parameters.length === 0) return;
+			if (fn.parameters.length === 0 || (ofPlayer && fn.parameters.length === 1)) return;
 			if (!player || fn.parameters.length > 1 || !ts.isIdentifier(fn.parameters[0].name)) {
 				left.push({ file, line: lineOf(handler), why: BY_HAND });
 				return;
@@ -222,6 +227,16 @@ export function upgradeHandlers(file: string, text: string): { text: string; cha
 	return { ...applyEdits(file, text, source, edits), left };
 }
 
+/** Whether a command's call adds one without arguments: no type argument, and none in its usage - the first name of an array of them. */
+function takesNoArguments(call: ts.CallExpression): boolean {
+	if (call.typeArguments?.length) return false;
+	const usage = call.arguments[0];
+	const first = usage && ts.isArrayLiteralExpression(usage) ? usage.elements[0] : usage;
+	if (!first || !ts.isStringLiteralLike(first)) return !first || !ts.isTemplateExpression(first);
+	const parsed = parseUsage(first.text);
+	return typeof parsed !== 'string' && parsed.args.length === 0;
+}
+
 /** A piece of a file's text to replace: where, with what, and what it was. */
 export interface Edit {
 	start: number;
@@ -775,9 +790,6 @@ export function upgradeFlags(file: string, text: string): { text: string; change
 /** Folders that are not the project's code: what is installed, built or generated. */
 const SKIP = new Set(['node_modules', 'dist', '.amxts', '.git']);
 
-/** A server's addons/amxts: the module's files, written over on every start. */
-const SERVER_FOLDER = /[\\/]addons[\\/]amxts$/i;
-
 /** The project's TypeScript files: its plugins, its tests and fixtures, a module's sources. */
 function codeFiles(dir: string, skip: Set<string>): string[] {
 	return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
@@ -787,37 +799,32 @@ function codeFiles(dir: string, skip: Set<string>): string[] {
 	});
 }
 
-/** The server's addons/amxts that AMXTS_SERVER names, or '' when it names none. */
-function serverDir(): string {
-	try {
-		const dir = serverFolder(process.env.AMXTS_SERVER ?? '');
-		return dir && resolve(dir);
-	} catch {
-		return '';
-	}
-}
-
 /**
- * The project's code to upgrade. The module's own files - the API a server
- * writes beside its plugins, at the core's version it runs - are not, in the
- * server's folder or a copy of one; a file of that name in the plugins
- * folder is the author's.
+ * The project's code to upgrade. The module's own files - the API an older
+ * server wrote beside its plugins - are not, in the server's folder or a copy
+ * of one; a file of that name in the plugins folder is the author's.
  */
 function projectFiles(dir: string, pluginsDir: string, outDir: string): string[] {
-	// The API at the top of as/, and the editor's globals: what the module
-	// writes beside the plugins (scripts/server-files.ts).
+	// The API at the top of as/, and the editor's globals: what an older
+	// module wrote beside the plugins.
 	const theirs = new Set([...apiFiles(), 'imports.d.ts']);
 	return codeFiles(dir, new Set([outDir, serverDir()])).filter(file => !theirs.has(basename(file)) || dirname(file) === pluginsDir);
 }
 
-/** Rewrites the project in `dir`: every change, in the order of the files, and what is left to do by hand. `write: false` only lists them. */
-export function upgradeProject(dir: string, { write = true } = {}): { changes: Change[]; left: Left[] } {
+/**
+ * Rewrites the project in `dir`: every change, in the order of the files, and
+ * what is left to do by hand. Then removes the copies of the core's API an
+ * older amxts left in the plugins folder - after the rewrite, so nothing
+ * still imports them by `~/`. `write: false` only lists them.
+ */
+export function upgradeProject(dir: string, { write = true } = {}): { changes: Change[]; left: Left[]; removed: string[] } {
 	const project = loadProject(dir);
 	const ownFolder = resolve(project.pluginsDir) !== resolve(CORE_PLUGINS);
-	const renames = renamesFor(project.modules, place => ownFolder && existsSync(join(project.pluginsDir, place)));
+	const stale = staleCopies(project);
+	const renames = renamesFor(project.modules, place => ownFolder && existsSync(join(project.pluginsDir, place)) && !stale.includes(join(project.pluginsDir, place)));
 	const changes: Change[] = [];
 	const left: Left[] = [];
-	for (const file of projectFiles(project.dir, resolve(project.pluginsDir), project.outDir)) {
+	for (const file of projectFiles(project.dir, resolve(project.pluginsDir), project.outDir).filter(file => !stale.includes(file))) {
 		const text = readFileSync(file, 'utf8');
 		const name = relative(project.dir, file).replace(/\\/g, '/');
 		const http = dropHttpImports(name, text);
@@ -830,12 +837,16 @@ export function upgradeProject(dir: string, { write = true } = {}): { changes: C
 		const events = upgradeEvents(name, names.text);
 		const messages = upgradeMessages(name, events.text);
 		const flags = upgradeFlags(name, messages.text);
-		left.push(...http.left, ...handlers.left, ...menus.left, ...names.left, ...events.left, ...messages.left, ...flags.left);
-		if (flags.text === text) continue;
-		if (write) writeFileSync(file, flags.text);
-		changes.push(...http.changes, ...imports.changes, ...handlers.changes, ...menus.changes, ...names.changes, ...events.changes, ...messages.changes, ...flags.changes);
+		const calls = upgradeCalls(name, flags.text);
+		left.push(...http.left, ...handlers.left, ...menus.left, ...names.left, ...events.left, ...messages.left, ...flags.left, ...calls.left);
+		if (calls.text === text) continue;
+		if (write) writeFileSync(file, calls.text);
+		changes.push(...http.changes, ...imports.changes, ...handlers.changes, ...menus.changes, ...names.changes, ...events.changes, ...messages.changes, ...flags.changes, ...calls.changes);
+	}
+	if (write) {
+		for (const file of stale) rmSync(file);
 	}
-	return { changes, left };
+	return { changes, left, removed: stale.map(file => basename(file)) };
 }
 
 // Run as a task (scripts/run.ts names it in argv) or by itself.
@@ -844,14 +855,16 @@ if (import.meta.main || resolve(process.argv[1] ?? '') === fileURLToPath(import.
 	// amxts command as JSON, which prints what is left to do in its summary.
 	const args = process.argv.slice(2);
 	const report = args.includes('--report') ? args[args.indexOf('--report') + 1] : undefined;
-	const { changes, left } = upgradeProject(process.cwd(), { write: !args.includes('--dry-run') });
+	const write = !args.includes('--dry-run');
+	const { changes, left, removed } = upgradeProject(process.cwd(), { write });
+	if (removed.length) log.success(`${write ? 'removed' : 'would remove'} amxts's old API copies from plugins/: ${removed.join(', ')}`);
 	for (const change of changes) console.log(`  ${c.dim(`${change.file}:${change.line}`)}  ${change.from} ${c.dim('→')} ${change.to}`);
 	if (report) {
 		writeFileSync(report, JSON.stringify({ changes, left }));
 	} else {
 		const files = new Set(changes.map(change => change.file)).size;
 		if (changes.length) log.success(`upgraded ${changes.length} place(s) in ${files} file(s)`);
-		else if (!left.length) log.success('nothing to upgrade: the code already uses this core\'s API');
+		else if (!left.length && !removed.length) log.success('nothing to upgrade: the code already uses this core\'s API');
 		for (const each of left) log.warn(`${each.file}:${each.line}  ${each.why}`);
 	}
 }

package/src/cli-api.mjs

@@ -84,7 +84,8 @@ const SCRIPTS = {
  * - `upgrade` rewrites the project's code to this core's API, listing each change;
  *   `--dry-run` writes nothing, `--report <file>` writes `{ changes, left }` there as JSON
  *   and leaves what is left to do by hand to the caller to print;
- * - `typecheck` runs TypeScript over the project, after `prepare`.
+ * - `typecheck` runs TypeScript over the project, after `prepare`, and says
+ *   what TypeScript allows and the build does not (src/typecheck.mjs).
  *
  * A failure is printed by the task itself and ends it with a non-zero code.
  *
@@ -94,7 +95,7 @@ const SCRIPTS = {
  */
 export function task(name, args = []) {
 	if (name === 'typecheck') {
-		return { runtime: 'node', args: [require.resolve('typescript/bin/tsc'), '--noEmit', '-p', '.amxts/tsconfig.json', ...args] };
+		return { runtime: 'node', args: [join(coreDir, 'src', 'typecheck.mjs'), ...args] };
 	}
 	const script = SCRIPTS[name];
 	if (!script) throw new Error(`@amxts/core ${version} has no task "${name}"`);

package/src/system.mjs

@@ -40,19 +40,14 @@ export const MODULE_FILE = { windows: 'amxts_amxx.dll', linux: 'amxts_amxx_i386.
 
 /**
  * The files of a system's GitHub Release that a server runs: the name each is
- * attached under, and where it goes under the game folder (cstrike). A `tool`
- * is the compiler for `.ts` plugins written on the server, which a server has
- * only when its kit put it there.
+ * attached under, and where it goes under the game folder (cstrike). A server
+ * runs the module alone - it loads plugins built elsewhere. `tool` is a file
+ * a server has only when its kit put it there; no such file is left.
  * @param {System} system
- * @returns {{ asset: string, path: string, tool: boolean }[]} the module first, then the tools
+ * @returns {{ asset: string, path: string, tool: boolean }[]} the module first
  */
 export function serverFiles(system) {
-	const suffix = `${system}-x64`;
-	return [
-		{ asset: MODULE_FILE[system], path: `addons/amxmodx/modules/${MODULE_FILE[system]}`, tool: false },
-		{ asset: executable(`amxts-compile-${suffix}`, system), path: `addons/amxts/tools/${executable('amxts-compile', system)}`, tool: true },
-		{ asset: executable(`wamrc-${suffix}`, system), path: `addons/amxts/tools/${executable('wamrc', system)}`, tool: true },
-	];
+	return [{ asset: MODULE_FILE[system], path: `addons/amxmodx/modules/${MODULE_FILE[system]}`, tool: false }];
 }
 
 /** A system's release manifest, attached beside its files: the version, and each file's size and sha256. */
@@ -77,8 +72,23 @@ const MODULE_ABI = /(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\+abi\.[0-9a-f]{8}/;
  * @returns {string | null} the version: `0.2.0`
  */
 export function moduleVersion(file) {
+	return moduleAbiMatch(file)?.[1] ?? null;
+}
+
+/**
+ * The ABI a module file loads plugins of, read as moduleVersion reads its
+ * release. Null when there is no file or no such string.
+ * @param {string} file
+ * @returns {string | null} the ABI: `0.2.0+abi.1a2b3c4d`
+ */
+export function moduleAbiOf(file) {
+	return moduleAbiMatch(file)?.[0] ?? null;
+}
+
+/** @param {string} file */
+function moduleAbiMatch(file) {
 	try {
-		return MODULE_ABI.exec(readFileSync(file, 'latin1'))?.[1] ?? null;
+		return MODULE_ABI.exec(readFileSync(file, 'latin1'));
 	} catch {
 		return null;
 	}

package/src/testing/compile.ts

@@ -11,6 +11,7 @@ import { playerFieldsBuild } from '../../scripts/player-fields';
 import { nativesBeside, nativesTransform, setNativesBeside } from '../../scripts/plugin-natives';
 import { ascPath, CONFIG_FILE, currentProjectDir, sourcesFor } from '../../scripts/project';
 import { targetTransforms } from '../../scripts/reapi-events';
+import { envBuild } from '../../scripts/server-env';
 import { sharedModulesBuild } from '../../scripts/shared-modules';
 import { existsSync, hashOf } from '../../scripts/tracked-fs';
 import { cached } from './compile-cache';
@@ -26,6 +27,8 @@ export interface Compiled {
 	binary: Uint8Array;
 	/** Whether it carries the coroutine scheduler's exports (as/promise.ts). */
 	async: boolean;
+	/** Its env() calls as the section amxts.env writes them, a line a name (scripts/server-env.ts). */
+	env: string[];
 }
 
 const compiled = new Map<string, Promise<Compiled>>();
@@ -77,6 +80,19 @@ function moduleOwner(source: string): string | null {
 /** A compile as the disk cache keeps it: no WebAssembly.Module, and an error as its text. */
 type Built = (Omit<Compiled, 'module'> & { beside: NativesBeside }) | { error: string };
 
+/**
+ * `AMXTS_GC_STRESS=1` in the environment: every plugin and snippet a test
+ * compiles runs a step of the collector on every allocation
+ * (`ASC_GC_STRESS`), so a value a function holds without a shadow-stack
+ * slot is freed at once and its test fails. Part of the cache's key.
+ */
+const GC_STRESS = process.env.AMXTS_GC_STRESS ? ['--use', 'ASC_GC_STRESS=1'] : [];
+
+/** `args` with GC_STRESS, unless they ask for it themselves. */
+export function stressed(args: string[]): string[] {
+	return args.includes('ASC_GC_STRESS=1') ? args : [...args, ...GC_STRESS];
+}
+
 /** A failure worth keeping on disk is the compiler's; a file that could not be opened is not. */
 const PASSING = /\b(?:EBUSY|EPERM|EACCES|EMFILE|ENFILE|EAGAIN)\b/;
 
@@ -89,7 +105,7 @@ function lasting(built: Built): boolean {
  * when an earlier run compiled it from the same files.
  */
 async function build(path: string): Promise<Compiled> {
-	const built = await cached<Built>(['plugin', process.cwd(), path, PLUGINS_ROOT], async () => {
+	const built = await cached<Built>(['plugin', process.cwd(), path, PLUGINS_ROOT, GC_STRESS], async () => {
 		try {
 			const fresh = await buildFresh(path);
 			return { ...fresh, beside: nativesBeside(fresh.natives) };
@@ -127,11 +143,12 @@ async function buildWith(path: string, hoodExports: string): Promise<Omit<Compil
 	let binary: Uint8Array | undefined;
 	const natives: PluginNative[] = [];
 	const playerFields = playerFieldsBuild();
+	const env = envBuild();
 	// scripts/compile.ts's shared modules: a proxy for one another plugin owns.
 	const shared = await sharedModulesBuild(PLUGINS_ROOT, entry);
 
 	const { error, stderr } = await ascMain(
-		[entry, HOOD_EXPORTS, '--outFile', 'plugin.wasm', '--optimize', '--exportTable', '--exportStart', '_start'],
+		stressed([entry, HOOD_EXPORTS, '--outFile', 'plugin.wasm', '--optimize', '--exportTable', '--exportStart', '_start']),
 		{
 			// scripts/compile.ts's readFile: the `~/` alias, the hood's exports and the fields plugins add to Player.
 			readFile(filename: string, baseDir: string): string | null {
@@ -139,7 +156,10 @@ async function buildWith(path: string, hoodExports: string): Promise<Omit<Compil
 
 				const file = ascPath(PLUGINS_ROOT, filename, baseDir);
 				const text = sources.read(file);
-				return text === null ? null : shared.read(file, playerFields.read(relative('.', (sources.real(file) ?? file)), text));
+				if (text === null) return null;
+				const shown = relative('.', (sources.real(file) ?? file));
+				env.read(shown, text);
+				return shared.read(file, playerFields.read(shown, text));
 			},
 			// Only the binary is wanted; nothing is written to disk.
 			writeFile(_: string, contents: string | Uint8Array) {
@@ -151,12 +171,13 @@ async function buildWith(path: string, hoodExports: string): Promise<Omit<Compil
 	);
 
 	if (sources.problems.length) throw new Error(sources.problems.join('\n'));
+	if (env.problems.length) throw new Error(env.problems.join('\n'));
 
 	if (error || !binary) {
 		throw new Error(`${relative(process.cwd(), path)} does not compile:\n${stderr.toString() || String(error?.message ?? error)}`);
 	}
 
-	return { natives, binary, async: false };
+	return { natives, binary, async: false, env: env.entries() };
 }
 
 /**
@@ -188,19 +209,21 @@ export interface SourcesCompiled {
 /**
  * asc - the patched one, as the build runs it - on `sources` alone, a test's
  * snippet of the compiler at work, with the disk cache in front. Nothing is
- * read from disk, so the sources and `args` are the whole key.
+ * read from disk, so the sources and `args` are the whole key. `finished`
+ * adds what a full build does after asc's optimiser (finishing).
  */
-export async function compileSources(args: string[], sources: Record<string, string>): Promise<SourcesCompiled> {
-	return cached<SourcesCompiled>(['sources', args, sources], async () => {
+export async function compileSources(args: string[], sources: Record<string, string>, finished = false): Promise<SourcesCompiled> {
+	return cached<SourcesCompiled>(['sources', stressed(args), sources, finished], async () => {
 		let binary: Uint8Array | null = null;
 		const text: Record<string, string> = {};
-		const { error, stderr } = await ascMain(args, {
+		const { error, stderr } = await ascMain(stressed(args), {
 			readFile: (name: string) => sources[name] ?? null,
 			writeFile(name: string, contents: string | Uint8Array) {
 				if (typeof contents === 'string') text[name] = contents;
 				else binary = contents;
 			},
 			listFiles: () => [],
+			transforms: finished ? [finishing(BASE_EXPORTS, null)] : [],
 		});
 		return error ? { error: stderr.toString(), binary: null, text } : { error: null, binary, text };
 	});

package/src/testing/coroutines.ts

@@ -24,15 +24,6 @@ interface Coroutine {
 	drop: boolean;
 }
 
-// co_id(): a task id no other plugin on the server has, as module.cpp's is -
-// one counter for every plugin.
-let nextId = 0x60000000;
-
-/** The next of those ids. @internal */
-export function nextTaskId(): number {
-	return nextId++;
-}
-
 export class Coroutines {
 	/** What a trap inside a coroutine said: it drops that one coroutine, as on the server. */
 	readonly traps: string[] = [];
@@ -81,7 +72,6 @@ export class Coroutines {
 				this.exports.asyncify_start_unwind(coroutine.buffer);
 			},
 			co_wake: () => { this.wake = true; },
-			co_id: nextTaskId,
 		};
 	}
 

package/src/testing/memory.ts

@@ -22,6 +22,22 @@ export function bitsFloat(cell: number): number {
 	return floatView[0];
 }
 
+/** How many of the bytes are whole UTF-8 characters: a last one cut short is left out. */
+function wholeUtf8(bytes: Uint8Array): number {
+	let lead = bytes.length;
+	while (lead > 0 && (bytes[lead - 1] & 0xC0) === 0x80) lead--;
+	if (lead === 0 || bytes[lead - 1] < 0xC0) return bytes.length;
+	const size = bytes[lead - 1] >= 0xF0 ? 4 : bytes[lead - 1] >= 0xE0 ? 3 : 2;
+	return bytes.length - (lead - 1) < size ? lead - 1 : bytes.length;
+}
+
+// The AMX heap the module passes text through (Frame::inText, outText):
+// cells of the fake's own at addresses past any plugin's memory, which a
+// native reads and writes as it does the plugin's.
+const HEAP = 0x7F000000;
+// The longest text that crosses, in bytes and its terminator (MAX_CROSSING_CELLS).
+const CROSSING_CELLS = 16384;
+
 /** How many of the bytes fit in `max` without cutting a UTF-8 character in two. */
 export function utf8Fit(bytes: Uint8Array, max: number): number {
 	let length = Math.min(bytes.length, max);
@@ -31,6 +47,8 @@ export function utf8Fit(bytes: Uint8Array, max: number): number {
 
 export class Memory {
 	private dataView?: DataView;
+	private heap = new Int32Array(1 << 18);
+	private heapTop = 0;
 
 	constructor(private exports: any) {}
 
@@ -42,11 +60,70 @@ export class Memory {
 	}
 
 	cell(pointer: number): number {
-		return this.view.getInt32(pointer, true);
+		return pointer >= HEAP ? this.heap[(pointer - HEAP) >> 2] : this.view.getInt32(pointer, true);
+	}
+
+	byte(pointer: number): number {
+		return this.view.getUint8(pointer);
 	}
 
 	setCell(pointer: number, value: number): void {
-		this.view.setInt32(pointer, value | 0, true);
+		if (pointer >= HEAP) this.heap[(pointer - HEAP) >> 2] = value | 0;
+		else this.view.setInt32(pointer, value | 0, true);
+	}
+
+	/**
+	 * A native's call as the module's thunk makes it, by the native's marks in
+	 * runtime/natives.txt: an `s` argument is the plugin's string, handed to
+	 * the native as a Pawn string on the heap; a `t` one is a buffer the
+	 * native fills on the heap, back in the plugin as UTF-8 bytes up to its end.
+	 */
+	across(marks: readonly string[], args: number[], call: (cells: number[]) => number): number {
+		const top = this.heapTop;
+		try {
+			const cells = args.map((arg, i) => marks[i] === 's' ? this.heapText(this.string(arg)) : marks[i] === 't' ? this.heapCells(args[i + 1] + 1) : arg);
+			const result = call(cells);
+			marks.forEach((mark, i) => {
+				if (mark !== 't') return;
+				const bytes = this.bytes(cells[i], args[i + 1]);
+				const kept = bytes.subarray(0, wholeUtf8(bytes));
+				this.setRaw(args[i], Uint8Array.of(...kept, 0));
+				this.setTextHead(args[i], kept);
+			});
+			return result;
+		} finally {
+			this.heapTop = top;
+		}
+	}
+
+	/** Frame::backText's head before a text a native filled: its count, the top bit for one not ASCII, and its hash. */
+	private setTextHead(pointer: number, bytes: Uint8Array): void {
+		// As the module's: four bytes a word, little-endian, while all four are there, then a byte at a time.
+		let hash = 0;
+		let bits = 0;
+		let i = 0;
+		for (; i + 4 <= bytes.length; i += 4) hash = (Math.imul(hash, 31) + (bytes[i] | bytes[i + 1] << 8 | bytes[i + 2] << 16 | bytes[i + 3] << 24)) >>> 0;
+		for (; i < bytes.length; i++) hash = (Math.imul(hash, 31) + bytes[i]) >>> 0;
+		for (const byte of bytes) bits |= byte;
+		this.view.setUint32(pointer - 8, (bytes.length | (bits >= 0x80 ? 0x80000000 : 0)) >>> 0, true);
+		this.view.setUint32(pointer - 4, hash, true);
+	}
+
+	/** `count` empty cells of the heap: their address. */
+	private heapCells(count: number): number {
+		const at = this.heapTop;
+		this.heapTop += Math.min(Math.max(count, 1), CROSSING_CELLS);
+		this.heap.fill(0, at, this.heapTop);
+		return HEAP + at * 4;
+	}
+
+	/** Text as a Pawn string on the heap, cut at the longest that crosses, between letters. */
+	private heapText(text: string): number {
+		const bytes = encoder.encode(text);
+		const length = utf8Fit(bytes, CROSSING_CELLS - 1);
+		const at = this.heapCells(length + 1);
+		this.heap.set(bytes.subarray(0, length), (at - HEAP) >> 2);
+		return at;
 	}
 
 	float(pointer: number): number {
@@ -61,6 +138,16 @@ export class Memory {
 		return [this.float(pointer), this.float(pointer + 4), this.float(pointer + 8)];
 	}
 
+	/** A plugin's number (f64) read from its own memory. */
+	number(pointer: number): number {
+		return this.view.getFloat64(pointer, true);
+	}
+
+	/** A plugin's number (f64) in its own memory. */
+	setNumber(pointer: number, value: number): void {
+		this.view.setFloat64(pointer, value, true);
+	}
+
 	setVector(pointer: number, value: number[]): void {
 		for (let i = 0; i < 3; i++) this.setFloat(pointer + i * 4, value[i] ?? 0);
 	}