@wildshard/shard-format 0.0.0 → 0.4.5

package/src/format/sceneDressing.ts

@@ -0,0 +1,247 @@
+import { BinaryFileSchema } from './binarySource.ts';
+import { SceneInstancesSchema } from './sceneInstances.ts';
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+import { SpecimenCatalogueSchema, PackedSpecimenSchema, SpecimenMaterialSchema, SpecimenAssetSchema, SpecimenModelMetadataSchema, SpecimenTextureSchema } from './specimenCatalogue.ts';
+import { AmbientFlockSchema, AmbientPerchesSchema } from './ambientLife.ts';
+import { PrivateSceneSchema } from './clientChannels.ts';
+import { EncounterSitesSchema } from './encounterRows.ts';
+
+const id = v.pipe(v.string(), v.minLength(1), v.maxLength(512));
+const finite = v.pipe(v.number(), v.finite());
+const count = v.pipe(finite, v.integer(), v.minValue(0), v.maxValue(1000000));
+const list = <T extends v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>>(schema: T, max: number) => v.pipe(v.array(schema), v.maxLength(max));
+export const SceneBakedGeometrySchema: v.GenericSchema<SceneBakedGeometryRowsInput, SceneBakedGeometryRows> = v.strictObject({ attrs: list(v.tuple([id, v.picklist(['f32','f16','u16','i8','u8']), count, v.boolean()]),32),count,index:v.nullable(v.picklist(['u16','u32'])),indexCount:count,box:v.boolean(),expand:v.boolean() });
+const geometry = v.variant('kind',[
+  v.strictObject({kind:v.literal('asset'),row:SpecimenAssetSchema}),
+  v.strictObject({kind:v.literal('baked'),url:id,address:v.strictObject({file:id,word:count}),row:SceneBakedGeometrySchema}),
+  v.strictObject({kind:v.literal('baked-file'),...BinaryFileSchema.entries,address:v.strictObject({file:id,word:count}),row:SceneBakedGeometrySchema,sphere:v.exactOptional(v.tuple([finite,finite,finite,finite]))}),
+  v.strictObject({kind:v.literal('inline'),data:v.pipe(v.string(),v.maxLength(1048576)),row:SceneBakedGeometrySchema,sphere:v.exactOptional(v.tuple([finite,finite,finite,finite]))}),
+  v.strictObject({kind:v.literal('file'),...BinaryFileSchema.entries,row:SceneBakedGeometrySchema,sphere:v.exactOptional(v.tuple([finite,finite,finite,finite]))}),
+  v.strictObject({kind:v.literal('packed'),source:id,key:id}),
+]);
+export const SceneScatterPoseSchema: v.GenericSchema<SceneScatterPoseRowsInput, SceneScatterPoseRows> = v.strictObject({x:finite,y:finite,z:finite,yaw:finite,sx:finite,sy:finite,sz:finite,far:finite,r:finite,g:finite,b:finite,
+  tiltX:v.exactOptional(finite),tiltZ:v.exactOptional(finite),solid:v.exactOptional(v.union([v.literal(true),v.literal(1)]))});
+const finiteField = (row: object, key: string): number | undefined => {
+  if (!Object.hasOwn(row, key)) return undefined;
+  const value: unknown = Reflect.get(row, key);
+  if (typeof value !== 'number' || !Number.isFinite(value)) throw new Error(`Invalid scene scatter pose ${key}`);
+  return value;
+};
+/** One scatter pose by SceneScatterPoseSchema's rules in one pass: the same required finite fields, optional tilts and
+ *  solid flag, no other key, and the same output (G782: the schema's per-row strict object was ~130 ms of a phone-4x
+ *  Nalati dressing). */
+export function readSceneScatterPose(input: unknown): SceneScatterPoseRows {
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) throw new Error('Invalid scene scatter pose');
+  let known = 0;
+  const field = (key: string): number => { const value = finiteField(input, key); if (value === undefined) throw new Error(`Missing scene scatter pose ${key}`); known++; return value; };
+  const pose: SceneScatterPoseRows = { x: field('x'), y: field('y'), z: field('z'), yaw: field('yaw'), sx: field('sx'), sy: field('sy'), sz: field('sz'),
+    far: field('far'), r: field('r'), g: field('g'), b: field('b') };
+  const tiltX = finiteField(input, 'tiltX'), tiltZ = finiteField(input, 'tiltZ');
+  if (tiltX !== undefined) { pose.tiltX = tiltX; known++; }
+  if (tiltZ !== undefined) { pose.tiltZ = tiltZ; known++; }
+  if (Object.hasOwn(input, 'solid')) {
+    const solid: unknown = Reflect.get(input, 'solid');
+    if (solid !== true && solid !== 1) throw new Error('Invalid scene scatter pose solid');
+    pose.solid = solid; known++;
+  }
+  if (Object.keys(input).length !== known) throw new Error('Unknown scene scatter pose key');
+  return pose;
+}
+const surface=v.exactOptional(v.picklist(['sand','wetSand','grass','rock','planks','stone','water','wood','metal','flesh','shell','ground','edge','felt','earth']));
+const point=v.strictObject({x:finite,y:finite,z:finite});
+const base={x:finite,y:finite,z:finite,surface,yaw:v.exactOptional(finite),rot:v.exactOptional(v.strictObject({x:finite,y:finite,z:finite,w:finite}))};
+export const SceneDressingContactsSchema: v.GenericSchema<SceneDressingContactsRowsInput, SceneDressingContactsRows> =list(v.variant('kind',[
+  v.strictObject({kind:v.literal('hull'),...base,points:list(finite,24576)}),
+  v.strictObject({kind:v.literal('box'),...base,hx:finite,hy:finite,hz:finite}),
+  v.strictObject({kind:v.literal('capsule'),...base,halfHeight:finite,radius:finite}),
+  v.strictObject({kind:v.literal('treads'),from:point,to:point,width:finite,count:v.pipe(finite,v.integer(),v.minValue(1)),surface}),
+]),32768);
+export const SceneFloorSchema: v.GenericSchema<SceneFloorRowsInput, SceneFloorRows> =v.union([
+  v.strictObject({rects:list(v.strictObject({x:finite,z:finite,hw:finite,hd:finite,y:finite,rot:v.exactOptional(finite),slope:v.exactOptional(finite),tilt:v.exactOptional(finite),profile:v.exactOptional(list(v.tuple([finite,finite,finite]),8))}),4096)}),
+  v.strictObject({x:finite,z:finite,size:v.pipe(finite,v.minValue(0)),res:v.pipe(count,v.minValue(2)),data:v.pipe(v.string(),v.maxLength(1048576))}),
+  v.strictObject({x:finite,z:finite,size:v.pipe(finite,v.minValue(0)),res:v.pipe(count,v.minValue(2)),...BinaryFileSchema.entries}),
+]);
+const packedContacts={kind:v.literal('packed-hulls'),origins:list(v.tuple([finite,finite,finite,count]),8192),surface:v.picklist(['rock','wood','stone','ground'])};
+const contactSource = v.union([SceneDressingContactsSchema,
+  v.strictObject({...packedContacts,data:v.pipe(v.string(),v.maxLength(1048576))}),
+  v.strictObject({...packedContacts,file:id}),
+]);
+const pose = v.strictObject({x:finite,y:finite,z:finite,variant:v.exactOptional(id),yaw:v.exactOptional(finite),heading:v.exactOptional(v.tuple([finite,finite])),matrix:v.exactOptional(v.pipe(v.array(finite),v.length(16)))});
+/** Z2 client-only scatter/static/ambient projection; shader and model identities are declared data. */
+const sceneDressing = v.pipe(v.unknown(), v.check(isJsonData), v.strictObject({
+  name:id,
+  instances:v.optional(SceneInstancesSchema,[]),
+  staticModels:v.optional(list(v.strictObject({model:SpecimenModelMetadataSchema,geometry:id,material:id}),128),[]),
+  catalogues:list(v.union([v.strictObject({rows:SpecimenCatalogueSchema,load:v.exactOptional(v.literal('after-control')),packed:v.exactOptional(PackedSpecimenSchema),materials:v.optional(v.record(id,SpecimenMaterialSchema),{})}),v.strictObject({rows:SpecimenCatalogueSchema,load:v.exactOptional(v.literal('after-control')),pack:id})]),8),
+  packs:v.record(id,v.strictObject({rows:PackedSpecimenSchema,materials:v.record(id,SpecimenMaterialSchema)})),
+  geometry:v.record(id,geometry),
+  materials:v.record(id,v.variant('kind',[
+    v.strictObject({kind:v.literal('specimen'),row:SpecimenMaterialSchema}),
+    v.strictObject({kind:v.literal('asset'),row:SpecimenAssetSchema}),
+    v.strictObject({kind:v.literal('painterly'),rim:finite,bands:finite,sway:v.exactOptional(finite),shade:v.exactOptional(finite),emissive:v.exactOptional(finite)}),
+    v.strictObject({kind:v.literal('look'),look:id,params:v.exactOptional(v.record(id,v.union([finite,list(finite,16)]))),textures:v.exactOptional(v.record(id,SpecimenTextureSchema))}),
+    v.strictObject({kind:v.literal('mapped'),look:id,over:id}),
+    /** Painted lettering borrows raw RGBA8 from a file, or retains the legacy compressed inline atlas. */
+    v.strictObject({kind:v.literal('lettering'),width:count,height:count,data:v.pipe(v.string(),v.maxLength(1048576)),rim:finite}),
+    v.strictObject({kind:v.literal('lettering-file'),...BinaryFileSchema.entries,width:count,height:count,rim:finite}),
+  ])),
+  layers:list(v.strictObject({id,model:id,geometry:id,material:id,file:id,member:v.exactOptional(id),binary:v.boolean(),far:finite,castShadow:v.boolean(),keepNear:finite,
+    select:v.exactOptional(v.strictObject({modulo:v.pipe(count,v.minValue(1)),remainder:count,equal:v.boolean()})),contacts:contactSource}),32),
+  statics:list(v.strictObject({name:id,recipe:PrivateSceneSchema,geometry:v.record(id,id),materials:v.record(id,id),tris:finite,
+    /** the place's named gameplay points (an entrance, ledges, a tie spot), read by the encounters it hosts */
+    anchors:v.optional(v.record(id,list(v.strictObject({x:finite,y:finite,z:finite,r:v.optional(finite,0),facing:v.optional(finite,0)}),256)),{}),
+    members:list(v.strictObject({model:id,draw:v.picklist(['single','instanced','merged']),placements:list(pose,8192),boxes:list(finite,49152),contacts:contactSource,floors:v.optional(list(SceneFloorSchema,64),[])}),128)}),32),
+  wings:v.exactOptional(v.strictObject({groups:list(v.strictObject({kind:id,row:AmbientFlockSchema,perches:AmbientPerchesSchema}),32),
+    layers:list(v.strictObject({id,capacity:count,palette:list(v.union([finite,id]),256),flap:v.nullable(v.tuple([finite,finite,finite])),geometry:id,material:id}),32)})),
+  animations:list(v.strictObject({look:id,timeParam:id,windParam:id,windScale:finite,windMax:finite}),32),
+  motes:v.exactOptional(v.strictObject({name:id,count,seed:count,look:id,drift:finite,driftParam:id,pixelParam:id})),
+  /** encounter sites (game/boss/encounterView) drawing a declared model, solid while they stand */
+  sites:v.optional(list(v.strictObject({name:id,model:id,rows:EncounterSitesSchema}),8),[]),
+  /** instanced quads in a lent look, their per-instance attributes baked; the look hears the painted wind (clamped), shade and sun */
+  emitters:v.optional(list(v.strictObject({name:id,look:id,renderOrder:count,centre:v.tuple([finite,finite,finite]),radius:finite,
+    attributes:v.record(id,v.strictObject({width:v.pipe(count,v.minValue(1),v.maxValue(4)),values:list(finite,1048576)})),
+    params:v.strictObject({wind:id,windClamp:finite,shade:id,sun:id})}),8),[]),
+}),v.check(rows=>{
+  const models=new Set(rows.catalogues.flatMap(source=>source.rows.map(row=>row.model.id)).concat(rows.staticModels.map(row=>row.model.id)));
+  const shape=(key:string)=>Object.hasOwn(rows.geometry,key),paint=(key:string)=>Object.hasOwn(rows.materials,key);
+  return new Set(rows.statics.map(row=>row.name)).size===rows.statics.length
+    && rows.catalogues.every(source=>!('pack'in source)||Object.hasOwn(rows.packs,source.pack))
+    && rows.staticModels.every(row=>shape(row.geometry)&&paint(row.material))
+    && rows.instances.every(row=>shape(row.geometry)&&paint(row.material)&&rows.statics.some(group=>group.name===row.group))
+    && rows.sites.every(row=>models.has(row.model))
+    && rows.layers.every(row=>models.has(row.model)&&shape(row.geometry)&&paint(row.material)&&(row.select===undefined||row.select.remainder<row.select.modulo))
+    && rows.statics.every(row=>Object.values(row.geometry).every(shape)&&Object.values(row.materials).every(paint)&&row.members.every(member=>models.has(member.model)&&member.boxes.length===member.placements.length*6))
+    && Object.values(rows.materials).every(row=>row.kind!=='mapped'||paint(row.over)&&rows.materials[row.over]?.kind!=='mapped')
+    && Object.values(rows.geometry).every(row=>row.kind!=='packed'||Object.hasOwn(rows.packs,row.source))
+    && (rows.wings===undefined||rows.wings.layers.every(row=>shape(row.geometry)&&paint(row.material)));
+},'Dressing references require declared shapes, materials, models and complete copy bounds'));
+export interface SceneDressingRows { name: string; instances: v.InferOutput<typeof SceneInstancesSchema>;
+  staticModels: ({ model: v.InferOutput<typeof SpecimenModelMetadataSchema>; geometry: string; material: string;
+  })[]; catalogues: (({ rows: v.InferOutput<typeof SpecimenCatalogueSchema>; load?: 'after-control'; packed?: v.InferOutput<typeof
+  PackedSpecimenSchema>; materials: Record<string, v.InferOutput<typeof SpecimenMaterialSchema>>; }) | ({ rows:
+  v.InferOutput<typeof SpecimenCatalogueSchema>; load?: 'after-control'; pack: string; }))[]; packs: Record<string, { rows:
+  v.InferOutput<typeof PackedSpecimenSchema>; materials: Record<string, v.InferOutput<typeof
+  SpecimenMaterialSchema>>; }>; geometry: Record<string, ({ kind: 'asset'; row: v.InferOutput<typeof
+  SpecimenAssetSchema>; }) | ({ kind: 'baked'; url: string; address: { file: string; word: number; }; row:
+  SceneBakedGeometryRows; }) | ({ kind: 'baked-file'; address: { file: string; word: number; }; row:
+  SceneBakedGeometryRows; sphere?: [number, number, number, number]; } & v.InferOutput<typeof BinaryFileSchema>) | ({ kind: 'inline'; data: string; row:
+  SceneBakedGeometryRows; sphere?: [number, number, number, number]; }) | ({ kind: 'file'; row:
+  SceneBakedGeometryRows; sphere?: [number, number, number, number]; } & v.InferOutput<typeof BinaryFileSchema>)
+  | ({ kind: 'packed'; source: string; key: string; })>; materials: Record<string, ({ kind: 'specimen'; row:
+  v.InferOutput<typeof SpecimenMaterialSchema>; }) | ({ kind: 'asset'; row: v.InferOutput<typeof
+  SpecimenAssetSchema>; }) | ({ kind: 'painterly'; rim: number; bands: number; sway?: number; shade?: number;
+  emissive?: number; }) | ({ kind: 'look'; look: string; params?: Record<string, (number) | ((number)[])>;
+  textures?: Record<string, v.InferOutput<typeof SpecimenTextureSchema>>; }) | ({ kind: 'mapped'; look: string;
+  over: string; }) | ({ kind: 'lettering'; width: number; height: number; data: string; rim: number; }) | ({
+  kind: 'lettering-file'; width: number; height: number; rim: number; } & v.InferOutput<typeof
+  BinaryFileSchema>)>; layers: ({ id: string; model: string; geometry: string; material: string; file: string; member?: string;
+  binary: boolean; far: number; castShadow: boolean; keepNear: number; select?: { modulo: number; remainder:
+  number; equal: boolean; }; contacts: (SceneDressingContactsRows) | ({ data: string; } & { kind:
+  'packed-hulls'; origins: ([number, number, number, number])[]; surface: 'rock' | 'wood' | 'stone' | 'ground';
+  }) | ({ file: string; } & { kind: 'packed-hulls'; origins: ([number, number, number, number])[]; surface:
+  'rock' | 'wood' | 'stone' | 'ground'; }); })[]; statics: ({ name: string; recipe: v.InferOutput<typeof
+  PrivateSceneSchema>; geometry: Record<string, string>; materials: Record<string, string>; tris: number;
+  anchors: Record<string, ({ x: number; y: number; z: number; r: number; facing: number; })[]>; members: ({
+  model: string; draw: 'single' | 'instanced' | 'merged'; placements: ({ x: number; y: number; z: number;
+  variant?: string; yaw?: number; heading?: [number, number]; matrix?: (number)[]; })[]; boxes: (number)[];
+  contacts: (SceneDressingContactsRows) | ({ data: string; } & { kind: 'packed-hulls'; origins: ([number,
+  number, number, number])[]; surface: 'rock' | 'wood' | 'stone' | 'ground'; }) | ({ file: string; } & { kind:
+  'packed-hulls'; origins: ([number, number, number, number])[]; surface: 'rock' | 'wood' | 'stone' | 'ground';
+  }); floors: (SceneFloorRows)[]; })[]; })[]; wings?: { groups: ({ kind: string; row: v.InferOutput<typeof
+  AmbientFlockSchema>; perches: v.InferOutput<typeof AmbientPerchesSchema>; })[]; layers: ({ id: string;
+  capacity: number; palette: ((number) | (string))[]; flap: ([number, number, number]) | null; geometry: string;
+  material: string; })[]; }; animations: ({ look: string; timeParam: string; windParam: string; windScale:
+  number; windMax: number; })[]; motes?: { name: string; count: number; seed: number; look: string; drift:
+  number; driftParam: string; pixelParam: string; }; sites: ({ name: string; model: string; rows:
+  v.InferOutput<typeof EncounterSitesSchema>; })[]; emitters: ({ name: string; look: string; renderOrder:
+  number; centre: [number, number, number]; radius: number; attributes: Record<string, { width: number; values:
+  (number)[]; }>; params: { wind: string; windClamp: number; shade: string; sun: string; }; })[]; }
+export const SceneDressingSchema:v.GenericSchema<unknown,SceneDressingRows>=sceneDressing;
+
+/** Bounded validated dressing data, independent of schema implementation metadata. */
+export interface SceneBakedGeometryRowsInput { attrs: ([string, 'f32' | 'f16' | 'u16' | 'i8' | 'u8', number,
+  boolean])[]; count: number; index: ('u16' | 'u32') | null; indexCount: number; box: boolean; expand: boolean;
+  }
+export interface SceneBakedGeometryRows { attrs: ([string, 'f32' | 'f16' | 'u16' | 'i8' | 'u8', number,
+  boolean])[]; count: number; index: ('u16' | 'u32') | null; indexCount: number; box: boolean; expand: boolean;
+  }
+export interface SceneScatterPoseRowsInput { x: number; y: number; z: number; yaw: number; sx: number; sy: number;
+  sz: number; far: number; r: number; g: number; b: number; tiltX?: number; tiltZ?: number; solid?: (true) |
+  (1); }
+export interface SceneScatterPoseRows { x: number; y: number; z: number; yaw: number; sx: number; sy: number; sz:
+  number; far: number; r: number; g: number; b: number; tiltX?: number; tiltZ?: number; solid?: (true) | (1); }
+export type SceneDressingContactsRowsInput = (({ kind: 'hull'; points: (number)[]; } & { x: number; y: number;
+  z: number; surface?: 'sand' | 'wetSand' | 'grass' | 'rock' | 'planks' | 'stone' | 'water' | 'wood' | 'metal' |
+  'flesh' | 'shell' | 'ground' | 'edge' | 'felt' | 'earth'; yaw?: number; rot?: { x: number; y: number; z:
+  number; w: number; }; }) | ({ kind: 'box'; hx: number; hy: number; hz: number; } & { x: number; y: number; z:
+  number; surface?: 'sand' | 'wetSand' | 'grass' | 'rock' | 'planks' | 'stone' | 'water' | 'wood' | 'metal' |
+  'flesh' | 'shell' | 'ground' | 'edge' | 'felt' | 'earth'; yaw?: number; rot?: { x: number; y: number; z:
+  number; w: number; }; }) | ({ kind: 'capsule'; halfHeight: number; radius: number; } & { x: number; y: number;
+  z: number; surface?: 'sand' | 'wetSand' | 'grass' | 'rock' | 'planks' | 'stone' | 'water' | 'wood' | 'metal' |
+  'flesh' | 'shell' | 'ground' | 'edge' | 'felt' | 'earth'; yaw?: number; rot?: { x: number; y: number; z:
+  number; w: number; }; }) | ({ kind: 'treads'; from: { x: number; y: number; z: number; }; to: { x: number; y:
+  number; z: number; }; width: number; count: number; surface?: 'sand' | 'wetSand' | 'grass' | 'rock' | 'planks'
+  | 'stone' | 'water' | 'wood' | 'metal' | 'flesh' | 'shell' | 'ground' | 'edge' | 'felt' | 'earth'; }))[];
+export type SceneDressingContactsRows = (({ kind: 'hull'; points: (number)[]; } & { x: number; y: number; z:
+  number; surface?: 'sand' | 'wetSand' | 'grass' | 'rock' | 'planks' | 'stone' | 'water' | 'wood' | 'metal' |
+  'flesh' | 'shell' | 'ground' | 'edge' | 'felt' | 'earth'; yaw?: number; rot?: { x: number; y: number; z:
+  number; w: number; }; }) | ({ kind: 'box'; hx: number; hy: number; hz: number; } & { x: number; y: number; z:
+  number; surface?: 'sand' | 'wetSand' | 'grass' | 'rock' | 'planks' | 'stone' | 'water' | 'wood' | 'metal' |
+  'flesh' | 'shell' | 'ground' | 'edge' | 'felt' | 'earth'; yaw?: number; rot?: { x: number; y: number; z:
+  number; w: number; }; }) | ({ kind: 'capsule'; halfHeight: number; radius: number; } & { x: number; y: number;
+  z: number; surface?: 'sand' | 'wetSand' | 'grass' | 'rock' | 'planks' | 'stone' | 'water' | 'wood' | 'metal' |
+  'flesh' | 'shell' | 'ground' | 'edge' | 'felt' | 'earth'; yaw?: number; rot?: { x: number; y: number; z:
+  number; w: number; }; }) | ({ kind: 'treads'; from: { x: number; y: number; z: number; }; to: { x: number; y:
+  number; z: number; }; width: number; count: number; surface?: 'sand' | 'wetSand' | 'grass' | 'rock' | 'planks'
+  | 'stone' | 'water' | 'wood' | 'metal' | 'flesh' | 'shell' | 'ground' | 'edge' | 'felt' | 'earth'; }))[];
+export type SceneFloorRowsInput = ({ rects: ({ x: number; z: number; hw: number; hd: number; y: number; rot?:
+  number; slope?: number; tilt?: number; profile?: ([number, number, number])[]; })[]; }) | ({ x: number; z:
+  number; size: number; res: number; data: string; }) | ({ x: number; z: number; size: number; res: number; } &
+  v.InferInput<typeof BinaryFileSchema>);
+export type SceneFloorRows = ({ rects: ({ x: number; z: number; hw: number; hd: number; y: number; rot?: number;
+  slope?: number; tilt?: number; profile?: ([number, number, number])[]; })[]; }) | ({ x: number; z: number;
+  size: number; res: number; data: string; }) | ({ x: number; z: number; size: number; res: number; } &
+  v.InferOutput<typeof BinaryFileSchema>);
+
+const pageNumber = v.pipe(v.number(), v.finite());
+const pageId = v.pipe(v.string(), v.regex(/^[a-z][a-z0-9-]{0,63}$/u));
+const pageXz = { x: pageNumber, z: pageNumber };
+const pageRows = <T extends v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>>(schema: T) =>
+  v.pipe(v.array(schema), v.maxLength(100000));
+const pagePose = v.strictObject({ x: pageNumber, y: pageNumber, z: pageNumber, yaw: pageNumber, sx: pageNumber, sy: pageNumber, sz: pageNumber,
+  far: pageNumber, r: pageNumber, g: pageNumber, b: pageNumber,
+  tiltX: v.exactOptional(pageNumber), tiltZ: v.exactOptional(pageNumber), solid: v.exactOptional(v.literal(true)) });
+const pageSpot = v.strictObject({ ...pageXz, s: pageNumber });
+/** Complete native scatter-list members. Each kind keeps its original row
+ * grammar; pages alter transport only, never row order or numeric values. */
+const SceneScatterMemberSchema = v.variant('kind', [
+  v.strictObject({ kind: v.literal('poses'), id: pageId, rows: pageRows(pagePose) }),
+  v.strictObject({ kind: v.literal('logs'), id: pageId, rows: pageRows(v.strictObject({ ax: pageNumber, az: pageNumber, bx: pageNumber, bz: pageNumber, r: pageNumber, drift: v.boolean() })) }),
+  v.strictObject({ kind: v.literal('spots'), id: pageId, rows: pageRows(pageSpot) }),
+  v.strictObject({ kind: v.literal('paths'), id: pageId, rows: pageRows(pageRows(v.tuple([pageNumber, pageNumber]))) }),
+  v.strictObject({ kind: v.literal('gates'), id: pageId, rows: pageRows(v.strictObject({ ...pageXz, yaw: pageNumber })) }),
+  v.strictObject({ kind: v.literal('drifts'), id: pageId, rows: pageRows(v.strictObject({ ...pageXz, y: pageNumber, r: pageNumber })) }),
+  v.strictObject({ kind: v.literal('bounds'), id: pageId, rows: pageRows(v.strictObject({ ...pageXz, hw: pageNumber, hd: pageNumber, rot: pageNumber, yBottom: pageNumber, yTop: pageNumber,
+    ghost: v.exactOptional(v.literal(true)) })) }),
+  v.strictObject({ kind: v.literal('clutter'), id: pageId, rows: pageRows(v.strictObject({ ...pageXz, yaw: pageNumber, kind: pageNumber })) }),
+]);
+interface ScatterPosePageRow { x: number; z: number; y: number; yaw: number; sx: number; sy: number; sz: number;
+  tiltX?: number; tiltZ?: number; solid?: true; far: number; r: number; g: number; b: number }
+type ScatterPageMember =
+  | { id: string; kind: 'poses'; rows: ScatterPosePageRow[] }
+  | { id: string; kind: 'logs'; rows: { ax: number; az: number; bx: number; bz: number; r: number; drift: boolean }[] }
+  | { id: string; kind: 'spots'; rows: { x: number; z: number; s: number }[] }
+  | { id: string; kind: 'paths'; rows: [number, number][][] }
+  | { id: string; kind: 'gates'; rows: { x: number; z: number; yaw: number }[] }
+  | { id: string; kind: 'drifts'; rows: { x: number; z: number; y: number; r: number }[] }
+  | { id: string; kind: 'bounds'; rows: { x: number; z: number; hw: number; hd: number; rot: number; yBottom: number; yTop: number; ghost?: true }[] }
+  | { id: string; kind: 'clutter'; rows: { x: number; z: number; yaw: number; kind: number }[] };
+/** A transport owns at most four complete, typed, independently named lists. */
+export interface SceneScatterPage { version: 1; members: ScatterPageMember[] }
+
+/** At most four complete lists per page; duplicate identities never alias. */
+export const SceneScatterPageSchema: v.GenericSchema<SceneScatterPage, SceneScatterPage> = v.strictObject({ version: v.literal(1), members: v.pipe(v.array(SceneScatterMemberSchema),
+  v.minLength(1), v.maxLength(4), v.check(members => new Set(members.map(row => row.id)).size === members.length, 'Scatter page member identities must be unique')) });
+/** Decode the entire bounded page before any member can be published. */
+export function parseSceneScatterPage(input: unknown): SceneScatterPage { return v.parse(SceneScatterPageSchema, input); }

