@voltro/plugin-rooms 0.0.0-stage → 0.87.0

package/dist/bots.js

@@ -0,0 +1,563 @@
+import { BudgetExceeded as e, ProtocolError as t, RoomAuthoringError as n } from "./errors.js";
+import { RoomInputCodec as r } from "./stateCodec.js";
+import { projectRoomView as i } from "./viewProjection.js";
+import { Effect as a, Result as o, Schema as s } from "effect";
+//#region src/bots.ts
+function c(e) {
+	throw new t({ detail: e });
+}
+var l = (e) => Number.isFinite(e) ? e : c("Bot helper requires finite numbers"), u = (e) => {
+	if (typeof e != "function") return c("Bot helper requires the caller-owned replay random source");
+	let t = e();
+	return Number.isFinite(t) && t >= 0 && t < 1 ? t : c("Bot random source must return a number in [0, 1)");
+}, d = (e) => {
+	(a.isEffect(e) || e && typeof e == "object" && "then" in e) && (e instanceof Promise && e.catch(() => void 0), c("Bot behavior must return synchronous intention data"));
+}, f = (e) => {
+	if (!e || typeof e != "object" || Array.isArray(e) || Object.keys(e).some((e) => ![
+		"name",
+		"view",
+		"input",
+		"memory",
+		"initialMemory",
+		"decide",
+		"maxInputs",
+		"maxRandomDraws"
+	].includes(e)) || typeof e.name != "string" || !e.name.trim() || e.name.length > 191 || ![
+		e.view,
+		e.input,
+		e.memory
+	].every(s.isSchema) || typeof e.initialMemory != "function" || typeof e.decide != "function") throw new n({
+		room: "",
+		detail: "Invalid implemented Bot behavior"
+	});
+	let t = e.maxInputs ?? 64, r = e.maxRandomDraws ?? 256;
+	if (![t, r].every((e) => Number.isSafeInteger(e) && e > 0 && e <= 4096)) throw new n({
+		room: e.name,
+		detail: "Bot decision and random draw budgets must be bounded positive integers"
+	});
+	return Object.freeze({
+		_tag: "RoomBotDescriptor",
+		name: e.name,
+		view: e.view,
+		input: e.input,
+		memory: e.memory,
+		initialMemory: e.initialMemory,
+		decide: e.decide,
+		maxInputs: t,
+		maxRandomDraws: r
+	});
+}, p = class {
+	rng;
+	descriptor;
+	memory;
+	lastTick = null;
+	pendingRandom = [];
+	deciding = !1;
+	decision = null;
+	constructor(e, t) {
+		this.rng = t, (!e || typeof e != "object") && c("Bot brain requires an admitted behavior");
+		let { _tag: n, ...r } = e;
+		(n !== "RoomBotDescriptor" || typeof t != "function") && c("Bot brain requires an admitted behavior and replay random source"), this.descriptor = f(r);
+		let i = this.descriptor.initialMemory();
+		d(i), this.memory = structuredClone(s.decodeUnknownSync(s.toType(this.descriptor.memory))(i, { onExcessProperty: "error" }));
+	}
+	step(t, n, r = 1) {
+		if (this.deciding || !Number.isSafeInteger(n) || n < 0 || this.lastTick !== null && n < this.lastTick || !Number.isFinite(r) || r < 0) return c("Invalid or reentrant Bot decision boundary");
+		if (n === this.lastTick) return [];
+		let i = structuredClone(s.decodeUnknownSync(s.toType(this.descriptor.view))(t, { onExcessProperty: "error" })), a = structuredClone(this.memory), o = 0, l = Object.freeze({});
+		this.decision = l, this.deciding = !0;
+		try {
+			let t = Object.freeze({
+				view: i,
+				memory: a,
+				tick: n,
+				difficulty: r,
+				rng: () => {
+					if (this.decision !== l) return c("Bot random capability cannot escape its decision boundary");
+					if (o >= this.descriptor.maxRandomDraws) throw new e({
+						budget: "botRandomDraws",
+						limit: this.descriptor.maxRandomDraws
+					});
+					return o === this.pendingRandom.length && this.pendingRandom.push(u(this.rng)), this.pendingRandom[o++];
+				}
+			}), f = this.descriptor.decide(t);
+			if (d(f), !Array.isArray(f)) return c("Bot decisions must return an array of intentions");
+			if (f.length > this.descriptor.maxInputs) throw new e({
+				budget: "botDecisionInputs",
+				limit: this.descriptor.maxInputs
+			});
+			for (let e = 0; e < f.length; e++) if (!Object.hasOwn(f, e)) return c("Sparse Bot intention arrays are refused");
+			let p = f.map((e) => structuredClone(s.encodeSync(this.descriptor.input)(s.decodeUnknownSync(s.toType(this.descriptor.input))(e, { onExcessProperty: "error" }), { onExcessProperty: "error" }))), m = structuredClone(s.decodeUnknownSync(s.toType(this.descriptor.memory))(a, { onExcessProperty: "error" }));
+			return this.memory = m, this.lastTick = n, this.pendingRandom.splice(0, o), Object.freeze(p);
+		} finally {
+			this.deciding = !1, this.decision = null;
+		}
+	}
+	snapshot() {
+		return this.deciding ? c("Bot memory snapshot must wait for the decision boundary") : Object.freeze({
+			version: 1,
+			memory: structuredClone(this.memory),
+			lastTick: this.lastTick,
+			pendingRandom: Object.freeze([...this.pendingRandom])
+		});
+	}
+	restore(e) {
+		if (this.deciding || !e || e.version !== 1 || !Array.isArray(e.pendingRandom) || e.pendingRandom.length > this.descriptor.maxRandomDraws || !Array.from(e.pendingRandom).every((e) => Number.isFinite(e) && e >= 0 && e < 1) || e.lastTick !== null && (!Number.isSafeInteger(e.lastTick) || e.lastTick < 0) || Object.keys(e).some((e) => ![
+			"version",
+			"memory",
+			"lastTick",
+			"pendingRandom"
+		].includes(e))) return c("Invalid Bot memory/random snapshot");
+		let t = structuredClone(s.decodeUnknownSync(s.toType(this.descriptor.memory))(e.memory, { onExcessProperty: "error" }));
+		this.memory = t, this.lastTick = e.lastTick, this.pendingRandom.splice(0, this.pendingRandom.length, ...e.pendingRandom);
+	}
+}, m = class {
+	connection;
+	brain;
+	now;
+	send;
+	interval;
+	difficulty;
+	nextSendAt;
+	lastTime;
+	current = null;
+	stopped = !1;
+	failed = null;
+	submitted = 0;
+	constructor(e, t, n, r, i) {
+		this.connection = e, (!i || typeof i != "object" || Array.isArray(i) || Object.keys(i).some((e) => !["sendRate", "difficulty"].includes(e)) || !Number.isFinite(i.sendRate) || i.sendRate <= 0 || i.sendRate > 128 || !Number.isFinite(i.difficulty ?? 1) || (i.difficulty ?? 1) < 0 || typeof r?.now != "function" || typeof e?.send != "function" || !t || t.view.ast !== e.manifest.state.ast || t.input.ast !== e.manifest.input.ast) && c("Bot network client requires explicit cadence and the actual connection state/input schemas"), this.brain = new p(t, n), this.now = r.now.bind(r), this.send = e.send.bind(e), this.interval = 1e3 / i.sendRate, this.difficulty = i.difficulty ?? 1, this.lastTime = this.now(), (!Number.isFinite(this.lastTime) || this.lastTime < 0 || !Number.isFinite(this.interval)) && c("Invalid Bot network monotonic clock/cadence"), this.nextSendAt = this.lastTime;
+	}
+	get failure() {
+		return this.failed;
+	}
+	metrics() {
+		return Object.freeze({
+			submitted: this.submitted,
+			stopped: this.stopped,
+			failed: this.failed !== null
+		});
+	}
+	snapshot() {
+		return this.brain.snapshot();
+	}
+	turn() {
+		if (this.current) return this.current;
+		if (this.failed) return Promise.reject(this.failed.cause);
+		if (this.stopped) return Promise.reject(new t({ detail: "Bot network client is fenced" }));
+		let e = Promise.resolve().then(() => this.execute());
+		return this.current = e, e.then(() => {
+			this.current = null;
+		}, () => {
+			this.current = null;
+		}), e;
+	}
+	async execute() {
+		let e = this.connection.lastAppliedTick, t = null;
+		try {
+			if (this.stopped) return [];
+			let n = this.now();
+			if ((!Number.isFinite(n) || n < this.lastTime) && c("Bot network clock must remain finite and monotonic"), this.lastTime = n, n < this.nextSendAt || this.connection.status !== "joined" || e < 0) return [];
+			let r = this.connection.state;
+			if (r === null) return [];
+			let i = this.nextSendAt + (Math.floor((n - this.nextSendAt) / this.interval) + 1) * this.interval;
+			(!Number.isFinite(i) || i <= n) && c("Bot network send cadence is exhausted");
+			let a = this.brain.step(r, e, this.difficulty);
+			this.nextSendAt = i;
+			let o = [];
+			for (t = 0; t < a.length && !this.stopped; t++) {
+				let e = s.decodeUnknownSync(this.brain.descriptor.input)(a[t], { onExcessProperty: "error" }), n = await this.send(e);
+				(!Number.isSafeInteger(n) || n < 0) && c("Bot connection returned an invalid submitted sequence"), this.submitted++, o.push(n);
+			}
+			return Object.freeze(o);
+		} catch (n) {
+			throw this.failed = Object.freeze({
+				tick: e,
+				intentionIndex: t,
+				cause: n
+			}), n;
+		}
+	}
+	fence() {
+		this.stopped = !0;
+	}
+	async close() {
+		if (this.fence(), this.current && await this.current, this.failed) throw this.failed.cause;
+	}
+}, h = class e {
+	actor;
+	identity;
+	countsAsPlayer;
+	brain;
+	codec;
+	now;
+	interval;
+	difficulty;
+	view;
+	lease = null;
+	nextSendAt;
+	lastTime;
+	sequence = 0;
+	stopped = !1;
+	cleaned = !1;
+	closing = null;
+	failed = null;
+	constructor(e, t, n, i, a) {
+		this.actor = e, (!t || ![t.sessionId, t.tenantId].every((e) => typeof e == "string" && e.length > 0 && e.length <= 191) || t.subjectId !== null && (typeof t.subjectId != "string" || !t.subjectId || t.subjectId.length > 191) || !a || typeof a != "object" || Array.isArray(a) || Object.keys(a).some((e) => ![
+			"sendRate",
+			"difficulty",
+			"countsAsPlayer"
+		].includes(e)) || !n || n.view.ast !== e.descriptor.state.ast || n.input.ast !== e.descriptor.input.ast) && c("Local Bot requires trusted identity and the actual actor state/input schemas");
+		let o = a.sendRate ?? e.descriptor.sendRate;
+		(!Number.isFinite(o) || o <= 0 || o > e.descriptor.tickRate || !Number.isFinite(a.difficulty ?? 1) || (a.difficulty ?? 1) < 0 || a.countsAsPlayer !== void 0 && typeof a.countsAsPlayer != "boolean") && c("Invalid local Bot cadence/difficulty/capacity options"), this.identity = Object.freeze({
+			sessionId: t.sessionId,
+			subjectId: t.subjectId,
+			tenantId: t.tenantId
+		}), this.countsAsPlayer = a.countsAsPlayer ?? !0, this.brain = new p(n, i), this.codec = new r(e.descriptor.input), this.now = e.monotonicNow.bind(e), this.view = e.descriptor.view, this.interval = 1e3 / o, this.difficulty = a.difficulty ?? 1, this.lastTime = this.now(), (!Number.isFinite(this.lastTime) || this.lastTime < 0 || !Number.isFinite(this.interval)) && c("Invalid local Bot clock/cadence"), this.nextSendAt = this.lastTime;
+	}
+	static async attach(t, n, r, i, a = {}) {
+		let o = new e(t, n, r, i, a);
+		return o.lease = await t.joinBotAsync({
+			...o.identity,
+			send: () => {},
+			kick: () => o.fence()
+		}, o.countsAsPlayer), o;
+	}
+	get failure() {
+		return this.failed;
+	}
+	get isClosed() {
+		return this.cleaned;
+	}
+	isCurrent() {
+		return this.lease?.isCurrent() === !0;
+	}
+	snapshot() {
+		return this.brain.snapshot();
+	}
+	turn() {
+		if (this.failed) throw this.failed.cause;
+		if (this.stopped || !this.lease) return c("Local Bot is fenced or not attached");
+		let e = this.actor.lastGoodSnapshot(), t = null;
+		try {
+			if (!this.lease.isCurrent()) return c("Local Bot actor membership was withdrawn");
+			let n = this.now();
+			if (!Number.isFinite(n) || n < this.lastTime) return c("Local Bot clock must be finite and monotonic");
+			if (this.lastTime = n, n < this.nextSendAt || this.actor.isLifecycleBusy()) return [];
+			let r = this.nextSendAt + (Math.floor((n - this.nextSendAt) / this.interval) + 1) * this.interval;
+			if (!Number.isFinite(r) || r <= n) return c("Local Bot send cadence is exhausted");
+			let a = i(this.actor.descriptor.state, this.view, {
+				state: e.state,
+				tick: e.tick,
+				client: {
+					...this.identity,
+					isBot: !0,
+					countsAsPlayer: this.countsAsPlayer
+				},
+				role: "player"
+			}), l = this.brain.step(a, e.tick, this.difficulty);
+			this.nextSendAt = r;
+			let u = [];
+			for (t = 0; t < l.length && !this.stopped; t++) {
+				if (!Number.isSafeInteger(this.sequence)) return c("Local Bot intention sequence is exhausted");
+				let n = s.decodeUnknownSync(this.brain.descriptor.input)(l[t], { onExcessProperty: "error" }), r = this.codec.full(n);
+				if (o.isFailure(r)) throw r.failure;
+				if (!this.lease.input(this.sequence, e.tick, l[t], r.success.byteLength)) return c("Local Bot submitted a duplicate intention sequence");
+				u.push(this.sequence++);
+			}
+			return Object.freeze(u);
+		} catch (n) {
+			throw this.failed = Object.freeze({
+				tick: e.tick,
+				intentionIndex: t,
+				cause: n
+			}), n;
+		}
+	}
+	fence() {
+		this.stopped = !0;
+	}
+	close() {
+		if (this.fence(), this.cleaned) return Promise.resolve();
+		if (this.closing) return this.closing;
+		let e = Promise.resolve().then(async () => {
+			this.lease && await this.lease.leave(), this.cleaned = !0;
+		});
+		return this.closing = e, e.then(() => {
+			this.closing = null;
+		}, () => {
+			this.closing = null;
+		}), e;
+	}
+}, g = class {
+	actor;
+	options;
+	startedAt;
+	lastTime;
+	ordinal = 0;
+	bots = /* @__PURE__ */ new Map();
+	current = null;
+	kind = null;
+	stopped = !1;
+	closing = null;
+	constructor(e, t) {
+		this.actor = e, (!t || typeof t != "object" || Array.isArray(t) || Object.keys(t).some((e) => ![
+			"toMin",
+			"afterMs",
+			"removeWhenHuman",
+			"behaviors",
+			"makeIdentity",
+			"random",
+			"difficultyFrom"
+		].includes(e)) || !Number.isSafeInteger(t.toMin) || t.toMin < 0 || t.toMin > e.descriptor.maxClients || !Number.isSafeInteger(t.afterMs ?? 1e4) || (t.afterMs ?? 1e4) < 0 || (t.afterMs ?? 1e4) > 2147483647 || t.removeWhenHuman !== void 0 && typeof t.removeWhenHuman != "boolean" || !Array.isArray(t.behaviors) || !t.behaviors.length || t.behaviors.length > 128 || typeof t.makeIdentity != "function" || typeof t.random != "function" || t.difficultyFrom !== void 0 && typeof t.difficultyFrom != "function") && c("Invalid explicit local Bot fill options");
+		let n = /* @__PURE__ */ new Set(), r = Array.from(t.behaviors, (t) => {
+			(!t || t._tag !== "RoomBotDescriptor" || t.view.ast !== e.descriptor.state.ast || t.input.ast !== e.descriptor.input.ast || n.has(t.name)) && c("Bot fill requires distinct actual room behaviors"), n.add(t.name);
+			let { _tag: r, ...i } = t;
+			return f(i);
+		});
+		this.options = Object.freeze({
+			toMin: t.toMin,
+			afterMs: t.afterMs ?? 1e4,
+			removeWhenHuman: t.removeWhenHuman ?? !0,
+			behaviors: Object.freeze(r),
+			makeIdentity: t.makeIdentity,
+			random: t.random,
+			difficultyFrom: t.difficultyFrom ?? (() => 1)
+		}), this.startedAt = e.monotonicNow(), this.lastTime = this.startedAt;
+	}
+	metrics() {
+		let e = this.actor.roster();
+		return Object.freeze({
+			humans: e.filter((e) => !e.isBot && e.countsAsPlayer).length,
+			bots: e.filter((e) => e.isBot && e.countsAsPlayer).length,
+			npcs: e.filter((e) => e.isBot && !e.countsAsPlayer).length,
+			ownedBots: this.bots.size
+		});
+	}
+	desiredBots() {
+		let e = [...this.bots.values()].filter((e) => e.isCurrent()).length;
+		return Math.max(0, Math.min(this.options.toMin - (this.actor.playerCount() - e), e + this.actor.availablePlayerSlots()));
+	}
+	execute(e, r) {
+		if (this.current) return e === "turn" && this.kind === "turn" ? this.current : Promise.reject(new n({
+			room: this.actor.descriptor.name,
+			detail: "Bot fill admission must wait for its accepted operation"
+		}));
+		if (this.stopped) return Promise.reject(new t({ detail: "Bot fill is fenced" }));
+		let i = Promise.resolve().then(r);
+		return this.kind = e, this.current = i, i.then(() => {
+			this.current = null, this.kind = null;
+		}, () => {
+			this.current = null, this.kind = null;
+		}), i;
+	}
+	turn() {
+		return this.execute("turn", async () => {
+			if (this.stopped) return;
+			let e = this.actor.monotonicNow();
+			if (e < this.lastTime) return c("Bot fill clock must be monotonic");
+			this.lastTime = e;
+			for (let [e, t] of this.bots) t.isCurrent() || (await t.close(), this.bots.delete(e));
+			if (this.options.removeWhenHuman) for (; this.bots.size > this.desiredBots() && !this.stopped;) {
+				let [e, t] = this.bots.entries().next().value;
+				await t.close(), this.bots.delete(e);
+			}
+			if (e - this.startedAt >= this.options.afterMs) for (; this.bots.size < this.desiredBots() && !this.stopped && !this.actor.isLifecycleBusy();) {
+				if (!Number.isSafeInteger(this.ordinal)) return c("Bot fill identity ordinal is exhausted");
+				let e = this.ordinal++, t = this.options.makeIdentity(e);
+				if (d(t), !t || typeof t != "object" || !("sessionId" in t) || typeof t.sessionId != "string" || this.bots.has(t.sessionId)) return c("Bot fill identity factory returned invalid or reused membership");
+				let n = this.actor.lastGoodSnapshot(), r = this.options.difficultyFrom(Object.freeze({
+					state: structuredClone(n.state),
+					options: structuredClone(this.actor.options),
+					tick: n.tick,
+					roster: this.actor.roster()
+				}));
+				if (d(r), typeof r != "number" || !Number.isFinite(r) || r < 0) return c("Bot fill difficulty must return a synchronous finite nonnegative value");
+				let i = await h.attach(this.actor, t, this.options.behaviors[e % this.options.behaviors.length], this.options.random(e), { difficulty: r });
+				this.bots.set(i.identity.sessionId, i), this.stopped && i.fence();
+			}
+			for (let e of this.bots.values()) {
+				if (this.stopped) break;
+				e.turn();
+			}
+		});
+	}
+	admitHuman(e, t) {
+		let n = Object.freeze({
+			sessionId: e.sessionId,
+			subjectId: e.subjectId,
+			tenantId: e.tenantId,
+			isBot: e.isBot,
+			countsAsPlayer: e.countsAsPlayer,
+			send: e.send.bind(e),
+			kick: e.kick.bind(e)
+		});
+		return this.execute("human", async () => {
+			if (this.stopped) return c("Bot fill was fenced before human admission");
+			let e = this.actor.humanAdmissionNeedsReplacement(n);
+			if (this.options.removeWhenHuman && e) {
+				let e = [...this.bots.values()].find((e) => e.isCurrent());
+				e && (await e.close(), this.bots.delete(e.identity.sessionId));
+			}
+			if (this.stopped) return c("Bot fill was fenced before human join");
+			await this.actor.joinAsync(n, t);
+		});
+	}
+	fence() {
+		this.stopped = !0;
+		for (let e of this.bots.values()) e.fence();
+	}
+	close() {
+		if (this.fence(), this.closing) return this.closing;
+		let e = Promise.resolve().then(async () => {
+			let e = [];
+			if (this.current) try {
+				await this.current;
+			} catch (t) {
+				e.push(t);
+			}
+			for (let [t, n] of [...this.bots].reverse()) try {
+				await n.close(), this.bots.delete(t);
+			} catch (t) {
+				e.push(t);
+			}
+			if (e.length) throw AggregateError(e, "Bot fill cleanup retains failed local members");
+		});
+		return this.closing = e, e.then(() => {
+			this.closing = null;
+		}, () => {
+			this.closing = null;
+		}), e;
+	}
+}, _ = (e) => ({
+	x: l(e.x),
+	y: l(e.y)
+}), v = (e, t, n) => {
+	let r = _(e), i = _(t), a = l(i.x - r.x), o = l(i.y - r.y), s = Math.hypot(a, o);
+	return !Number.isFinite(n) || n < 0 || !Number.isFinite(s) ? c("Invalid Bot steering magnitude") : Object.freeze(s === 0 ? {
+		x: 0,
+		y: 0
+	} : {
+		x: a / s * n,
+		y: o / s * n
+	});
+}, y = Object.freeze({
+	seek: (e, t, n = 1) => v(e, t, n),
+	flee: (e, t, n = 1) => {
+		let r = v(e, t, n);
+		return Object.freeze({
+			x: r.x === 0 ? 0 : -r.x,
+			y: r.y === 0 ? 0 : -r.y
+		});
+	},
+	wander: (e, t, n, r = 1) => {
+		if (!Number.isFinite(t) || t < 0 || !Number.isFinite(r) || r < 0) return c("Invalid Bot wander budget");
+		let i = l(l(e) + (u(n) * 2 - 1) * t), a = i % 360 * Math.PI / 180;
+		return Object.freeze({
+			headingDegrees: i,
+			intention: Object.freeze({
+				x: Math.cos(a) * r,
+				y: Math.sin(a) * r
+			})
+		});
+	}
+}), b = (e, t, n) => ![e, t].every((e) => Number.isSafeInteger(e) && e >= 0 && e <= 2147483647) || e + t > 2147483647 ? c("Invalid Bot reaction delay budget") : Math.max(0, Math.round(e + (u(n) * 2 - 1) * t)), x = (e, t) => {
+	if (!Number.isFinite(e) || e < 0 || e > 180) return c("Invalid Bot aim error budget");
+	let n = (u(t) * 2 - 1) * e;
+	return n === 0 ? 0 : n;
+}, S = (e) => {
+	if (!e || Object.keys(e).some((e) => e !== "actions") || !Array.isArray(e.actions) || e.actions.length > 4096) return c("Invalid bounded Bot utility actions");
+	let t = /* @__PURE__ */ new Set(), n = Array.from(e.actions, (e) => !e || typeof e != "object" || Object.keys(e).some((e) => ![
+		"id",
+		"action",
+		"score"
+	].includes(e)) || typeof e.id != "string" || !e.id.trim() || e.id.length > 191 || t.has(e.id) || typeof e.score != "function" ? c("Invalid Bot utility action identity or scorer") : (t.add(e.id), Object.freeze({
+		id: e.id,
+		action: structuredClone(e.action),
+		score: e.score
+	})));
+	return (e) => {
+		let t = null, r = -Infinity;
+		for (let i of n) {
+			let n = i.score(e);
+			if (d(n), typeof n != "number" || !Number.isFinite(n)) return c("Bot utility scorers must return synchronous finite scores");
+			n > r && (r = n, t = i.action);
+		}
+		return t === null ? null : structuredClone(t);
+	};
+}, C = (t) => {
+	if (!Array.isArray(t) || !t.length || !Array.isArray(t[0]) || !t[0].length) return c("Bot nav grid must be a nonempty rectangle");
+	let n = t[0].length, r = t.length;
+	if (n * r > 65536 || Array.from(t).some((e) => !Array.isArray(e) || e.length !== n || Array.from(e).some((e) => typeof e != "boolean"))) return c("Invalid bounded rectangular Bot nav grid");
+	let i = t.map((e) => [...e]), a = (e) => ![e.x, e.y].every(Number.isSafeInteger) || e.x < 0 || e.y < 0 || e.x >= n || e.y >= r ? c("Bot path point is outside its integer grid") : e.y * n + e.x;
+	return Object.freeze({
+		width: n,
+		height: r,
+		path: (t, o, s = 8192) => {
+			if (!Number.isSafeInteger(s) || s < 1 || s > 65536) return c("Invalid Bot path search budget");
+			let l = a(t), u = a(o);
+			if (!i[t.y][t.x] || !i[o.y][o.x]) return null;
+			let d = [], f = /* @__PURE__ */ new Map([[l, 0]]), p = /* @__PURE__ */ new Map(), m = /* @__PURE__ */ new Set(), h = (e, t) => e.score < t.score || e.score === t.score && e.order < t.order, g = (e) => {
+				let t = d.length;
+				for (d.push(e); t > 0;) {
+					let n = Math.floor((t - 1) / 2);
+					if (!h(e, d[n])) break;
+					d[t] = d[n], t = n;
+				}
+				d[t] = e;
+			}, _ = () => {
+				let e = d[0], t = d.pop();
+				if (d.length) {
+					let e = 0;
+					for (; e * 2 + 1 < d.length;) {
+						let n = e * 2 + 1;
+						if (n + 1 < d.length && h(d[n + 1], d[n]) && n++, !h(d[n], t)) break;
+						d[e] = d[n], e = n;
+					}
+					d[e] = t;
+				}
+				return e;
+			}, v = 0;
+			for (g({
+				key: l,
+				cost: 0,
+				score: Math.abs(t.x - o.x) + Math.abs(t.y - o.y),
+				order: v++
+			}); d.length;) {
+				let t = _();
+				if (m.has(t.key) || t.cost !== f.get(t.key)) continue;
+				if (m.size >= s) throw new e({
+					budget: "botNavVisited",
+					limit: s
+				});
+				if (m.add(t.key), t.key === u) {
+					let e = [], t = u;
+					for (; t !== void 0;) e.push(Object.freeze({
+						x: t % n,
+						y: Math.floor(t / n)
+					})), t = p.get(t);
+					return Object.freeze(e.reverse());
+				}
+				let a = t.key % n, c = Math.floor(t.key / n);
+				for (let [e, s] of [
+					[1, 0],
+					[0, 1],
+					[-1, 0],
+					[0, -1]
+				]) {
+					let l = a + e, u = c + s, d = u * n + l;
+					if (l < 0 || u < 0 || l >= n || u >= r || !i[u][l] || m.has(d)) continue;
+					let h = t.cost + 1;
+					h >= (f.get(d) ?? Infinity) || (f.set(d, h), p.set(d, t.key), g({
+						key: d,
+						cost: h,
+						score: h + Math.abs(l - o.x) + Math.abs(u - o.y),
+						order: v++
+					}));
+				}
+			}
+			return null;
+		}
+	});
+};
+//#endregion
+export { p as RoomBotBrain, g as RoomBotFill, h as RoomBotLocalClient, m as RoomBotNetworkClient, x as aimError, f as defineBot, C as navGrid, b as reactionDelay, y as steer, S as utilityAI };

