@wildshard/shard-format 0.0.1 → 0.4.6

package/src/format/bossSocketRig.ts

@@ -0,0 +1,92 @@
+import * as v from 'valibot';
+import { LimbCollisionBake } from './limbCollision.ts';
+import { isJsonData } from './json.ts';
+
+const n = v.pipe(v.number(), v.finite()), id = v.pipe(v.string(), v.minLength(1), v.maxLength(256));
+const xyz = v.tuple([n, n, n]);
+const part = v.strictObject({ id, geometry: id, material: id });
+/** Client-only attachments, weak-point query and affine opening channels. */
+export const BossSocketRigSchema: v.GenericSchema<BossSocketRigRowsInput, BossSocketRigRows> = v.pipe(v.unknown(), v.check(isJsonData, 'Socket rig requires JSON rows'), v.strictObject({
+  id, pool: v.strictObject({ url: id, parts: v.pipe(v.array(id), v.maxLength(8)) }), collision: v.strictObject({ joints: LimbCollisionBake.entries.joints, volumes: LimbCollisionBake.entries.volumes }),
+  materials: v.pipe(v.array(v.strictObject({ id, colour: xyz, emissive: xyz, gain: n, roughness: n, metalness: n, lit: v.boolean(), fog: v.boolean() })), v.maxLength(8)),
+  attachments: v.pipe(v.array(v.strictObject({ id, name: id, socket: id, at: xyz, meshes: v.pipe(v.array(part), v.maxLength(4)) })), v.maxLength(9)),
+  hazards: v.pipe(v.array(id), v.maxLength(8)), focus: id, radius: n,
+  glow: v.pipe(v.array(v.strictObject({ material: id, gain: n })), v.maxLength(8)),
+  opening: v.pipe(v.array(v.strictObject({ part: id, scale: xyz, breathe: xyz, frequency: n })), v.maxLength(8)),
+  emission: v.pipe(v.array(v.strictObject({ material: id, base: n, open: n })), v.maxLength(8)),
+}));
+
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type BossSocketRigRowsInput = unknown;
+interface BossSocketRigRowsFields {
+    id: string;
+    pool: {
+        url: string;
+        parts: (string)[];
+    };
+    collision: {
+        joints: v.InferOutput<(typeof LimbCollisionBake)['entries']['joints']>;
+        volumes: v.InferOutput<(typeof LimbCollisionBake)['entries']['volumes']>;
+    };
+    materials: ({
+        id: string;
+        colour: [
+            number,
+            number,
+            number
+        ];
+        emissive: [
+            number,
+            number,
+            number
+        ];
+        gain: number;
+        roughness: number;
+        metalness: number;
+        lit: boolean;
+        fog: boolean;
+    })[];
+    attachments: ({
+        id: string;
+        name: string;
+        socket: string;
+        at: [
+            number,
+            number,
+            number
+        ];
+        meshes: ({
+            id: string;
+            geometry: string;
+            material: string;
+        })[];
+    })[];
+    hazards: (string)[];
+    focus: string;
+    radius: number;
+    glow: ({
+        material: string;
+        gain: number;
+    })[];
+    opening: ({
+        part: string;
+        scale: [
+            number,
+            number,
+            number
+        ];
+        breathe: [
+            number,
+            number,
+            number
+        ];
+        frequency: number;
+    })[];
+    emission: ({
+        material: string;
+        base: number;
+        open: number;
+    })[];
+}
+export type BossSocketRigRows = { [Key in keyof BossSocketRigRowsFields]: BossSocketRigRowsFields[Key] };

package/src/format/bowVariantRows.ts

@@ -0,0 +1,68 @@
+import * as v from 'valibot';
+import {isJsonData} from './json.ts';
+import {ReturnProgramSchema} from './namedJsonContracts.ts';
+import {ProjectedTrailSchema} from './clientTrails.ts';
+
+const text=v.pipe(v.string(),v.minLength(1),v.maxLength(512)),finite=v.pipe(v.number(),v.finite()),positive=v.pipe(finite,v.minValue(0));
+const tag=v.custom<`${string}.${string}`>(input=>typeof input==='string'&&/^[^.]+\..+$/u.test(input));
+const tags=v.pipe(v.array(tag),v.maxLength(64));
+const weapon=v.custom<`weapon.${string}`>(input=>typeof input==='string'&&/^weapon\.[a-z0-9.-]+$/u.test(input));
+/** Original source rules are evaluated only by the variant baker. */
+export const BowSourceMultipliersSchema: v.GenericSchema<BowSourceMultipliersRowsInput, BowSourceMultipliersRows>=v.pipe(v.array(v.strictObject({id:text,when:v.strictObject({sourceTags:v.exactOptional(tags),targetTags:v.exactOptional(tags),weaponTags:v.exactOptional(tags),targetState:v.exactOptional(tags)}),mul:positive})),v.maxLength(128));
+const scales=v.strictTuple([positive,positive]);
+/** Build-only admission of the held variant; its native bow and actor owner stay charged. */
+export const BowVariantSchema: v.GenericSchema<BowVariantRowsInput, BowVariantRows> & { readonly pipe: readonly [unknown, unknown, { readonly entries: { readonly id: v.GenericSchema<BowVariantRows['id'], BowVariantRows['id']>; readonly sourceTag: v.GenericSchema<BowVariantRows['sourceTag'], BowVariantRows['sourceTag']> } }] }=v.pipe(v.unknown(),v.check(isJsonData),v.strictObject({
+  id:weapon,name:text,style:v.picklist(['recurve','golden','sky-wolf']),drawSpeed:v.pipe(positive,v.minValue(.001)),
+  program:ReturnProgramSchema,signal:text,threshold:positive,pierce:positive,crush:positive,crushKinds:v.pipe(v.array(text),v.maxLength(32)),
+  sourceTag:tag,damageScale:v.strictObject({base:scales,kinds:v.record(text,scales)}),
+  flight:v.strictObject({base:positive,draw:positive,offset:positive,step:v.pipe(positive,v.minValue(.001)),from:positive,gap:v.pipe(positive,v.minValue(.001))}),
+  trail:ProjectedTrailSchema,
+}));
+
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+export type BowSourceMultipliersRowsInput = BowSourceMultipliersRows;
+export type BowSourceMultipliersRows = ({
+    id: string;
+    when: {
+        sourceTags?: (`${string}.${string}`)[];
+        targetTags?: (`${string}.${string}`)[];
+        weaponTags?: (`${string}.${string}`)[];
+        targetState?: (`${string}.${string}`)[];
+    };
+    mul: number;
+})[];
+export type BowVariantRowsInput = unknown;
+interface BowVariantRowsFields {
+    id: `weapon.${string}`;
+    name: string;
+    style: 'recurve' | 'golden' | 'sky-wolf';
+    drawSpeed: number;
+    program: v.InferOutput<typeof ReturnProgramSchema>;
+    signal: string;
+    threshold: number;
+    pierce: number;
+    crush: number;
+    crushKinds: (string)[];
+    sourceTag: `${string}.${string}`;
+    damageScale: {
+        base: [
+            number,
+            number
+        ];
+        kinds: Record<string, [
+            number,
+            number
+        ]>;
+    };
+    flight: {
+        base: number;
+        draw: number;
+        offset: number;
+        step: number;
+        from: number;
+        gap: number;
+    };
+    trail: v.InferOutput<typeof ProjectedTrailSchema>;
+}
+export type BowVariantRows = { [Key in keyof BowVariantRowsFields]: BowVariantRowsFields[Key] };