package/src/format/sceneInstances.ts

@@ -0,0 +1,192 @@
+import * as v from 'valibot';
+import { ClientChannelProgramSchema, ClientChannelPropertySchema } from './clientChannels.ts';
+
+const id=v.pipe(v.string(),v.minLength(1),v.maxLength(256));
+const finite=v.pipe(v.number(),v.finite());
+const slot=v.pipe(finite,v.integer(),v.minValue(0),v.maxValue(31));
+const list=<T extends v.BaseSchema<unknown,unknown,v.BaseIssue<unknown>>>(schema:T,max:number)=>v.pipe(v.array(schema),v.maxLength(max));
+const uint=v.pipe(finite,v.integer(),v.minValue(0),v.maxValue(0xffffffff));
+const input=v.variant('kind',[
+  v.strictObject({kind:v.literal('state'),slot}),v.strictObject({kind:v.literal('constant'),value:finite}),
+  v.strictObject({kind:v.literal('frame'),property:ClientChannelPropertySchema}),v.strictObject({kind:v.literal('random')}),v.strictObject({kind:v.literal('blocked')}),
+]);
+/** Z2 client-only instanced pose projection. No actor, player, physics or authoritative state is writable. */
+const sceneInstances: v.GenericSchema<SceneInstancesRowsInput, SceneInstancesRows>=list(v.strictObject({
+  id,name:v.exactOptional(id),group:id,geometry:id,material:id,step:v.pipe(finite,v.minValue(0)),initialCredit:finite,clock:v.picklist(['elapsed','world']),
+  random:v.exactOptional(v.strictObject({id,state:v.strictObject({version:v.literal(1),state:uint,initial:uint,scrambledFork:v.boolean()})})),
+  states:list(list(finite,32),8192),pose:v.strictObject({x:slot,z:slot,y:v.exactOptional(slot),yaw:v.exactOptional(slot),pitch:v.exactOptional(slot),roll:v.exactOptional(slot),scale:v.exactOptional(slot),colour:v.exactOptional(slot)}),
+  programs:list(v.strictObject({row:ClientChannelProgramSchema,inputs:list(input,128),outputs:list(v.strictObject({property:ClientChannelPropertySchema,slot}),32)}),8),
+  blocked:list(v.strictObject({x:finite,z:finite,r:v.pipe(finite,v.minValue(0))}),128),
+  ground:finite,near:v.pipe(finite,v.minValue(0)),far:v.nullable(v.pipe(finite,v.minValue(0))),
+  bounds:v.tuple([finite,finite,finite,v.pipe(finite,v.minValue(0))]),groundBounds:v.boolean(),castShadow:v.boolean(),receiveShadow:v.boolean(),
+  palette:list(v.tuple([finite,finite,finite]),256),attributes:list(v.strictObject({name:id,width:v.picklist([1,2,3,4]),values:list(finite,32768)}),32),
+  uniform:v.exactOptional(v.strictObject({look:id,param:id})),
+}),32);
+
+export const SceneInstancesSchema:v.GenericSchema<unknown,SceneInstancesRows>=sceneInstances;
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type SceneInstancesRowsInput = ({
+    id: string;
+    name?: string;
+    group: string;
+    geometry: string;
+    material: string;
+    step: number;
+    initialCredit: number;
+    clock: 'elapsed' | 'world';
+    random?: {
+        id: string;
+        state: {
+            version: 1;
+            state: number;
+            initial: number;
+            scrambledFork: boolean;
+        };
+    };
+    states: ((number)[])[];
+    pose: {
+        x: number;
+        z: number;
+        y?: number;
+        yaw?: number;
+        pitch?: number;
+        roll?: number;
+        scale?: number;
+        colour?: number;
+    };
+    programs: ({
+        row: v.InferInput<typeof ClientChannelProgramSchema>;
+        inputs: (({
+            kind: 'state';
+            slot: number;
+        }) | ({
+            kind: 'constant';
+            value: number;
+        }) | ({
+            kind: 'frame';
+            property: v.InferInput<typeof ClientChannelPropertySchema>;
+        }) | ({
+            kind: 'random';
+        }) | ({
+            kind: 'blocked';
+        }))[];
+        outputs: ({
+            property: v.InferInput<typeof ClientChannelPropertySchema>;
+            slot: number;
+        })[];
+    })[];
+    blocked: ({
+        x: number;
+        z: number;
+        r: number;
+    })[];
+    ground: number;
+    near: number;
+    far: (number) | null;
+    bounds: [
+        number,
+        number,
+        number,
+        number
+    ];
+    groundBounds: boolean;
+    castShadow: boolean;
+    receiveShadow: boolean;
+    palette: ([
+        number,
+        number,
+        number
+    ])[];
+    attributes: ({
+        name: string;
+        width: 1 | 2 | 3 | 4;
+        values: (number)[];
+    })[];
+    uniform?: {
+        look: string;
+        param: string;
+    };
+})[];
+export type SceneInstancesRows = ({
+    id: string;
+    name?: string;
+    group: string;
+    geometry: string;
+    material: string;
+    step: number;
+    initialCredit: number;
+    clock: 'elapsed' | 'world';
+    random?: {
+        id: string;
+        state: {
+            version: 1;
+            state: number;
+            initial: number;
+            scrambledFork: boolean;
+        };
+    };
+    states: ((number)[])[];
+    pose: {
+        x: number;
+        z: number;
+        y?: number;
+        yaw?: number;
+        pitch?: number;
+        roll?: number;
+        scale?: number;
+        colour?: number;
+    };
+    programs: ({
+        row: v.InferOutput<typeof ClientChannelProgramSchema>;
+        inputs: (({
+            kind: 'state';
+            slot: number;
+        }) | ({
+            kind: 'constant';
+            value: number;
+        }) | ({
+            kind: 'frame';
+            property: v.InferOutput<typeof ClientChannelPropertySchema>;
+        }) | ({
+            kind: 'random';
+        }) | ({
+            kind: 'blocked';
+        }))[];
+        outputs: ({
+            property: v.InferOutput<typeof ClientChannelPropertySchema>;
+            slot: number;
+        })[];
+    })[];
+    blocked: ({
+        x: number;
+        z: number;
+        r: number;
+    })[];
+    ground: number;
+    near: number;
+    far: (number) | null;
+    bounds: [
+        number,
+        number,
+        number,
+        number
+    ];
+    groundBounds: boolean;
+    castShadow: boolean;
+    receiveShadow: boolean;
+    palette: ([
+        number,
+        number,
+        number
+    ])[];
+    attributes: ({
+        name: string;
+        width: 1 | 2 | 3 | 4;
+        values: (number)[];
+    })[];
+    uniform?: {
+        look: string;
+        param: string;
+    };
+})[];

