conveyor-engine-assets 0.0.0-stage → 0.1.0

package/dist/acquisition.d.ts

@@ -0,0 +1,23 @@
+export type ByteSource = {
+    bytes: Uint8Array;
+    contentType?: string;
+    uri: string;
+};
+export type AcquisitionContext = {
+    uri: string;
+    /** Temporary locator supplied by the app layer. Never treated as asset identity. */
+    runtimeUrl?: string;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+export interface AcquisitionProvider {
+    readonly id: string;
+    accepts?(uri: string): boolean;
+    acquire(ctx: AcquisitionContext): Promise<ByteSource>;
+}
+export declare class AcquisitionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function composeProviders(providers: AcquisitionProvider[]): AcquisitionProvider;

package/dist/acquisition.js

@@ -0,0 +1,29 @@
+export class AcquisitionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "AcquisitionError";
+        this.code = code;
+    }
+}
+export function composeProviders(providers) {
+    return {
+        id: providers.map((p) => p.id).join("+") || "empty",
+        async acquire(ctx) {
+            let last;
+            for (const p of providers) {
+                if (p.accepts && !p.accepts(ctx.runtimeUrl ?? ctx.uri))
+                    continue;
+                try {
+                    return await p.acquire(ctx);
+                }
+                catch (err) {
+                    last = err;
+                }
+            }
+            if (last instanceof Error)
+                throw last;
+            throw new AcquisitionError("provider", `no provider could acquire ${ctx.uri}`);
+        },
+    };
+}

package/dist/admission.d.ts

@@ -0,0 +1,38 @@
+import { AssetLoadError, type AssetHandle, type AssetRuntime, type RequestOptions } from "./loader.js";
+import type { AdmissionRecord, AssetId, AuthoritativeCompatibility, EngineManifest } from "./types.js";
+export declare class StaticAdmissionError extends Error {
+    readonly missing: AssetId[];
+    constructor(missing: AssetId[], message?: string);
+}
+export type StagedAdmission = {
+    assetId: AssetId;
+    handle?: AssetHandle;
+    requestId: string;
+    error?: AssetLoadError;
+};
+/**
+ * Off-tick staging + tick-boundary take. Does not mutate AuthoritativeWorld.
+ */
+export declare class AssetAdmissionQueue {
+    private readonly staged;
+    private readonly applied;
+    private readonly runtime;
+    constructor(runtime: AssetRuntime);
+    get manifest(): EngineManifest;
+    /**
+     * Load and pin every authoritative / authoritative-static asset. Fail closed.
+     * Pins last for the session on purpose — call `runtime.unpin(id)` to evict.
+     */
+    requireStaticReady(opts?: RequestOptions): Promise<AuthoritativeCompatibility>;
+    /** Resolve off the simulation tick. Presentation assets are rejected. */
+    stage(id: AssetId, opts?: RequestOptions): Promise<StagedAdmission>;
+    peek(): StagedAdmission[];
+    history(): AdmissionRecord[];
+    /**
+     * Admit or reject everything currently staged. Call only on a simulation tick boundary.
+     * Records are the replay surface; the caller applies world effects separately.
+     */
+    takeAdmitted(tick: bigint, decide?: (staged: StagedAdmission) => AdmissionRecord["outcome"] | void): AdmissionRecord[];
+    reject(id: AssetId, tick: bigint, reason?: string): AdmissionRecord | undefined;
+    private emit;
+}

package/dist/admission.js