package/src/format/brains.ts

@@ -0,0 +1,252 @@
+import * as v from 'valibot';
+
+const key = v.pipe(v.string(), v.regex(/^[a-z][a-z0-9.:-]*$/u), v.maxLength(128));
+const cue = v.pipe(v.string(), v.regex(/^[a-z][a-z0-9_.:-]*$/u), v.maxLength(128));
+const radius = v.pipe(v.number(), v.finite(), v.minValue(0), v.maxValue(600));
+const cadence = v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(60), v.check(n => 60 % n === 0, 'Brain divisor divides 60')), 6);
+const duration = v.pipe(v.number(), v.finite(), v.minValue(0), v.maxValue(600));
+/** Circling melee policy data; the host retains navigation, attack tokens, strike clocks and random streams. */
+export const SkirmisherSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{ readonly id: v.GenericSchema<ShardSkirmisherInput['id'], ShardSkirmisher['id']>; readonly kind: v.GenericSchema<ShardSkirmisherInput['kind'], ShardSkirmisher['kind']>; readonly thinkDivisor: v.OptionalSchema<v.GenericSchema<Exclude<ShardSkirmisherInput['thinkDivisor'], undefined>, Exclude<ShardSkirmisher['thinkDivisor'], undefined>>, 6>; readonly awareRadius: v.GenericSchema<ShardSkirmisherInput['awareRadius'], ShardSkirmisher['awareRadius']>; readonly shyRadius: v.GenericSchema<ShardSkirmisherInput['shyRadius'], ShardSkirmisher['shyRadius']>; readonly disengageRadius: v.GenericSchema<ShardSkirmisherInput['disengageRadius'], ShardSkirmisher['disengageRadius']>; readonly holdRadius: v.GenericSchema<ShardSkirmisherInput['holdRadius'], ShardSkirmisher['holdRadius']>; readonly attackRadius: v.GenericSchema<ShardSkirmisherInput['attackRadius'], ShardSkirmisher['attackRadius']>; readonly attackDuration: v.GenericSchema<ShardSkirmisherInput['attackDuration'], ShardSkirmisher['attackDuration']>; readonly attackCooldown: v.GenericSchema<ShardSkirmisherInput['attackCooldown'], ShardSkirmisher['attackCooldown']>; readonly alertCooldown: v.GenericSchema<ShardSkirmisherInput['alertCooldown'], ShardSkirmisher['alertCooldown']>; readonly fleeSpeed: v.GenericSchema<ShardSkirmisherInput['fleeSpeed'], ShardSkirmisher['fleeSpeed']>; readonly subordinateVariant: v.GenericSchema<ShardSkirmisherInput['subordinateVariant'], ShardSkirmisher['subordinateVariant']>; readonly leaderVariant: v.GenericSchema<ShardSkirmisherInput['leaderVariant'], ShardSkirmisher['leaderVariant']>; readonly noticeCue: v.GenericSchema<ShardSkirmisherInput['noticeCue'], ShardSkirmisher['noticeCue']>; }, undefined>, v.CheckAction<{ [K in keyof ShardSkirmisher]: ShardSkirmisher[K] }, 'Ordered skirmisher perception and strike radii'>]> = v.pipe(v.strictObject({
+  id: key, kind: v.literal('skirmisher'), thinkDivisor: cadence, awareRadius: radius, shyRadius: radius, disengageRadius: radius,
+  holdRadius: radius, attackRadius: radius, attackDuration: v.pipe(duration, v.minValue(Number.MIN_VALUE)),
+  attackCooldown: duration, alertCooldown: duration,
+  fleeSpeed: v.pipe(v.number(), v.finite(), v.minValue(0), v.maxValue(15)),
+  subordinateVariant: key, leaderVariant: key, noticeCue: cue,
+}), v.check((row) => row.shyRadius <= row.awareRadius && row.awareRadius <= row.disengageRadius
+  && row.attackRadius <= row.awareRadius, 'Ordered skirmisher perception and strike radii'));
+/** Admitted archetype parameters, identified independently from a particular creature spawn. */
+
+/** Reject unknown fields, nonfinite tuning and invalid radii before installing an actor policy. */
+export function parseSkirmisher(data: unknown): ShardSkirmisher { return v.parse(SkirmisherSchema, data); }
+
+/** Custom author policy over bounded host queries; actor identity and observation provenance are injected by the loader. */
+export const ScriptBrainSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{ readonly id: v.GenericSchema<ShardScriptBrainInput['id'], ShardScriptBrain['id']>; readonly kind: v.GenericSchema<ShardScriptBrainInput['kind'], ShardScriptBrain['kind']>; readonly module: v.GenericSchema<ShardScriptBrainInput['module'], ShardScriptBrain['module']>; readonly thinkDivisor: v.GenericSchema<ShardScriptBrainInput['thinkDivisor'], ShardScriptBrain['thinkDivisor']>; readonly maxSpeed: v.GenericSchema<ShardScriptBrainInput['maxSpeed'], ShardScriptBrain['maxSpeed']>; readonly maxStrafe: v.GenericSchema<ShardScriptBrainInput['maxStrafe'], ShardScriptBrain['maxStrafe']>; readonly maxTurnRate: v.GenericSchema<ShardScriptBrainInput['maxTurnRate'], ShardScriptBrain['maxTurnRate']>; readonly parameters: v.GenericSchema<ShardScriptBrainInput['parameters'], ShardScriptBrain['parameters']>; readonly strikes: v.GenericSchema<ShardScriptBrainInput['strikes'], ShardScriptBrain['strikes']>; }, undefined>, v.CheckAction<{ [K in keyof ShardScriptBrain]: ShardScriptBrain[K] }, 'Unique declared brain strike events'>]> = v.pipe(v.strictObject({
+  id: key, kind: v.literal('script'), module: v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/u)),
+  thinkDivisor: v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(60), v.check(n => 60 % n === 0, 'Brain divisor divides 60')),
+  maxSpeed: v.pipe(v.number(), v.finite(), v.minValue(0), v.maxValue(15)),
+  maxStrafe: v.pipe(v.number(), v.finite(), v.minValue(0), v.maxValue(15)),
+  maxTurnRate: v.pipe(v.number(), v.finite(), v.minValue(0), v.maxValue(30)),
+  parameters: v.pipe(v.array(v.pipe(v.number(), v.finite(), v.minValue(-10000), v.maxValue(10000))), v.maxLength(64)),
+  strikes: v.pipe(v.array(v.strictObject({ event: v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(0x7fffffff)), strike: key })), v.maxLength(32)),
+}), v.check(row => new Set(row.strikes.map(strike => strike.event)).size === row.strikes.length, 'Unique declared brain strike events'));
+/** Validated script policy; only named admitted strikes may be requested and motion stays within its declared bounds. */
+
+/** Validate a custom policy before module admission, trusted actor binding or physics allocation. */
+export function parseScriptBrain(data: unknown): ShardScriptBrain { return v.parse(ScriptBrainSchema, data); }
+
+/** Interior guardian policy; native floor and rise/sink recipes publish completion through trusted ports. */
+export const GuardianSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{ readonly id: v.GenericSchema<ShardGuardianInput['id'], ShardGuardian['id']>; readonly kind: v.GenericSchema<ShardGuardianInput['kind'], ShardGuardian['kind']>; readonly thinkDivisor: v.OptionalSchema<v.GenericSchema<Exclude<ShardGuardianInput['thinkDivisor'], undefined>, Exclude<ShardGuardian['thinkDivisor'], undefined>>, 6>; readonly wakeRadius: v.GenericSchema<ShardGuardianInput['wakeRadius'], ShardGuardian['wakeRadius']>; readonly guardRadius: v.GenericSchema<ShardGuardianInput['guardRadius'], ShardGuardian['guardRadius']>; readonly approachRadius: v.GenericSchema<ShardGuardianInput['approachRadius'], ShardGuardian['approachRadius']>; readonly swingRadius: v.GenericSchema<ShardGuardianInput['swingRadius'], ShardGuardian['swingRadius']>; readonly swingDuration: v.GenericSchema<ShardGuardianInput['swingDuration'], ShardGuardian['swingDuration']>; readonly speed: v.GenericSchema<ShardGuardianInput['speed'], ShardGuardian['speed']>; readonly holdRadius: v.GenericSchema<ShardGuardianInput['holdRadius'], ShardGuardian['holdRadius']>; readonly sideSpeed: v.GenericSchema<ShardGuardianInput['sideSpeed'], ShardGuardian['sideSpeed']>; readonly sideFlipSeconds: v.GenericSchema<ShardGuardianInput['sideFlipSeconds'], ShardGuardian['sideFlipSeconds']>; readonly sinkAfterSeconds: v.GenericSchema<ShardGuardianInput['sinkAfterSeconds'], ShardGuardian['sinkAfterSeconds']>; readonly cooldownSeconds: v.GenericSchema<ShardGuardianInput['cooldownSeconds'], ShardGuardian['cooldownSeconds']>; readonly hideOffset: v.GenericSchema<ShardGuardianInput['hideOffset'], ShardGuardian['hideOffset']>; readonly noticeCue: v.GenericSchema<ShardGuardianInput['noticeCue'], ShardGuardian['noticeCue']>; }, undefined>, v.CheckAction<{ [K in keyof ShardGuardian]: ShardGuardian[K] }, 'Ordered guardian radii'>]> = v.pipe(v.strictObject({
+  id: key, kind: v.literal('guardian'), thinkDivisor: cadence, wakeRadius: radius, guardRadius: radius, approachRadius: radius,
+  swingRadius: radius, swingDuration: v.pipe(duration, v.minValue(Number.MIN_VALUE)),
+  speed: v.pipe(v.number(), v.finite(), v.minValue(0), v.maxValue(15)), holdRadius: radius,
+  sideSpeed: v.pipe(v.number(), v.finite(), v.minValue(0), v.maxValue(15)),
+  sideFlipSeconds: duration, sinkAfterSeconds: duration, cooldownSeconds: duration,
+  hideOffset: v.pipe(v.number(), v.finite(), v.minValue(-15), v.maxValue(15)), noticeCue: cue,
+}), v.check(row => row.wakeRadius <= row.guardRadius && row.swingRadius <= row.approachRadius, 'Ordered guardian radii'));
+/** Admitted interior guardian tuning, independent from a native rig or floor recipe. */
+
+/** Validate guardian decisions before selecting the existing native motion and strike recipes. */
+export function parseGuardian(data: unknown): ShardGuardian { return v.parse(GuardianSchema, data); }
+
+/** Perch hunting decisions; native perch selection, vertical completion and shared attack RNG remain trusted host ports. */
+export const PerchHunterSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{ readonly id: v.GenericSchema<ShardPerchHunterInput['id'], ShardPerchHunter['id']>; readonly kind: v.GenericSchema<ShardPerchHunterInput['kind'], ShardPerchHunter['kind']>; readonly thinkDivisor: v.OptionalSchema<v.GenericSchema<Exclude<ShardPerchHunterInput['thinkDivisor'], undefined>, Exclude<ShardPerchHunter['thinkDivisor'], undefined>>, 6>; readonly throwRadius: v.GenericSchema<ShardPerchHunterInput['throwRadius'], ShardPerchHunter['throwRadius']>; readonly throwDuration: v.GenericSchema<ShardPerchHunterInput['throwDuration'], ShardPerchHunter['throwDuration']>; readonly biteRadius: v.GenericSchema<ShardPerchHunterInput['biteRadius'], ShardPerchHunter['biteRadius']>; readonly biteDuration: v.GenericSchema<ShardPerchHunterInput['biteDuration'], ShardPerchHunter['biteDuration']>; readonly underRadius: v.GenericSchema<ShardPerchHunterInput['underRadius'], ShardPerchHunter['underRadius']>; readonly underSeconds: v.GenericSchema<ShardPerchHunterInput['underSeconds'], ShardPerchHunter['underSeconds']>; readonly holdRadius: v.GenericSchema<ShardPerchHunterInput['holdRadius'], ShardPerchHunter['holdRadius']>; readonly runSpeed: v.GenericSchema<ShardPerchHunterInput['runSpeed'], ShardPerchHunter['runSpeed']>; readonly activeGroundSeconds: v.GenericSchema<ShardPerchHunterInput['activeGroundSeconds'], ShardPerchHunter['activeGroundSeconds']>; readonly biteCooldown: v.GenericSchema<ShardPerchHunterInput['biteCooldown'], ShardPerchHunter['biteCooldown']>; readonly throwCooldownMin: v.GenericSchema<ShardPerchHunterInput['throwCooldownMin'], ShardPerchHunter['throwCooldownMin']>; readonly throwCooldownMax: v.GenericSchema<ShardPerchHunterInput['throwCooldownMax'], ShardPerchHunter['throwCooldownMax']>; readonly alertCue: v.GenericSchema<ShardPerchHunterInput['alertCue'], ShardPerchHunter['alertCue']>; readonly noticeCue: v.GenericSchema<ShardPerchHunterInput['noticeCue'], ShardPerchHunter['noticeCue']>; }, undefined>, v.CheckAction<{ [K in keyof ShardPerchHunter]: ShardPerchHunter[K] }, 'Ordered perch attack ranges and cooldowns'>]> = v.pipe(v.strictObject({
+  id: key, kind: v.literal('perch-hunter'), thinkDivisor: cadence, throwRadius: radius, throwDuration: v.pipe(duration, v.minValue(Number.MIN_VALUE)),
+  biteRadius: radius, biteDuration: v.pipe(duration, v.minValue(Number.MIN_VALUE)), underRadius: radius, underSeconds: duration,
+  holdRadius: radius, runSpeed: v.pipe(v.number(), v.finite(), v.minValue(0), v.maxValue(15)), activeGroundSeconds: duration,
+  biteCooldown: duration, throwCooldownMin: duration, throwCooldownMax: duration, alertCue: cue, noticeCue: cue,
+}), v.check(row => row.biteRadius <= row.throwRadius && row.throwCooldownMin <= row.throwCooldownMax, 'Ordered perch attack ranges and cooldowns'));
+/** Admitted ranged-perch and ground-attack policy parameters. */
+
+/** Validate policy data while retaining the loader's authority over perches, projectiles and tokens. */
+export function parsePerchHunter(data: unknown): ShardPerchHunter { return v.parse(PerchHunterSchema, data); }
+
+/** One home/perch guardian archetype; each branch keeps the exact legacy bounds, defaults and predicate. */
+export const GuardianPatternsSchema: v.VariantSchema<'pattern', readonly [
+ v.StrictObjectSchema<(typeof GuardianSchema)['pipe'][0]['entries'] & { readonly pattern: v.LiteralSchema<'interior', undefined> }, undefined>,
+ v.StrictObjectSchema<Omit<(typeof PerchHunterSchema)['pipe'][0]['entries'], 'kind'> & { readonly kind: v.LiteralSchema<'guardian', undefined>; readonly pattern: v.LiteralSchema<'perch', undefined> }, undefined>
+], undefined> = v.variant('pattern', [
+  v.pipe(v.strictObject({ ...GuardianSchema.pipe[0].entries, pattern: v.literal('interior') }),
+    v.check(row => GuardianSchema.pipe[1].requirement(row), 'Ordered guardian radii')),
+  v.pipe(v.strictObject({ ...PerchHunterSchema.pipe[0].entries, kind: v.literal('guardian'), pattern: v.literal('perch') }),
+    v.check(row => PerchHunterSchema.pipe[1].requirement({ ...row, kind: 'perch-hunter' }), 'Ordered perch attack ranges and cooldowns')),
+]);
+/** Admitted guardian pattern data; native floor/perch/body/RNG ports retain gameplay authority. */
+
+/** Validate a pattern without allocating an actor or executing its native recipes. */
+export function parseGuardianPattern(data: unknown): ShardGuardianPattern { return v.parse(GuardianPatternsSchema, data); }
+/** Canonical old row, including parsed field order, for existing native adapters and saved policy strings. */
+export function guardianPreset(data: ShardGuardianPattern): ShardGuardian | ShardPerchHunter {
+  const { pattern: _pattern, ...row } = data;
+  return data.pattern === 'interior' ? parseGuardian(row) : parsePerchHunter({ ...row, kind: 'perch-hunter' });
+}
+
+/** Circling melee pattern of the stalker archetype, retaining exact legacy bounds and cadence. */
+export const StalkerSchema: v.SchemaWithPipe<readonly [v.StrictObjectSchema<{ readonly id: v.GenericSchema<ShardStalkerInput['id'], ShardStalker['id']>; readonly kind: v.GenericSchema<ShardStalkerInput['kind'], ShardStalker['kind']>; readonly thinkDivisor: v.OptionalSchema<v.GenericSchema<Exclude<ShardStalkerInput['thinkDivisor'], undefined>, Exclude<ShardStalker['thinkDivisor'], undefined>>, 6>; readonly awareRadius: v.GenericSchema<ShardStalkerInput['awareRadius'], ShardStalker['awareRadius']>; readonly shyRadius: v.GenericSchema<ShardStalkerInput['shyRadius'], ShardStalker['shyRadius']>; readonly disengageRadius: v.GenericSchema<ShardStalkerInput['disengageRadius'], ShardStalker['disengageRadius']>; readonly holdRadius: v.GenericSchema<ShardStalkerInput['holdRadius'], ShardStalker['holdRadius']>; readonly attackRadius: v.GenericSchema<ShardStalkerInput['attackRadius'], ShardStalker['attackRadius']>; readonly attackDuration: v.GenericSchema<ShardStalkerInput['attackDuration'], ShardStalker['attackDuration']>; readonly attackCooldown: v.GenericSchema<ShardStalkerInput['attackCooldown'], ShardStalker['attackCooldown']>; readonly alertCooldown: v.GenericSchema<ShardStalkerInput['alertCooldown'], ShardStalker['alertCooldown']>; readonly fleeSpeed: v.GenericSchema<ShardStalkerInput['fleeSpeed'], ShardStalker['fleeSpeed']>; readonly subordinateVariant: v.GenericSchema<ShardStalkerInput['subordinateVariant'], ShardStalker['subordinateVariant']>; readonly leaderVariant: v.GenericSchema<ShardStalkerInput['leaderVariant'], ShardStalker['leaderVariant']>; readonly noticeCue: v.GenericSchema<ShardStalkerInput['noticeCue'], ShardStalker['noticeCue']>; readonly pattern: v.GenericSchema<ShardStalkerInput['pattern'], ShardStalker['pattern']>; }, undefined>, v.CheckAction<{ [K in keyof ShardStalker]: ShardStalker[K] }, 'Ordered skirmisher perception and strike radii'>]> = v.pipe(v.strictObject({ ...SkirmisherSchema.pipe[0].entries,
+  kind: v.literal('stalker'), pattern: v.literal('skirmish') }),
+  v.check(row => SkirmisherSchema.pipe[1].requirement({ ...row, kind: 'skirmisher' }), 'Ordered skirmisher perception and strike radii'));
+/** Admitted stalker pattern data; native body, attack tokens and RNG remain host-owned. */
+
+/** Admit a stalker row before any actor, native recipe or callback is allocated. */
+export function parseStalker(data: unknown): ShardStalker { return v.parse(StalkerSchema, data); }
+/** Canonical legacy row, including parsed key order, for native adapters and existing saved policy strings. */
+export function stalkerPreset(data: ShardStalker): ShardSkirmisher {
+  const { pattern: _pattern, ...row } = data;
+  return parseSkirmisher({ ...row, kind: 'skirmisher' });
+}
+
+/** Admitted data contracts, independent of validator implementation metadata. */
+interface ShardSkirmisherInputFields {
+    id: string;
+    kind: 'skirmisher';
+    thinkDivisor?: number | undefined;
+    awareRadius: number;
+    shyRadius: number;
+    disengageRadius: number;
+    holdRadius: number;
+    attackRadius: number;
+    attackDuration: number;
+    attackCooldown: number;
+    alertCooldown: number;
+    fleeSpeed: number;
+    subordinateVariant: string;
+    leaderVariant: string;
+    noticeCue: string;
+}
+export type ShardSkirmisherInput = { [Key in keyof ShardSkirmisherInputFields]: ShardSkirmisherInputFields[Key] };
+interface ShardSkirmisherFields {
+    id: string;
+    kind: 'skirmisher';
+    thinkDivisor: number;
+    awareRadius: number;
+    shyRadius: number;
+    disengageRadius: number;
+    holdRadius: number;
+    attackRadius: number;
+    attackDuration: number;
+    attackCooldown: number;
+    alertCooldown: number;
+    fleeSpeed: number;
+    subordinateVariant: string;
+    leaderVariant: string;
+    noticeCue: string;
+}
+export type ShardSkirmisher = { [Key in keyof ShardSkirmisherFields]: ShardSkirmisherFields[Key] };
+export type ShardScriptBrainInput = ShardScriptBrain;
+interface ShardScriptBrainFields {
+    id: string;
+    kind: 'script';
+    module: string;
+    thinkDivisor: number;
+    maxSpeed: number;
+    maxStrafe: number;
+    maxTurnRate: number;
+    parameters: (number)[];
+    strikes: ({
+        event: number;
+        strike: string;
+    })[];
+}
+export type ShardScriptBrain = { [Key in keyof ShardScriptBrainFields]: ShardScriptBrainFields[Key] };
+interface ShardGuardianInputFields {
+    id: string;
+    kind: 'guardian';
+    thinkDivisor?: number | undefined;
+    wakeRadius: number;
+    guardRadius: number;
+    approachRadius: number;
+    swingRadius: number;
+    swingDuration: number;
+    speed: number;
+    holdRadius: number;
+    sideSpeed: number;
+    sideFlipSeconds: number;
+    sinkAfterSeconds: number;
+    cooldownSeconds: number;
+    hideOffset: number;
+    noticeCue: string;
+}
+export type ShardGuardianInput = { [Key in keyof ShardGuardianInputFields]: ShardGuardianInputFields[Key] };
+interface ShardGuardianFields {
+    id: string;
+    kind: 'guardian';
+    thinkDivisor: number;
+    wakeRadius: number;
+    guardRadius: number;
+    approachRadius: number;
+    swingRadius: number;
+    swingDuration: number;
+    speed: number;
+    holdRadius: number;
+    sideSpeed: number;
+    sideFlipSeconds: number;
+    sinkAfterSeconds: number;
+    cooldownSeconds: number;
+    hideOffset: number;
+    noticeCue: string;
+}
+export type ShardGuardian = { [Key in keyof ShardGuardianFields]: ShardGuardianFields[Key] };
+interface ShardPerchHunterInputFields {
+    id: string;
+    kind: 'perch-hunter';
+    thinkDivisor?: number | undefined;
+    throwRadius: number;
+    throwDuration: number;
+    biteRadius: number;
+    biteDuration: number;
+    underRadius: number;
+    underSeconds: number;
+    holdRadius: number;
+    runSpeed: number;
+    activeGroundSeconds: number;
+    biteCooldown: number;
+    throwCooldownMin: number;
+    throwCooldownMax: number;
+    alertCue: string;
+    noticeCue: string;
+}
+export type ShardPerchHunterInput = { [Key in keyof ShardPerchHunterInputFields]: ShardPerchHunterInputFields[Key] };
+interface ShardPerchHunterFields {
+    id: string;
+    kind: 'perch-hunter';
+    thinkDivisor: number;
+    throwRadius: number;
+    throwDuration: number;
+    biteRadius: number;
+    biteDuration: number;
+    underRadius: number;
+    underSeconds: number;
+    holdRadius: number;
+    runSpeed: number;
+    activeGroundSeconds: number;
+    biteCooldown: number;
+    throwCooldownMin: number;
+    throwCooldownMax: number;
+    alertCue: string;
+    noticeCue: string;
+}
+export type ShardPerchHunter = { [Key in keyof ShardPerchHunterFields]: ShardPerchHunterFields[Key] };
+export type ShardGuardianPattern = (Omit<v.InferOutput<(typeof GuardianSchema)['pipe'][0]>, keyof ({
+    pattern: 'interior';
+})> & {
+    pattern: 'interior';
+}) | (Omit<v.InferOutput<(typeof PerchHunterSchema)['pipe'][0]>, keyof ({
+    kind: 'guardian';
+    pattern: 'perch';
+})> & {
+    kind: 'guardian';
+    pattern: 'perch';
+});
+export type ShardStalkerInput = Omit<v.InferInput<(typeof SkirmisherSchema)['pipe'][0]>, keyof ({
+    kind: 'stalker';
+    pattern: 'skirmish';
+})> & {
+    kind: 'stalker';
+    pattern: 'skirmish';
+};
+export type ShardStalker = Omit<v.InferOutput<(typeof SkirmisherSchema)['pipe'][0]>, keyof ({
+    kind: 'stalker';
+    pattern: 'skirmish';
+})> & {
+    kind: 'stalker';
+    pattern: 'skirmish';
+};

