@amxts/core 0.1.0

package/src/testing/compile.ts

@@ -0,0 +1,222 @@
+import type { NativesBeside, PluginNative } from '../../scripts/plugin-natives';
+// A plugin compiled for a test: the same AssemblyScript, the same facade and
+// the same flags as scripts/compile.ts, stopping at the .wasm - bun runs that
+// directly, so wamrc and its .aot are not needed.
+import { spawnSync } from 'node:child_process';
+import { readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { ascMain } from '../../scripts/asc';
+import { ASYNC_EXPORTS, asyncify, BASE_EXPORTS, compileToWasm, HoistImports, HOOD_EXPORTS, importsOf } from '../../scripts/compile';
+import { playerFieldsBuild } from '../../scripts/player-fields';
+import { nativesBeside, nativesTransform, setNativesBeside } from '../../scripts/plugin-natives';
+import { ascPath, CONFIG_FILE, currentProjectDir, sourcesFor } from '../../scripts/project';
+import { sharedModulesBuild } from '../../scripts/shared-modules';
+import { existsSync, hashOf } from '../../scripts/tracked-fs';
+import { cached } from './compile-cache';
+import { PLUGINS_ROOT } from './tables';
+
+declare const WebAssembly: any;
+
+/** A compiled plugin, and the natives its `export function`s became. */
+export interface Compiled {
+	module: any;
+	natives: PluginNative[];
+	/** The binary, for a plugin that awaits: the scheduler reads its function table. */
+	binary: Uint8Array;
+	/** Whether it carries the coroutine scheduler's exports (as/promise.ts). */
+	async: boolean;
+}
+
+const compiled = new Map<string, Promise<Compiled>>();
+
+/** Forgets what this run compiled, so that the next compile() asks the disk cache again. */
+export function forgetCompiled() {
+	compiled.clear();
+}
+
+/**
+ * The plugin at `source` as a WebAssembly.Module, compiled once per test run.
+ *
+ * One flag differs from the server build: `--exportStart`. On the server WAMR
+ * runs a plugin's top level while it instantiates, and its natives can read
+ * the plugin's memory while that happens. A JavaScript import cannot - the
+ * instance, and the memory with it, exists only once instantiation is over -
+ * so the top level is exported as `_start` and the fake calls it straight
+ * afterwards. The order of everything is the same.
+ */
+export function compile(source: string): Promise<Compiled> {
+	const path = moduleOwner(source) ?? resolve(source);
+	// A module's owner is ~/<name>.ts in every project, with the options that
+	// project's amxts.config.ts merges into it: the project and its config are
+	// part of what was compiled.
+	const config = join(currentProjectDir(), CONFIG_FILE);
+	const key = [path, currentProjectDir(), existsSync(config) ? statSync(config).mtimeMs : 'none'].join('\0');
+	let module = compiled.get(key);
+
+	if (!module) {
+		module = build(path);
+		compiled.set(key, module);
+	}
+
+	return module;
+}
+
+/**
+ * A module package by name - "@amxts/menu-core" - is its owner plugin: its
+ * natives, or the one the build generates for a module without them.
+ */
+function moduleOwner(source: string): string | null {
+	if (!/^@?[\w.-]+(?:\/[\w.-]+)?$/.test(source) || source.endsWith('.ts')) return null;
+	const sources = sourcesFor(PLUGINS_ROOT);
+	const pkg = sources.project.modules.find(each => each.name === source);
+	return pkg ? sources.ownerSource(pkg) : 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 };
+
+/** 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/;
+
+function lasting(built: Built): boolean {
+	return !('error' in built) || !PASSING.test(built.error);
+}
+
+/**
+ * The plugin compiled - or taken from the disk cache (./compile-cache.ts),
+ * 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 () => {
+		try {
+			const fresh = await buildFresh(path);
+			return { ...fresh, beside: nativesBeside(fresh.natives) };
+		} catch (problem) {
+			return { error: String((problem as Error).message ?? problem) };
+		}
+	}, lasting);
+	if ('error' in built) throw new Error(built.error);
+	const { beside, ...compiled } = built;
+	setNativesBeside(compiled.natives, beside);
+	return { ...compiled, module: new WebAssembly.Module(compiled.binary) };
+}
+
+/**
+ * A plugin that makes a promise is compiled again with the scheduler's
+ * exports and run through Asyncify, as scripts/compile.ts builds it for a
+ * server - so an async function parks and resumes here as it does there.
+ */
+async function buildFresh(path: string): Promise<Omit<Compiled, 'module'>> {
+	const first = await buildWith(path, BASE_EXPORTS);
+	if (!importsOf(first.binary).has('env.co_wake')) return first;
+
+	const second = await buildWith(path, ASYNC_EXPORTS);
+	return { natives: second.natives, binary: asyncify(second.binary), async: true };
+}
+
+async function buildWith(path: string, hoodExports: string): Promise<Omit<Compiled, 'module'>> {
+	const sources = sourcesFor(PLUGINS_ROOT);
+	if (!existsSync(path) && !sources.exists(path)) throw new Error(`no plugin at ${path}`);
+
+	// A module package's plugin compiles as ~/<name>.ts (scripts/project.ts).
+	if (sources.project.problems.length) throw new Error(sources.project.problems.join('\n'));
+	const entry = sources.entry(path);
+	let binary: Uint8Array | undefined;
+	const natives: PluginNative[] = [];
+	const playerFields = playerFieldsBuild();
+	// 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'],
+		{
+			// 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 {
+				if (filename.replace(/\\/g, '/').endsWith(HOOD_EXPORTS)) return hoodExports;
+
+				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));
+			},
+			// Only the binary is wanted; nothing is written to disk.
+			writeFile(_: string, contents: string | Uint8Array) {
+				if (typeof contents !== 'string') binary = contents;
+			},
+			listFiles: () => [],
+			transforms: [HoistImports, nativesTransform(entry, natives, PLUGINS_ROOT), playerFields.transform, shared.transform],
+		},
+	);
+
+	if (sources.problems.length) throw new Error(sources.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 };
+}
+
+/**
+ * scripts/compile.ts's compileToWasm - the server build's first half - with
+ * the disk cache in front: the problem it reports, or null and `wasm` written.
+ */
+export async function compileWasmFile(plugin: { source: string; root: string }, wasm: string, names = false): Promise<string | null> {
+	const made = await cached<{ problem: string } | { binary: Uint8Array }>(
+		['wasm', process.cwd(), resolve(plugin.source), resolve(plugin.root), resolve(wasm), names],
+		async () => {
+			const problem = await compileToWasm(plugin, wasm, names);
+			return problem === null ? { binary: new Uint8Array(readFileSync(wasm)) } : { problem };
+		},
+		made => !('problem' in made) || !PASSING.test(made.problem),
+	);
+	if ('problem' in made) return made.problem;
+	writeFileSync(wasm, made.binary);
+	return null;
+}
+
+/** What asc made of sources held in memory: the binary and the text files it wrote, or what it printed. */
+export interface SourcesCompiled {
+	error: string | null;
+	binary: Uint8Array | null;
+	/** Text outputs by the name asc was given: `--textFile probe.wat`. */
+	text: Record<string, string>;
+}
+
+/**
+ * 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.
+ */
+export async function compileSources(args: string[], sources: Record<string, string>): Promise<SourcesCompiled> {
+	return cached<SourcesCompiled>(['sources', args, sources], async () => {
+		let binary: Uint8Array | null = null;
+		const text: Record<string, string> = {};
+		const { error, stderr } = await ascMain(args, {
+			readFile: (name: string) => sources[name] ?? null,
+			writeFile(name: string, contents: string | Uint8Array) {
+				if (typeof contents === 'string') text[name] = contents;
+				else binary = contents;
+			},
+			listFiles: () => [],
+		});
+		return error ? { error: stderr.toString(), binary: null, text } : { error: null, binary, text };
+	});
+}
+
+/**
+ * wamrc from `wasm` to `aot`, with the disk cache in front - keyed by the
+ * binary, wamrc itself and its arguments: its exit status and what it printed.
+ */
+export async function compileAot(wamrc: string, args: string[], wasm: string, aot: string): Promise<{ status: number | null; output: string }> {
+	const made = await cached<{ status: number | null; output: string; aot?: Uint8Array }>(
+		['aot', hashOf(readFileSync(wasm)), hashOf(readFileSync(wamrc)), args],
+		async () => {
+			const run = spawnSync(wamrc, [...args, '-o', aot, wasm], { encoding: 'utf-8' });
+			const output = `${run.stdout}${run.stderr}`;
+			return run.status === 0 ? { status: 0, output, aot: new Uint8Array(readFileSync(aot)) } : { status: run.status, output };
+		},
+		made => made.status === 0,
+	);
+	if (made.aot) writeFileSync(aot, made.aot);
+	return { status: made.status, output: made.output };
+}