@@ -0,0 +1,216 @@
+import { collectAuthoritativeCompatibility } from "./schema.js";
+import { AssetLoadError } from "./loader.js";
+export class StaticAdmissionError extends Error {
+    missing;
+    constructor(missing, message) {
+        super(message ?? `authoritative static assets not ready: ${missing.join(", ")}`);
+        this.name = "StaticAdmissionError";
+        this.missing = missing;
+    }
+}
+function isAdmittedClass(authority) {
+    return authority === "authoritative-admitted";
+}
+function isStaticAuth(authority) {
+    return authority === "authoritative" || authority === "authoritative-static";
+}
+/**
+ * Off-tick staging + tick-boundary take. Does not mutate AuthoritativeWorld.
+ */
+export class AssetAdmissionQueue {
+    staged = new Map();
+    applied = [];
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    get manifest() {
+        return this.runtime.manifest;
+    }
+    /**
+     * Load and pin every authoritative / authoritative-static asset. Fail closed.
+     * Pins last for the session on purpose — call `runtime.unpin(id)` to evict.
+     */
+    async requireStaticReady(opts = {}) {
+        const staticEntries = this.runtime.manifest.assets.filter((a) => isStaticAuth(a.authority));
+        const missing = [];
+        for (const entry of staticEntries) {
+            try {
+                const handle = await this.runtime.request(entry.id, opts);
+                this.runtime.pin(entry.id);
+                handle.release();
+            }
+            catch {
+                missing.push(entry.id);
+            }
+        }
+        if (missing.length)
+            throw new StaticAdmissionError(missing);
+        return collectAuthoritativeCompatibility(this.runtime.manifest);
+    }
+    /** Resolve off the simulation tick. Presentation assets are rejected. */
+    async stage(id, opts = {}) {
+        const entry = this.runtime.getEntry(id);
+        if (!entry) {
+            const staged = {
+                assetId: id,
+                requestId: `missing-${id}`,
+                error: new AssetLoadError("not-found", `unknown asset ${id}`, {
+                    requestId: `missing-${id}`,
+                    assetId: id,
+                    state: "failed",
+                    retryCount: 0,
+                    degraded: false,
+                    failureCode: "not-found",
+                }),
+            };
+            this.staged.set(id, staged);
+            this.runtime.metrics.admissionStagedCount += 1;
+            this.emit({
+                type: "admission-staged",
+                record: {
+                    assetId: id,
+                    version: "0",
+                    contentHash: "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+                    authority: "authoritative-admitted",
+                    requestId: staged.requestId,
+                },
+            });
+            return staged;
+        }
+        if (!isAdmittedClass(entry.authority)) {
+            const staged = {
+                assetId: id,
+                requestId: `policy-${id}`,
+                error: new AssetLoadError("policy", `${id} is ${entry.authority}, not authoritative-admitted`, {
+                    requestId: `policy-${id}`,
+                    assetId: id,
+                    version: entry.version,
+                    contentHash: entry.contentHash,
+                    state: "failed",
+                    retryCount: 0,
+                    degraded: false,
+                    failureCode: "policy",
+                }),
+            };
+            this.staged.set(id, staged);
+            this.runtime.metrics.admissionStagedCount += 1;
+            this.emit({
+                type: "admission-staged",
+                record: {
+                    assetId: entry.id,
+                    version: entry.version,
+                    contentHash: entry.contentHash,
+                    authority: entry.authority,
+                    requestId: staged.requestId,
+                },
+            });
+            return staged;
+        }
+        try {
+            const handle = await this.runtime.request(id, opts);
+            const staged = { assetId: id, handle, requestId: handle.requestId };
+            this.staged.set(id, staged);
+            this.runtime.metrics.admissionStagedCount += 1;
+            this.emit({
+                type: "admission-staged",
+                record: {
+                    assetId: handle.assetId,
+                    version: handle.version,
+                    contentHash: handle.contentHash,
+                    authority: handle.entry.authority,
+                    requestId: handle.requestId,
+                },
+            });
+            return staged;
+        }
+        catch (err) {
+            const error = err instanceof AssetLoadError ? err : undefined;
+            const staged = {
+                assetId: id,
+                requestId: error?.snapshot.requestId ?? `fail-${id}`,
+                error: error ?? new AssetLoadError("provider", messageOf(err), {
+                    requestId: `fail-${id}`,
+                    assetId: id,
+                    state: "failed",
+                    retryCount: 0,
+                    degraded: false,
+                }),
+            };
+            this.staged.set(id, staged);
+            this.runtime.metrics.admissionStagedCount += 1;
+            return staged;
+        }
+    }
+    peek() {
+        return [...this.staged.values()];
+    }
+    history() {
+        return [...this.applied];
+    }
+    /**
+     * Admit or reject everything currently staged. Call only on a simulation tick boundary.
+     * Records are the replay surface; the caller applies world effects separately.
+     */
+    takeAdmitted(tick, decide) {
+        const records = [];
+        const pending = [...this.staged.entries()];
+        for (const [id, staged] of pending) {
+            const entry = staged.handle?.entry ?? this.runtime.getEntry(id);
+            const outcome = staged.error
+                ? "rejected"
+                : (decide?.(staged) ?? "accepted");
+            const record = {
+                assetId: id,
+                version: entry?.version ?? "0",
+                contentHash: entry?.contentHash ?? "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+                authority: entry?.authority ?? "authoritative-admitted",
+                tick,
+                outcome,
+                requestId: staged.requestId,
+                reason: staged.error?.message,
+            };
+            if (outcome === "accepted")
+                this.runtime.metrics.admissionAcceptedCount += 1;
+            else
+                this.runtime.metrics.admissionRejectedCount += 1;
+            if (outcome === "rejected")
+                staged.handle?.release();
+            else if (staged.handle)
+                this.runtime.pin(id);
+            records.push(record);
+            this.applied.push(record);
+            this.emit({ type: "admission-applied", record });
+            this.staged.delete(id);
+        }
+        return records;
+    }
+    reject(id, tick, reason) {
+        const staged = this.staged.get(id);
+        if (!staged)
+            return undefined;
+        staged.handle?.release();
+        const entry = staged.handle?.entry ?? this.runtime.getEntry(id);
+        const record = {
+            assetId: id,
+            version: entry?.version ?? "0",
+            contentHash: entry?.contentHash ?? "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+            authority: entry?.authority ?? "authoritative-admitted",
+            tick,
+            outcome: "rejected",
+            requestId: staged.requestId,
+            reason,
+        };
+        this.runtime.metrics.admissionRejectedCount += 1;
+        this.applied.push(record);
+        this.staged.delete(id);
+        this.emit({ type: "admission-applied", record });
+        return record;
+    }
+    emit(event) {
+        this.runtime.emit(event);
+    }
+}
+function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/animation-profile.d.ts