package/dist/catalog.js

@@ -0,0 +1,80 @@
+import { RoomAuthoringError as e } from "./errors.js";
+import { defineRoom as t } from "./room.js";
+import { roomCodecs as n } from "./web.js";
+import { advanceRoomSchemaHistory as r, validateRoomSchemaHistory as i } from "./schemaHistory.js";
+import { Schema as a } from "effect";
+//#region src/catalog.ts
+var o = async (n, r, i = {}) => {
+	let o = i.maxRooms ?? 256;
+	if (!Number.isSafeInteger(o) || o < 1) throw new e({
+		room: "catalog",
+		detail: "Room inventory budget must be a positive safe integer"
+	});
+	let c = [...new Set(n)].sort();
+	if (c.length > o) throw new e({
+		room: "catalog",
+		detail: "Room inventory exceeds its declared budget"
+	});
+	let l = [];
+	for (let n of c) {
+		let i = (await r(n)).default;
+		if (!i || typeof i != "object" || Object.getOwnPropertyDescriptor(i, "_tag")?.value !== "RoomDescriptor") throw new e({
+			room: n,
+			detail: "Room modules must default-export a defineRoom descriptor"
+		});
+		for (let t of [
+			"state",
+			"input",
+			"options"
+		]) if (!a.isSchema(Object.getOwnPropertyDescriptor(i, t)?.value)) throw new e({
+			room: n,
+			detail: "Room descriptor schemas are malformed"
+		});
+		let o = t(i);
+		l.push({
+			source: n,
+			descriptor: o
+		});
+	}
+	return new s(l, i);
+}, s = class {
+	descriptors = /* @__PURE__ */ new Map();
+	history;
+	constructor(a, o = {}) {
+		let s = o.maxRooms ?? 256;
+		if (!Number.isSafeInteger(s) || s < 1 || a.length > s) throw new e({
+			room: "catalog",
+			detail: "Room inventory exceeds its declared budget"
+		});
+		let c = i(o.previousHistory ?? {
+			version: 1,
+			rooms: {}
+		}, { maxRooms: s });
+		for (let { source: i, descriptor: o } of a) {
+			let a = t(o), l = this.descriptors.get(a.name);
+			if (l) throw new e({
+				room: a.name,
+				detail: `Duplicate room name in ${l.source} and ${i}`
+			});
+			let u = n(a);
+			c = r(c, a.name, u.schemaHash, u.state.fieldManifest(), { maxRooms: s }), this.descriptors.set(a.name, Object.freeze({
+				source: i,
+				descriptor: a
+			}));
+		}
+		this.history = c;
+	}
+	get(t) {
+		let n = this.descriptors.get(t);
+		if (!n) throw new e({
+			room: t,
+			detail: "Room name is not present in the admitted inventory"
+		});
+		return n.descriptor;
+	}
+	inventory() {
+		return Object.freeze([...this.descriptors.values()].sort((e, t) => e.descriptor.name < t.descriptor.name ? -1 : +(e.descriptor.name > t.descriptor.name)));
+	}
+};
+//#endregion
+export { s as RoomCatalog, o as loadRoomCatalog };