package/src/testing/coroutines.ts

@@ -0,0 +1,191 @@
+// The module's coroutine scheduler, for a plugin that awaits on the fake
+// server: co_spawn, co_suspend, the shadow-stack park and the jobs run once
+// the plugin's stack is empty, as runtime/src/module.cpp runs them (and
+// tests/async-host.ts, which checks the protocol on its own).
+//
+// A plugin with no async function imports none of this and never gets here.
+// @ts-ignore - its types are beside it, under a path tsconfig does not map
+import binaryen from '../../runtime/deps/assemblyscript/node_modules/binaryen/index.js';
+
+// Must match CO_* in runtime/src/module.cpp and as/promise.ts.
+const CO_FINISHED = 0;
+const CO_PARKED = 1;
+const CO_TRAPPED = 2;
+const CO_DROPPED = 3;
+
+type Kind = 'i32' | 'i64' | 'f32' | 'f64';
+
+interface Coroutine {
+	id: number;
+	fn: number;
+	cells: Uint32Array;
+	buffer: number;
+	base: number;
+	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[] = [];
+
+	private exports: any = null;
+	private kinds = new Map<number, Kind[]>();
+	private coroutines = new Map<number, Coroutine>();
+	private running: Coroutine[] = [];
+	private wake = false;
+	private entering = false;
+	private top = 0;
+	/** How deep the server is inside this plugin: jobs run when it is out. */
+	depth = 0;
+
+	constructor(wasm: Uint8Array) {
+		this.readTable(wasm);
+	}
+
+	/** The imports the scheduler answers. */
+	imports(): Record<string, (...args: any[]) => any> {
+		return {
+			co_entered: () => {
+				const entering = this.entering;
+				this.entering = false;
+				return entering ? 1 : 0;
+			},
+			co_spawn: (fn: number, args: number, cells: number, id: number, buffer: number) => {
+				const coroutine: Coroutine = {
+					id,
+					fn,
+					buffer,
+					drop: false,
+					cells: new Uint32Array(this.exports.memory.buffer.slice(args, args + cells * 4)),
+					base: this.exports.__co_stack(),
+				};
+				this.coroutines.set(id, coroutine);
+				return this.run(coroutine, false);
+			},
+			co_suspend: (drop: number) => {
+				if (this.exports.asyncify_get_state() === 2) {
+					this.exports.asyncify_stop_rewind();
+					return;
+				}
+				const coroutine = this.running[this.running.length - 1];
+				coroutine.drop = drop !== 0;
+				this.exports.asyncify_start_unwind(coroutine.buffer);
+			},
+			co_wake: () => { this.wake = true; },
+			co_id: nextTaskId,
+		};
+	}
+
+	/** Once the instance is there: where the shadow stack starts with nothing running. */
+	attach(exports: any): void {
+		this.exports = exports;
+		this.top = exports.__co_stack ? exports.__co_stack() : 0;
+	}
+
+	/** Whether a job is waiting to run. */
+	get waiting(): boolean {
+		return this.wake;
+	}
+
+	/** Runs the plugin's jobs once nothing of it is on the stack - module.cpp's DrainJobs. */
+	drain(): void {
+		if (!this.wake || !this.exports?.__co_next) return;
+		this.wake = false;
+		if (this.top) this.exports.__co_stack_set(this.top);
+		for (;;) {
+			const id = this.exports.__co_next();
+			if (id === 0) break;
+			const coroutine = this.coroutines.get(id);
+			const outcome = coroutine ? this.run(coroutine, true) : CO_FINISHED;
+			this.exports.__co_done(outcome);
+		}
+	}
+
+	/** One call into a coroutine, first or resumed - module.cpp's RunCoroutine. */
+	private run(coroutine: Coroutine, rewind: boolean): number {
+		const outer = this.exports.__co_stack();
+		const memory = this.exports.memory;
+		if (rewind) {
+			const low = coroutine.base - this.exports.__co_saved(coroutine.id);
+			new Uint8Array(memory.buffer, coroutine.base, outer - coroutine.base).fill(0);
+			this.exports.__co_stack_set(low);
+			this.exports.__co_restore(coroutine.id, low);
+			this.exports.asyncify_start_rewind(coroutine.buffer);
+		} else {
+			this.entering = true;
+		}
+
+		this.running.push(coroutine);
+		try {
+			this.callRaw(coroutine.fn, coroutine.cells);
+		} catch (error) {
+			this.running.pop();
+			this.traps.push((error as Error).message);
+			const state = this.exports.asyncify_get_state();
+			if (state === 1) this.exports.asyncify_stop_unwind();
+			if (state === 2) this.exports.asyncify_stop_rewind();
+			this.exports.__co_stack_set(outer);
+			this.coroutines.delete(coroutine.id);
+			return CO_TRAPPED;
+		}
+		this.running.pop();
+
+		if (this.exports.asyncify_get_state() !== 1) {
+			this.exports.__co_stack_set(outer);
+			this.coroutines.delete(coroutine.id);
+			return CO_FINISHED;
+		}
+		this.exports.asyncify_stop_unwind();
+		if (coroutine.drop) {
+			this.exports.__co_stack_set(outer);
+			this.coroutines.delete(coroutine.id);
+			return CO_DROPPED;
+		}
+		this.exports.__co_save(coroutine.id, this.exports.__co_stack(), coroutine.base);
+		this.exports.__co_stack_set(outer);
+		return CO_PARKED;
+	}
+
+	/** call_indirect with the cells co_spawn copied, each read as the parameter it is. */
+	private callRaw(fn: number, cells: Uint32Array) {
+		const bytes = new DataView(new Uint32Array(Array.from(cells)).buffer);
+		const args: (number | bigint)[] = [];
+		let at = 0;
+		for (const kind of this.kinds.get(fn) ?? []) {
+			if (kind === 'i32') args.push(bytes.getInt32(at, true));
+			if (kind === 'f32') args.push(bytes.getFloat32(at, true));
+			if (kind === 'i64') args.push(bytes.getBigInt64(at, true));
+			if (kind === 'f64') args.push(bytes.getFloat64(at, true));
+			at += kind === 'i64' || kind === 'f64' ? 8 : 4;
+		}
+		return this.exports.table.get(fn)(...args);
+	}
+
+	/** The parameter types of every function in the table, by index. */
+	private readTable(wasm: Uint8Array) {
+		const module = binaryen.readBinary(wasm);
+		try {
+			const kindOf = (type: number): Kind =>
+				type === binaryen.i64 ? 'i64' : type === binaryen.f32 ? 'f32' : type === binaryen.f64 ? 'f64' : 'i32';
+			for (let i = 0; i < module.getNumElementSegments(); i++) {
+				const segment = binaryen.getElementSegmentInfo(module.getElementSegmentByIndex(i));
+				const offset = (binaryen.getExpressionInfo(segment.offset as any) as any).value as number;
+				segment.data.forEach((name: string, at: number) => {
+					const info = binaryen.getFunctionInfo(module.getFunction(name));
+					this.kinds.set(offset + at, binaryen.expandType(info.params).map(kindOf));
+				});
+			}
+		} finally {
+			module.dispose();
+		}
+	}
+}

