@world-engines/spatial-authoring 0.1.0-alpha.0

package/dist/schema.d.ts

@@ -0,0 +1,47 @@
+import { type PlaneGenerationV1 } from "./plane-generation.js";
+/** 空间作者源的唯一内存模型；持久化由宿主的 protobuf/WESP adapter 负责。 */
+export declare const SPATIAL_WORLD_SOURCE_VERSION: 1;
+export type SpatialTopologyKind = "grid" | "freeform";
+export type SpatialObjectKind = "location" | "portal" | "region";
+export interface SpatialTopologyV1 {
+    readonly kind: SpatialTopologyKind;
+    readonly width: number;
+    readonly height: number;
+    readonly cellSize?: number;
+    /** 可重放生成参数；高度/纹理缓存不进入作者源。 */
+    readonly generation?: PlaneGenerationV1;
+}
+/** 外部作者域对空间 id 的引用；删除前必须由宿主消费影响列表。 */
+export interface SpatialReferenceV1 {
+    readonly ownerId: string;
+    readonly ownerKind: "ladybug" | "trigger" | "scenario";
+    readonly fieldPath: string;
+}
+export interface SpatialObjectV1 {
+    readonly id: string;
+    readonly key: string;
+    readonly kind: SpatialObjectKind;
+    readonly label: string;
+    readonly x: number;
+    readonly y: number;
+    readonly references: readonly SpatialReferenceV1[];
+}
+export interface SpatialWorldSourceV1 {
+    readonly schemaVersion: typeof SPATIAL_WORLD_SOURCE_VERSION;
+    readonly worldId: string;
+    /** 由 source authority 递增；worker 的结果必须回带此 revision。 */
+    readonly revision: number;
+    readonly topology: SpatialTopologyV1;
+    readonly objects: readonly SpatialObjectV1[];
+}
+export interface SpatialValidationIssue {
+    readonly path: string;
+    readonly message: string;
+}
+export declare class SpatialWorldValidationError extends Error {
+    readonly issues: readonly SpatialValidationIssue[];
+    constructor(issues: readonly SpatialValidationIssue[]);
+}
+export declare function stableSpatialId(kind: SpatialObjectKind, key: string): string;
+/** 验证并返回同一对象，不复制或序列化 source，避免制造 JSON 第二 authority。 */
+export declare function validateSpatialWorldSourceV1(source: SpatialWorldSourceV1): SpatialWorldSourceV1;

package/dist/schema.js

