@adobe/ecs-persistence 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Adobe, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @adobe/ecs-persistence
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Saving, loading and copying the entities of `@adobe/ecs` worlds. A snapshot holds whole archetypes' columns: a struct's
+or a number's bytes as the world stores them, which saving and loading copy as blocks, and the values of strings and
+other data. Its entity values are rewritten as they're loaded, so references between the entities it holds still name
+each other.
+
+## Marking what persists
+
+A component or resource persists when its declaration names it with the `persist` trait, by a stable name: saved data
+names it so, whatever its module's path or version.
+
+```ts
+import type { Entity, Vec3 } from "@adobe/ecs";
+import { persist } from "@adobe/ecs-persistence";
+
+export const position = Symbol();
+export const parent = Symbol();
+export const score = Symbol();
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: Vec3; [persist]: "position" };
+        [parent]: { type: Entity; reference: "owner"; [persist]: "parent" };
+    }
+    interface Resources {
+        [score]: { type: number; default: 0; [persist]: "score" };
+    }
+}
+```
+
+Only data persists: a value with a schema. A derived component doesn't: its rule derives it again once its entity is
+loaded.
+
+## Saving and loading
+
+```ts
+import { decode, encode, snapshot, spawn } from "@adobe/ecs-persistence";
+
+const taken = await snapshot({ world });
+if (taken.failure !== undefined) throw new Error(taken.failure);
+const bytes = encode(taken);
+
+const loaded = decode(bytes);
+if (loaded.failure !== undefined) throw new Error(loaded.failure);
+const spawned = await spawn({ world: other, snapshot: loaded });
+```
+
+- `snapshot({ world, ... })` takes every entity holding a persisted component, those matching `with` and `not`, or
+  `root` and everything it owns through persisted owner references. Except with `root` or `resources: false`, it
+  takes the persisted resources too.
+- `encode` writes it as bytes, and `decode` reads them back, viewing each column's bytes where they are in the buffer.
+  It refuses bytes naming a component or resource this program doesn't persist, or persists with another schema.
+- `spawn({ world, snapshot, entities? })` spawns an entity for each of the snapshot's and sets its resources, its entity values
+  naming the entities spawned for theirs. An entity value naming an entity outside the snapshot follows what
+  despawning that entity would do: an entity it owns isn't spawned, nor what that owns, and the result counts them in
+  `dropped`; a weak reference to it is left out; any other value naming it is `Entity.none`. The result's `entities`
+  maps each of the snapshot's entities to the one spawned for it, or null; `entities: false` leaves the map out, which
+  saves about 85 ms and 50 MB at a million entities.
+- Copying entities from one world into another is a snapshot spawned there: `spawn({ world: to, snapshot: await snapshot({ world: from }) })`, without
+  bytes.
+
+Each reports why it didn't happen as `{ failure }`, rather than throwing, and `result.failure !== undefined` tells
+which. A snapshot is opaque: only these functions
+read it.
+
+## Speed
+
+`pnpm test:perf` compares, at 100K and 1M entities with a `Vec3`, a number, an owner reference and a struct holding an
+entity, this package with reading rows and spawning entity by entity. At 1M entities, a snapshot takes about 6 ms
+against 110 ms, encoding 5 ms against 150 ms for `JSON.stringify` of the rows, and decoding views the bytes where they
+are. Spawning takes about 310 ms against 1,450 ms, most of it the world's bookkeeping of owner references at its sync
+point; without references, 1M entities spawn in about 26 ms.

package/dist/index.js

