@amxts/core 0.1.0

package/as/promise.types.d.ts

@@ -0,0 +1,82 @@
+// The Promise globals as the editor reads them, and what it knows of
+// Promise.all, allSettled, race and any.
+//
+// as/promise.ts is where the classes are; the compiler makes them global
+// through `@global`. The editor treats every file with an import or an export
+// as a module - a project's plugin without an import line too - so here they
+// are made global for it: `Promise`, `AbortController`, `AbortSignal`,
+// `Event`, and what the hood's other files call.
+//
+// The four statics are TypeScript's own lib signatures, which type a list
+// written in place as a tuple - `Promise.all([fetch(url), sleep(1000)])` is a
+// `Promise<[Response, void]>`. AssemblyScript has no tuple types and no
+// mapped types to declare these with, so as/promise.ts leaves the four out of
+// its Promise class and the compiler lowers each call to a hidden function
+// there (Resolver.lowerPromiseCall in the compiler patch). A namespace of the
+// same name merges them into the class, as statics.
+//
+// Only the editor reads this file.
+import * as impl from "./promise";
+
+declare global {
+	/** The value a promise gives, or the value itself. */
+	type __PromiseValue<T> = T extends impl.Promise<infer U> ? U : T;
+
+	/** The value `await` gives of a promise or of a plain value - TypeScript's own name for it, which `await 5` and `for await` look up. */
+	type Awaited<T> = __PromiseValue<T>;
+
+	/** The statics that take a list of promises: `all`, `allSettled`, `race` and `any`. */
+	// oxlint-disable-next-line no-redeclare -- merged into the class below, as statics
+	namespace Promise {
+		/**
+		 * Waits for every promise and gives their values in order; rejects with the
+		 * first rejection. Promises of different types give a tuple:
+		 *
+		 * ```ts
+		 * const [response, count] = await Promise.all([fetch(url), countAsync()]);
+		 * ```
+		 */
+		function all<T extends readonly unknown[] | []>(values: T): Promise<{ -readonly [P in keyof T]: __PromiseValue<T[P]> }>;
+
+		/**
+		 * Waits for every promise to settle, either way, and tells how each did:
+		 * `status` is `"fulfilled"` with `value`, or `"rejected"` with `reason`.
+		 */
+		function allSettled<T extends readonly unknown[] | []>(values: T): Promise<{ -readonly [P in keyof T]: PromiseSettledResult<__PromiseValue<T[P]>> }>;
+
+		/**
+		 * Settles like the first promise to settle. Promises of different types
+		 * need a common base class; a Promise<void> among them makes the value
+		 * nullable.
+		 */
+		function race<T extends readonly unknown[] | []>(values: T): Promise<__PromiseValue<T[number]>>;
+
+		/**
+		 * Gives the first value to arrive; once all promises are rejected, rejects
+		 * with an AggregateError whose `errors` hold every reason.
+		 */
+		function any<T extends readonly unknown[] | []>(values: T): Promise<__PromiseValue<T[number]>>;
+	}
+
+	// The class the namespace above merges its statics into.
+	class Promise<T> extends impl.Promise<T> {}
+	export import PromiseLike = impl.PromiseLike;
+	export import PromiseBase = impl.PromiseBase;
+	export import PromiseSettledResult = impl.PromiseSettledResult;
+	export import AggregateError = impl.AggregateError;
+	export import Event = impl.Event;
+	export import AbortSignal = impl.AbortSignal;
+	export import AbortController = impl.AbortController;
+
+	// The hood's: what the facade and the libraries beside it call.
+	export import __AbortWatch = impl.__AbortWatch;
+	export import __AbortGuard = impl.__AbortGuard;
+	export import __co_promise = impl.__co_promise;
+	export import __co_resolve = impl.__co_resolve;
+	export import __co_reject = impl.__co_reject;
+	export import __co_bindEnv = impl.__co_bindEnv;
+	export import __co_sleep = impl.__co_sleep;
+	export import __co_player_signal = impl.__co_player_signal;
+	/** @hidden The player whose command or event is being handled. */
+	let __co_ambient_player: i32;
+}

package/as/remote.ts

