@wildshard/shard-format 0.0.1 → 0.4.6

package/src/format/propMaterials.ts

@@ -0,0 +1,254 @@
+import { graphUsesMeshMap } from './materialGraph.ts';
+/**
+ * Named prop materials (SHARD-PLATFORM SF55, G211): the data half of the GLB material adapter for authored (Blender)
+ * worlds. Without it, every declared prop mesh draws with `props.family` and one per-model colour texture (the default
+ * path, unchanged). With it, `props.materials` maps each baked GLB `material.name` (the source glTF material's exact name,
+ * which the world bake keeps) to an admitted `look.materials` ID (or a platform family default) plus that surface's KTX2
+ * texture slots and their glTF samplers: colour, normal (with its scale), metallic-roughness, occlusion (with its strength)
+ * and emissive.
+ *
+ * - **No silent slot:** a mapped name whose material family cannot draw a slot is refused here (painterly reads no
+ *   metallic-roughness; emissive reads only colour), and a graph material takes a slot only into its own texture param of
+ *   the same name. A GLB material name absent from the map refuses its install (`checkPropMaterialNames`, and the engine
+ *   installer at parse time).
+ * - **Charged by the tiles:** every slot file is a KTX2 dependency of a declared props GLB, so the tile (or library) claim
+ *   that leases the GLB already carries its textures.
+ * - **One sampler per file:** a texture file is one GPU texture; two bindings may share a file only with equal samplers, and
+ *   a slot file is never also a `look.materials` texture (whose sampler is the platform's default).
+ *
+ * The schema lives here, outside the format file (format ownership: sp-x5 wires `materials: v.exactOptional(PropMaterialsSchema)`
+ * into `PropsSchema` and calls `validatePropMaterials` from the props reference check).
+ */
+import * as v from 'valibot';
+import { FAMILY_IDS } from './materialFamilies.ts';
+import { materialGraphIr, materialTextureRefs, type MaterialsSchema } from './materials.ts';
+
+const ref = v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/u));
+const id = v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.-]*$/u), v.maxLength(128));
+/** A glTF material name as Blender exports it: exact, case-sensitive, spaces and numeric suffixes kept. */
+const glbName = v.pipe(v.string(), v.minLength(1), v.maxLength(128), v.regex(/^\P{Cc}+$/u, 'no control characters'), v.check((name) => name.trim() === name, 'no edge whitespace'), v.check((name) => !['__proto__', 'prototype', 'constructor'].includes(name), 'reserved name'));
+/** glTF sampler enums (WebGL constants), as the world normalizer admits them. */
+const wrap = v.picklist([33071, 33648, 10497]);
+/** `anisotropy` (G227): the texture's anisotropic filtering samples, 1 (off) to 16, capped by the device (a hero prop's 4) */
+const sampler = { file: ref, wrapS: v.optional(wrap, 10497), wrapT: v.optional(wrap, 10497), minFilter: v.optional(v.nullable(v.picklist([9728, 9729, 9984, 9985, 9986, 9987])), null), magFilter: v.optional(v.nullable(v.picklist([9728, 9729])), null), anisotropy: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(16)), 1) };
+const slot = v.strictObject(sampler);
+const finite = v.pipe(v.number(), v.finite());
+/** The texture slots a named prop material may bind. */
+export const PROP_MATERIAL_SLOTS = ['colour', 'normal', 'metallicRoughness', 'occlusion', 'emissive'] as const;
+/** One texture slot name. */
+export type PropMaterialSlot = (typeof PROP_MATERIAL_SLOTS)[number];
+const binding = v.strictObject({
+  id,
+  colour: v.optional(v.nullable(slot), null),
+  normal: v.optional(v.nullable(v.strictObject({ ...sampler, scale: v.optional(v.pipe(finite, v.minValue(0), v.maxValue(4)), 1) })), null),
+  metallicRoughness: v.optional(v.nullable(slot), null),
+  occlusion: v.optional(v.nullable(v.strictObject({ ...sampler, strength: v.optional(v.pipe(finite, v.minValue(0), v.maxValue(1)), 1) })), null),
+  emissive: v.optional(v.nullable(slot), null),
+});
+/** `props.materials`: baked GLB material name → admitted material ID and its texture slots (1–256 names). */
+export const PropMaterialsSchema: v.GenericSchema<PropMaterialsInput, PropMaterials> = v.pipe(v.record(glbName, binding), v.check((rows) => { const n = Object.keys(rows).length; return n >= 1 && n <= 256; }, '1–256 named prop materials'));
+/** Admitted named prop materials. */
+
+/** One admitted binding. */
+export type PropMaterialBinding = PropMaterials[string];
+/** One admitted texture slot with its sampler (and the normal scale / occlusion strength where the slot has one). */
+export type PropTextureSlot = NonNullable<PropMaterialBinding['colour']> & { readonly scale?: number; readonly strength?: number };
+
+const read = new WeakMap<object, PropMaterials | undefined>();
+/**
+ * A props section's named materials, admitted (undefined: the one-family path). Reads the additive `materials` field
+ * whether or not the format's `PropsSchema` declares it yet, and validates it once per props object.
+ */
+export function propMaterialsOf(props: object): PropMaterials | undefined {
+  if (read.has(props)) return read.get(props);
+  const raw: unknown = 'materials' in props ? props.materials : undefined;
+  const value = raw === undefined ? undefined : v.parse(PropMaterialsSchema, raw);
+  read.set(props, value); return value;
+}
+
+/** A binding's filled slots, in slot order. */
+export function propMaterialSlots(row: PropMaterialBinding): [PropMaterialSlot, PropTextureSlot][] {
+  return PROP_MATERIAL_SLOTS.flatMap((name): [PropMaterialSlot, PropTextureSlot][] => { const value = row[name]; return value === null ? [] : [[name, value]]; });
+}
+/** Every texture file the named prop materials bind (the client transcodes them with the catalogue). */
+export function propMaterialTextureRefs(materials: PropMaterials | undefined): string[] {
+  return materials === undefined ? [] : [...new Set(Object.values(materials).flatMap((row) => propMaterialSlots(row).map(([, value]) => value.file)))];
+}
+/** How a slot's texels are read: colour and emissive are sRGB, the rest numeric data. */
+export function propSlotUse(name: PropMaterialSlot): 'colour' | 'data' { return name === 'colour' || name === 'emissive' ? 'colour' : 'data'; }
+
+/** The slots each material family can draw; a graph draws a slot only through its own texture param of that name. */
+const FAMILY_SLOTS: Readonly<Record<string, readonly PropMaterialSlot[]>> = {
+  pbr: PROP_MATERIAL_SLOTS, toon: PROP_MATERIAL_SLOTS, painterly: ['colour', 'normal', 'occlusion', 'emissive'], emissive: ['colour'],
+};
+const samplerKey = (s: PropTextureSlot): string => `${s.wrapS}/${s.wrapT}/${s.minFilter ?? '-'}/${s.magFilter ?? '-'}/${s.anisotropy}`;
+
+/**
+ * Check named prop materials against the look catalogue and the admitted files: each ID resolves (an authored entry or a
+ * family default), each slot is one its family draws, each file is a KTX2 dependency of a declared props GLB in one
+ * colour / data role with one sampler, and never also a catalogue texture; `props.textures` stays empty (`models` is
+ * every declared props GLB: tiles, panels, models and the far proxy). Throws the first refusal, naming it.
+ */
+export function validatePropMaterials(materials: PropMaterials, context: {
+  look: v.InferOutput<typeof MaterialsSchema>; models: readonly string[]; textures: readonly { model: string }[];
+  files: readonly { hash: string; kind: string; dependencies: readonly string[] }[];
+  /** a graph file's bytes (product admission); without it a graph file's slots are checked there (D74) */
+  graphFile?: (hash: string) => Uint8Array | undefined;
+}): void {
+  // the per-model colour texture is the one-family path's; with named materials every texture is a slot
+  if (context.textures.length > 0) throw new Error('props.materials replaces props.textures: bind each texture as a named material slot');
+  const files = new Map(context.files.map((file) => [file.hash, file]));
+  const declared = new Set(context.models.flatMap((model) => files.get(model)?.dependencies ?? []));
+  const catalogue = new Set(materialTextureRefs(context.look)), roles = new Map<string, string>(), samplers = new Map<string, string>();
+  for (const [name, row] of Object.entries(materials)) {
+    const entry = Object.hasOwn(context.look, row.id) ? context.look[row.id] : undefined;
+    const family = entry?.family ?? FAMILY_IDS.find((f) => f === row.id);
+    if (family === undefined) throw new Error(`props material "${name}": ${row.id} is not an admitted material ID`);
+    for (const [slotName, value] of propMaterialSlots(row)) {
+      if (family === 'graph') {
+        if (entry?.family === 'graph' && 'preset' in entry) throw new Error(`props material "${name}": its texture slots bind a graph, not a preset reference`);
+        const graphFile = context.graphFile, graph = entry?.family !== 'graph' ? undefined : !('file' in entry) ? entry.graph : graphFile === undefined ? null : materialGraphIr(entry, graphFile);
+        const param = graph === null ? undefined : graph?.params?.[slotName];
+        if (graph !== null && param?.type !== 'texture' && !(slotName === 'colour' && graph !== undefined && graphUsesMeshMap(graph))) throw new Error(`props material "${name}": graph ${row.id} has no texture param "${slotName}" for its ${slotName} slot`);
+      } else if (!(FAMILY_SLOTS[family] ?? []).includes(slotName)) throw new Error(`props material "${name}": the ${family} family draws no ${slotName} slot`);
+      const file = files.get(value.file);
+      if (file?.kind !== 'ktx2' || !declared.has(value.file)) throw new Error(`props material "${name}": its ${slotName} texture must be a KTX2 dependency of a declared props GLB`);
+      if (catalogue.has(value.file)) throw new Error(`props material "${name}": its ${slotName} texture is also a look.materials texture (one sampler per file)`);
+      // a graph reads every texture param in the colour role (clientGraphs): its slots take that role
+      const role = family === 'graph' ? 'colour' : propSlotUse(slotName), seenRole = roles.get(value.file);
+      if (seenRole !== undefined && seenRole !== role) throw new Error(`props material "${name}": one texture cannot mix colour and numeric data roles`);
+      roles.set(value.file, role);
+      const key = samplerKey(value), seenSampler = samplers.get(value.file);
+      if (seenSampler !== undefined && seenSampler !== key) throw new Error(`props material "${name}": one texture file takes one sampler`);
+      samplers.set(value.file, key);
+    }
+  }
+}
+
+/** An admitted GLB's JSON document (its JSON chunk only; run after the bounded GLB parser admitted the bytes). */
+function glbDocument(bytes: Uint8Array): object {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (bytes.length < 20 || view.getUint32(0, true) !== 0x46546c67 || view.getUint32(16, true) !== 0x4e4f534a) throw new Error('invalid GLB header');
+  const doc: unknown = JSON.parse(new TextDecoder().decode(bytes.subarray(20, 20 + view.getUint32(12, true))));
+  if (typeof doc !== 'object' || doc === null) throw new Error('invalid GLB JSON');
+  return doc;
+}
+const rowsOf = (value: unknown, key: string): unknown[] => { const rows: unknown = typeof value === 'object' && value !== null ? Reflect.get(value, key) : undefined; return Array.isArray(rows) ? rows : []; };
+/** The material names an admitted self-contained GLB declares ('' for an unnamed one). */
+export function glbMaterialNames(bytes: Uint8Array): string[] {
+  return rowsOf(glbDocument(bytes), 'materials').map((row) => { const name: unknown = typeof row === 'object' && row !== null ? Reflect.get(row, 'name') : undefined; return typeof name === 'string' ? name : ''; });
+}
+/**
+ * Refuse a props GLB that names (or leaves unnamed) a material the map does not carry, or has a primitive without a
+ * material: with named materials on, nothing draws a guessed surface.
+ */
+export function checkPropMaterialNames(materials: PropMaterials, bytes: Uint8Array): void {
+  for (const name of glbMaterialNames(bytes)) if (!Object.hasOwn(materials, name)) throw new Error(`props GLB material "${name || '(unnamed)'}" is not in props.materials`);
+  for (const mesh of rowsOf(glbDocument(bytes), 'meshes')) for (const primitive of rowsOf(mesh, 'primitives')) {
+    if (typeof primitive !== 'object' || primitive === null || typeof Reflect.get(primitive, 'material') !== 'number') throw new Error('props GLB primitive has no material');
+  }
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type PropMaterialsInput = Record<string, {
+    id: string;
+    colour?: ({
+        file: string;
+        wrapS?: 33071 | 33648 | 10497 | undefined;
+        wrapT?: 33071 | 33648 | 10497 | undefined;
+        minFilter?: (9728 | 9729 | 9984 | 9985 | 9986 | 9987) | null | undefined;
+        magFilter?: (9728 | 9729) | null | undefined;
+        anisotropy?: number | undefined;
+    }) | null | undefined;
+    normal?: (Omit<{
+        file: string;
+        wrapS?: 33071 | 33648 | 10497 | undefined;
+        wrapT?: 33071 | 33648 | 10497 | undefined;
+        minFilter?: (9728 | 9729 | 9984 | 9985 | 9986 | 9987) | null | undefined;
+        magFilter?: (9728 | 9729) | null | undefined;
+        anisotropy?: number | undefined;
+    }, keyof ({
+        scale?: number | undefined;
+    })> & {
+        scale?: number | undefined;
+    }) | null | undefined;
+    metallicRoughness?: ({
+        file: string;
+        wrapS?: 33071 | 33648 | 10497 | undefined;
+        wrapT?: 33071 | 33648 | 10497 | undefined;
+        minFilter?: (9728 | 9729 | 9984 | 9985 | 9986 | 9987) | null | undefined;
+        magFilter?: (9728 | 9729) | null | undefined;
+        anisotropy?: number | undefined;
+    }) | null | undefined;
+    occlusion?: (Omit<{
+        file: string;
+        wrapS?: 33071 | 33648 | 10497 | undefined;
+        wrapT?: 33071 | 33648 | 10497 | undefined;
+        minFilter?: (9728 | 9729 | 9984 | 9985 | 9986 | 9987) | null | undefined;
+        magFilter?: (9728 | 9729) | null | undefined;
+        anisotropy?: number | undefined;
+    }, keyof ({
+        strength?: number | undefined;
+    })> & {
+        strength?: number | undefined;
+    }) | null | undefined;
+    emissive?: ({
+        file: string;
+        wrapS?: 33071 | 33648 | 10497 | undefined;
+        wrapT?: 33071 | 33648 | 10497 | undefined;
+        minFilter?: (9728 | 9729 | 9984 | 9985 | 9986 | 9987) | null | undefined;
+        magFilter?: (9728 | 9729) | null | undefined;
+        anisotropy?: number | undefined;
+    }) | null | undefined;
+}>;
+export type PropMaterials = Record<string, {
+    id: string;
+    colour: ({
+        file: string;
+        wrapS: 33071 | 33648 | 10497;
+        wrapT: 33071 | 33648 | 10497;
+        minFilter: (9728 | 9729 | 9984 | 9985 | 9986 | 9987) | null;
+        magFilter: (9728 | 9729) | null;
+        anisotropy: number;
+    }) | null;
+    normal: (Omit<{
+        file: string;
+        wrapS: 33071 | 33648 | 10497;
+        wrapT: 33071 | 33648 | 10497;
+        minFilter: (9728 | 9729 | 9984 | 9985 | 9986 | 9987) | null;
+        magFilter: (9728 | 9729) | null;
+        anisotropy: number;
+    }, keyof ({
+        scale: number;
+    })> & {
+        scale: number;
+    }) | null;
+    metallicRoughness: ({
+        file: string;
+        wrapS: 33071 | 33648 | 10497;
+        wrapT: 33071 | 33648 | 10497;
+        minFilter: (9728 | 9729 | 9984 | 9985 | 9986 | 9987) | null;
+        magFilter: (9728 | 9729) | null;
+        anisotropy: number;
+    }) | null;
+    occlusion: (Omit<{
+        file: string;
+        wrapS: 33071 | 33648 | 10497;
+        wrapT: 33071 | 33648 | 10497;
+        minFilter: (9728 | 9729 | 9984 | 9985 | 9986 | 9987) | null;
+        magFilter: (9728 | 9729) | null;
+        anisotropy: number;
+    }, keyof ({
+        strength: number;
+    })> & {
+        strength: number;
+    }) | null;
+    emissive: ({
+        file: string;
+        wrapS: 33071 | 33648 | 10497;
+        wrapT: 33071 | 33648 | 10497;
+        minFilter: (9728 | 9729 | 9984 | 9985 | 9986 | 9987) | null;
+        magFilter: (9728 | 9729) | null;
+        anisotropy: number;
+    }) | null;
+}>;

package/src/format/props.ts

@@ -0,0 +1,137 @@
+import * as v from 'valibot';
+import { CELL_ABOVE, CELL_BELOW } from './contentBounds.ts';
+import { isJsonData } from './json.ts';
+import { PropMaterialsSchema, propMaterialTextureRefs, validatePropMaterials } from './propMaterials.ts';
+import { SplatTerrainSchema, validateSplatTerrain } from './splatTerrain.ts';
+import { glbPoint, glbTransform } from './glbTriangles.ts';
+
+const ref = v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/u));
+const id = v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.-]*$/u), v.maxLength(128));
+const address = v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(7));
+const named = v.strictObject({ id, file: ref });
+const coord = v.pipe(v.number(), v.finite(), v.minValue(-250), v.maxValue(250));
+const height = v.pipe(v.number(), v.finite(), v.minValue(-CELL_BELOW), v.maxValue(CELL_ABOVE));
+const finite = v.pipe(v.number(), v.finite());
+const extent = v.pipe(finite, v.minValue(0.005), v.maxValue(250));
+const point = v.strictObject({ x: coord, y: height, z: coord });
+const surface = v.optional(v.picklist(['wood', 'stone', 'grass', 'sand', 'rock', 'metal', 'earth', 'felt']));
+const rotation = v.pipe(v.strictObject({ x: finite, y: finite, z: finite, w: finite }), v.check((q) => Math.abs(q.x ** 2 + q.y ** 2 + q.z ** 2 + q.w ** 2 - 1) < 1e-5, 'unit collider rotation'));
+const boxData = v.strictObject({ kind: v.literal('box'), x: coord, y: height, z: coord, hx: extent, hy: extent, hz: extent, yaw: v.optional(finite), rot: v.optional(rotation), surface });
+function boxWithinCell(b: v.InferOutput<typeof boxData>): boolean {
+  const q = b.rot ?? { x: 0, y: Math.sin((b.yaw ?? 0) / 2), z: 0, w: Math.cos((b.yaw ?? 0) / 2) };
+  const transform = glbTransform({ translation: [b.x, b.y, b.z], rotation: [q.x, q.y, q.z, q.w] });
+  return Array.from({ length: 8 }, (_unused, index) => glbPoint(transform, {
+    x: (index & 1) === 0 ? -b.hx : b.hx, y: (index & 2) === 0 ? -b.hy : b.hy, z: (index & 4) === 0 ? -b.hz : b.hz,
+  })).every(vertex => Math.abs(vertex.x) <= 250 && Math.abs(vertex.z) <= 250 && vertex.y >= -CELL_BELOW && vertex.y <= CELL_ABOVE);
+}
+const box = v.pipe(boxData, v.check(boxWithinCell, 'collider within cell'));
+const treads = v.pipe(v.strictObject({ kind: v.literal('treads'), from: point, to: point, width: extent, count: v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(256)), surface }), v.check((t) => Math.hypot(t.to.x - t.from.x, t.to.z - t.from.z) > 0 && t.to.y >= t.from.y && [t.from, t.to].every((p) => Math.abs(p.x) + t.width / 2 <= 250 && Math.abs(p.z) + t.width / 2 <= 250), 'bounded nondegenerate stair'));
+const collider = v.strictObject({ id, panel: v.nullable(id), initialActive: v.boolean(), shapes: v.pipe(v.array(v.variant('kind', [box, treads])), v.minLength(1), v.maxLength(256)) });
+/** Declared self-contained GLBs: merged tile meshes, EXT_mesh_gpu_instancing lists, far proxy and script-addressable panels. */
+export const PropsSchema: v.GenericSchema<PropsDataInput, PropsData> = v.pipe(v.unknown(), v.check(isJsonData, 'JSON-only props'), v.strictObject({ version: v.literal(1), family: id,
+  materials: v.exactOptional(PropMaterialsSchema),
+  /** Explicit visual-only edge allowance in metres; absent preserves the fixed-cell refusal. */
+  overhang: v.exactOptional(v.pipe(v.number(), v.finite(), v.minValue(0), v.maxValue(1))),
+  /** Exact whole source draws in ordinary library GLBs, installed only by a props-bound runtime. */
+  wholeLibrary: v.exactOptional(v.pipe(v.array(ref), v.minLength(1), v.maxLength(512), v.check(rows => new Set(rows).size === rows.length, 'unique whole library refs'))),
+  splat: v.exactOptional(SplatTerrainSchema),
+  tiles: v.pipe(v.array(v.strictObject({ lod: v.picklist([0, 1]), x: address, z: address, file: ref,
+    additionalFiles: v.exactOptional(v.pipe(v.array(ref), v.minLength(1), v.maxLength(128))) })), v.maxLength(80)),
+  panels: v.pipe(v.array(v.strictObject({ id, file: ref, visible: v.optional(v.boolean(), true) })), v.maxLength(64)), models: v.pipe(v.array(named), v.maxLength(64)), far: v.nullable(ref),
+  colliders: v.optional(v.pipe(v.array(collider), v.maxLength(1024)), []),
+  textures: v.pipe(v.array(v.strictObject({ model: ref, colour: ref })), v.maxLength(256)),
+}), v.check((s) => new Set(s.tiles.map((t) => `${t.lod}/${t.x}/${t.z}`)).size === s.tiles.length && s.tiles.every((t) => t.x < (t.lod === 0 ? 8 : 4) && t.z < (t.lod === 0 ? 8 : 4)) && new Set([...s.panels, ...s.models].map((p) => p.id)).size === s.panels.length + s.models.length && new Set(s.textures.map((t) => t.model)).size === s.textures.length && new Set(s.colliders.map((c) => c.id)).size === s.colliders.length && s.colliders.reduce((n, c) => n + c.shapes.reduce((m, shape) => m + (shape.kind === 'treads' ? shape.count : 1), 0), 0) <= 2048 && s.colliders.every((c) => c.panel === null || s.panels.some((p) => p.id === c.panel)), 'unique props addresses and ids'));
+/** Validated data for the props renderer; no callbacks, URLs or generator code enter this section. */
+export type ShardProps = v.InferOutput<typeof PropsSchema>;
+/** Check every render binding against ordinary admitted file, tile and library rows before allocating content. */
+export function validatePropsReferences(props: ShardProps, content: { files: readonly { hash: string; kind: string; dependencies: readonly string[] }[]; tiles: readonly { lod: number; x: number; z: number; files: readonly string[] }[]; library: readonly string[]; far: { files: readonly string[] } | null; look?: { materials: Parameters<typeof validatePropMaterials>[1]['look'] } }): void {
+  const files = new Map(content.files.map((f) => [f.hash, f]));
+  const model = (hash: string) => { if (files.get(hash)?.kind !== 'glb') throw new Error('Prop model must reference an admitted GLB'); };
+  for (const tile of props.tiles) {
+    const refs = [tile.file, ...tile.additionalFiles ?? []];
+    if (new Set(refs).size !== refs.length) throw new Error('Props tile repeats a file');
+    for (const hash of refs) { model(hash); if (!content.tiles.find((t) => t.lod === tile.lod && t.x === tile.x && t.z === tile.z)?.files.includes(hash)) throw new Error('Props tile disagrees with tile files'); }
+  }
+  for (const hash of props.wholeLibrary ?? []) { model(hash); if (!content.library.includes(hash)) throw new Error('Whole geometry must belong to the library'); }
+  for (const entry of [...props.panels, ...props.models]) { model(entry.file); if (!content.library.includes(entry.file)) throw new Error('Prop panel/model must belong to the library'); }
+  if (props.far !== null) { model(props.far); if (!content.far?.files.includes(props.far)) throw new Error('Props far proxy disagrees with far files'); }
+  const refs = new Set([...props.tiles.flatMap((t) => [t.file, ...t.additionalFiles ?? []]), ...props.panels.map((p) => p.file), ...props.models.map((p) => p.file), ...(props.far === null ? [] : [props.far])]);
+  for (const texture of props.textures) if (!refs.has(texture.model) || files.get(texture.colour)?.kind !== 'ktx2' || !files.get(texture.model)?.dependencies.includes(texture.colour)) throw new Error('Prop texture must be a declared KTX2 dependency');
+  if (props.materials !== undefined) validatePropMaterials(props.materials, { look: content.look?.materials ?? {}, models: [...refs], textures: props.textures, files: content.files });
+  if (props.splat !== undefined) {
+    if (props.materials !== undefined && Object.hasOwn(props.materials, props.splat.material)) throw new Error('Splat terrain material cannot also name a prop material');
+    validateSplatTerrain(props.splat, { look: content.look?.materials ?? {}, tiles: props.tiles.map(tile => tile.file),
+      propTextures: [...props.textures.map(texture => texture.colour), ...propMaterialTextureRefs(props.materials)], files: content.files });
+  }
+}
+
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type PropsDataInput = unknown;
+interface PropsDataFields {
+    version: 1;
+    family: string;
+    materials?: v.InferOutput<typeof PropMaterialsSchema>;
+    overhang?: number;
+    wholeLibrary?: (string)[];
+    splat?: v.InferOutput<typeof SplatTerrainSchema>;
+    tiles: ({
+        lod: 0 | 1;
+        x: number;
+        z: number;
+        file: string;
+        additionalFiles?: (string)[];
+    })[];
+    panels: ({
+        id: string;
+        file: string;
+        visible: boolean;
+    })[];
+    models: ({
+        id: string;
+        file: string;
+    })[];
+    far: (string) | null;
+    colliders: ({
+        id: string;
+        panel: (string) | null;
+        initialActive: boolean;
+        shapes: (({
+            kind: 'box';
+            x: number;
+            y: number;
+            z: number;
+            hx: number;
+            hy: number;
+            hz: number;
+            yaw?: number | undefined;
+            rot?: {
+                x: number;
+                y: number;
+                z: number;
+                w: number;
+            } | undefined;
+            surface?: 'wood' | 'stone' | 'grass' | 'sand' | 'rock' | 'metal' | 'earth' | 'felt' | undefined;
+        }) | ({
+            kind: 'treads';
+            from: {
+                x: number;
+                y: number;
+                z: number;
+            };
+            to: {
+                x: number;
+                y: number;
+                z: number;
+            };
+            width: number;
+            count: number;
+            surface?: 'wood' | 'stone' | 'grass' | 'sand' | 'rock' | 'metal' | 'earth' | 'felt' | undefined;
+        }))[];
+    })[];
+    textures: ({
+        model: string;
+        colour: string;
+    })[];
+}
+export type PropsData = { [Key in keyof PropsDataFields]: PropsDataFields[Key] };

