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

package/dist/procedural-city.js

@@ -0,0 +1,595 @@
+export const PROCEDURAL_WORLD_PROFILE = "procedural-world-v1";
+import { validateSpatialTemplateConfiguration, } from "./spatial-templates.js";
+/**
+ * 该字符串绑定 profile、算法版本与下方 canonical 规则字节的 SHA-256。
+ * 算法语义变化时必须发布新 identity，禁止让旧 seed 静默产生不同世界。
+ */
+export const PROCEDURAL_GENERATOR_RULES_CANONICAL = '{"building":"parcel-entry-v1","city":"clipped-orthogonal-lattice-v1","hash":"fnv1a32-avalanche-v1","interior":"central-corridor-v1","landUse":"weighted-hash-v1","metrics":"meters","terrain":"parcel-buildability-sampler-v1"}';
+export const PROCEDURAL_GENERATOR_IDENTITY = "chat.worldengine.procedural-city/v1;rules-sha256=8bcf4d18e9827049e4addca1b2c43480325d904bb1cb1fbe9b09a170b4152632";
+export const PROCEDURAL_CITY_BUDGET = Object.freeze({
+    maxCitiesPerWorld: 256,
+    maxRoadsPerCity: 2_048,
+    maxParcelsPerCity: 65_536,
+    maxRoadsPerWorld: 16_384,
+    maxParcelsPerWorld: 262_144,
+    maxBuildingsPerParcel: 4,
+    maxRoomsPerBuilding: 24,
+});
+/** 城市用途颜色的唯一 authority。 */
+export const PALETTE = Object.freeze({
+    residential: Object.freeze({ label: "居住", color: "#d8b384" }),
+    commercial: Object.freeze({ label: "商业", color: "#d87878" }),
+    industrial: Object.freeze({ label: "工业", color: "#8c9299" }),
+    civic: Object.freeze({ label: "公共设施", color: "#7c8fce" }),
+    park: Object.freeze({ label: "公园", color: "#6fa66f" }),
+});
+const LAND_USES = Object.freeze([
+    "residential", "commercial", "industrial", "civic", "park",
+]);
+const WORLD_KEYS = ["profile", "identity", "worldSeed", "cities", "templates"];
+const WORLD_REQUIRED_KEYS = ["profile", "identity", "worldSeed", "cities"];
+const CITY_KEYS = ["id", "label", "x", "y", "seed", "parameters"];
+const PARAMETER_KEYS = ["radiusMeters", "blockSizeMeters", "roadWidthMeters", "landUseWeights"];
+const WEIGHT_KEYS = ["residential", "commercial", "industrial", "civic", "park"];
+const PARCEL_KEYS = ["id", "cityId", "landUse", "bounds"];
+const PARCEL_ALLOWED_KEYS = [...PARCEL_KEYS, "polygon"];
+const BUILDING_KEYS = [
+    "id", "cityId", "parcelId", "landUse", "footprint", "entrance", "floors", "heightMeters",
+];
+const BOUNDS_KEYS = ["x", "y", "width", "height"];
+const ENTRANCE_KEYS = ["x", "y", "edge"];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertRecord(value, label) {
+    if (!isRecord(value))
+        throw new TypeError(`${label} 必须是对象`);
+}
+function assertExactKeys(value, expected, label) {
+    const expectedSet = new Set(expected);
+    const unknown = Object.keys(value).filter((key) => !expectedSet.has(key));
+    if (unknown.length > 0)
+        throw new TypeError(`${label} 包含未知字段：${unknown.join(", ")}`);
+    const missing = expected.filter((key) => !Object.hasOwn(value, key));
+    if (missing.length > 0)
+        throw new TypeError(`${label} 缺少字段：${missing.join(", ")}`);
+}
+function finiteNumber(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw new TypeError(`${label} 必须是有限数`);
+    return value;
+}
+function boundedNumber(value, label, minimum, maximum) {
+    const number = finiteNumber(value, label);
+    if (number < minimum || number > maximum) {
+        throw new RangeError(`${label} 必须位于 ${minimum}..${maximum}`);
+    }
+    return number;
+}
+function uint32(value, label) {
+    const number = finiteNumber(value, label);
+    if (!Number.isInteger(number) || number < 0 || number > 0xffff_ffff) {
+        throw new RangeError(`${label} 必须是 uint32`);
+    }
+    return number;
+}
+function identifier(value, label) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value)) {
+        throw new TypeError(`${label} 必须是 1..128 字符的稳定 identifier`);
+    }
+    return value;
+}
+function labelText(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0 || value.trim().length > 128) {
+        throw new TypeError(`${label} 必须是 1..128 字符的非空文本`);
+    }
+    return value.trim();
+}
+function metric(value) {
+    return Math.round(value * 1_000_000) / 1_000_000;
+}
+function freezePoint(x, y) {
+    return Object.freeze({ x: metric(x), y: metric(y) });
+}
+function freezeBounds(x, y, width, height) {
+    return Object.freeze({ x: metric(x), y: metric(y), width: metric(width), height: metric(height) });
+}
+function parseBounds(value, label) {
+    assertRecord(value, label);
+    assertExactKeys(value, BOUNDS_KEYS, label);
+    const bounds = freezeBounds(finiteNumber(value.x, `${label}.x`), finiteNumber(value.y, `${label}.y`), finiteNumber(value.width, `${label}.width`), finiteNumber(value.height, `${label}.height`));
+    if (bounds.width <= 0 || bounds.height <= 0)
+        throw new RangeError(`${label} 尺寸必须大于 0`);
+    return bounds;
+}
+function parseParcelPolygon(value, label) {
+    if (!Array.isArray(value) || value.length < 3)
+        throw new TypeError(`${label} 必须是至少三个点的数组`);
+    const polygon = value.map((candidate, index) => {
+        assertRecord(candidate, `${label}[${index}]`);
+        assertExactKeys(candidate, ["x", "y"], `${label}[${index}]`);
+        return freezePoint(finiteNumber(candidate.x, `${label}[${index}].x`), finiteNumber(candidate.y, `${label}[${index}].y`));
+    });
+    let twiceArea = 0;
+    for (let index = 0; index < polygon.length; index += 1) {
+        const current = polygon[index];
+        const next = polygon[(index + 1) % polygon.length];
+        if (current === undefined || next === undefined)
+            continue;
+        twiceArea += current.x * next.y - next.x * current.y;
+    }
+    if (Math.abs(twiceArea) <= 0.000001)
+        throw new RangeError(`${label} 面积必须大于 0`);
+    return Object.freeze(polygon);
+}
+function hash32(parts) {
+    const input = parts.join("\u001f");
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < input.length; index += 1) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    hash ^= hash >>> 16;
+    hash = Math.imul(hash, 0x7feb352d);
+    hash ^= hash >>> 15;
+    hash = Math.imul(hash, 0x846ca68b);
+    return (hash ^ (hash >>> 16)) >>> 0;
+}
+function unit(parts) {
+    return hash32(parts) / 0x1_0000_0000;
+}
+function stableId(prefix, parts) {
+    const first = hash32(["id-a", ...parts]).toString(16).padStart(8, "0");
+    const second = hash32(["id-b", ...parts]).toString(16).padStart(8, "0");
+    return `${prefix}_${first}${second}`;
+}
+function citySeedParts(worldSeed, city) {
+    return [PROCEDURAL_GENERATOR_IDENTITY, worldSeed, city.seed, city.id];
+}
+function estimateCityBudget(city) {
+    const halfSpan = Math.floor(city.parameters.radiusMeters / city.parameters.blockSizeMeters);
+    const lineCount = halfSpan * 2 + 1;
+    return Object.freeze({ roads: lineCount * 2, parcels: (lineCount - 1) ** 2 });
+}
+function validateLandUseWeights(value, label) {
+    assertRecord(value, label);
+    assertExactKeys(value, WEIGHT_KEYS, label);
+    const weights = Object.freeze({
+        residential: boundedNumber(value.residential, `${label}.residential`, 0, 1_000_000),
+        commercial: boundedNumber(value.commercial, `${label}.commercial`, 0, 1_000_000),
+        industrial: boundedNumber(value.industrial, `${label}.industrial`, 0, 1_000_000),
+        civic: boundedNumber(value.civic, `${label}.civic`, 0, 1_000_000),
+        park: boundedNumber(value.park, `${label}.park`, 0, 1_000_000),
+    });
+    const total = LAND_USES.reduce((sum, landUse) => sum + weights[landUse], 0);
+    if (total <= 0)
+        throw new RangeError(`${label} 至少需要一个正权重`);
+    return weights;
+}
+function validateCityDescriptor(value, label) {
+    assertRecord(value, label);
+    assertExactKeys(value, CITY_KEYS, label);
+    assertRecord(value.parameters, `${label}.parameters`);
+    assertExactKeys(value.parameters, PARAMETER_KEYS, `${label}.parameters`);
+    const radiusMeters = boundedNumber(value.parameters.radiusMeters, `${label}.parameters.radiusMeters`, 32, 200_000);
+    const blockSizeMeters = boundedNumber(value.parameters.blockSizeMeters, `${label}.parameters.blockSizeMeters`, 16, 2_000);
+    const roadWidthMeters = boundedNumber(value.parameters.roadWidthMeters, `${label}.parameters.roadWidthMeters`, 3, 40);
+    if (radiusMeters < blockSizeMeters * 2) {
+        throw new RangeError(`${label}.parameters.radiusMeters 必须至少容纳两个 blockSizeMeters`);
+    }
+    if (roadWidthMeters > blockSizeMeters * 0.45 || blockSizeMeters - roadWidthMeters < 8) {
+        throw new RangeError(`${label}.parameters.roadWidthMeters 过宽，无法形成可用地块`);
+    }
+    const city = Object.freeze({
+        id: identifier(value.id, `${label}.id`),
+        label: labelText(value.label, `${label}.label`),
+        x: boundedNumber(value.x, `${label}.x`, -1_000_000_000, 1_000_000_000),
+        y: boundedNumber(value.y, `${label}.y`, -1_000_000_000, 1_000_000_000),
+        seed: uint32(value.seed, `${label}.seed`),
+        parameters: Object.freeze({
+            radiusMeters,
+            blockSizeMeters,
+            roadWidthMeters,
+            landUseWeights: validateLandUseWeights(value.parameters.landUseWeights, `${label}.parameters.landUseWeights`),
+        }),
+    });
+    const estimate = estimateCityBudget(city);
+    if (estimate.roads > PROCEDURAL_CITY_BUDGET.maxRoadsPerCity) {
+        throw new RangeError(`${label} 道路预算超限：${estimate.roads} > ${PROCEDURAL_CITY_BUDGET.maxRoadsPerCity}`);
+    }
+    if (estimate.parcels > PROCEDURAL_CITY_BUDGET.maxParcelsPerCity) {
+        throw new RangeError(`${label} 地块预算超限：${estimate.parcels} > ${PROCEDURAL_CITY_BUDGET.maxParcelsPerCity}`);
+    }
+    return city;
+}
+/** 严格验证 exact-key 世界描述；返回不可变 canonical 副本。 */
+export function validateProceduralWorld(input, extent) {
+    assertRecord(input, "ProceduralWorldV1");
+    const unknown = Object.keys(input).filter((key) => !WORLD_KEYS.includes(key));
+    const missing = WORLD_REQUIRED_KEYS.filter((key) => !Object.hasOwn(input, key));
+    if (unknown.length > 0)
+        throw new TypeError(`ProceduralWorldV1 包含未知字段：${unknown.join(", ")}`);
+    if (missing.length > 0)
+        throw new TypeError(`ProceduralWorldV1 缺少字段：${missing.join(", ")}`);
+    if (input.profile !== PROCEDURAL_WORLD_PROFILE)
+        throw new TypeError(`profile 必须为 ${PROCEDURAL_WORLD_PROFILE}`);
+    if (input.identity !== PROCEDURAL_GENERATOR_IDENTITY) {
+        throw new TypeError(`identity 必须为 ${PROCEDURAL_GENERATOR_IDENTITY}`);
+    }
+    if (!Array.isArray(input.cities))
+        throw new TypeError("cities 必须是数组");
+    if (input.cities.length > PROCEDURAL_CITY_BUDGET.maxCitiesPerWorld) {
+        throw new RangeError(`城市预算超限：${input.cities.length} > ${PROCEDURAL_CITY_BUDGET.maxCitiesPerWorld}`);
+    }
+    const cities = input.cities.map((city, index) => validateCityDescriptor(city, `cities[${index}]`));
+    const ids = new Set();
+    let roadBudget = 0;
+    let parcelBudget = 0;
+    for (const city of cities) {
+        if (ids.has(city.id))
+            throw new TypeError(`city id 重复：${city.id}`);
+        ids.add(city.id);
+        const estimate = estimateCityBudget(city);
+        roadBudget += estimate.roads;
+        parcelBudget += estimate.parcels;
+    }
+    if (roadBudget > PROCEDURAL_CITY_BUDGET.maxRoadsPerWorld) {
+        throw new RangeError(`世界道路预算超限：${roadBudget} > ${PROCEDURAL_CITY_BUDGET.maxRoadsPerWorld}`);
+    }
+    if (parcelBudget > PROCEDURAL_CITY_BUDGET.maxParcelsPerWorld) {
+        throw new RangeError(`世界地块预算超限：${parcelBudget} > ${PROCEDURAL_CITY_BUDGET.maxParcelsPerWorld}`);
+    }
+    if (extent !== undefined) {
+        const width = boundedNumber(extent.widthMeters, "extent.widthMeters", 1, 1_000_000_000);
+        const height = boundedNumber(extent.heightMeters, "extent.heightMeters", 1, 1_000_000_000);
+        for (const city of cities) {
+            const radius = city.parameters.radiusMeters;
+            if (city.x - radius < 0 || city.y - radius < 0 || city.x + radius > width || city.y + radius > height) {
+                throw new RangeError(`城市 ${city.id} 超出 world extent`);
+            }
+        }
+    }
+    const templates = Object.hasOwn(input, "templates")
+        ? validateSpatialTemplateConfiguration(input.templates)
+        : undefined;
+    return Object.freeze({
+        profile: PROCEDURAL_WORLD_PROFILE,
+        identity: PROCEDURAL_GENERATOR_IDENTITY,
+        worldSeed: uint32(input.worldSeed, "worldSeed"),
+        cities: Object.freeze(cities),
+        ...(templates === undefined ? {} : { templates }),
+    });
+}
+function weightedLandUse(seedParts, weights) {
+    const total = LAND_USES.reduce((sum, landUse) => sum + weights[landUse], 0);
+    let cursor = unit(["land-use", ...seedParts]) * total;
+    for (const landUse of LAND_USES) {
+        cursor -= weights[landUse];
+        if (cursor < 0)
+            return landUse;
+    }
+    return LAND_USES[LAND_USES.length - 1] ?? "park";
+}
+function boundsInsideCircle(bounds, city) {
+    const radiusSquared = city.parameters.radiusMeters ** 2;
+    const corners = [
+        [bounds.x, bounds.y],
+        [bounds.x + bounds.width, bounds.y],
+        [bounds.x, bounds.y + bounds.height],
+        [bounds.x + bounds.width, bounds.y + bounds.height],
+    ];
+    return corners.every(([x, y]) => (x - city.x) ** 2 + (y - city.y) ** 2 <= radiusSquared);
+}
+function assertUniqueIds(items, label) {
+    const ids = new Set();
+    for (const item of items) {
+        if (ids.has(item.id))
+            throw new Error(`${label} 产生重复 id：${item.id}`);
+        ids.add(item.id);
+    }
+}
+/** 只生成可重建的道路与地块 cache；绝不提前生成建筑。 */
+export function generateCityLayout(worldSeedInput, cityInput, options = {}) {
+    const worldSeed = uint32(worldSeedInput, "worldSeed");
+    const city = validateCityDescriptor(cityInput, "city");
+    const parcelTemplate = options.templates === undefined
+        ? undefined
+        : validateSpatialTemplateConfiguration(options.templates).parcel?.parameters;
+    const { radiusMeters: radius, blockSizeMeters: block, roadWidthMeters: roadWidth } = city.parameters;
+    const halfSpan = Math.floor(radius / block);
+    const offsets = Array.from({ length: halfSpan * 2 + 1 }, (_, index) => (index - halfSpan) * block);
+    const seeds = citySeedParts(worldSeed, city);
+    const roads = [];
+    for (let index = -halfSpan; index <= halfSpan; index += 1) {
+        const offset = index * block;
+        const chord = Math.sqrt(Math.max(0, radius ** 2 - offset ** 2));
+        if (chord <= roadWidth / 2)
+            continue;
+        roads.push(Object.freeze({
+            id: stableId("road", [...seeds, "vertical", index]),
+            points: Object.freeze([
+                freezePoint(city.x + offset, city.y - chord),
+                freezePoint(city.x + offset, city.y + chord),
+            ]),
+            widthMeters: roadWidth,
+        }));
+        roads.push(Object.freeze({
+            id: stableId("road", [...seeds, "horizontal", index]),
+            points: Object.freeze([
+                freezePoint(city.x - chord, city.y + offset),
+                freezePoint(city.x + chord, city.y + offset),
+            ]),
+            widthMeters: roadWidth,
+        }));
+    }
+    if (roads.length > PROCEDURAL_CITY_BUDGET.maxRoadsPerCity)
+        throw new RangeError("道路预算超限");
+    const parcels = [];
+    const roadHalfWidth = roadWidth / 2;
+    for (let yIndex = 0; yIndex < offsets.length - 1; yIndex += 1) {
+        for (let xIndex = 0; xIndex < offsets.length - 1; xIndex += 1) {
+            const left = offsets[xIndex];
+            const top = offsets[yIndex];
+            if (left === undefined || top === undefined)
+                continue;
+            const latticeX = xIndex - halfSpan;
+            const latticeY = yIndex - halfSpan;
+            const bounds = freezeBounds(city.x + left + roadHalfWidth, city.y + top + roadHalfWidth, block - roadWidth, block - roadWidth);
+            if (!boundsInsideCircle(bounds, city))
+                continue;
+            const sample = Object.freeze({ cityId: city.id, latticeX, latticeY, bounds });
+            if (options.buildabilitySampler !== undefined) {
+                const buildable = options.buildabilitySampler(sample);
+                if (typeof buildable !== "boolean")
+                    throw new TypeError("buildabilitySampler 必须返回 boolean");
+                if (!buildable)
+                    continue;
+            }
+            const subdivision = parcelTemplate?.subdivision ?? 1;
+            if (parcelTemplate === undefined) {
+                parcels.push(Object.freeze({
+                    id: stableId("parcel", [...seeds, latticeX, latticeY]),
+                    cityId: city.id,
+                    landUse: weightedLandUse([...seeds, latticeX, latticeY], city.parameters.landUseWeights),
+                    bounds,
+                }));
+                continue;
+            }
+            for (let splitY = 0; splitY < subdivision; splitY += 1) {
+                for (let splitX = 0; splitX < subdivision; splitX += 1) {
+                    const childBounds = subdivision === 1 ? bounds : freezeBounds(bounds.x + bounds.width * splitX / subdivision, bounds.y + bounds.height * splitY / subdivision, bounds.width / subdivision, bounds.height / subdivision);
+                    parcels.push(Object.freeze({
+                        id: stableId("parcel", [...seeds, latticeX, latticeY, "template-subdivision", subdivision, splitX, splitY]),
+                        cityId: city.id,
+                        landUse: weightedLandUse([...seeds, latticeX, latticeY, splitX, splitY], city.parameters.landUseWeights),
+                        bounds: childBounds,
+                    }));
+                }
+            }
+        }
+    }
+    if (parcels.length === 0)
+        throw new RangeError(`城市 ${city.id} 没有可建地块`);
+    if (parcels.length > PROCEDURAL_CITY_BUDGET.maxParcelsPerCity)
+        throw new RangeError("地块预算超限");
+    assertUniqueIds(roads, "道路");
+    assertUniqueIds(parcels, "地块");
+    return Object.freeze({ roads: Object.freeze(roads), parcels: Object.freeze(parcels) });
+}
+function validateParcel(value, city) {
+    assertRecord(value, "parcel");
+    const unknown = Object.keys(value).filter((key) => !PARCEL_ALLOWED_KEYS.includes(key));
+    if (unknown.length > 0)
+        throw new TypeError(`parcel 包含未知字段：${unknown.join(", ")}`);
+    const missing = PARCEL_KEYS.filter((key) => !Object.hasOwn(value, key));
+    if (missing.length > 0)
+        throw new TypeError(`parcel 缺少字段：${missing.join(", ")}`);
+    if (!LAND_USES.includes(value.landUse))
+        throw new TypeError("parcel.landUse 非法");
+    const polygon = Object.hasOwn(value, "polygon") ? parseParcelPolygon(value.polygon, "parcel.polygon") : undefined;
+    const parcel = Object.freeze({
+        id: identifier(value.id, "parcel.id"),
+        cityId: identifier(value.cityId, "parcel.cityId"),
+        landUse: value.landUse,
+        bounds: parseBounds(value.bounds, "parcel.bounds"),
+        ...(polygon === undefined ? {} : { polygon }),
+    });
+    if (parcel.cityId !== city.id)
+        throw new TypeError("parcel.cityId 与 city.id 不匹配");
+    if (!boundsInsideCircle(parcel.bounds, city))
+        throw new RangeError("parcel.bounds 超出城市半径");
+    return parcel;
+}
+const BUILDING_PROFILES = Object.freeze({
+    residential: Object.freeze({ maxBuildings: 4, minimumFloors: 2, maximumFloors: 12, floorHeight: 3, fill: 0.78 }),
+    commercial: Object.freeze({ maxBuildings: 2, minimumFloors: 3, maximumFloors: 30, floorHeight: 3.6, fill: 0.88 }),
+    industrial: Object.freeze({ maxBuildings: 2, minimumFloors: 1, maximumFloors: 4, floorHeight: 4.8, fill: 0.86 }),
+    civic: Object.freeze({ maxBuildings: 2, minimumFloors: 2, maximumFloors: 8, floorHeight: 3.8, fill: 0.74 }),
+});
+/** 按地块进入 gate 调用；park 固定为空，其余用途生成 1-N 个稳定 footprint。 */
+export function generateParcelBuildings(worldSeedInput, cityInput, parcelInput, options = {}) {
+    const worldSeed = uint32(worldSeedInput, "worldSeed");
+    const city = validateCityDescriptor(cityInput, "city");
+    const parcel = validateParcel(parcelInput, city);
+    if (parcel.landUse === "park")
+        return Object.freeze([]);
+    const profile = BUILDING_PROFILES[parcel.landUse];
+    const template = options.templates === undefined
+        ? undefined
+        : validateSpatialTemplateConfiguration(options.templates).building?.parameters;
+    const seeds = [...citySeedParts(worldSeed, city), parcel.id];
+    let count = template === undefined
+        ? 1 + Math.floor(unit(["building-count", ...seeds]) * profile.maxBuildings)
+        : Math.min(profile.maxBuildings, template.maxBuildings);
+    const outerMargin = Math.max(2, Math.min(parcel.bounds.width, parcel.bounds.height) * 0.08);
+    const gap = Math.max(1.5, Math.min(parcel.bounds.width, parcel.bounds.height) * 0.035);
+    while (count > 1) {
+        const columns = Math.ceil(Math.sqrt(count));
+        const rows = Math.ceil(count / columns);
+        const cellWidth = (parcel.bounds.width - outerMargin * 2 - gap * (columns - 1)) / columns;
+        const cellHeight = (parcel.bounds.height - outerMargin * 2 - gap * (rows - 1)) / rows;
+        const fill = profile.fill * (template?.fillScale ?? 1);
+        if (cellWidth * fill >= 4 && cellHeight * fill >= 4)
+            break;
+        count -= 1;
+    }
+    const columns = Math.ceil(Math.sqrt(count));
+    const rows = Math.ceil(count / columns);
+    const cellWidth = (parcel.bounds.width - outerMargin * 2 - gap * (columns - 1)) / columns;
+    const cellHeight = (parcel.bounds.height - outerMargin * 2 - gap * (rows - 1)) / rows;
+    const fill = profile.fill * (template?.fillScale ?? 1);
+    if (cellWidth * fill < 4 || cellHeight * fill < 4) {
+        throw new RangeError(`地块 ${parcel.id} 太小，无法生成有效建筑`);
+    }
+    const buildings = [];
+    for (let index = 0; index < count; index += 1) {
+        const column = index % columns;
+        const row = Math.floor(index / columns);
+        const width = cellWidth * fill;
+        const height = cellHeight * fill;
+        const x = parcel.bounds.x + outerMargin + column * (cellWidth + gap) + (cellWidth - width) / 2;
+        const y = parcel.bounds.y + outerMargin + row * (cellHeight + gap) + (cellHeight - height) / 2;
+        const floorRange = profile.maximumFloors - profile.minimumFloors + 1;
+        const floors = profile.minimumFloors + Math.floor(unit(["floors", ...seeds, index]) * floorRange);
+        const edge = unit(["entrance-edge", ...seeds, index]) < 0.5 ? "west" : "east";
+        const footprint = freezeBounds(x, y, width, height);
+        const entrance = Object.freeze({
+            x: edge === "west" ? footprint.x : metric(footprint.x + footprint.width),
+            y: metric(footprint.y + footprint.height / 2),
+            edge,
+        });
+        buildings.push(Object.freeze({
+            id: stableId("building", [...seeds, index]),
+            cityId: city.id,
+            parcelId: parcel.id,
+            landUse: parcel.landUse,
+            footprint,
+            entrance,
+            floors,
+            heightMeters: metric(floors * profile.floorHeight),
+        }));
+    }
+    if (buildings.length > PROCEDURAL_CITY_BUDGET.maxBuildingsPerParcel)
+        throw new RangeError("建筑预算超限");
+    assertUniqueIds(buildings, "建筑");
+    return Object.freeze(buildings);
+}
+function validateBuilding(value) {
+    assertRecord(value, "building");
+    assertExactKeys(value, BUILDING_KEYS, "building");
+    if (value.landUse === "park" || !LAND_USES.includes(value.landUse)) {
+        throw new TypeError("building.landUse 非法");
+    }
+    const footprint = parseBounds(value.footprint, "building.footprint");
+    assertRecord(value.entrance, "building.entrance");
+    assertExactKeys(value.entrance, ENTRANCE_KEYS, "building.entrance");
+    const edge = value.entrance.edge;
+    if (edge !== "west" && edge !== "east")
+        throw new TypeError("building.entrance.edge 非法");
+    const entrance = Object.freeze({
+        x: finiteNumber(value.entrance.x, "building.entrance.x"),
+        y: finiteNumber(value.entrance.y, "building.entrance.y"),
+        edge,
+    });
+    const expectedX = edge === "west" ? footprint.x : footprint.x + footprint.width;
+    if (Math.abs(entrance.x - expectedX) > 0.000001
+        || entrance.y < footprint.y || entrance.y > footprint.y + footprint.height) {
+        throw new RangeError("building.entrance 必须位于 footprint 的东西外墙");
+    }
+    const floors = finiteNumber(value.floors, "building.floors");
+    if (!Number.isSafeInteger(floors) || floors < 1 || floors > 256)
+        throw new RangeError("building.floors 非法");
+    const heightMeters = boundedNumber(value.heightMeters, "building.heightMeters", 2, 2_000);
+    return Object.freeze({
+        id: identifier(value.id, "building.id"),
+        cityId: identifier(value.cityId, "building.cityId"),
+        parcelId: identifier(value.parcelId, "building.parcelId"),
+        landUse: value.landUse,
+        footprint,
+        entrance,
+        floors,
+        heightMeters,
+    });
+}
+const ROOM_KINDS = Object.freeze({
+    residential: Object.freeze(["living", "kitchen", "bedroom", "bedroom", "bathroom"]),
+    commercial: Object.freeze(["lobby", "retail", "office", "office", "storage"]),
+    industrial: Object.freeze(["workshop", "storage", "utility", "office"]),
+    civic: Object.freeze(["lobby", "hall", "office", "service"]),
+});
+function rectangleInside(inner, outer) {
+    const epsilon = 0.000001;
+    return inner.x + epsilon >= outer.x && inner.y + epsilon >= outer.y
+        && inner.x + inner.width <= outer.x + outer.width + epsilon
+        && inner.y + inner.height <= outer.y + outer.height + epsilon;
+}
+/** 按建筑进入 gate 调用；返回有界且通过中央走廊全连通的房间/门 cache。 */
+export function generateBuildingInterior(worldSeedInput, buildingInput, options = {}) {
+    const worldSeed = uint32(worldSeedInput, "worldSeed");
+    const building = validateBuilding(buildingInput);
+    const footprint = building.footprint;
+    const template = options.templates === undefined
+        ? undefined
+        : validateSpatialTemplateConfiguration(options.templates).interior?.parameters;
+    if (footprint.width < 4 || footprint.height < 4)
+        throw new RangeError("building footprint 太小，无法生成连通室内");
+    const seedParts = [PROCEDURAL_GENERATOR_IDENTITY, worldSeed, building.id];
+    const corridorRatio = template?.corridorRatio ?? 0.18;
+    const corridorHeight = metric(Math.min(2.4, Math.max(1.2, footprint.height * corridorRatio)));
+    const corridorBounds = freezeBounds(footprint.x, footprint.y + (footprint.height - corridorHeight) / 2, footprint.width, corridorHeight);
+    const corridorId = stableId("room", [...seedParts, "corridor"]);
+    const rooms = [Object.freeze({ id: corridorId, kind: "corridor", bounds: corridorBounds })];
+    const maximumPerSide = Math.max(1, Math.floor(footprint.width / 3));
+    const maximumRooms = Math.min(PROCEDURAL_CITY_BUDGET.maxRoomsPerBuilding - 1, maximumPerSide * 2);
+    const areaTarget = Math.max(2, Math.floor((footprint.width * footprint.height) / (28 / (template?.roomDensity ?? 1))));
+    const desiredRooms = Math.min(maximumRooms, areaTarget + Math.floor(unit(["room-count", ...seedParts]) * 3));
+    const roomCount = Math.max(2, desiredRooms);
+    const topCount = Math.ceil(roomCount / 2);
+    const bottomCount = Math.floor(roomCount / 2);
+    const roomKinds = ROOM_KINDS[building.landUse];
+    const kindOffset = Math.floor(unit(["room-kind-offset", ...seedParts]) * roomKinds.length);
+    const doors = [];
+    let roomOrdinal = 0;
+    for (const side of ["north", "south"]) {
+        const sideCount = side === "north" ? topCount : bottomCount;
+        for (let index = 0; index < sideCount; index += 1) {
+            const x = footprint.x + footprint.width * index / sideCount;
+            const nextX = footprint.x + footprint.width * (index + 1) / sideCount;
+            const y = side === "north" ? footprint.y : corridorBounds.y + corridorBounds.height;
+            const height = side === "north"
+                ? corridorBounds.y - footprint.y
+                : footprint.y + footprint.height - (corridorBounds.y + corridorBounds.height);
+            const bounds = freezeBounds(x, y, nextX - x, height);
+            const roomId = stableId("room", [...seedParts, side, index]);
+            const kind = roomKinds[(kindOffset + roomOrdinal) % roomKinds.length] ?? roomKinds[0] ?? "service";
+            rooms.push(Object.freeze({ id: roomId, kind, bounds }));
+            const doorY = side === "north" ? corridorBounds.y : corridorBounds.y + corridorBounds.height;
+            doors.push(Object.freeze({
+                id: stableId("door", [...seedParts, side, index]),
+                kind: "interior",
+                position: freezePoint(bounds.x + bounds.width / 2, doorY),
+                connects: Object.freeze([roomId, corridorId]),
+            }));
+            roomOrdinal += 1;
+        }
+    }
+    doors.push(Object.freeze({
+        id: stableId("door", [...seedParts, "entrance"]),
+        kind: "entrance",
+        position: freezePoint(building.entrance.x, building.entrance.y),
+        connects: Object.freeze([corridorId]),
+    }));
+    if (rooms.length > PROCEDURAL_CITY_BUDGET.maxRoomsPerBuilding)
+        throw new RangeError("房间预算超限");
+    if (rooms.some((room) => !rectangleInside(room.bounds, footprint)))
+        throw new Error("室内房间越出建筑 footprint");
+    assertUniqueIds(rooms, "房间");
+    assertUniqueIds(doors, "门");
+    const connected = new Set([corridorId]);
+    for (const door of doors)
+        for (const roomId of door.connects)
+            connected.add(roomId);
+    if (rooms.some((room) => !connected.has(room.id)))
+        throw new Error("室内房间图不连通");
+    return Object.freeze({ buildingId: building.id, rooms: Object.freeze(rooms), doors: Object.freeze(doors) });
+}