@@ -0,0 +1,288 @@
+// Calls between plugins, for the modules one plugin runs for the whole server.
+//
+// A module at ~/modules/<name> that the plugin ~/<name>.ts owns (see
+// scripts/shared-modules.ts) has one instance on the server:
+// the owner's. Every other plugin that imports it is given a proxy instead,
+// generated by scripts/shared-modules.ts - the same exported functions, each
+// of which writes its arguments here, has the module (runtime/src/module.cpp)
+// run the owner's copy, and reads the answer back. A function passed across -
+// a condition, an action - stays where it was written; the other side gets a
+// stand-in that calls back the same way.
+//
+// This file is the part both sides share: the byte buffers the arguments
+// travel in, the plugin's table of functions others may call back, and the
+// one export the module calls, __amxts_rpc. It is hood: plugins never import it.
+// __co_bindEnv, which makes a stand-in, is as/promise.ts's; __env, where the
+// stand-in finds its place, the compiler library's.
+import "~/promise";
+
+// @ts-ignore: decorator
+@external("env", "amxts_serve") declare function _serve(name: string, hash: i32): void;
+// @ts-ignore: decorator
+@external("env", "amxts_owner") declare function _owner(name: string, hash: i32): i32;
+// @ts-ignore: decorator
+@external("env", "amxts_rpc") declare function _rpc(service: i32, plugin: i32, data: usize, length: i32): i32;
+// @ts-ignore: decorator
+@external("env", "amxts_rpc_take") declare function _take(to: usize): void;
+// @ts-ignore: decorator
+@external("env", "amxts_rpc_reply") declare function _reply(data: usize, length: i32): void;
+// @ts-ignore: decorator
+@external("env", "amxts_rpc_result") declare function _result(to: usize): void;
+
+const KIND_MODULE: i32 = 0;
+const KIND_CALLBACK: i32 = 1;
+
+/** What a call carries: its arguments, or its answer, as bytes. */
+export class Writer {
+	data: ArrayBuffer = new ArrayBuffer(64);
+	length: i32 = 0;
+
+	private room(bytes: i32): usize {
+		if (this.length + bytes > this.data.byteLength) {
+			let size = this.data.byteLength * 2;
+			while (size < this.length + bytes) size *= 2;
+			const grown = new ArrayBuffer(size);
+			memory.copy(changetype<usize>(grown), changetype<usize>(this.data), <usize>this.length);
+			this.data = grown;
+		}
+
+		const at = changetype<usize>(this.data) + <usize>this.length;
+		this.length += bytes;
+		return at;
+	}
+
+	i32(value: i32): void {
+		store<i32>(this.room(4), value);
+	}
+
+	f64(value: f64): void {
+		store<f64>(this.room(8), value);
+	}
+
+	bool(value: bool): void {
+		store<u8>(this.room(1), value ? 1 : 0);
+	}
+
+	str(value: string): void {
+		const bytes = String.UTF8.encode(value);
+		const size = bytes.byteLength;
+		this.i32(size);
+		memory.copy(this.room(size), changetype<usize>(bytes), <usize>size);
+	}
+}
+
+/** The other end of a Writer. Past the end every read is zero - what a failed call reads as. */
+export class Reader {
+	at: i32 = 0;
+
+	/** `from`: the plugin that wrote it - where a function it carries lives. */
+	constructor(public data: ArrayBuffer, public from: i32) {}
+
+	private take(bytes: i32): usize {
+		if (this.at + bytes > this.data.byteLength) {
+			this.at = this.data.byteLength;
+			return 0;
+		}
+
+		const at = changetype<usize>(this.data) + <usize>this.at;
+		this.at += bytes;
+		return at;
+	}
+
+	i32(): i32 {
+		const at = this.take(4);
+		return at != 0 ? load<i32>(at) : 0;
+	}
+
+	f64(): f64 {
+		const at = this.take(8);
+		return at != 0 ? load<f64>(at) : 0.0;
+	}
+
+	bool(): bool {
+		const at = this.take(1);
+		return at != 0 ? load<u8>(at) != 0 : false;
+	}
+
+	str(): string {
+		const size = this.i32();
+		if (size <= 0) return "";
+		const at = this.take(size);
+		return at != 0 ? String.UTF8.decodeUnsafe(at, <usize>size) : "";
+	}
+}
+
+/** A module another plugin owns, as a proxy knows it. */
+export class Service {
+	private id: i32 = -1;
+	private failed: bool = false;
+
+	constructor(public name: string, public hash: i32) {}
+
+	/** A call of the module's `op`-th function (or field). */
+	begin(op: i32): Writer {
+		const w = new Writer();
+		w.i32(KIND_MODULE);
+		w.i32(op);
+		return w;
+	}
+
+	/** Runs it in the owner and returns the answer; an empty one, and an error in the log, when it cannot. */
+	call(w: Writer): Reader {
+		if (this.id < 0) {
+			const id = _owner(this.name, this.hash);
+			if (id < 0) return this.fail(id == -2
+				? `~/modules/${this.name}: ${this.name}.aot was built from another version of it - build both again`
+				: `~/modules/${this.name}: no plugin runs it - is ${this.name}.aot in plugins.ini?`);
+			this.id = id;
+		}
+
+		const answer = send(this.id, -1, w);
+		if (answer == null) return this.fail(`~/modules/${this.name}: the call failed in ${this.name}`);
+		this.failed = false;
+		return answer!;
+	}
+
+	private fail(message: string): Reader {
+		if (!this.failed) console.error(message);
+		this.failed = true;
+		return new Reader(new ArrayBuffer(0), -1);
+	}
+}
+
+/** The answer from `service`, or from `plugin` when service is -1; null when there is none. */
+function send(service: i32, plugin: i32, w: Writer): Reader | null {
+	const length = _rpc(service, plugin, changetype<usize>(w.data), w.length);
+	if (length < 4) return null;
+	const data = new ArrayBuffer(length);
+	_result(changetype<usize>(data));
+	const r = new Reader(data, 0);
+	r.from = r.i32();
+	return r;
+}
+
+// ---------------------------------------------------------------- functions passed across
+
+/** Calls `fn`, a function of signature `sig`, with the arguments in `r`; its answer goes to `w`. */
+export type Invoke = (fn: usize, sig: i32, r: Reader, w: Writer) => void;
+
+class Callback {
+	constructor(public fn: Object, public sig: i32, public invoke: Invoke) {}
+}
+
+const callbacks: Callback[] = [];
+const callbackIds = new Map<usize, i32>();
+
+/** The number another plugin calls `fn` back by; 0 for null. The same function keeps its number. */
+export function sendFunction(fn: usize, sig: i32, invoke: Invoke): i32 {
+	if (fn == 0) return 0;
+
+	if (callbackIds.has(fn)) {
+		const id = callbackIds.get(fn);
+		if (callbacks[id - 1].sig == sig) return id;
+	}
+
+	callbacks.push(new Callback(changetype<Object>(fn), sig, invoke));
+	const id = callbacks.length;
+	callbackIds.set(fn, id);
+	return id;
+}
+
+/** Where a stand-in calls: the plugin a function lives in, and its number there. */
+class Remote {
+	constructor(public plugin: i32, public id: i32) {}
+}
+
+const standIns = new Map<string, usize>();
+
+/**
+ * A stand-in for function `id` of the plugin that wrote `r`: a copy of
+ * `stub` - a function of the same signature that calls back - with the place
+ * in its `_env`, where the stub finds it (__env, the compiler's). The same
+ * function is the same stand-in, so it can be compared and removed.
+ */
+export function receiveFunction(r: Reader, stub: usize): usize {
+	const id = r.i32();
+	if (id == 0) return 0;
+	const key = `${r.from}:${id}`;
+	if (standIns.has(key)) return standIns.get(key);
+	// @ts-ignore: as/promise.ts's, global to the compiler and unknown to the editor
+	const bound: usize = __co_bindEnv(stub, new Remote(r.from, id));
+	standIns.set(key, bound);
+	// Held here: the stand-in is only ever reached through what it was given to.
+	kept.push(changetype<Object>(bound));
+	return bound;
+}
+
+const kept: Object[] = [];
+
+/** The first thing a stub does: where it calls. Before any other call, which would change __env. */
+export function remoteTarget(): Remote {
+	// @ts-ignore: the compiler library's, unknown to the editor
+	return changetype<Remote>(__env);
+}
+
+/** A call of the function a stand-in stands for. */
+export function beginCallback(target: Remote): Writer {
+	const w = new Writer();
+	w.i32(KIND_CALLBACK);
+	w.i32(target.id);
+	return w;
+}
+
+export function callBack(target: Remote, w: Writer): Reader {
+	const answer = send(-1, target.plugin, w);
+	return answer ?? new Reader(new ArrayBuffer(0), -1);
+}
+
+// ---------------------------------------------------------------- the owner's side
+
+/** Runs op `op` of the served module with the arguments in `r`; the answer goes to `w`. */
+export type Dispatch = (op: i32, r: Reader, w: Writer) => void;
+
+let served: Dispatch | null = null;
+
+/** The module this plugin runs for the others; one a plugin. */
+export function serve(name: string, hash: i32, dispatch: Dispatch): void {
+	served = dispatch;
+	_serve(name, hash);
+}
+
+/** Objects the owner hands out and takes back by number: a menu, a config, a section. */
+export class Handles {
+	objects: Object[] = [];
+	ids: Map<usize, i32> = new Map<usize, i32>();
+
+	id(object: usize): i32 {
+		if (object == 0) return 0;
+		if (this.ids.has(object)) return this.ids.get(object);
+		this.objects.push(changetype<Object>(object));
+		const id = this.objects.length;
+		this.ids.set(object, id);
+		return id;
+	}
+
+	at(id: i32): usize {
+		return id > 0 && id <= this.objects.length ? changetype<usize>(this.objects[id - 1]) : 0;
+	}
+}
+
+/** @hidden What the module calls: a request of `length` bytes from plugin `from`. */
+export function __amxts_rpc(length: i32, from: i32): void {
+	const data = new ArrayBuffer(length);
+	_take(changetype<usize>(data));
+	const r = new Reader(data, from);
+	const kind = r.i32();
+	const id = r.i32();
+	const w = new Writer();
+
+	if (kind == KIND_MODULE) {
+		const dispatch = served;
+		if (dispatch != null) dispatch(id, r, w);
+	} else if (kind == KIND_CALLBACK && id > 0 && id <= callbacks.length) {
+		const callback = callbacks[id - 1];
+		callback.invoke(changetype<usize>(callback.fn), callback.sig, r, w);
+	}
+
+	_reply(changetype<usize>(w.data), w.length);
+}