package/src/format/sceneMotion.ts

@@ -0,0 +1,122 @@
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+import { HandleIdSchema, ScenePointRefSchema } from './sceneRefs.ts';
+import { ClientChannelPropertySchema } from './clientChannels.ts';
+
+const id = v.pipe(v.string(), v.minLength(1), v.maxLength(128));
+const finite = v.pipe(v.number(), v.finite());
+const ids = v.pipe(v.array(id), v.maxLength(128));
+const owners = v.pipe(v.array(id), v.maxLength(32));
+const vector = v.strictObject({ x: finite, y: finite, z: finite });
+const unique = (rows: readonly { readonly id: string }[]) => new Set(rows.map(row => row.id)).size === rows.length;
+const transform = v.picklist(['x', 'y', 'z', 'yaw', 'pitch', 'roll']);
+const inputSchema = v.union([v.strictObject({ flag: id }), v.strictObject({ mode: id }),
+  v.strictObject({ part: HandleIdSchema, property: transform })]);
+/** Existing native mover configuration and the views bound to its published poses.
+ * Groups only partition declared channel programs; no new scheduler is authored. */
+export const SceneMotionSchema: v.GenericSchema<SceneMotionInput, SceneMotion> = v.pipe(v.unknown(), v.check(isJsonData, 'Scene motion requires plain JSON'), v.strictObject({
+  version: v.literal(1), owner: id,
+  installation: v.strictObject({ systemId: id, viewSystemId: v.exactOptional(id), frameSystemId: v.exactOptional(id), socketLiftPrompts: v.exactOptional(v.boolean()),
+    permissions: v.optional(v.pipe(v.array(v.strictObject({ mover: id,
+      flags: v.pipe(v.array(v.strictObject({ name: id, bit: v.pipe(finite, v.safeInteger(), v.minValue(0), v.maxValue(65536)) })), v.maxLength(16)) })), v.maxLength(32)), []) }),
+  groups: v.pipe(v.array(v.strictObject({ id, programs: ids,
+    targets: v.pipe(v.record(id, HandleIdSchema), v.check(rows => Object.keys(rows).length <= 128)),
+    nativeOwners: v.optional(owners, []), copiedOwners: v.optional(owners, []), bindings: v.optional(ids, []),
+    rest: v.optional(v.pipe(v.array(v.strictObject({ id, position: vector, euler: vector, enabled: v.boolean() })), v.maxLength(32)), []),
+    initial: v.optional(v.pipe(v.array(v.strictObject({ program: id, at: ScenePointRefSchema })), v.maxLength(32)), []),
+    prompts: v.optional(v.pipe(v.array(v.strictObject({ id, action: id })), v.maxLength(64)), []),
+    observations: v.optional(v.pipe(v.array(v.strictObject({ program: id, channel: ClientChannelPropertySchema, value: HandleIdSchema })), v.maxLength(64)), []),
+  })), v.minLength(1), v.maxLength(16)),
+  frames: v.optional(v.pipe(v.array(v.strictObject({ id, program: id, cube: v.exactOptional(v.picklist(['standalone', 'cell'])),
+    targets: v.pipe(v.record(id, HandleIdSchema), v.check(rows => Object.keys(rows).length <= 128)),
+    inputs: v.pipe(v.record(id, inputSchema), v.check(rows => Object.keys(rows).length <= 128)),
+    materials: v.optional(v.pipe(v.array(v.strictObject({ channel: ClientChannelPropertySchema,
+      material: HandleIdSchema, property: v.picklist(['opacity', 'emissiveIntensity']) })), v.maxLength(32)), []),
+  })), v.maxLength(128)), []),
+}), v.check(rows => unique(rows.groups) && rows.groups.some(row => row.id === rows.owner)
+  && new Set(rows.groups.flatMap(row => row.programs)).size === rows.groups.reduce((count, row) => count + row.programs.length, 0)
+  && rows.groups.every((row, index) => new Set([...row.nativeOwners, ...row.copiedOwners]).size === row.nativeOwners.length + row.copiedOwners.length
+    && new Set(row.programs).size === row.programs.length && new Set(row.bindings).size === row.bindings.length
+    && unique(row.prompts) && row.bindings.every(targetId => rows.groups.slice(0, index).some(group => group.id === targetId)))
+  && (rows.frames.length === 0 || rows.installation.frameSystemId !== undefined)
+  && unique(rows.frames) && new Set(rows.groups.flatMap(row => row.programs).concat(rows.frames.map(row => row.program))).size
+    === rows.groups.reduce((count, row) => count + row.programs.length, 0) + rows.frames.length,
+'Unique motion groups and channel programs; child groups precede their parent'));
+
+/** Admission creates no channel, physics body, prompt or system. */
+export function parseSceneMotion(input: unknown): SceneMotion { return v.parse(SceneMotionSchema, input); }
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type SceneMotionInput = unknown;
+interface SceneMotionFields {
+    version: 1;
+    owner: string;
+    installation: {
+        systemId: string;
+        viewSystemId?: string;
+        frameSystemId?: string;
+        socketLiftPrompts?: boolean;
+        permissions: ({
+            mover: string;
+            flags: ({
+                name: string;
+                bit: number;
+            })[];
+        })[];
+    };
+    groups: ({
+        id: string;
+        programs: (string)[];
+        targets: Record<string, v.InferOutput<typeof HandleIdSchema>>;
+        nativeOwners: (string)[];
+        copiedOwners: (string)[];
+        bindings: (string)[];
+        rest: ({
+            id: string;
+            position: {
+                x: number;
+                y: number;
+                z: number;
+            };
+            euler: {
+                x: number;
+                y: number;
+                z: number;
+            };
+            enabled: boolean;
+        })[];
+        initial: ({
+            program: string;
+            at: v.InferOutput<typeof ScenePointRefSchema>;
+        })[];
+        prompts: ({
+            id: string;
+            action: string;
+        })[];
+        observations: ({
+            program: string;
+            channel: v.InferOutput<typeof ClientChannelPropertySchema>;
+            value: v.InferOutput<typeof HandleIdSchema>;
+        })[];
+    })[];
+    frames: ({
+        id: string;
+        program: string;
+        cube?: 'standalone' | 'cell';
+        targets: Record<string, v.InferOutput<typeof HandleIdSchema>>;
+        inputs: Record<string, ({
+            flag: string;
+        }) | ({
+            mode: string;
+        }) | ({
+            part: v.InferOutput<typeof HandleIdSchema>;
+            property: 'x' | 'y' | 'z' | 'yaw' | 'pitch' | 'roll';
+        })>;
+        materials: ({
+            channel: v.InferOutput<typeof ClientChannelPropertySchema>;
+            material: v.InferOutput<typeof HandleIdSchema>;
+            property: 'opacity' | 'emissiveIntensity';
+        })[];
+    })[];
+}
+export type SceneMotion = { [Key in keyof SceneMotionFields]: SceneMotionFields[Key] };