package/src/testing/index.ts

@@ -0,0 +1,39 @@
+// @amxts/core/test-utils: unit tests for amxts plugins and modules, without a
+// game server.
+//
+//   import { loadPlugin, setup } from "@amxts/core/test-utils";
+//
+//   const server = await setup();                      // the project: its modules, then its plugins
+//   const player = server.join("Alice", { team: "CT" });
+//   player.say("/tour");
+//   expect(player.chat).toContain("100 HP");
+//
+// The plugin is the real one - compiled by the same AssemblyScript, against
+// the same facade and generated natives - and runs under WebAssembly with a
+// fake server behind its imports. See docs/en/7.testing/01.index.md.
+import type { ServerOptions } from './server';
+import { FakeServer } from './server';
+
+export { defineTestKit } from './kits';
+export type { TestKit } from './kits';
+export { bitsFloat, floatBits, Memory } from './memory';
+export type { Native, NativeCall } from './natives';
+export { FakeEntity, FakePlayer, FakeServer, FakeWeapon, PluginInstance } from './server';
+export type { ArgValue, HookResult, JoinOptions, Message, NativeResult, SentForward, ServerOptions, TeamName, UserMessage, Value } from './server';
+export { setup } from './setup';
+export type { SetupOptions } from './setup';
+export { constant } from './tables';
+
+/**
+ * Compiles a plugin (once per test run), loads it into a new fake server and
+ * starts the map: its top level runs, then plugin_init and plugin_cfg.
+ *
+ * Several plugins go into one server as an array - they hear each other's
+ * forwards and natives, as on a real one.
+ */
+export async function loadPlugin(source: string | string[], options: ServerOptions = {}): Promise<FakeServer> {
+	const server = new FakeServer(options);
+	for (const file of Array.isArray(source) ? source : [source]) await server.load(file);
+	server.start();
+	return server;
+}