package/as/tsconfig.json

@@ -0,0 +1,22 @@
+{
+	"extends": "assemblyscript/std/assembly.json",
+	"compilerOptions": {
+		"target": "es2015",
+		"moduleDetection": "force",
+		"module": "esnext",
+		"moduleResolution": "bundler",
+		"paths": {
+			"~/*": ["./*"],
+			"@amxts/core": ["./facade.ts"],
+			"@amxts/core/*": ["./*"],
+			"@amxts/menu-core": ["../../amxts-modules/menu-core/src/index.ts"],
+			"@amxts/config-core": ["../../amxts-modules/config-core/src/index.ts"]
+		}
+	},
+	"include": [
+		"./**/*.ts",
+		"../amxts.config.ts",
+		"../../amxts-modules/menu-core/src/index.ts",
+		"../../amxts-modules/config-core/src/index.ts"
+	]
+}

package/as/vector.ts

@@ -0,0 +1,65 @@
+// A point or a direction in the game world: an origin, a velocity, angles.
+//
+// It is an array of three numbers underneath, so `origin[0]`, a native that
+// takes a vector (get_distance_f, message_begin) and a literal written as
+// `[0.0, 0.0, 100.0]` all keep working next to `origin.x` and `origin.add(...)`.
+// Being an array is also why its size is `magnitude()`: `length` is already
+// the array's 3.
+
+/** Three numbers, x y z, with the math a plugin needs on them. */
+export class Vector extends Array<number> {
+	constructor(x: number = 0.0, y: number = 0.0, z: number = 0.0) {
+		super(3);
+		this[0] = x;
+		this[1] = y;
+		this[2] = z;
+	}
+
+	/** The x coordinate, `vector[0]`. */
+	get x() { return this[0]; }
+	set x(value: number) { this[0] = value; }
+
+	/** The y coordinate, `vector[1]`. */
+	get y() { return this[1]; }
+	set y(value: number) { this[1] = value; }
+
+	/** The z coordinate, `vector[2]`. */
+	get z() { return this[2]; }
+	set z(value: number) { this[2] = value; }
+
+	/** A new vector: this one plus `other`, number by number. */
+	add(other: number[]) {
+		return new Vector(this[0] + other[0], this[1] + other[1], this[2] + other[2]);
+	}
+
+	/** A new vector: this one minus `other`, the way from `other` to this point. */
+	subtract(other: number[]) {
+		return new Vector(this[0] - other[0], this[1] - other[1], this[2] - other[2]);
+	}
+
+	/** A new vector with every number multiplied by `factor`. */
+	scale(factor: number) {
+		return new Vector(this[0] * factor, this[1] * factor, this[2] * factor);
+	}
+
+	/** The dot product with `other`; zero when the two are at right angles. */
+	dot(other: number[]) {
+		return this[0] * other[0] + this[1] * other[1] + this[2] * other[2];
+	}
+
+	/** The vector's length: the distance from the map's origin to this point. */
+	magnitude() {
+		return Math.sqrt(this.dot(this));
+	}
+
+	/** The distance from this point to `other`, in game units. */
+	distanceTo(other: number[]) {
+		return this.subtract(other).magnitude();
+	}
+
+	/** A new vector in the same direction, one unit long; a zero vector stays zero. */
+	normalize() {
+		const size = this.magnitude();
+		return size > 0 ? this.scale(1 / size) : new Vector();
+	}
+}

package/bin/amxts.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// The amxts command a project runs: `npx amxts --help`. The command is its own
+// package, @amxts/cli, which the core depends on; a package manager links the
+// bins of a project's own dependencies only, so the core carries this one.
+// The command finds the project's core again and drives it through
+// @amxts/core/cli-api.
+import process from 'node:process';
+import { main } from '@amxts/cli';
+
+main(process.argv.slice(2));