@@ -0,0 +1,516 @@
+import { Component, Resource, System } from "@adobe/ecs";
+//#region src/persist.ts
+/**
+* The trait marking a component or resource to persist, its value the stable name saved data names it by: unlike its
+* key's id, the name stays the same across versions and moves of its module. Not on a derived component, which its
+* rule derives again once its entity is loaded.
+*/
+var persist = Symbol();
+declare$(persist, "trait");
+function declare$(key, kind, declaration) {
+	(globalThis[Symbol.for("@adobe/ecs/declarations@1")] ??= /* @__PURE__ */ new Map()).set(key, {
+		kind,
+		declaration
+	});
+}
+//#endregion
+//#region src/program/program.ts
+/** The keys of `declarations` with a `persist` trait by name, or why one can't persist: it isn't data, or a name is taken. */
+var namedIn = (declarations, kind) => {
+	const named = /* @__PURE__ */ new Map();
+	for (const [key, declaration] of declarations) {
+		const name = declaration[persist];
+		if (typeof name !== "string") continue;
+		if (declaration.type === void 0) return `The ${kind} persisted as "${name}" isn't data: it has no schema.`;
+		if (named.has(name)) return `Two ${kind}s are persisted as "${name}".`;
+		named.set(name, {
+			name,
+			key,
+			schema: declaration.type
+		});
+	}
+	return named;
+};
+/** What the program persists, as its modules registered so far declare it, or why it can't. */
+var programOf = () => {
+	const components = namedIn(Component.declarations(), "component");
+	if (typeof components === "string") return components;
+	const resources = namedIn(Resource.declarations(), "resource");
+	if (typeof resources === "string") return resources;
+	return {
+		components,
+		resources
+	};
+};
+//#endregion
+//#region src/values/values.ts
+/** A number JSON can't hold, as text: `NaN`, `Infinity`, `-Infinity` or `-0`. */
+var numberToJson = (value) => Number.isNaN(value) ? "NaN" : value === Infinity ? "Infinity" : value === -Infinity ? "-Infinity" : Object.is(value, -0) ? "-0" : value;
+var numberFromJson = (json) => {
+	if (typeof json !== "string") return json;
+	switch (json) {
+		case "NaN": return NaN;
+		case "Infinity": return Infinity;
+		case "-Infinity": return -Infinity;
+		case "-0": return -0;
+		default: return json;
+	}
+};
+/** Whether a value is of the JSON kind a schema's values are, to pick a union's member. */
+var fits = (schema, value) => {
+	if ("const" in schema) return Object.is(schema.const, value) || JSON.stringify(schema.const) === JSON.stringify(value);
+	if ("anyOf" in schema) return schema.anyOf.some((member) => fits(member, value));
+	if ("allOf" in schema) return schema.allOf.every((member) => fits(member, value));
+	if (!("type" in schema)) return true;
+	switch (schema.type) {
+		case "number":
+		case "integer": return typeof value === "number";
+		case "string": return typeof value === "string";
+		case "boolean": return typeof value === "boolean";
+		case "null": return value === null;
+		case "array": return Array.isArray(value);
+		case "set": return value instanceof Set;
+		case "map": return value instanceof Map;
+		case "object": return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Set) && !(value instanceof Map);
+		default: return true;
+	}
+};
+/** A value of `schema` as JSON. */
+var toJson = (schema, value) => {
+	if ("anyOf" in schema) {
+		const index = schema.anyOf.findIndex((candidate) => fits(candidate, value));
+		const member = schema.anyOf[index];
+		return member === void 0 ? [-1, value] : [index, toJson(member, value)];
+	}
+	if (typeof value === "number") return numberToJson(value);
+	if (!("type" in schema)) return value;
+	switch (schema.type) {
+		case "array": return Array.isArray(value) ? value.map((item) => toJson(schema.items, item)) : value;
+		case "set": return value instanceof Set ? Array.from(value, (item) => toJson(schema.items, item)) : value;
+		case "map": return value instanceof Map ? Array.from(value, ([key, item]) => [toJson(schema.keys, key), toJson(schema.values, item)]) : value;
+		case "object": {
+			if (typeof value !== "object" || value === null) return value;
+			const json = {};
+			for (const name of Object.keys(value)) {
+				const field = schema.properties[name];
+				const item = Reflect.get(value, name);
+				if (item !== void 0) json[name] = field === void 0 ? item : toJson(field, item);
+			}
+			return json;
+		}
+		default: return value;
+	}
+};
+/** A value of `schema` read back from its JSON. */
+var fromJson = (schema, json) => {
+	if ("anyOf" in schema) {
+		if (!Array.isArray(json) || typeof json[0] !== "number") return json;
+		const member = schema.anyOf[json[0]];
+		return member === void 0 ? json[1] : fromJson(member, json[1]);
+	}
+	if ("const" in schema) return schema.const;
+	if (!("type" in schema)) return json;
+	switch (schema.type) {
+		case "number":
+		case "integer": return numberFromJson(json);
+		case "array": return Array.isArray(json) ? json.map((item) => fromJson(schema.items, item)) : json;
+		case "set": return Array.isArray(json) ? new Set(json.map((item) => fromJson(schema.items, item))) : json;
+		case "map": return Array.isArray(json) ? new Map(json.map((entry) => Array.isArray(entry) ? [fromJson(schema.keys, entry[0]), fromJson(schema.values, entry[1])] : [entry, void 0])) : json;
+		case "object": {
+			if (typeof json !== "object" || json === null || Array.isArray(json)) return json;
+			const value = {};
+			for (const name of Object.keys(json)) {
+				const field = schema.properties[name];
+				const item = Reflect.get(json, name);
+				value[name] = field === void 0 ? item : fromJson(field, item);
+			}
+			return value;
+		}
+		default: return json;
+	}
+};
+//#endregion
+//#region src/format/format.ts
+/**
+* The binary form of a snapshot, little-endian:
+* - 16 bytes: `ECSP`, the format's version as a u32, the header's length in bytes as a u32, and 4 bytes of zeros;
+* - the header, JSON text padded with spaces to a multiple of 8 bytes: each component and resource by name with its
+*   schema, and each table's count and where its entities and columns are;
+* - blocks, each starting at a multiple of 8 bytes: a table's entities as f64s, a column's bytes as its components'
+*   layout holds them, and a column of values as JSON text.
+* A loader views the blocks of bytes where they are, in the buffer it's given.
+*/
+var magic = [
+	69,
+	67,
+	83,
+	80
+];
+var version = 1;
+var prefix = 16;
+var aligned = (offset) => Math.ceil(offset / 8) * 8;
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+/** A snapshot's contents as bytes. */
+var encodeContents = (snapshot) => {
+	const blocks = [];
+	let offset = 0;
+	/** Places a block, returning its offset from the first block. */
+	const place = (bytes) => {
+		const at = offset;
+		blocks.push(bytes);
+		offset = aligned(offset + bytes.byteLength);
+		return at;
+	};
+	const indexOf = new Map(snapshot.components.map((persisted, index) => [persisted.key, index]));
+	const tables = snapshot.tables.map((table) => {
+		const entities = place(new Uint8Array(table.entities.buffer, table.entities.byteOffset, table.entities.byteLength));
+		const columns = snapshot.components.flatMap((persisted) => {
+			const key = persisted.key;
+			const column = Reflect.get(table.columns, key);
+			const component = indexOf.get(persisted.key) ?? -1;
+			if (column === void 0) return [];
+			if (column.kind === "bytes") return [{
+				component,
+				kind: "bytes",
+				offset: place(column.bytes),
+				length: column.bytes.byteLength,
+				stride: column.stride
+			}];
+			if (column.kind === "value") return [{
+				component,
+				kind: "value",
+				value: toJson(persisted.schema, column.value)
+			}];
+			const text = encoder.encode(JSON.stringify(column.values.map((value) => toJson(persisted.schema, value))));
+			return [{
+				component,
+				kind: "values",
+				offset: place(text),
+				length: text.byteLength
+			}];
+		});
+		return {
+			count: table.count,
+			entities,
+			columns
+		};
+	});
+	const header = {
+		components: snapshot.components.map(({ name, schema }) => ({
+			name,
+			schema
+		})),
+		resources: snapshot.resources.map(({ persisted, value }) => ({
+			name: persisted.name,
+			schema: persisted.schema,
+			value: toJson(persisted.schema, value)
+		})),
+		tables
+	};
+	const text = encoder.encode(JSON.stringify(header));
+	const headerLength = aligned(text.byteLength);
+	const bytes = new Uint8Array(prefix + headerLength + offset);
+	bytes.set(magic, 0);
+	const view = new DataView(bytes.buffer);
+	view.setUint32(4, version, true);
+	view.setUint32(8, headerLength, true);
+	bytes.set(text, prefix);
+	bytes.fill(32, prefix + text.byteLength, prefix + headerLength);
+	let at = prefix + headerLength;
+	for (const block of blocks) {
+		bytes.set(block, at);
+		at = aligned(at + block.byteLength);
+	}
+	return bytes;
+};
+var isObject = (value) => typeof value === "object" && value !== null;
+/** The header's JSON, checked enough to read it without casts, or null. */
+var headerOf = (json) => {
+	if (!isObject(json)) return null;
+	const components = Reflect.get(json, "components");
+	const resources = Reflect.get(json, "resources");
+	const tables = Reflect.get(json, "tables");
+	if (!Array.isArray(components) || !Array.isArray(resources) || !Array.isArray(tables)) return null;
+	const named = (item) => isObject(item) && typeof Reflect.get(item, "name") === "string" && isObject(Reflect.get(item, "schema"));
+	if (!components.every(named) || !resources.every(named)) return null;
+	const isColumn = (item) => {
+		if (!isObject(item) || typeof Reflect.get(item, "component") !== "number") return false;
+		const kind = Reflect.get(item, "kind");
+		if (kind === "value") return true;
+		const numbers = kind === "bytes" ? [
+			"offset",
+			"length",
+			"stride"
+		] : kind === "values" ? ["offset", "length"] : null;
+		return numbers !== null && numbers.every((name) => typeof Reflect.get(item, name) === "number");
+	};
+	const isTable = (item) => {
+		if (!isObject(item) || typeof Reflect.get(item, "count") !== "number" || typeof Reflect.get(item, "entities") !== "number") return false;
+		const columns = Reflect.get(item, "columns");
+		return Array.isArray(columns) && columns.every(isColumn);
+	};
+	if (!tables.every(isTable)) return null;
+	return json;
+};
+/** Whether two schemas are the same, by their JSON in their properties' order, which places a struct's fields. */
+var sameSchema = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+* The snapshot contents `bytes` holds, its components and resources by name as this program persists them, its blocks of
+* bytes viewed where they are; or why it can't be read: it isn't one, or names what this program doesn't persist, or
+* persists with another schema.
+*/
+var decodeContents = (bytes) => {
+	if (bytes.byteLength < prefix || magic.some((byte, at) => bytes[at] !== byte)) return { failure: "These bytes aren't a snapshot." };
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const found = view.getUint32(4, true);
+	if (found !== version) return { failure: `This snapshot's format is version ${found}; this package reads version ${version}.` };
+	const headerLength = view.getUint32(8, true);
+	let json;
+	try {
+		json = JSON.parse(decoder.decode(bytes.subarray(prefix, prefix + headerLength)));
+	} catch {
+		return { failure: "This snapshot's header isn't JSON." };
+	}
+	const header = headerOf(json);
+	if (header === null) return { failure: "This snapshot's header isn't one this package writes." };
+	const program = programOf();
+	if (typeof program === "string") return { failure: program };
+	const components = [];
+	for (const { name, schema } of header.components) {
+		const persisted = program.components.get(name);
+		if (persisted === void 0) return { failure: `This snapshot holds component "${name}", which this program doesn't persist.` };
+		if (!sameSchema(persisted.schema, schema)) return { failure: `Component "${name}" has another schema here than in this snapshot.` };
+		components.push(persisted);
+	}
+	const resources = [];
+	for (const { name, schema, value } of header.resources) {
+		const persisted = program.resources.get(name);
+		if (persisted === void 0) return { failure: `This snapshot holds resource "${name}", which this program doesn't persist.` };
+		if (!sameSchema(persisted.schema, schema)) return { failure: `Resource "${name}" has another schema here than in this snapshot.` };
+		resources.push({
+			persisted,
+			value: fromJson(schema, value)
+		});
+	}
+	const blocks = (bytes.byteOffset + prefix + headerLength) % 8 === 0 ? bytes : bytes.slice();
+	const base = blocks.byteOffset + prefix + headerLength;
+	const end = blocks.byteOffset + blocks.byteLength;
+	const inBounds = (offset, length) => offset >= 0 && length >= 0 && base + offset + length <= end;
+	const tables = [];
+	for (const table of header.tables) {
+		if (!inBounds(table.entities, table.count * 8)) return { failure: "This snapshot's blocks are cut short." };
+		const columns = {};
+		for (const column of table.columns) {
+			const persisted = components[column.component];
+			if (persisted === void 0) return { failure: "This snapshot names a component it doesn't hold." };
+			if (column.kind === "value") columns[persisted.key] = {
+				kind: "value",
+				value: fromJson(persisted.schema, column.value)
+			};
+			else if (!inBounds(column.offset, column.length)) return { failure: "This snapshot's blocks are cut short." };
+			else if (column.kind === "bytes") columns[persisted.key] = {
+				kind: "bytes",
+				bytes: new Uint8Array(blocks.buffer, base + column.offset, column.length),
+				stride: column.stride
+			};
+			else {
+				let values;
+				try {
+					values = JSON.parse(decoder.decode(new Uint8Array(blocks.buffer, base + column.offset, column.length)));
+				} catch {
+					return { failure: `Component "${persisted.name}"'s values in this snapshot aren't JSON.` };
+				}
+				if (!Array.isArray(values)) return { failure: `Component "${persisted.name}"'s values in this snapshot aren't a list.` };
+				columns[persisted.key] = {
+					kind: "values",
+					values: values.map((value) => fromJson(persisted.schema, value))
+				};
+			}
+		}
+		tables.push({
+			count: table.count,
+			entities: new Float64Array(blocks.buffer, base + table.entities, table.count),
+			columns
+		});
+	}
+	return {
+		components,
+		tables,
+		resources
+	};
+};
+//#endregion
+//#region src/program/contents.ts
+/** Where a snapshot holds what it holds, a key only this package uses. */
+var contents = Symbol("snapshot contents");
+//#endregion
+//#region src/decode.ts
+/**
+* The snapshot `bytes` holds, its columns of bytes viewed where they are in `bytes`, copied once only when `bytes`
+* doesn't start at a multiple of 8; or why it can't be read: it isn't one, or names a component or resource this
+* program doesn't persist, or persists with another schema.
+*/
+var decode = (bytes) => {
+	const decoded = decodeContents(bytes);
+	return "failure" in decoded ? decoded : { [contents]: decoded };
+};
+//#endregion
+//#region src/encode.ts
+/**
+* A snapshot as bytes, little-endian: a header naming each persisted component and resource with its schema, then
+* 8-byte-aligned blocks of each table's entities and columns, its bytes columns copied whole.
+*/
+var encode = (snapshot) => encodeContents(snapshot[contents]);
+//#endregion
+//#region src/selection/selection.ts
+/** A readonly system reading the tables `declaration` names. */
+var tablesSystemOf = (declaration) => System.create({
+	readonly: true,
+	tables: declaration
+}, ({ tables }) => tables);
+/** The rows of `table` whose entities `keep` takes, as a table of their own. */
+var rowsOf = (table, keep) => {
+	const rows = [];
+	for (let row = 0; row < table.count; row++) if (keep(table.entities[row])) rows.push(row);
+	if (rows.length === table.count) return table;
+	if (rows.length === 0) return null;
+	const columns = {};
+	for (const key of Object.getOwnPropertySymbols(table.columns)) {
+		const column = Reflect.get(table.columns, key);
+		if (column === void 0) continue;
+		if (column.kind === "value") columns[key] = column;
+		else if (column.kind === "values") columns[key] = {
+			kind: "values",
+			values: rows.map((row) => column.values[row])
+		};
+		else {
+			const { stride } = column;
+			const bytes = new Uint8Array(rows.length * stride);
+			rows.forEach((row, at) => bytes.set(column.bytes.subarray(row * stride, (row + 1) * stride), at * stride));
+			columns[key] = {
+				kind: "bytes",
+				bytes,
+				stride
+			};
+		}
+	}
+	return {
+		count: rows.length,
+		entities: Float64Array.from(rows, (row) => table.entities[row]),
+		columns
+	};
+};
+/** The entities `root` owns, itself included, through the owner references among `owners` in the tables. */
+var subtreeOf = (tables, owners, root) => {
+	const children = /* @__PURE__ */ new Map();
+	for (const table of tables) for (const reference of owners) {
+		const key = reference;
+		const column = Reflect.get(table.columns, key);
+		if (column?.kind !== "bytes") continue;
+		const view = new DataView(column.bytes.buffer, column.bytes.byteOffset, column.bytes.byteLength);
+		for (let row = 0; row < table.count; row++) {
+			const owner = view.getFloat64(row * column.stride, true);
+			const list = children.get(owner);
+			if (list === void 0) children.set(owner, [table.entities[row]]);
+			else list.push(table.entities[row]);
+		}
+	}
+	const taken = /* @__PURE__ */ new Set([root]);
+	const waiting = [root];
+	for (let next = waiting.pop(); next !== void 0; next = waiting.pop()) for (const child of children.get(next) ?? []) {
+		if (taken.has(child)) continue;
+		taken.add(child);
+		waiting.push(child);
+	}
+	return taken;
+};
+/** The persisted part of the entities `selection` takes from `world`, on its thread, or why it can't be read. */
+var select = async (world, program, selection) => {
+	const components = [...program.components.values()];
+	const keys = components.map((persisted) => persisted.key);
+	const subtree = "root" in selection;
+	const resources = subtree || selection.resources === false ? [] : [...program.resources.values()];
+	const declaration = subtree ? { components: keys } : {
+		components: keys,
+		with: selection.with ?? [],
+		not: selection.not ?? [],
+		resources: resources.map((persisted) => persisted.key)
+	};
+	const read = await world.run(tablesSystemOf(declaration)).catch((error) => ({ failure: error instanceof Error ? error.message : String(error) }));
+	if ("failure" in read) return read;
+	let tables = read.archetypes;
+	if (subtree) {
+		const owners = keys.filter((key) => Component.declarations().get(key)?.reference === "owner");
+		const taken = subtreeOf(tables, owners, selection.root);
+		tables = tables.flatMap((table) => rowsOf(table, (entity) => taken.has(entity)) ?? []);
+	}
+	return {
+		components,
+		tables,
+		resources: resources.map((persisted) => ({
+			persisted,
+			value: read.resources[persisted.key]
+		}))
+	};
+};
+//#endregion
+//#region src/snapshot.ts
+/**
+* A snapshot of some of `world`'s entities, read on its thread: by default every entity holding a persisted
+* component, and the persisted resources; with `with` and `not`, those a query matches, and the resources unless
+* `resources` is false; with `root`, it and every entity it owns, through persisted owner references, without
+* resources. Fails, as data, when the program's persisted keys can't be saved or the world can't be read.
+*/
+var snapshot = async (input) => {
+	const program = programOf();
+	if (typeof program === "string") return { failure: program };
+	const taken = await select(input.world, program, input);
+	return "failure" in taken ? taken : { [contents]: taken };
+};
+//#endregion
+//#region src/spawn.ts
+var isTables = (value) => Array.isArray(value) && value.every((table) => typeof table === "object" && table !== null && typeof Reflect.get(table, "count") === "number" && Reflect.get(table, "entities") instanceof Float64Array && typeof Reflect.get(table, "columns") === "object");
+var isKeyed = (value) => typeof value === "object" && value !== null;
+/** Spawns its input's tables and sets its resources, a snapshot's, rewriting their entities. */
+var spawnTables = System.create({}, ({ commands }, input) => {
+	if (!isTables(input.tables) || !isKeyed(input.resources)) throw new Error("A snapshot holds tables and resources.");
+	return commands.spawnTables(input.tables, input.resources);
+}, {
+	"type": "object",
+	"properties": {
+		"tables": { "allOf": [] },
+		"resources": { "allOf": [] }
+	}
+});
+async function spawn(input) {
+	const { tables, resources } = input.snapshot[contents];
+	const values = {};
+	for (const { persisted, value } of resources) values[persisted.key] = value;
+	const spawned = await input.world.run(spawnTables, {
+		tables,
+		resources: values
+	}).catch((error) => ({ failure: error instanceof Error ? error.message : String(error) }));
+	if ("failure" in spawned) return spawned;
+	if (input.entities === false) return { dropped: spawned.dropped };
+	return {
+		dropped: spawned.dropped,
+		entities: entitiesOf(tables, spawned.entities)
+	};
+}
+/** Each of the tables' entities to the one spawned for it, or null for one that wasn't. */
+var entitiesOf = (tables, spawned) => {
+	const entities = /* @__PURE__ */ new Map();
+	tables.forEach((table, t) => {
+		const made = spawned[t];
+		for (let row = 0; row < table.count; row++) {
+			const entity = made[row];
+			entities.set(table.entities[row], entity === 0 ? null : entity);
+		}
+	});
+	return entities;
+};
+//#endregion
+export { decode, encode, persist, snapshot, spawn };
+
+//# sourceMappingURL=index.js.map