package/dist/protobuf-source-codec.d.ts

@@ -0,0 +1,57 @@
+import { type PlaneGenerationV1 } from "./plane-generation.js";
+import { type ProceduralWorldV1 } from "./procedural-city.js";
+import { type RoadGenerationV1 } from "./road-generation.js";
+import type { SpatialObjectKind } from "./schema.js";
+import { type SpatialTemplateConfigurationV1, type SpatialTemplateLibraryV1 } from "./spatial-templates.js";
+/**
+ * `world_search.spatial_world` 的无损作者侧投影。
+ *
+ * 这是唯一给 Web/desktop 地图编辑器的 seam：调用者只修改已建模字段，再由
+ * encode 恢复原有 protobuf 顺序、未知 field 和未修改 object 的原始 bytes。
+ * 它不解释也不暴露 ScenarioPart 的其余字段。
+ */
+export type SpatialReferenceProtobufV1 = {
+    ownerId: string;
+    ownerKind: "ladybug" | "trigger" | "scenario";
+    fieldPath: string;
+};
+export type SpatialObjectProtobufV1 = {
+    id: string;
+    key: string;
+    kind: SpatialObjectKind;
+    label: string;
+    x: number;
+    y: number;
+    references: SpatialReferenceProtobufV1[];
+    /** 私有 round-trip witness；编辑器不得删除或重写。 */
+    _wireField?: number;
+    _wireBase64?: string;
+    _wireSignature?: string;
+    _authorSettings?: Record<string, unknown>;
+};
+export type SpatialTopologyProtobufV1 = {
+    kind: "grid" | "freeform";
+    width: number;
+    height: number;
+    cellSize?: number;
+    generation?: PlaneGenerationV1;
+    roadGeneration?: RoadGenerationV1;
+    procedural?: ProceduralWorldV1;
+    controlledActorId?: string | null;
+    templateLibrary?: SpatialTemplateLibraryV1;
+    templates?: SpatialTemplateConfigurationV1;
+    [key: string]: unknown;
+};
+export type SpatialWorldProtobufV1 = {
+    schemaVersion: 1;
+    worldId: string;
+    spatialRevision: number;
+    topology: SpatialTopologyProtobufV1;
+    objects: SpatialObjectProtobufV1[];
+    /** 私有 round-trip witness；编辑器不得删除或重写。 */
+    _wireBase64?: string;
+    _topologyWireBase64?: string;
+    _topologyWireKind?: number;
+};
+export declare function decodeSpatialWorldProtobuf(bytes: Uint8Array | undefined): SpatialWorldProtobufV1 | undefined;
+export declare function encodeSpatialWorldProtobuf(world: SpatialWorldProtobufV1 | undefined): Uint8Array | undefined;