@@ -0,0 +1,31 @@
+import type { AssetId } from "./types.js";
+import type { GlbValidationReport } from "./glb.js";
+export type AnimationSemantic = "idle" | "walk" | "run" | "action-primary";
+export type AnimationProfile = {
+    id: string;
+    clips: Partial<Record<AnimationSemantic, string>>;
+    rootMotion: "disabled";
+    idleWalkFadeMs?: number;
+    walkRunFadeMs?: number;
+    actionFadeInMs?: number;
+    actionFadeOutMs?: number;
+    walkSpeed?: number;
+    runSpeed?: number;
+    minPlayback?: number;
+    maxPlayback?: number;
+    idleThreshold?: number;
+    runThreshold?: number;
+};
+export type AnimationProfileValidation = {
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+};
+export declare function validateAnimationProfile(profile: AnimationProfile, sniffed?: Pick<GlbValidationReport, "animationNames" | "skinCount" | "animationCount" | "ok">): AnimationProfileValidation;
+export declare const HUMANOID_BASIC_V1: AnimationProfile;
+export type SkinnedModelMeta = {
+    assetId: AssetId;
+    profileId: string;
+    rootMotion: "disabled";
+    fallbackAssetId?: AssetId;
+};

package/dist/animation-profile.js

@@ -0,0 +1,49 @@
+const REQUIRED = ["idle", "walk", "run", "action-primary"];
+export function validateAnimationProfile(profile, sniffed) {
+    const errors = [];
+    const warnings = [];
+    if (!profile.id)
+        errors.push("profile.id required");
+    if (profile.rootMotion !== "disabled")
+        errors.push("A4 requires rootMotion: disabled");
+    for (const sem of REQUIRED) {
+        if (!profile.clips[sem])
+            errors.push(`missing clip alias for ${sem}`);
+    }
+    if (sniffed) {
+        if (!sniffed.ok)
+            errors.push("skinned GLB failed structural validation");
+        if (sniffed.skinCount < 1)
+            errors.push("skinned-model requires at least one skin");
+        if (sniffed.animationCount < 1)
+            errors.push("animated-model requires at least one animation");
+        const names = new Set(sniffed.animationNames ?? []);
+        if (names.size) {
+            for (const [sem, clip] of Object.entries(profile.clips)) {
+                if (clip && !names.has(clip))
+                    errors.push(`clip alias ${sem} → ${clip} not in GLB`);
+            }
+        }
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}
+export const HUMANOID_BASIC_V1 = {
+    id: "humanoid-basic-v1",
+    clips: {
+        idle: "Idle",
+        walk: "Walk",
+        run: "Run",
+        "action-primary": "Attack",
+    },
+    rootMotion: "disabled",
+    idleWalkFadeMs: 120,
+    walkRunFadeMs: 100,
+    actionFadeInMs: 80,
+    actionFadeOutMs: 120,
+    walkSpeed: 2,
+    runSpeed: 5,
+    minPlayback: 0.5,
+    maxPlayback: 1.5,
+    idleThreshold: 0.2,
+    runThreshold: 4,
+};

package/dist/collision.d.ts

@@ -0,0 +1,108 @@
+import type { AssetId, ContentHash, LoadedPayload } from "./types.js";
+export type CollisionRepresentation = "aabb" | "triangle-mesh" | "occupancy-grid" | "primitives";
+export type CollisionCoordinateSystem = "y-up" | "z-up";
+export type CollisionBounds = {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+    minZ: number;
+    maxZ: number;
+};
+/** Matches conveyor-engine-world StaticObstacle. No render fields. */
+export type CollisionObstacle = {
+    id: number;
+    minX: number;
+    maxX: number;
+    minZ: number;
+    maxZ: number;
+};
+export type CollisionAabb = CollisionObstacle & {
+    minY?: number;
+    maxY?: number;
+};
+export type CollisionTriangleMesh = {
+    positions: number[];
+    indices: number[];
+};
+export type CollisionOccupancyGrid = {
+    originX: number;
+    originZ: number;
+    cellSize: number;
+    width: number;
+    depth: number;
+    /** Row-major occupancy, width * depth. 0 = free, nonzero = blocked. */
+    cells: number[];
+};
+export type CollisionPrimitive = {
+    type: "box";
+    id: number;
+    minX: number;
+    maxX: number;
+    minY?: number;
+    maxY?: number;
+    minZ: number;
+    maxZ: number;
+} | {
+    type: "sphere";
+    id: number;
+    x: number;
+    y?: number;
+    z: number;
+    radius: number;
+} | {
+    type: "capsule";
+    id: number;
+    x: number;
+    y?: number;
+    z: number;
+    radius: number;
+    height: number;
+};
+export type CollisionSpawnPoint = {
+    id: string;
+    x: number;
+    y?: number;
+    z: number;
+    yaw?: number;
+    team?: string;
+    priority?: number;
+    clearance?: number;
+};
+export type CollisionArtifact = {
+    formatVersion: 1;
+    representation: CollisionRepresentation;
+    coordinateSystem: CollisionCoordinateSystem;
+    unitScale: number;
+    origin: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    bounds: CollisionBounds;
+    visualAssetId?: AssetId;
+    contentHash?: ContentHash;
+    aabbs?: CollisionAabb[];
+    mesh?: CollisionTriangleMesh;
+    grid?: CollisionOccupancyGrid;
+    primitives?: CollisionPrimitive[];
+    spawnPoints?: CollisionSpawnPoint[];
+};
+export type CollisionValidation = {
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+    triangleCount?: number;
+    aabbCount?: number;
+    primitiveCount?: number;
+    occupiedCells?: number;
+};
+export declare class CollisionParseError extends Error {
+    readonly issues: string[];
+    constructor(issues: string[]);
+}
+export declare function parseCollisionArtifact(input: unknown): CollisionArtifact;
+export declare function collisionFromPayload(payload: LoadedPayload): CollisionArtifact;
+export declare function validateCollisionArtifact(artifact: CollisionArtifact): CollisionValidation;
+/** Flatten any representation into world StaticObstacle-shaped AABBs on XZ. */
+export declare function collisionToObstacles(artifact: CollisionArtifact): CollisionObstacle[];