package/src/format/sceneRefs.ts

@@ -0,0 +1,71 @@
+import * as v from 'valibot';
+import { isJsonData } from './json.ts';
+
+/** Exact Z2 publication names, never paths into a shard-owned object. */
+export const HandleIdSchema: v.GenericSchema<HandleIdInput, HandleId> = v.pipe(v.string(), v.minLength(1), v.maxLength(256), v.regex(/^[a-z0-9][a-zA-Z0-9.-]*$/));
+
+const id = v.pipe(v.string(), v.minLength(1), v.maxLength(256));
+const finite = v.pipe(v.number(), v.finite());
+/** A named scene origin, published point with world offset, or prompt identity. */
+export const ScenePointRefSchema: v.GenericSchema<ScenePointRefInput, ScenePointRef> = v.pipe(v.unknown(), v.check(isJsonData, 'Scene point reference requires plain JSON'), v.union([
+  v.strictObject({ part: HandleIdSchema }),
+  v.strictObject({ point: HandleIdSchema, offset: v.exactOptional(v.tuple([finite, finite, finite])) }),
+]));
+
+export const SceneRefSchema: v.GenericSchema<SceneRefInput, SceneRef> = v.union([ScenePointRefSchema, v.pipe(v.unknown(), v.check(isJsonData, 'Scene reference requires plain JSON'), v.strictObject({ prompt: id }))]);
+
+/** Read-only game state identities; no reflected property or function access. */
+export const ObservationRefSchema: v.GenericSchema<ObservationRefInput, ObservationRef> = v.pipe(v.unknown(), v.check(isJsonData, 'Observation reference requires plain JSON'), v.union([
+  v.strictObject({ flag: id }), v.strictObject({ mark: id }),
+  v.strictObject({ mover: id, state: v.picklist(['at-end', 'moving']) }),
+  v.strictObject({ quest: id, step: v.exactOptional(id), state: v.exactOptional(v.picklist(['active', 'complete'])) }),
+  v.strictObject({ saved: v.strictObject({ record: v.picklist(['bosses', 'elites']), id,
+    field: v.picklist(['defeated', 'rewardTaken', 'kills']) }) }),
+]));
+
+/** Check all publications before a consumer allocates prompts or effects. */
+export function admitSceneRefs(refs: readonly SceneRef[], published: ReadonlySet<HandleId>, prompts: ReadonlySet<string> = new Set()): void {
+  for (const input of refs) {
+    const ref = v.parse(SceneRefSchema, input);
+    const target = 'part' in ref ? ref.part : 'point' in ref ? ref.point : ref.prompt;
+    if (!('prompt' in ref ? prompts : published).has(target)) throw new Error(`Missing scene reference: ${target}`);
+  }
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type HandleIdInput = HandleId;
+export type HandleId = string;
+export type ScenePointRefInput = unknown;
+export type ScenePointRef = ({
+    part: HandleId;
+}) | ({
+    point: HandleId;
+    offset?: [
+        number,
+        number,
+        number
+    ];
+});
+export type SceneRefInput = unknown;
+export type SceneRef = (ScenePointRef) | ({
+    prompt: string;
+});
+export type ObservationRefInput = unknown;
+export type ObservationRef = ({
+    flag: string;
+}) | ({
+    mark: string;
+}) | ({
+    mover: string;
+    state: 'at-end' | 'moving';
+}) | ({
+    quest: string;
+    step?: string;
+    state?: 'active' | 'complete';
+}) | ({
+    saved: {
+        record: 'bosses' | 'elites';
+        id: string;
+        field: 'defeated' | 'rewardTaken' | 'kills';
+    };
+});