package/src/testing/kits.ts

@@ -0,0 +1,55 @@
+// A module's test kit: what the fake server needs to run the module - the
+// natives its plugin calls that the fake does not answer, the messages it
+// sends read back for a test. The module ships it and names it in its
+// package.json, and the fake server installs it before the module's plugin
+// loads:
+//
+//   "amxts": { "module": "src/index.ts", "testing": "testing/index.ts" }
+//
+//   // testing/index.ts
+//   import { defineTestKit } from "@amxts/core/test-utils";
+//   export default defineTestKit({ install: server => installMenus(server) });
+import type { ModulePackage } from '../../scripts/project';
+import type { FakeServer } from './server';
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { sourcesFor } from '../../scripts/project';
+import { PLUGINS_ROOT } from './tables';
+
+/** What a module's test kit does to a new fake server - before any plugin loads. */
+export interface TestKit<T = unknown> {
+	/**
+	 * Adds what the module needs on the fake server - `server.defineNative`,
+	 * `server.messageListeners` - and gives back what its tests use.
+	 */
+	install: (server: FakeServer) => T;
+}
+
+/**
+ * A module's test kit, as the default export of the file its package.json
+ * names in `"amxts": { "testing": ... }`.
+ */
+export function defineTestKit<T>(kit: TestKit<T>): TestKit<T> {
+	return kit;
+}
+
+/** Installs a module package's test kit on the server, once; nothing for a package without one. */
+export async function installKit(server: FakeServer, pkg: ModulePackage): Promise<void> {
+	if (!pkg.testing || server.kits.has(pkg.name)) return;
+	// By its real path: the test imports the same file through node_modules,
+	// and one file must be one module - the kit keeps its state per server.
+	const loaded = await import(pathToFileURL(realpathSync(pkg.testing)).href);
+	const kit = loaded.default as TestKit | undefined;
+	if (!kit || typeof kit.install !== 'function') {
+		throw new Error(`${pkg.name}: ${pkg.testing} has no \`export default defineTestKit({ install(server) { ... } })\``);
+	}
+	if (server.kits.has(pkg.name)) return;
+	server.kits.set(pkg.name, kit.install(server));
+}
+
+/** The kit of the module package `source` names, when it is one: `server.load("@amxts/menu-core")`. */
+export async function installKitFor(server: FakeServer, source: string): Promise<void> {
+	if (source.endsWith('.ts') || !/^@?[\w.-]+(?:\/[\w.-]+)?$/.test(source)) return;
+	const pkg = sourcesFor(PLUGINS_ROOT).project.modules.find(each => each.name === source);
+	if (pkg) await installKit(server, pkg);
+}