package/src/format/questContinuation.ts

@@ -0,0 +1,42 @@
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+import { LootBagSchema } from './lootBag.ts';
+
+const id = v.pipe(v.string(), v.minLength(1), v.maxLength(256));
+/** Client-only continuation over entered quest and collection owners. Every
+ * model, economy and scheduling choice is an admitted data identity. */
+export const QuestContinuationSchema: v.GenericSchema<QuestContinuationRowsInput, QuestContinuationRows> = v.pipe(v.unknown(), v.check(isJsonData, 'Quest continuation requires JSON rows'), v.strictObject({
+  quest: id, collection: id,
+  collections: v.literal('collections/displays'),
+  cosmetics: v.strictObject({ file: id, models: v.pipe(v.record(id, id), v.maxEntries(32)) }),
+  loot: v.strictObject({ bag: v.exactOptional(LootBagSchema), id, shop: id, minimap: v.boolean(), before: v.pipe(v.array(id), v.maxLength(64)) }),
+}));
+
+/** Read standalone rows or the fixed resource field of an admitted quest page.
+ * The field is compiled here; documents cannot provide a selector or callback. */
+export function parseQuestContinuationDocument(input: unknown): v.InferOutput<typeof QuestContinuationSchema> {
+  const rows = v.parse(v.pipe(v.unknown(), v.check(isJsonData, 'Quest document requires JSON rows'), v.union([
+    QuestContinuationSchema, v.object({ entryResources: v.object({ continuation: QuestContinuationSchema }) }),
+  ])), input);
+  return 'entryResources' in rows ? rows.entryResources.continuation : rows;
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type QuestContinuationRowsInput = unknown;
+interface QuestContinuationRowsFields {
+    quest: string;
+    collection: string;
+    collections: 'collections/displays';
+    cosmetics: {
+        file: string;
+        models: Record<string, string>;
+    };
+    loot: {
+        bag?: v.InferOutput<typeof LootBagSchema>;
+        id: string;
+        shop: string;
+        minimap: boolean;
+        before: (string)[];
+    };
+}
+export type QuestContinuationRows = { [Key in keyof QuestContinuationRowsFields]: QuestContinuationRowsFields[Key] };

package/src/format/questFigures.ts

@@ -0,0 +1,227 @@
+/** A quest page's placed kit figures (`quest.composition` `figures.file`, G571): each figure's kit and catalogue rows by
+ *  id, where it stands (composition places), its part geometry and extra objects by scene resource id, what it
+ *  publishes, and its pose system; a trader figure adds its counter model and live owners. Numbers and ids only. */
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+import { SpecimenModelMetadataSchema } from './specimenCatalogue.ts';
+import { FigureGroupSchema } from './figures.ts';
+
+const id = v.pipe(v.string(), v.minLength(1), v.maxLength(128)), n = v.pipe(v.number(), v.finite()), triple = v.tuple([n, n, n]);
+const place = v.strictObject({ poi: id, x: n, z: n, y: v.exactOptional(n), dy: v.exactOptional(n), yaw: v.exactOptional(n), anchor: v.exactOptional(id) });
+/** where an object sits in the figure's frame: its feet (origin), or the fire turned into that frame */
+const at = v.picklist(['feet', 'fire']);
+const object = v.variant('kind', [
+  /** an unlit vertex-coloured mesh (a fire's flames: colour > 1 blooms) */
+  v.strictObject({ kind: v.literal('basic-mesh'), id, name: id, draw: id, colour: triple, vertexColors: v.boolean(), at, lift: n }),
+  /** a building cloud (smoke) in a lent look: hidden, on an empty draw, until its draw and look are both lent */
+  v.strictObject({ kind: v.literal('cloud'), id, name: id, draw: id, look: id, at, center: triple, radius: n, order: n, seeds: v.boolean() }),
+]);
+const system = v.strictObject({ id, before: v.pipe(v.array(id), v.maxLength(8)) });
+const ids = v.pipe(v.record(id, id), v.maxEntries(16));
+export const QuestFigureSchema: v.GenericSchema<QuestFigureRowsInput, QuestFigureRows> = v.strictObject({
+  id, kit: id, feet: place, fire: v.exactOptional(place),
+  /** each kit part's fixed draw slot; campAt 'fire' moves the camp part to the fire */
+  parts: ids, campAt: v.exactOptional(v.literal('fire')),
+  objects: v.optional(v.pipe(v.array(object), v.maxLength(8)), []),
+  publish: v.optional(v.pipe(v.array(v.strictObject({ id, draw: id })), v.maxLength(8)), []),
+  /** a placed trader: its registry piece and name, the catalogue model whose static card is its specimen, and the counter
+   *  model ahead metres in front of its feet */
+  piece: v.exactOptional(id), card: v.exactOptional(id), name: v.exactOptional(id),
+  counter: v.exactOptional(v.strictObject({ model: id, ahead: n, piece: id, name: id, solidFloor: v.boolean() })),
+  system,
+});
+/** One live figure per kit: a kit's catalogue rows name its part sources (`<kit>.<part>.source`) and its attention
+ *  programs (`npc.<kit>`), so two rows reusing a kit would collide in the page's resources; ids are unique too. A page
+ *  may instead declare one merged figure group (format/figures `FigureGroupSchema`: its figures drawn as one atlas skin),
+ *  never beside kit figures. */
+export const QuestFiguresSchema: v.GenericSchema<QuestFiguresRowsInput, QuestFiguresRows> = v.pipe(v.unknown(), v.check(isJsonData, 'plain JSON figures'),
+  v.strictObject({ figures: v.pipe(v.array(QuestFigureSchema), v.maxLength(8),
+    v.check(rows => new Set(rows.map(row => row.kit)).size === rows.length && new Set(rows.map(row => row.id)).size === rows.length, 'one figure per kit, unique ids')),
+  group: v.exactOptional(FigureGroupSchema) }), v.check(rows => rows.group === undefined || rows.figures.length === 0, 'a merged figure group stands alone'));
+
+
+
+
+/** Cold Explorer kit cards reuse the live figure rows; their model has no
+ * ignored params or variants and their source selects one fixed field only. */
+export const KitFigureCardsSchema: v.GenericSchema<KitFigureCardsRowsInput, KitFigureCardsRows> = v.pipe(v.unknown(), v.check(isJsonData, 'Kit figure cards require plain JSON'), v.strictObject({
+  catalogue: id, draws: v.literal('models/island-library'),
+  cards: v.pipe(v.record(id, v.strictObject({
+    model: v.strictObject({ ...v.pick(SpecimenModelMetadataSchema, ['id', 'name', 'file', 'category', 'pipeline', 'surface']).entries, defaults: v.strictObject({}) }),
+    figure: QuestFigureSchema,
+  })), v.maxEntries(64), v.check(rows => Object.keys(rows).length > 0, 'at least one kit figure card')),
+}));
+
+
+/** Read standalone rows or the fixed resource field of an admitted quest page.
+ * The field is compiled here; documents cannot provide a selector or callback. */
+export function parseQuestFiguresDocument(input: unknown): QuestFiguresRows {
+  const rows = v.parse(v.pipe(v.unknown(), v.check(isJsonData, 'Quest document requires JSON rows'), v.union([
+    QuestFiguresSchema, v.object({ entryResources: v.object({ figures: QuestFiguresSchema }) }),
+  ])), input);
+  return 'entryResources' in rows ? rows.entryResources.figures : rows;
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+interface QuestFigureRowsInputFields {
+    id: string;
+    kit: string;
+    feet: {
+        poi: string;
+        x: number;
+        z: number;
+        y?: number;
+        dy?: number;
+        yaw?: number;
+        anchor?: string;
+    };
+    fire?: {
+        poi: string;
+        x: number;
+        z: number;
+        y?: number;
+        dy?: number;
+        yaw?: number;
+        anchor?: string;
+    };
+    parts: Record<string, string>;
+    campAt?: 'fire';
+    objects?: (({
+        kind: 'basic-mesh';
+        id: string;
+        name: string;
+        draw: string;
+        colour: [
+            number,
+            number,
+            number
+        ];
+        vertexColors: boolean;
+        at: 'feet' | 'fire';
+        lift: number;
+    }) | ({
+        kind: 'cloud';
+        id: string;
+        name: string;
+        draw: string;
+        look: string;
+        at: 'feet' | 'fire';
+        center: [
+            number,
+            number,
+            number
+        ];
+        radius: number;
+        order: number;
+        seeds: boolean;
+    }))[] | undefined;
+    publish?: ({
+        id: string;
+        draw: string;
+    })[] | undefined;
+    piece?: string;
+    card?: string;
+    name?: string;
+    counter?: {
+        model: string;
+        ahead: number;
+        piece: string;
+        name: string;
+        solidFloor: boolean;
+    };
+    system: {
+        id: string;
+        before: (string)[];
+    };
+}
+export type QuestFigureRowsInput = { [Key in keyof QuestFigureRowsInputFields]: QuestFigureRowsInputFields[Key] };
+interface QuestFigureRowsFields {
+    id: string;
+    kit: string;
+    feet: {
+        poi: string;
+        x: number;
+        z: number;
+        y?: number;
+        dy?: number;
+        yaw?: number;
+        anchor?: string;
+    };
+    fire?: {
+        poi: string;
+        x: number;
+        z: number;
+        y?: number;
+        dy?: number;
+        yaw?: number;
+        anchor?: string;
+    };
+    parts: Record<string, string>;
+    campAt?: 'fire';
+    objects: (({
+        kind: 'basic-mesh';
+        id: string;
+        name: string;
+        draw: string;
+        colour: [
+            number,
+            number,
+            number
+        ];
+        vertexColors: boolean;
+        at: 'feet' | 'fire';
+        lift: number;
+    }) | ({
+        kind: 'cloud';
+        id: string;
+        name: string;
+        draw: string;
+        look: string;
+        at: 'feet' | 'fire';
+        center: [
+            number,
+            number,
+            number
+        ];
+        radius: number;
+        order: number;
+        seeds: boolean;
+    }))[];
+    publish: ({
+        id: string;
+        draw: string;
+    })[];
+    piece?: string;
+    card?: string;
+    name?: string;
+    counter?: {
+        model: string;
+        ahead: number;
+        piece: string;
+        name: string;
+        solidFloor: boolean;
+    };
+    system: {
+        id: string;
+        before: (string)[];
+    };
+}
+export type QuestFigureRows = { [Key in keyof QuestFigureRowsFields]: QuestFigureRowsFields[Key] };
+export type QuestFiguresRowsInput = unknown;
+interface QuestFiguresRowsFields {
+    figures: (QuestFigureRows)[];
+    group?: v.InferOutput<typeof FigureGroupSchema>;
+}
+export type QuestFiguresRows = { [Key in keyof QuestFiguresRowsFields]: QuestFiguresRowsFields[Key] };
+export type KitFigureCardsRowsInput = unknown;
+interface KitFigureCardsRowsFields {
+    catalogue: string;
+    draws: 'models/island-library';
+    cards: Record<string, {
+        model: {
+            defaults: Record<never, never>;
+        } & Pick<v.InferOutput<typeof SpecimenModelMetadataSchema>, 'id' | 'name' | 'file' | 'category' | 'pipeline' | 'surface'>;
+        figure: QuestFigureRows;
+    }>;
+}
+export type KitFigureCardsRows = { [Key in keyof KitFigureCardsRowsFields]: KitFigureCardsRowsFields[Key] };