package/dist/checkpointJson.js

@@ -0,0 +1,24 @@
+import { ProtocolError as e } from "./errors.js";
+//#region src/checkpointJson.ts
+function t(t) {
+	throw new e({ detail: t });
+}
+var n = (e, r = 0) => {
+	if (r > 128) return t("Checkpoint JSON depth exceeds its budget");
+	if (e === null || typeof e == "boolean" || typeof e == "string") return JSON.stringify(e);
+	if (typeof e == "number") return Number.isFinite(e) && !Object.is(e, -0) ? JSON.stringify(e) : t("Checkpoint JSON numbers must be finite and lossless");
+	if (Array.isArray(e)) {
+		let i = [];
+		for (let a = 0; a < e.length; a++) {
+			if (!Object.hasOwn(e, a)) return t("Sparse checkpoint arrays are refused");
+			i.push(n(e[a], r + 1));
+		}
+		return `[${i.join(",")}]`;
+	}
+	return typeof e == "object" && (Object.getPrototypeOf(e) === Object.prototype || Object.getPrototypeOf(e) === null) ? Reflect.ownKeys(e).length === Object.keys(e).length ? `{${Object.keys(e).sort().map((i) => {
+		let a = Object.getOwnPropertyDescriptor(e, i);
+		return !a || !("value" in a) ? t("Checkpoint accessors are refused") : `${JSON.stringify(i)}:${n(a.value, r + 1)}`;
+	}).join(",")}}` : t("Non-JSON checkpoint properties are refused") : t("Checkpoint values must be lossless JSON data");
+};
+//#endregion
+export { n as canonicalRoomJson };