package/src/testing/memory.ts

@@ -0,0 +1,125 @@
+// A plugin's linear memory, read and written the ways the module does.
+//
+// Two kinds of text cross it. A Pawn string - what a native takes and fills -
+// is one character per 32-bit cell, terminated by a zero cell. An
+// AssemblyScript string - what the facade's own externals take, console.log's
+// included - is UTF-16, with its length in bytes in the word before it.
+
+const floatView = new Float32Array(1);
+const intView = new Int32Array(floatView.buffer);
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** A float as the cell Pawn carries it in: its bit pattern. */
+export function floatBits(value: number): number {
+	floatView[0] = value;
+	return intView[0];
+}
+
+/** The other way: a cell that holds a float. */
+export function bitsFloat(cell: number): number {
+	intView[0] = cell;
+	return floatView[0];
+}
+
+/** 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);
+	while (length > 0 && length < bytes.length && (bytes[length] & 0xC0) === 0x80) length--;
+	return length;
+}
+
+export class Memory {
+	private dataView?: DataView;
+
+	constructor(private exports: any) {}
+
+	// memory.grow detaches the old buffer, so the view follows the current one.
+	private get view(): DataView {
+		const buffer = this.exports.memory.buffer;
+		if (!this.dataView || this.dataView.buffer !== buffer) this.dataView = new DataView(buffer);
+		return this.dataView;
+	}
+
+	cell(pointer: number): number {
+		return this.view.getInt32(pointer, true);
+	}
+
+	setCell(pointer: number, value: number): void {
+		this.view.setInt32(pointer, value | 0, true);
+	}
+
+	float(pointer: number): number {
+		return bitsFloat(this.cell(pointer));
+	}
+
+	setFloat(pointer: number, value: number): void {
+		this.setCell(pointer, floatBits(value));
+	}
+
+	vector(pointer: number): number[] {
+		return [this.float(pointer), this.float(pointer + 4), this.float(pointer + 8)];
+	}
+
+	setVector(pointer: number, value: number[]): void {
+		for (let i = 0; i < 3; i++) this.setFloat(pointer + i * 4, value[i] ?? 0);
+	}
+
+	/** A Pawn string: a byte of UTF-8 a cell, up to the zero cell - what get_amxstring reads. */
+	text(pointer: number, max = 4096): string {
+		return decoder.decode(this.bytes(pointer, max));
+	}
+
+	/** A Pawn string's bytes as they are, at most `max` of them. */
+	bytes(pointer: number, max = 4096): Uint8Array {
+		if (!pointer) return new Uint8Array();
+		const bytes: number[] = [];
+		for (let i = 0; i < max; i++) {
+			const c = this.cell(pointer + i * 4);
+			if (c === 0) break;
+			bytes.push(c & 0xFF);
+		}
+		return Uint8Array.from(bytes);
+	}
+
+	/** Fills a Pawn buffer: at most `max` bytes of UTF-8 and the terminator, as set_amxstring. */
+	setText(pointer: number, max: number, value: string): number {
+		if (!pointer || max < 0) return 0;
+		const bytes = encoder.encode(value);
+		const length = Math.min(bytes.length, max);
+		for (let i = 0; i < length; i++) this.setCell(pointer + i * 4, bytes[i]);
+		this.setCell(pointer + length * 4, 0);
+		return length;
+	}
+
+	/** An AssemblyScript string. */
+	string(pointer: number): string {
+		if (!pointer) return '';
+		const bytes = this.view.getUint32(pointer - 4, true);
+		const chars = new Uint16Array(this.exports.memory.buffer, pointer, bytes >>> 1);
+		return String.fromCharCode(...chars);
+	}
+
+	/** Bytes as they are, into the plugin's memory. */
+	setRaw(pointer: number, bytes: Uint8Array): void {
+		new Uint8Array(this.exports.memory.buffer, pointer, bytes.length).set(bytes);
+	}
+
+	/** A text's UTF-8 length, and as much of it as fits into `max` bytes at `pointer`. */
+	setUtf8(pointer: number, max: number, value: string): number {
+		const bytes = encoder.encode(value);
+		if (pointer && max > 0) this.setRaw(pointer, bytes.subarray(0, max));
+		return bytes.length;
+	}
+
+	/** UTF-8 into a byte buffer the plugin decodes with String.UTF8 - the module's WriteBytes. */
+	setBytes(pointer: number, max: number, value: string): number {
+		if (!pointer || max <= 0) return 0;
+		const encoded = encoder.encode(value);
+		const length = Math.min(encoded.length, max - 1);
+		const target = new Uint8Array(this.exports.memory.buffer, pointer, length + 1);
+		target.set(encoded.subarray(0, length));
+		target[length] = 0;
+		return length;
+	}
+}