package/src/format/budget.ts

@@ -0,0 +1,214 @@
+import { CONTENT_CAPS as C } from './contentBounds.ts';
+import { contentCost } from './contentCost.ts';
+import type { Shardfile } from './shardSchema.ts';
+import { NEAR_PLACEHOLDER_LIMITS, nearPlaceholderCost } from './nearPlaceholder.ts';
+
+/** Category resident targets are tradeable warnings; only the complete playing/loading totals refuse memory. */
+export function memoryTargetWarnings(shard: Shardfile): { category: string; bytes: number; target: number }[] {
+  const warnings: { category: string; bytes: number; target: number }[] = [];
+  const check = (category: string, bytes: number, target: number): void => {
+    if (bytes > target) warnings.push({ category, bytes, target });
+  };
+  check('library', shard.budgets.library.resident, C.library.resident);
+  check('simulation', shard.budgets.sim.resident, C.sim.resident);
+  check('overlap', shard.budgets.overlap, C.overlap);
+  check('server simulation', shard.serverBudget.memory, C.sim.resident);
+  for (const tile of shard.tiles) check(`tile ${tile.lod}/${tile.x}/${tile.z}`, tile.decoded + tile.gpu, (tile.lod === 0 ? C.l0 : C.l1).resident);
+  if (shard.far !== null) check('far', shard.far.decoded + shard.far.gpu, C.far.resident);
+  return warnings;
+}
+
+/**
+ * Each L0 tile's resident bytes beyond what the shard's library already charges: a tile whose files the library holds
+ * (Nine Dragon draws its whole L0 city from its library) is charged once there, never again as a resident tile. A
+ * tile's declared bytes less its library files' bytes, never below zero; other tiles are unchanged.
+ */
+function ownTileBytes(shard: Shardfile): (tile: Shardfile['tiles'][number]) => number {
+  const files = new Map(shard.files.map(file => [file.hash, file]));
+  const closure = (roots: readonly string[]): Set<string> => {
+    const seen = new Set<string>(), pending = [...roots];
+    for (let ref = pending.pop(); ref !== undefined; ref = pending.pop()) if (!seen.has(ref)) { seen.add(ref); pending.push(...files.get(ref)?.dependencies ?? []); }
+    return seen;
+  };
+  const library = closure(shard.library);
+  return tile => {
+    let shared = 0;
+    if (library.size > 0) for (const ref of closure(tile.files)) {
+      const file = library.has(ref) ? files.get(ref) : undefined;
+      if (file !== undefined) shared += file.decoded + file.gpu;
+    }
+    return Math.max(0, tile.decoded + tile.gpu - shared);
+  };
+}
+
+const distance2 = (x: number, z: number, x0: number, z0: number, x1: number, z1: number): number => {
+  const dx = Math.max(x0 - x, x - x1, 0), dz = Math.max(z0 - z, z - z1, 0); return dx * dx + dz * dz;
+};
+type LocationCost = ReturnType<typeof contentCost> & { location: [number, number] };
+const GRID_STEP = 5;
+const RADIUS2 = (C.nearRadius + Math.SQRT2 * GRID_STEP / 2) ** 2;
+
+/** One synthetic-neighbour model of the location cost: `accounted` alone (no allocation, the worst-disc scan's hot loop)
+ *  and the whole `cost`. `playing` never falls as `accounted` rises, so a location whose accounted bytes do not exceed
+ *  the worst found so far cannot beat it. */
+interface LocationModel {
+  /** the three synthetic neighbour cells' centres this model charges */
+  neighbours: readonly (readonly [number, number])[];
+  /** accounted bytes that do not depend on the location (everything but L0 and libraries) */
+  fixed: number;
+  cost: (x: number, z: number) => LocationCost;
+}
+
+function locationModels(shard: Shardfile, commons: number): LocationModel[] {
+  const bytesOf = ownTileBytes(shard), own = shard.tiles.filter(tile => tile.lod === 0).map(tile => {
+    const bounds = tile.drawBounds ?? tile.bounds;
+    return { x0: bounds.min[0], z0: bounds.min[2], x1: bounds.max[0], z1: bounds.max[2], bytes: bytesOf(tile) };
+  });
+  const coarseExcess = shard.tiles.filter(tile => tile.lod === 1).reduce((sum, tile) => sum + Math.max(0, tile.decoded + tile.gpu - C.l1.resident), 0);
+  const models: LocationModel[] = [];
+  const nearBytes = shard.near === undefined ? 0 : nearPlaceholderCost(shard.near, shard).total.resident +
+    (NEAR_PLACEHOLDER_LIMITS.cells - 1) * (NEAR_PLACEHOLDER_LIMITS.terrainBytes + NEAR_PLACEHOLDER_LIMITS.contentBytes);
+  const l1 = C.l1Count * C.l1.resident + coarseExcess, far = (C.farCount - 1) * C.far.resident + (shard.far === null ? 0 : shard.far.decoded + shard.far.gpu);
+  const sims = Math.max(shard.budgets.sim.resident, shard.serverBudget.memory) + 3 * C.sim.resident, overlap = Math.max(C.overlap, shard.budgets.overlap);
+  // each neighbour's 8 x 8 synthetic tiles by column and row (the tile at column i, row j spans x0 ... x0 + 62.5)
+  const edges = (centre: number): Float64Array => Float64Array.from({ length: 8 }, (_, i) => centre - 250 + i * 62.5);
+  const dx2 = new Float64Array(8), dz2 = new Float64Array(8);
+  for (const sx of [-1, 1]) for (const sz of [-1, 1]) {
+    const neighbours = ([[sx * C.pitch, 0], [0, sz * C.pitch], [sx * C.pitch, sz * C.pitch]] as const).map(([cx, cz]) => ({ cx, cz, xs: edges(cx), zs: edges(cz) }));
+    // the last location's library bytes, beside its returned l0 (no object a location)
+    let libraries = 0;
+    const l0At = (x: number, z: number): number => {
+      let active = 0;
+      for (const { cx, cz } of neighbours) if (distance2(x, z, cx - 250, cz - 250, cx + 250, cz + 250) <= RADIUS2) active++;
+      const ownActive = distance2(x, z, -250, -250, 250, 250) <= RADIUS2;
+      // Eight heading lookahead slots charged at target, even when the project is empty.
+      let l0 = 8 * C.l0.resident;
+      for (const tile of own) if (distance2(x, z, tile.x0, tile.z0, tile.x1, tile.z1) <= RADIUS2) l0 += tile.bytes;
+      for (const { xs, zs } of neighbours) {
+        for (let i = 0; i < 8; i++) { const a = xs[i] ?? 0, d = Math.max(a - x, x - (a + 62.5), 0); dx2[i] = d * d; }
+        for (let j = 0; j < 8; j++) { const a = zs[j] ?? 0, d = Math.max(a - z, z - (a + 62.5), 0); dz2[j] = d * d; }
+        for (let j = 0; j < 8; j++) for (let i = 0; i < 8; i++) if ((dx2[i] ?? 0) + (dz2[j] ?? 0) <= RADIUS2) l0 += C.l0.resident;
+      }
+      libraries = (ownActive ? shard.budgets.library.resident : 0) + active * C.library.resident;
+      return l0;
+    };
+    models.push({
+      neighbours: neighbours.map(({ cx, cz }) => [cx, cz] as const), fixed: l1 + far + sims + commons + nearBytes,
+      cost: (x, z) => {
+        const l0 = l0At(x, z);
+        return { ...contentCost({ l0, l1, far, libraries, sims, commons, near: nearBytes, overlap }), location: [x, z] };
+      },
+    });
+  }
+  return models;
+}
+
+/** Conservative total around an actual player location, using the same neighbour assumptions as admission. */
+export function nearbyContentCost(shard: Shardfile, x: number, z: number, commons = 0): LocationCost {
+  if (![x, z, commons].every(Number.isFinite) || commons < 0) throw new Error('Invalid memory estimate location');
+  let worst: LocationCost = { playing: 0, loading: 0, accounted: 0, location: [x, z] };
+  for (const model of locationModels(shard, commons)) { const cost = model.cost(x, z); if (cost.playing > worst.playing) worst = cost; }
+  return worst;
+}
+
+const worstCache = new Map<string, LocationCost>();
+/** A synthetic neighbour cell's per-location grids (how many of its 8 x 8 target tiles, and whether the cell, lie within
+ *  near radius) depend on its offset alone, never the shard: built once a page, not per admission (a phone-4x Nine
+ *  drive rebuilt all eight, 512 tile sweeps, for each product it admitted). */
+const syntheticCells = new Map<string, { l0: Uint8Array; active: Uint8Array }>();
+
+/** Worst disc with three synthetic neighbours at the platform targets; grid padding covers unsampled gaps. */
+export function worstContentCost(shard: Shardfile, commons = 0): LocationCost {
+  const steps = worstContentCostSteps(shard, commons);
+  for (;;) { const step = steps.next(); if (step.done === true) return step.value; }
+}
+
+/** `worstContentCost` in steps, one per own tile and synthetic neighbour tile the grids sum, then one per scanned row:
+ *  a live admission paints between them (Pine's activation spent ~90 ms of a frame in this scan at 4x CPU). */
+export function* worstContentCostSteps(shard: Shardfile, commons = 0): Generator<void, LocationCost> {
+  const bytesOf = ownTileBytes(shard);
+  // The cache key is the JSON of every tile's [lod, bytes, x0, z0, x1, z1] and the shard's budgets, written row by row
+  // (the same text, without an array per tile).
+  const json = (n: number): string => Number.isFinite(n) ? String(n) : 'null';
+  let rows = '';
+  for (let i = 0; i < shard.tiles.length; i++) {
+    const tile = shard.tiles[i]; if (tile === undefined) continue;
+    const bounds = tile.drawBounds ?? tile.bounds;
+    rows += `${i > 0 ? ',' : ''}[${json(tile.lod)},${json(bytesOf(tile))},${json(bounds.min[0])},${json(bounds.min[2])},${json(bounds.max[0])},${json(bounds.max[2])}]`;
+  }
+  const key = `[[${rows}],${JSON.stringify([shard.far === null ? null : [shard.far.decoded, shard.far.gpu], shard.budgets.library.resident, shard.budgets.sim.resident, shard.budgets.overlap, shard.serverBudget.memory, commons,
+    shard.near === undefined ? 0 : nearPlaceholderCost(shard.near, shard).total.resident]).slice(1)}`;
+  const cached = worstCache.get(key);
+  if (cached !== undefined) return { ...cached, location: [...cached.location] };
+  let worst: LocationCost = { playing: 0, loading: 0, accounted: 0, location: [0, 0] };
+  // O14: the scan's ~51k locations sum their accounted bytes from per-location grids built once (own tiles, each
+  // synthetic neighbour cell's tiles); only a location whose bytes exceed the worst so far gets its whole cost (all
+  // bytes are naturals, so the sums are exact in any order and `playing` never falls as they rise)
+  const steps: number[] = []; for (let v = -280; v <= 280; v += GRID_STEP) steps.push(v);
+  const n = steps.length, at = (xi: number, zi: number): number => xi * n + zi;
+  const square = (lo: number, hi: number, v: number): number => { const d = Math.max(lo - v, v - hi, 0); return d * d; };
+  // One scratch row shared by every near() call. Cells retain their original
+  // column/row order; circular cross-sections avoid rejected inner-loop cells.
+  const dx = new Float64Array(n);
+  // Only the index window within the radius of a box (one step of margin; the exact test below decides) is visited: a
+  // tile far off this grid costs a few comparisons, not n x n.
+  const reach = Math.sqrt(RADIUS2), first = steps[0] ?? 0;
+  const below = (v: number): number => Math.max(0, Math.floor((v - reach - first) / GRID_STEP) - 1);
+  const above = (v: number): number => Math.min(n - 1, Math.ceil((v + reach - first) / GRID_STEP) + 1);
+  const near = (x0: number, z0: number, x1: number, z1: number, cells: Float64Array | Uint8Array, add: number, set = false): void => {
+    const xa = below(x0), xb = above(x1), za = below(z0), zb = above(z1);
+    for (let i = xa; i <= xb; i++) dx[i] = square(x0, x1, steps[i] ?? 0);
+    for (let xi = xa; xi <= xb; xi++) {
+      const ex = dx[xi] ?? 0; if (ex > RADIUS2) continue;
+      // A box's circular cross-section is one contiguous interval in z.
+      // Round outwards with one grid step, then use the original predicate
+      // at both ends so floating-point boundary membership stays exact.
+      const radius = Math.sqrt(RADIUS2 - ex);
+      let lo = Math.max(za, Math.ceil((z0 - radius - first) / GRID_STEP) - 1);
+      let hi = Math.min(zb, Math.floor((z1 + radius - first) / GRID_STEP) + 1);
+      while (lo <= hi && ex + square(z0, z1, steps[lo] ?? 0) > RADIUS2) lo++;
+      while (hi >= lo && ex + square(z0, z1, steps[hi] ?? 0) > RADIUS2) hi--;
+      if (lo > hi) continue;
+      const start = at(xi, lo), end = at(xi, hi) + 1;
+      if (set) cells.fill(add, start, end);
+      else for (let cell = start; cell < end; cell++) cells[cell] = (cells[cell] ?? 0) + add;
+    }
+  };
+  const ownL0 = new Float64Array(n * n).fill(8 * C.l0.resident), ownActive = new Uint8Array(n * n);
+  for (const tile of shard.tiles) if (tile.lod === 0) {
+    const bounds = tile.drawBounds ?? tile.bounds, bytes = bytesOf(tile);
+    near(bounds.min[0], bounds.min[2], bounds.max[0], bounds.max[2], ownL0, bytes);
+    yield;
+  }
+  near(-250, -250, 250, 250, ownActive, 1, true);
+  const cellOf = function* cellOf([cx, cz]: readonly [number, number]): Generator<void, { l0: Uint8Array; active: Uint8Array }> {
+    const id = `${cx},${cz}`, known = syntheticCells.get(id); if (known !== undefined) return known;
+    const made = { l0: new Uint8Array(n * n), active: new Uint8Array(n * n) };
+    for (let i = 0; i < 64; i++) {
+      const x0 = cx - 250 + (i % 8) * 62.5, z0 = cz - 250 + Math.floor(i / 8) * 62.5;
+      near(x0, z0, x0 + 62.5, z0 + 62.5, made.l0, 1);
+      yield;
+    }
+    near(cx - 250, cz - 250, cx + 250, cz + 250, made.active, 1, true);
+    syntheticCells.set(id, made); return made;
+  };
+  let worstAccounted = Number.NEGATIVE_INFINITY;
+  for (const model of locationModels(shard, commons)) {
+    const found: { l0: Uint8Array; active: Uint8Array }[] = [];
+    for (const neighbour of model.neighbours) found.push(yield* cellOf(neighbour));
+    const [a, b, c] = found;
+    if (a === undefined || b === undefined || c === undefined) throw new Error('Location model requires three neighbours');
+    for (let xi = 0; xi < n; xi++) for (let zi = 0; zi < n; zi++) {
+      const cell = at(xi, zi), active = (a.active[cell] ?? 0) + (b.active[cell] ?? 0) + (c.active[cell] ?? 0);
+      const libraries = (ownActive[cell] === 1 ? shard.budgets.library.resident : 0) + active * C.library.resident;
+      const accounted = (ownL0[cell] ?? 0) + ((a.l0[cell] ?? 0) + (b.l0[cell] ?? 0) + (c.l0[cell] ?? 0)) * C.l0.resident + libraries + model.fixed;
+      if (accounted <= worstAccounted) continue;
+      const cost = model.cost(steps[xi] ?? 0, steps[zi] ?? 0);
+      if (cost.playing > worst.playing) { worst = cost; worstAccounted = accounted; }
+    }
+    yield;
+  }
+  if (worstCache.size >= 8) { const oldest = worstCache.keys().next().value; if (oldest !== undefined) worstCache.delete(oldest); }
+  worstCache.set(key, worst);
+  return { ...worst, location: [...worst.location] };
+}