@@ -0,0 +1,82 @@
+import { validatePlaneGeneration } from "./plane-generation.js";
+/** 空间作者源的唯一内存模型；持久化由宿主的 protobuf/WESP adapter 负责。 */
+export const SPATIAL_WORLD_SOURCE_VERSION = 1;
+export class SpatialWorldValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`SpatialWorldSourceV1 无效：${issues.map((issue) => `${issue.path} ${issue.message}`).join("；")}`);
+        this.name = "SpatialWorldValidationError";
+        this.issues = issues;
+    }
+}
+const KEY_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+export function stableSpatialId(kind, key) {
+    return `spatial:${kind}:${key}`;
+}
+function isPositiveFinite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function isFiniteCoordinate(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+/** 验证并返回同一对象，不复制或序列化 source，避免制造 JSON 第二 authority。 */
+export function validateSpatialWorldSourceV1(source) {
+    if (source.topology.generation !== undefined) {
+        const generation = validatePlaneGeneration(source.topology.generation);
+        if (generation.widthMeters !== source.topology.width || generation.heightMeters !== source.topology.height) {
+            throw new SpatialWorldValidationError([{ path: "topology.generation", message: "生成范围必须与空间范围一致" }]);
+        }
+    }
+    const issues = [];
+    if (source.schemaVersion !== SPATIAL_WORLD_SOURCE_VERSION) {
+        issues.push({ path: "schemaVersion", message: "必须为 1" });
+    }
+    if (!KEY_PATTERN.test(source.worldId))
+        issues.push({ path: "worldId", message: "必须是稳定的 kebab-case key" });
+    if (!Number.isSafeInteger(source.revision) || source.revision < 0) {
+        issues.push({ path: "revision", message: "必须是非负安全整数" });
+    }
+    if (!isPositiveFinite(source.topology.width) || !isPositiveFinite(source.topology.height)) {
+        issues.push({ path: "topology", message: "width 和 height 必须为正数" });
+    }
+    if (source.topology.kind === "grid" && !isPositiveFinite(source.topology.cellSize)) {
+        issues.push({ path: "topology.cellSize", message: "grid 必须有正 cellSize" });
+    }
+    if (source.topology.kind !== "grid" && source.topology.kind !== "freeform") {
+        issues.push({ path: "topology.kind", message: "不支持的 topology kind" });
+    }
+    const ids = new Set();
+    const keys = new Set();
+    source.objects.forEach((object, index) => {
+        const path = `objects[${index}]`;
+        if (!KEY_PATTERN.test(object.key))
+            issues.push({ path: `${path}.key`, message: "必须是稳定的 kebab-case key" });
+        const expectedId = stableSpatialId(object.kind, object.key);
+        if (object.id !== expectedId)
+            issues.push({ path: `${path}.id`, message: `必须等于 ${expectedId}` });
+        if (ids.has(object.id))
+            issues.push({ path: `${path}.id`, message: "不能重复" });
+        ids.add(object.id);
+        if (keys.has(`${object.kind}:${object.key}`))
+            issues.push({ path: `${path}.key`, message: "同 kind 下不能重复" });
+        keys.add(`${object.kind}:${object.key}`);
+        if (object.kind !== "location" && object.kind !== "portal" && object.kind !== "region") {
+            issues.push({ path: `${path}.kind`, message: "不支持的 spatial object kind" });
+        }
+        if (object.label.trim().length === 0)
+            issues.push({ path: `${path}.label`, message: "不能为空" });
+        if (!isFiniteCoordinate(object.x) || !isFiniteCoordinate(object.y))
+            issues.push({ path, message: "坐标必须为有限数" });
+        if (object.x < 0 || object.x > source.topology.width || object.y < 0 || object.y > source.topology.height) {
+            issues.push({ path, message: "坐标必须位于 topology 边界内" });
+        }
+        object.references.forEach((reference, referenceIndex) => {
+            if (reference.ownerId.trim().length === 0 || reference.fieldPath.trim().length === 0) {
+                issues.push({ path: `${path}.references[${referenceIndex}]`, message: "引用必须有 ownerId 和 fieldPath" });
+            }
+        });
+    });
+    if (issues.length > 0)
+        throw new SpatialWorldValidationError(issues);
+    return source;
+}

package/dist/source-adapter.d.ts

@@ -0,0 +1,15 @@
+import type { SpatialObjectV1, SpatialReferenceV1, SpatialWorldSourceV1 } from "./schema.js";
+export interface SpatialReferenceImpact {
+    readonly spatialId: string;
+    readonly reference: SpatialReferenceV1;
+}
+export interface SpatialRemovalPlan {
+    readonly target: SpatialObjectV1;
+    readonly impacts: readonly SpatialReferenceImpact[];
+    readonly requiresConfirmation: boolean;
+    readonly sourceRevision: number;
+}
+export declare function collectSpatialReferenceImpacts(source: SpatialWorldSourceV1, spatialId: string): readonly SpatialReferenceImpact[];
+/** 删除只生成计划；实际 source mutation 必须由宿主在确认后完成。 */
+export declare function planSpatialObjectRemoval(source: SpatialWorldSourceV1, spatialId: string): SpatialRemovalPlan;
+export declare function assertSpatialRemovalConfirmation(plan: SpatialRemovalPlan, confirmed: boolean, sourceRevision: number): void;

package/dist/source-adapter.js

@@ -0,0 +1,23 @@
+import { validateSpatialWorldSourceV1 } from "./schema.js";
+export function collectSpatialReferenceImpacts(source, spatialId) {
+    const validSource = validateSpatialWorldSourceV1(source);
+    const target = validSource.objects.find((object) => object.id === spatialId);
+    if (target === undefined)
+        return [];
+    return target.references.map((reference) => ({ spatialId: target.id, reference }));
+}
+/** 删除只生成计划；实际 source mutation 必须由宿主在确认后完成。 */
+export function planSpatialObjectRemoval(source, spatialId) {
+    const validSource = validateSpatialWorldSourceV1(source);
+    const target = validSource.objects.find((object) => object.id === spatialId);
+    if (target === undefined)
+        throw new RangeError(`不存在空间对象 ${spatialId}`);
+    const impacts = collectSpatialReferenceImpacts(validSource, spatialId);
+    return { target, impacts, requiresConfirmation: impacts.length > 0, sourceRevision: validSource.revision };
+}
+export function assertSpatialRemovalConfirmation(plan, confirmed, sourceRevision) {
+    if (plan.sourceRevision !== sourceRevision)
+        throw new Error("source revision 已变化，必须重新计算引用影响");
+    if (plan.requiresConfirmation && !confirmed)
+        throw new Error("存在空间引用影响，必须显式确认删除");
+}

package/dist/spatial-runtime.d.ts

@@ -0,0 +1,210 @@
+import { type Bounds2D, type InteriorDoor, type InteriorRoom, type ProceduralBuilding, type ProceduralParcel, type ProceduralRoad, type ProceduralWorldV1 } from "./procedural-city.js";
+import { type RoadParcelBoundary, type RoadParcelTerrainGrid } from "./road-parcels.js";
+import { type RoadGenerationV1 } from "./road-generation.js";
+export declare const SPATIAL_DELTA_VERSION: 1;
+export declare const SPATIAL_RUNTIME_CACHE_LIMITS: Readonly<{
+    cityLayouts: 8;
+    activatedParcels: 128;
+    buildingInteriors: 64;
+}>;
+export declare const SPATIAL_DELTA_QUOTAS: Readonly<{
+    maxOverrides: 2048;
+    maxTombstones: 2048;
+    maxUtf8Bytes: 1048576;
+}>;
+export declare const BUILDING_ENTRANCE_TOLERANCE_METERS = 1.5;
+export type SpatialTargetType = "city" | "road" | "parcel" | "building" | "room" | "door";
+export type SpatialOverrideField = "label" | "blocked" | "destroyed";
+export type SpatialOverrideValue = string | boolean;
+export type SpatialTargetLocatorV1 = {
+    readonly cityId: string;
+} | {
+    readonly cityId: string;
+    readonly parcelId: string;
+} | {
+    readonly cityId: string;
+    readonly parcelId: string;
+    readonly buildingId: string;
+};
+export interface SpatialRuntimeBinding {
+    readonly artifactDigest: string;
+    readonly baseDigest: string;
+    readonly worldlineId: string;
+    readonly controlledActorId: string;
+}
+export interface SpatialDeltaBindingV1 {
+    readonly artifactDigest: string;
+    readonly baseDigest: string;
+    readonly worldlineId: string;
+}
+export interface ControlledSpatialPose {
+    readonly actorId: string;
+    readonly x: number;
+    readonly y: number;
+    readonly revision: string | number;
+}
+export interface SpatialDeltaOverrideV1 {
+    readonly targetType: SpatialTargetType;
+    readonly targetId: string;
+    readonly locator: SpatialTargetLocatorV1;
+    readonly field: SpatialOverrideField;
+    readonly value: SpatialOverrideValue;
+}
+export interface SpatialTombstoneV1 {
+    readonly targetType: SpatialTargetType;
+    readonly targetId: string;
+    readonly locator: SpatialTargetLocatorV1;
+}
+export interface SpatialDeltaV1 {
+    readonly version: typeof SPATIAL_DELTA_VERSION;
+    readonly binding: SpatialDeltaBindingV1;
+    readonly overrides: readonly SpatialDeltaOverrideV1[];
+    readonly tombstones: readonly SpatialTombstoneV1[];
+}
+export interface SpatialRuntimeAttributes {
+    readonly label?: string;
+    readonly blocked?: boolean;
+    readonly destroyed?: boolean;
+}
+export interface TerrainRoadPointV1 {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+export interface TerrainRoadSegmentV1 {
+    readonly kind: "surface" | "bridge" | "tunnel";
+    readonly points: readonly TerrainRoadPointV1[];
+    readonly lengthMeters: number;
+}
+/** terrain-roads-v1 的瞬态 WASM route cache；它不得进入 source sidecar 或 SAV。 */
+export interface TerrainRoadV1 {
+    readonly id: string;
+    readonly kind: "intercity" | "arterial" | "local";
+    readonly roadClass: "street" | "motorway";
+    readonly cityId?: string;
+    readonly fromCityId?: string;
+    readonly toCityId?: string;
+    readonly widthMeters: number;
+    readonly points: readonly TerrainRoadPointV1[];
+    readonly segments: readonly TerrainRoadSegmentV1[];
+}
+export interface TerrainRoadNetworkV1 {
+    readonly profile: "terrain-roads-v1";
+    readonly roads: readonly TerrainRoadV1[];
+    readonly unreachable: readonly Readonly<Record<string, unknown>>[];
+    readonly cityLayouts: readonly TerrainRoadCityLayoutV1[];
+}
+export interface TerrainRoadCityLayoutV1 {
+    readonly cityId: string;
+    readonly roads: readonly string[];
+    /** core 以实际 sampler 重建的城市可建边界；unbuildable 绝不回退为圆形。 */
+    readonly boundary: TerrainRoadBoundaryV1;
+    /** 给地块生成器的 city-bbox route cache；不进入 source 或 SAV。 */
+    readonly terrain: RoadParcelTerrainGrid;
+}
+/** wire cache 额外带 cityId，使 boundary 不能被错绑到另一个 layout。 */
+export interface TerrainRoadBoundaryV1 extends RoadParcelBoundary {
+    readonly cityId: string;
+}
+type RuntimeRoadBase = ProceduralRoad | TerrainRoadV1;
+export type RuntimeRoad = Readonly<RuntimeRoadBase & SpatialRuntimeAttributes>;
+export type RuntimeParcel = Readonly<ProceduralParcel & SpatialRuntimeAttributes>;
+export type RuntimeBuilding = Readonly<ProceduralBuilding & SpatialRuntimeAttributes>;
+export type RuntimeRoom = Readonly<InteriorRoom & SpatialRuntimeAttributes>;
+export type RuntimeDoor = Readonly<InteriorDoor & SpatialRuntimeAttributes>;
+export interface SpatialViewportRequest {
+    readonly bounds: Bounds2D;
+    readonly metersPerCssPixel: number;
+}
+export interface SpatialViewport {
+    readonly roads: readonly RuntimeRoad[];
+    readonly parcels: readonly RuntimeParcel[];
+    /** 仅返回已由真实进入 gate 物化且仍在 cache 中的建筑。 */
+    readonly buildings: readonly RuntimeBuilding[];
+}
+/**
+ * 视口请求的 canonical transport 形状。相机缩放是 projection 信息；
+ * chunk identity 只由已冻结 base/revision 与世界坐标决定。
+ */
+export interface SpatialViewportChunkRequest {
+    readonly baseDigest: string;
+    readonly spatialRevision: string | number;
+    readonly centerMeters: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    readonly metersPerCssPixel: number;
+    readonly viewportSize: Readonly<{
+        width: number;
+        height: number;
+    }>;
+    readonly chunk: Readonly<{
+        level: number;
+        x: number;
+        y: number;
+    }>;
+}
+export interface SpatialViewportChunkCache<T> {
+    read(request: SpatialViewportChunkRequest, signal?: AbortSignal): Promise<T>;
+    clear(): void;
+    retainRevision(baseDigest: string, spatialRevision: string | number): void;
+    getCacheSize(): number;
+}
+export interface ParcelEntry {
+    readonly pose: ControlledSpatialPose;
+    readonly parcel: RuntimeParcel;
+    readonly buildings: readonly RuntimeBuilding[];
+}
+export interface RuntimeBuildingInterior {
+    readonly buildingId: string;
+    readonly rooms: readonly RuntimeRoom[];
+    readonly doors: readonly RuntimeDoor[];
+}
+export interface BuildingEntry {
+    readonly pose: ControlledSpatialPose;
+    readonly building: RuntimeBuilding;
+    readonly interior: RuntimeBuildingInterior;
+}
+export interface SpatialRuntimeCacheStats {
+    readonly cityLayouts: number;
+    readonly activatedParcels: number;
+    readonly materializedBuildings: number;
+    readonly buildingInteriors: number;
+}
+export type SpatialRuntimeErrorCode = "HOST_POSE_UNAVAILABLE" | "HOST_POSE_ACTOR_MISMATCH" | "HOST_POSE_INVALID" | "POSE_OUTSIDE_PARCEL" | "POSE_OUTSIDE_BUILDING" | "TARGET_NOT_FOUND" | "PARENT_PARCEL_NOT_ACTIVATED" | "TARGET_UNAVAILABLE" | "DELTA_BINDING_MISMATCH" | "DELTA_INVALID" | "DELTA_QUOTA_EXCEEDED";
+export declare class SpatialRuntimeError extends Error {
+    readonly code: SpatialRuntimeErrorCode;
+    constructor(code: SpatialRuntimeErrorCode, message: string);
+}
+export interface SpatialRuntimeOptions {
+    readonly world: ProceduralWorldV1;
+    /** 仅在 sidecar 显式 roadGeneration 时由 Player 预加载并传入。 */
+    readonly roadNetwork?: TerrainRoadNetworkV1;
+    /** 新道路地块的坡度门必须消费与 route cache 相同的发布配置。 */
+    readonly roadGeneration?: RoadGenerationV1;
+    readonly binding: SpatialRuntimeBinding;
+    readonly readControlledPose: () => ControlledSpatialPose | null | undefined;
+}
+export interface SpatialRuntime {
+    readonly world: ProceduralWorldV1;
+    readonly binding: SpatialRuntimeBinding;
+    readViewport(request: SpatialViewportRequest): SpatialViewport;
+    enterCurrentParcel(): ParcelEntry;
+    enterCurrentBuilding(buildingId: string): BuildingEntry;
+    clearCache(): void;
+    getCacheStats(): SpatialRuntimeCacheStats;
+    setOverride(targetType: SpatialTargetType, targetId: string, field: SpatialOverrideField, value: SpatialOverrideValue): void;
+    applyOverride(targetType: SpatialTargetType, targetId: string, patch: Readonly<Partial<Record<SpatialOverrideField, SpatialOverrideValue>>>): void;
+    setTombstone(targetType: SpatialTargetType, targetId: string, tombstoned?: boolean): void;
+    serializeDelta(): SpatialDeltaV1;
+    serializeDeltaUtf8(): Uint8Array;
+    restoreDelta(input: unknown): void;
+    applyDelta(input: unknown): void;
+}
+/**
+ * scope-bound、可取消的 chunk cache。它不生成或持久化几何；调用者只能从同一个
+ * 已确认 base binding 请求 tile，取消或旧 revision 的响应绝不会成为新 revision cache。
+ */
+export declare function createSpatialViewportChunkCache<T>(load: (request: SpatialViewportChunkRequest, signal: AbortSignal) => Promise<T>): SpatialViewportChunkCache<T>;
+export declare function createSpatialRuntime(options: SpatialRuntimeOptions): SpatialRuntime;
+export {};