@hypersoniclabs/helix-cli 0.1.6 → 0.1.23

package/dist/cs2/lods.js

@@ -0,0 +1,136 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CSM2_BUILDING_LOD_TARGETS = void 0;
+exports.generateCsm2Lods = generateCsm2Lods;
+exports.CSM2_BUILDING_LOD_TARGETS = [
+    { ratio: 0.5, relativeError: 0.001, maxErrorM: 0.02 },
+    { ratio: 0.2, relativeError: 0.005, maxErrorM: 0.1 },
+];
+/** Generate complete assemblies; mesh/submesh IDs remain material identities, never inferred detail levels.
+ * LOD0 and vertex attributes are borrowed unchanged. Lower levels own their index/group arrays.
+ * Error is meshoptimizer's approximate combined geometry/attribute metric, not a certified surface distance.
+ */
+async function generateCsm2Lods(mesh, targets = exports.CSM2_BUILDING_LOD_TARGETS) {
+    const vertices = mesh.positions.length / 3;
+    if (!Number.isInteger(vertices) || !vertices || mesh.normals.length !== vertices * 3 || mesh.uvs.length !== vertices * 2) {
+        throw new Error('generateCsm2Lods: vertex attributes are not aligned');
+    }
+    for (const array of [mesh.positions, mesh.normals, mesh.uvs]) {
+        for (const value of array)
+            if (!Number.isFinite(value))
+                throw new Error('generateCsm2Lods: nonfinite vertex attribute');
+    }
+    for (const index of mesh.indices)
+        if (index >= vertices)
+            throw new Error('generateCsm2Lods: index outside vertex buffer');
+    let end = 0;
+    const seen = new Set();
+    for (const group of mesh.groups) {
+        const key = `${group.meshIndex}:${group.subMeshIndex}`;
+        if (seen.has(key) || group.indexStart !== end || group.indexCount <= 0 || group.indexCount % 3) {
+            throw new Error('generateCsm2Lods: invalid material groups');
+        }
+        seen.add(key);
+        end += group.indexCount;
+    }
+    if (!end || end !== mesh.indices.length)
+        throw new Error('generateCsm2Lods: groups do not cover indices');
+    let previousRatio = 1;
+    for (const target of targets) {
+        if (!Number.isFinite(target.ratio) || target.ratio <= 0 || target.ratio >= previousRatio
+            || !Number.isFinite(target.relativeError) || target.relativeError <= 0
+            || !Number.isFinite(target.maxErrorM) || target.maxErrorM <= 0)
+            throw new Error('generateCsm2Lods: invalid LOD target');
+        previousRatio = target.ratio;
+    }
+    const { MeshoptSimplifier } = await Promise.resolve().then(() => __importStar(require('meshoptimizer')));
+    await MeshoptSimplifier.ready;
+    // The installed 0.22 attribute API is experimental. Enable it on a private wrapper, without changing other consumers.
+    const simplifier = { ...MeshoptSimplifier, useExperimentalFeatures: true };
+    const levels = [{ mesh, target: null,
+            groups: mesh.groups.map(g => ({ sourceTriangles: g.indexCount / 3, triangles: g.indexCount / 3, error: 0, errorLimit: 0 })) }];
+    const prepared = mesh.groups.map(group => {
+        const indices = Uint32Array.from(mesh.indices.subarray(group.indexStart, group.indexStart + group.indexCount));
+        const [remap, count] = simplifier.compactMesh(indices);
+        const source = new Uint32Array(count);
+        const positions = new Float32Array(count * 3), attributes = new Float32Array(count * 5);
+        for (let original = 0; original < remap.length; original++) {
+            const local = remap[original];
+            if (local >= count)
+                continue;
+            source[local] = original;
+            positions.set(mesh.positions.subarray(original * 3, original * 3 + 3), local * 3);
+            attributes.set(mesh.normals.subarray(original * 3, original * 3 + 3), local * 5);
+            attributes.set(mesh.uvs.subarray(original * 2, original * 2 + 2), local * 5 + 3);
+        }
+        const locks = new Uint8Array(count);
+        for (let axis = 0; axis < 3; axis++) {
+            let low = 0, high = 0;
+            for (let i = 1; i < count; i++) {
+                if (positions[i * 3 + axis] < positions[low * 3 + axis])
+                    low = i;
+                if (positions[i * 3 + axis] > positions[high * 3 + axis])
+                    high = i;
+            }
+            locks[low] = locks[high] = 1;
+        }
+        return { indices, source, positions, attributes, locks, scale: simplifier.getScale(positions, 3) };
+    });
+    for (const target of targets) {
+        const buffers = [];
+        const groups = [];
+        const reports = [];
+        let cursor = 0;
+        for (let i = 0; i < mesh.groups.length; i++) {
+            const group = mesh.groups[i], data = prepared[i];
+            const limit = Math.min(target.relativeError, target.maxErrorM / Math.max(data.scale, 1e-9));
+            // Tiny accessories are already cheap. Keep them exact instead of deleting an entire window/water/material surface.
+            const [indices, error] = group.indexCount <= 96 * 3 ? [data.indices, 0] : simplifier.simplifyWithAttributes(data.indices, data.positions, 3, data.attributes, 5, [1, 1, 1, 1, 1], data.locks, Math.max(3, Math.floor(group.indexCount / 3 * target.ratio) * 3), limit, ['LockBorder']);
+            if (!indices.length || !Number.isFinite(error) || error > limit * 1.001)
+                throw new Error('generateCsm2Lods: invalid simplifier result');
+            const originalIndices = indices.map(index => data.source[index]);
+            buffers.push(originalIndices);
+            groups.push({ ...group, indexStart: cursor, indexCount: indices.length });
+            reports.push({ sourceTriangles: group.indexCount / 3, triangles: indices.length / 3, error, errorLimit: limit });
+            cursor += indices.length;
+        }
+        const indices = new Uint32Array(cursor);
+        buffers.forEach((buffer, i) => indices.set(buffer, groups[i].indexStart));
+        levels.push({ mesh: { ...mesh, indices, groups }, target: { ...target }, groups: reports });
+    }
+    return levels;
+}
+//# sourceMappingURL=lods.js.map

package/dist/cs2/lods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lods.js","sourceRoot":"","sources":["../../src/cs2/lods.ts"],"names":[],"mappings":"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"}

package/dist/cs2/materials.d.ts

@@ -0,0 +1,43 @@
+import { type Cs2MaterialBundleManifest, type Cs2MaterialEntry, type Cs2MaterialRecord, type Cs2TextureRecord } from './types';
+/** Share of opaque pixels that are fully on or fully off, and share with a wide channel spread. */
+export declare const IDENTITY_MAP_PURITY = 0.85;
+export declare const IDENTITY_MAP_CHROMA = 0.25;
+export type Cs2TextureRole = 'baseColor' | 'normal' | 'emissive' | 'mask';
+export interface Cs2MaterialBundle {
+    manifest: Cs2MaterialBundleManifest;
+    /** The folder the manifest sits in; `textures[].file` is relative to it. */
+    dir: string;
+    entriesByPrefab: Map<string, Cs2MaterialEntry>;
+    materialsById: Map<string, Cs2MaterialRecord>;
+    texturesById: Map<string, Cs2TextureRecord>;
+    /** prefab -> "meshIndex:subMeshIndex" -> materialId. The key is a CSM2 group. */
+    bindings: Map<string, Map<string, string>>;
+}
+export interface Cs2SelectedTexture {
+    parameter: string;
+    texture: Cs2TextureRecord;
+    score: number;
+}
+/** Reads one `prefab-materials.json` / `road-materials.json`; both carry the same schema. */
+export declare function readCs2MaterialBundle(file: string): Promise<Cs2MaterialBundle>;
+export declare function bindingKey(meshIndex: number, subMeshIndex: number): string;
+export declare function materialForGroup(bundle: Cs2MaterialBundle, prefab: string, meshIndex: number, subMeshIndex: number): Cs2MaterialRecord | null;
+/**
+ * Caches key on content, never on `materialId`: 6,572 Granit records collapse to 1,569 by (shader, texture files,
+ * properties). Texture ids differ between records that reference the same bytes, so the FILE is what identifies them.
+ */
+export declare function contentKey(bundle: Cs2MaterialBundle, material: Cs2MaterialRecord): string;
+/**
+ * Role scoring from the reference library (`prefab-material-library.ts:1013-1057`). CS2 binds both an HDRP packed mask
+ * and a colour-variation control mask as `data` textures, so `_MaskMap` must beat `_ControlMask`.
+ */
+export declare function textureRoleScore(parameter: string, semantic: string, role: Cs2TextureRole): number;
+export declare function resolveTextureRoles(bundle: Cs2MaterialBundle, material: Cs2MaterialRecord): Partial<Record<Cs2TextureRole, Cs2SelectedTexture>>;
+/** A colour map whose pixels are effectively an index palette rather than a photograph. */
+export declare function isIdentityMap(texture: Cs2TextureRecord): boolean;
+/** `textures[].bytes` is the PRE-TRANSCODE PNG size and sums to 2.95 GB against 1.2 GB on disk; measure the file. */
+export declare function textureFileBytes(bundle: Cs2MaterialBundle, texture: Cs2TextureRecord): Promise<number>;
+/** Distinct `textures[].file` values: the content-addressed set, which is smaller than the record count. */
+export declare function distinctTextureFiles(bundle: Cs2MaterialBundle): Set<string>;
+/** Projector and decal prefabs are identified by SHADER, never by name. */
+export declare function isDecalShader(shader: string): boolean;

package/dist/cs2/materials.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDENTITY_MAP_CHROMA = exports.IDENTITY_MAP_PURITY = void 0;
+exports.readCs2MaterialBundle = readCs2MaterialBundle;
+exports.bindingKey = bindingKey;
+exports.materialForGroup = materialForGroup;
+exports.contentKey = contentKey;
+exports.textureRoleScore = textureRoleScore;
+exports.resolveTextureRoles = resolveTextureRoles;
+exports.isIdentityMap = isIdentityMap;
+exports.textureFileBytes = textureFileBytes;
+exports.distinctTextureFiles = distinctTextureFiles;
+exports.isDecalShader = isDecalShader;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const binary_1 = require("./binary");
+const types_1 = require("./types");
+/** Share of opaque pixels that are fully on or fully off, and share with a wide channel spread. */
+exports.IDENTITY_MAP_PURITY = 0.85;
+exports.IDENTITY_MAP_CHROMA = 0.25;
+/** Reads one `prefab-materials.json` / `road-materials.json`; both carry the same schema. */
+async function readCs2MaterialBundle(file) {
+    const manifest = await (0, binary_1.readJsonFile)(file, 'readCs2MaterialBundle');
+    (0, binary_1.assertSchema)(manifest.schema, types_1.CS2_MATERIAL_BUNDLE_SCHEMA, `readCs2MaterialBundle: ${file}`);
+    const bindings = new Map();
+    for (const entry of manifest.entries) {
+        const byGroup = new Map();
+        for (const binding of entry.bindings)
+            byGroup.set(bindingKey(binding.meshIndex, binding.subMeshIndex), binding.materialId);
+        bindings.set(entry.prefab, byGroup);
+    }
+    return {
+        manifest,
+        dir: (0, node_path_1.dirname)(file),
+        entriesByPrefab: new Map(manifest.entries.map((entry) => [entry.prefab, entry])),
+        materialsById: new Map(manifest.materials.map((material) => [material.id, material])),
+        texturesById: new Map(manifest.textures.map((texture) => [texture.id, texture])),
+        bindings,
+    };
+}
+function bindingKey(meshIndex, subMeshIndex) {
+    return `${meshIndex}:${subMeshIndex}`;
+}
+function materialForGroup(bundle, prefab, meshIndex, subMeshIndex) {
+    const materialId = bundle.bindings.get(prefab)?.get(bindingKey(meshIndex, subMeshIndex));
+    return materialId ? bundle.materialsById.get(materialId) ?? null : null;
+}
+/**
+ * Caches key on content, never on `materialId`: 6,572 Granit records collapse to 1,569 by (shader, texture files,
+ * properties). Texture ids differ between records that reference the same bytes, so the FILE is what identifies them.
+ */
+function contentKey(bundle, material) {
+    const textures = Object.entries(material.textures ?? {})
+        .map(([parameter, id]) => `${parameter}=${bundle.texturesById.get(id)?.file ?? id}`)
+        .sort();
+    return JSON.stringify([material.shader, textures, canonicalProperties(material.properties)]);
+}
+/**
+ * Role scoring from the reference library (`prefab-material-library.ts:1013-1057`). CS2 binds both an HDRP packed mask
+ * and a colour-variation control mask as `data` textures, so `_MaskMap` must beat `_ControlMask`.
+ */
+function textureRoleScore(parameter, semantic, role) {
+    const name = parameter.toLowerCase();
+    if (role === 'normal') {
+        if (name.includes('normal'))
+            return 100;
+        return semantic === 'normal' ? 40 : 0;
+    }
+    if (role === 'emissive') {
+        if (/emiss|emission/.test(name))
+            return 100;
+        return semantic === 'emissive' ? 40 : 0;
+    }
+    if (role === 'mask') {
+        if (/maskmap/.test(name))
+            return 120;
+        if (/control/.test(name))
+            return 60;
+        if (/mask/.test(name))
+            return 110;
+        if (/rough|smooth|metal|occlusion/.test(name))
+            return 100;
+        return semantic === 'data' ? 30 : 0;
+    }
+    if (/base.?color/.test(name))
+        return 110;
+    if (/albedo/.test(name))
+        return 100;
+    if (/diffuse/.test(name))
+        return 90;
+    if (/^_?base(?:map|tex|texture)?$/.test(name))
+        return 80;
+    if (semantic === 'color' && !/interior|emiss|decal|detail|opacity|alpha|tint|weather|dirt/.test(name))
+        return 20;
+    return 0;
+}
+function resolveTextureRoles(bundle, material) {
+    const candidates = Object.entries(material.textures ?? {})
+        .map(([parameter, id]) => ({ parameter, texture: bundle.texturesById.get(id) }))
+        .filter((candidate) => Boolean(candidate.texture));
+    const best = (role) => candidates
+        .map((candidate) => ({ ...candidate, score: textureRoleScore(candidate.parameter, candidate.texture.semantic, role) }))
+        .filter((candidate) => candidate.score > 0)
+        .sort((left, right) => right.score - left.score || left.parameter.localeCompare(right.parameter) || left.texture.id.localeCompare(right.texture.id))[0];
+    return { baseColor: best('baseColor'), normal: best('normal'), emissive: best('emissive'), mask: best('mask') };
+}
+/** A colour map whose pixels are effectively an index palette rather than a photograph. */
+function isIdentityMap(texture) {
+    return texture.semantic === 'color'
+        && typeof texture.pixelPurity === 'number' && texture.pixelPurity >= exports.IDENTITY_MAP_PURITY
+        && typeof texture.pixelChroma === 'number' && texture.pixelChroma >= exports.IDENTITY_MAP_CHROMA;
+}
+/** `textures[].bytes` is the PRE-TRANSCODE PNG size and sums to 2.95 GB against 1.2 GB on disk; measure the file. */
+async function textureFileBytes(bundle, texture) {
+    return (await (0, promises_1.stat)((0, node_path_1.join)(bundle.dir, texture.file))).size;
+}
+/** Distinct `textures[].file` values: the content-addressed set, which is smaller than the record count. */
+function distinctTextureFiles(bundle) {
+    return new Set(bundle.manifest.textures.map((texture) => texture.file));
+}
+/** Projector and decal prefabs are identified by SHADER, never by name. */
+function isDecalShader(shader) {
+    return /Decals?\/|DecalShader/i.test(shader);
+}
+function canonicalProperties(properties) {
+    return canonical(properties ?? {});
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+        return Object.fromEntries(entries.map(([key, item]) => [key, canonical(item)]));
+    }
+    return value;
+}
+//# sourceMappingURL=materials.js.map

package/dist/cs2/materials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"materials.js","sourceRoot":"","sources":["../../src/cs2/materials.ts"],"names":[],"mappings":"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"}

package/dist/cs2/placements.d.ts

@@ -0,0 +1,57 @@
+import { type Cs2PlacementCollectionName, type Cs2PlacementTileRun, type Cs2PlacementsManifest } from './types';
+export declare const PLACEMENT_TRANSFORM_STRIDE = 7;
+export declare const PLACEMENT_RECORD_STRIDE = 4;
+export declare const PLACEMENT_LOT_SIZE_STRIDE = 2;
+export interface Cs2PlacementCollection {
+    name: Cs2PlacementCollectionName;
+    count: number;
+    /** Stride 7: x, y, z, qx, qy, qz, qw. Already mirrored, conjugated and normalised. */
+    transforms: Float32Array;
+    /** Stride 4: prefabIndex, entityId, rootOwnerEntityId, chainDepth. The owner pair is written for attachedObjects only. */
+    records: Uint32Array;
+    /** Stride 2: x, z in metres. Buildings only. */
+    lotSizes: Float32Array | null;
+    tiles: Cs2PlacementTileRun[];
+    tilesById: Map<string, Cs2PlacementTileRun>;
+}
+export interface Cs2Placements {
+    manifest: Cs2PlacementsManifest;
+    prefabNames: string[];
+    collections: Record<Cs2PlacementCollectionName, Cs2PlacementCollection>;
+}
+export interface Cs2Placement {
+    index: number;
+    tileId: string;
+    prefabIndex: number;
+    prefabName: string;
+    entityId: number;
+    rootOwnerEntityId: number;
+    chainDepth: number;
+    position: [number, number, number];
+    quaternion: [number, number, number, number];
+    /** Buildings only; metres. */
+    lotSize: [number, number] | null;
+}
+export interface Cs2TileBounds {
+    tileX: number;
+    tileZ: number;
+    minX: number;
+    maxX: number;
+    minZ: number;
+    maxZ: number;
+}
+/** Reads `placements/` in full: the manifest plus the three collections' bins as typed arrays, no per-record objects. */
+export declare function readCs2Placements(root: string): Promise<Cs2Placements>;
+/**
+ * Walks one collection, optionally restricted to a tile run. Each yielded record is a fresh object: bulk consumers
+ * should read the typed arrays through `tileRange()` instead.
+ */
+export declare function iterate(placements: Cs2Placements, collection: Cs2PlacementCollectionName, tileId?: string): Generator<Cs2Placement>;
+/** The half-open record range one tile occupies, for reading the typed arrays directly. */
+export declare function tileRange(placements: Cs2Placements, collection: Cs2PlacementCollectionName, tileId: string): [number, number];
+export declare function prefabName(placements: Cs2Placements, prefabIndex: number): string;
+/**
+ * `tile_X_Z` is computed from the UNMIRRORED source position, so Z runs backwards in the world frame:
+ * `worldZmax = 7168 - tileZ * 1792`. Verified against tile_0_0 buildings at z in [5554, 5589].
+ */
+export declare function tileBoundsWorld(tileId: string): Cs2TileBounds;

package/dist/cs2/placements.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLACEMENT_LOT_SIZE_STRIDE = exports.PLACEMENT_RECORD_STRIDE = exports.PLACEMENT_TRANSFORM_STRIDE = void 0;
+exports.readCs2Placements = readCs2Placements;
+exports.iterate = iterate;
+exports.tileRange = tileRange;
+exports.prefabName = prefabName;
+exports.tileBoundsWorld = tileBoundsWorld;
+const node_path_1 = require("node:path");
+const binary_1 = require("./binary");
+const types_1 = require("./types");
+exports.PLACEMENT_TRANSFORM_STRIDE = 7;
+exports.PLACEMENT_RECORD_STRIDE = 4;
+exports.PLACEMENT_LOT_SIZE_STRIDE = 2;
+/** Reads `placements/` in full: the manifest plus the three collections' bins as typed arrays, no per-record objects. */
+async function readCs2Placements(root) {
+    const dir = (0, node_path_1.join)(root, 'placements');
+    const manifest = await (0, binary_1.readJsonFile)((0, node_path_1.join)(dir, 'placements.json'), 'readCs2Placements');
+    (0, binary_1.assertSchema)(manifest.schema, types_1.CS2_PLACEMENTS_SCHEMA, 'readCs2Placements: placements.json');
+    const names = ['props', 'attachedObjects', 'buildings'];
+    const collections = {};
+    for (const name of names) {
+        const entry = manifest.collections[name];
+        if (!entry)
+            throw new Error(`readCs2Placements: placements.json has no "${name}" collection`);
+        collections[name] = await readCollection(dir, name, entry);
+    }
+    return { manifest, prefabNames: manifest.prefabNames, collections };
+}
+/**
+ * Walks one collection, optionally restricted to a tile run. Each yielded record is a fresh object: bulk consumers
+ * should read the typed arrays through `tileRange()` instead.
+ */
+function* iterate(placements, collection, tileId) {
+    const source = placements.collections[collection];
+    const runs = tileId === undefined ? source.tiles : [requireTile(source, tileId)];
+    for (const run of runs) {
+        for (let index = run.first; index < run.first + run.count; index += 1) {
+            const transform = index * exports.PLACEMENT_TRANSFORM_STRIDE;
+            const record = index * exports.PLACEMENT_RECORD_STRIDE;
+            const prefabIndex = source.records[record];
+            yield {
+                index,
+                tileId: run.id,
+                prefabIndex,
+                prefabName: prefabName(placements, prefabIndex),
+                entityId: source.records[record + 1],
+                rootOwnerEntityId: source.records[record + 2],
+                chainDepth: source.records[record + 3],
+                position: [source.transforms[transform], source.transforms[transform + 1], source.transforms[transform + 2]],
+                quaternion: [
+                    source.transforms[transform + 3],
+                    source.transforms[transform + 4],
+                    source.transforms[transform + 5],
+                    source.transforms[transform + 6],
+                ],
+                lotSize: source.lotSizes ? [source.lotSizes[index * exports.PLACEMENT_LOT_SIZE_STRIDE], source.lotSizes[index * exports.PLACEMENT_LOT_SIZE_STRIDE + 1]] : null,
+            };
+        }
+    }
+}
+/** The half-open record range one tile occupies, for reading the typed arrays directly. */
+function tileRange(placements, collection, tileId) {
+    const run = requireTile(placements.collections[collection], tileId);
+    return [run.first, run.first + run.count];
+}
+function prefabName(placements, prefabIndex) {
+    const name = placements.prefabNames[prefabIndex];
+    if (name === undefined)
+        throw new Error(`prefabName: index ${prefabIndex} is outside the ${placements.prefabNames.length}-name table`);
+    return name;
+}
+/**
+ * `tile_X_Z` is computed from the UNMIRRORED source position, so Z runs backwards in the world frame:
+ * `worldZmax = 7168 - tileZ * 1792`. Verified against tile_0_0 buildings at z in [5554, 5589].
+ */
+function tileBoundsWorld(tileId) {
+    const match = /^tile_(\d+)_(\d+)$/.exec(tileId);
+    if (!match)
+        throw new Error(`tileBoundsWorld: "${tileId}" is not a tile id of the form tile_X_Z`);
+    const tileX = Number(match[1]);
+    const tileZ = Number(match[2]);
+    return {
+        tileX,
+        tileZ,
+        minX: -types_1.CS2_WORLD_HALF_METRES + tileX * types_1.CS2_TILE_METRES,
+        maxX: -types_1.CS2_WORLD_HALF_METRES + (tileX + 1) * types_1.CS2_TILE_METRES,
+        minZ: types_1.CS2_WORLD_HALF_METRES - (tileZ + 1) * types_1.CS2_TILE_METRES,
+        maxZ: types_1.CS2_WORLD_HALF_METRES - tileZ * types_1.CS2_TILE_METRES,
+    };
+}
+async function readCollection(dir, name, entry) {
+    const label = `readCs2Placements: ${name}`;
+    const transforms = await (0, binary_1.readFloat32File)((0, node_path_1.join)(dir, entry.transforms.bin), `${label} transforms`, entry.count * exports.PLACEMENT_TRANSFORM_STRIDE);
+    const records = await (0, binary_1.readUint32File)((0, node_path_1.join)(dir, entry.records.bin), `${label} records`, entry.count * exports.PLACEMENT_RECORD_STRIDE);
+    const lotSizes = entry.lotSizes
+        ? await (0, binary_1.readFloat32File)((0, node_path_1.join)(dir, entry.lotSizes.bin), `${label} lotSizes`, entry.count * exports.PLACEMENT_LOT_SIZE_STRIDE)
+        : null;
+    const tiles = entry.tiles ?? [];
+    let cursor = 0;
+    for (const run of tiles) {
+        if (run.first !== cursor)
+            throw new Error(`${label}: tile ${run.id} starts at ${run.first}, expected the contiguous ${cursor}`);
+        cursor += run.count;
+    }
+    if (cursor !== entry.count)
+        throw new Error(`${label}: tile runs cover ${cursor} records, the manifest declares ${entry.count}`);
+    return { name, count: entry.count, transforms, records, lotSizes, tiles, tilesById: new Map(tiles.map((run) => [run.id, run])) };
+}
+function requireTile(collection, tileId) {
+    const run = collection.tilesById.get(tileId);
+    if (!run)
+        throw new Error(`iterate: collection "${collection.name}" has no tile "${tileId}"`);
+    return run;
+}
+//# sourceMappingURL=placements.js.map

package/dist/cs2/placements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placements.js","sourceRoot":"","sources":["../../src/cs2/placements.ts"],"names":[],"mappings":";;;AA2DA,8CAYC;AAMD,0BA2BC;AAGD,8BAGC;AAED,gCAIC;AAMD,0CAaC;AAvID,yCAAiC;AACjC,qCAAuF;AACvF,mCAQiB;AAEJ,QAAA,0BAA0B,GAAG,CAAC,CAAC;AAC/B,QAAA,uBAAuB,GAAG,CAAC,CAAC;AAC5B,QAAA,yBAAyB,GAAG,CAAC,CAAC;AA4C3C,yHAAyH;AAClH,KAAK,UAAU,iBAAiB,CAAC,IAAY;IAClD,MAAM,GAAG,GAAG,IAAA,gBAAI,EAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAG,MAAM,IAAA,qBAAY,EAAwB,IAAA,gBAAI,EAAC,GAAG,EAAE,iBAAiB,CAAC,EAAE,mBAAmB,CAAC,CAAC;IAC9G,IAAA,qBAAY,EAAC,QAAQ,CAAC,MAAM,EAAE,6BAAqB,EAAE,oCAAoC,CAAC,CAAC;IAC3F,MAAM,KAAK,GAAiC,CAAC,OAAO,EAAE,iBAAiB,EAAE,WAAW,CAAC,CAAC;IACtF,MAAM,WAAW,GAAG,EAAgE,CAAC;IACrF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,IAAI,cAAc,CAAC,CAAC;QAC9F,WAAW,CAAC,IAAI,CAAC,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,EAAE,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,QAAe,CAAC,CAAC,OAAO,CAAC,UAAyB,EAAE,UAAsC,EAAE,MAAe;IACzG,MAAM,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,KAAK,IAAI,KAAK,GAAG,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YACtE,MAAM,SAAS,GAAG,KAAK,GAAG,kCAA0B,CAAC;YACrD,MAAM,MAAM,GAAG,KAAK,GAAG,+BAAuB,CAAC;YAC/C,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC3C,MAAM;gBACJ,KAAK;gBACL,MAAM,EAAE,GAAG,CAAC,EAAE;gBACd,WAAW;gBACX,UAAU,EAAE,UAAU,CAAC,UAAU,EAAE,WAAW,CAAC;gBAC/C,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;gBACpC,iBAAiB,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;gBAC7C,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;gBACtC,QAAQ,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,SAAS,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;gBAC5G,UAAU,EAAE;oBACV,MAAM,CAAC,UAAU,CAAC,SAAS,GAAG,CAAC,CAAC;oBAChC,MAAM,CAAC,UAAU,CAAC,SAAS,GAAG,CAAC,CAAC;oBAChC,MAAM,CAAC,UAAU,CAAC,SAAS,GAAG,CAAC,CAAC;oBAChC,MAAM,CAAC,UAAU,CAAC,SAAS,GAAG,CAAC,CAAC;iBACjC;gBACD,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,GAAG,iCAAyB,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,GAAG,iCAAyB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;aAC/I,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,2FAA2F;AAC3F,SAAgB,SAAS,CAAC,UAAyB,EAAE,UAAsC,EAAE,MAAc;IACzG,MAAM,GAAG,GAAG,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC;IACpE,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;AAC5C,CAAC;AAED,SAAgB,UAAU,CAAC,UAAyB,EAAE,WAAmB;IACvE,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IACjD,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,WAAW,mBAAmB,UAAU,CAAC,WAAW,CAAC,MAAM,aAAa,CAAC,CAAC;IACvI,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,SAAgB,eAAe,CAAC,MAAc;IAC5C,MAAM,KAAK,GAAG,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAChD,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,MAAM,yCAAyC,CAAC,CAAC;IAClG,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/B,OAAO;QACL,KAAK;QACL,KAAK;QACL,IAAI,EAAE,CAAC,6BAAqB,GAAG,KAAK,GAAG,uBAAe;QACtD,IAAI,EAAE,CAAC,6BAAqB,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,uBAAe;QAC5D,IAAI,EAAE,6BAAqB,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,uBAAe;QAC3D,IAAI,EAAE,6BAAqB,GAAG,KAAK,GAAG,uBAAe;KACtD,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,GAAW,EAAE,IAAgC,EAAE,KAAqC;IAChH,MAAM,KAAK,GAAG,sBAAsB,IAAI,EAAE,CAAC;IAC3C,MAAM,UAAU,GAAG,MAAM,IAAA,wBAAe,EAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,aAAa,EAAE,KAAK,CAAC,KAAK,GAAG,kCAA0B,CAAC,CAAC;IAC3I,MAAM,OAAO,GAAG,MAAM,IAAA,uBAAc,EAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,UAAU,EAAE,KAAK,CAAC,KAAK,GAAG,+BAAuB,CAAC,CAAC;IAC9H,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ;QAC7B,CAAC,CAAC,MAAM,IAAA,wBAAe,EAAC,IAAA,gBAAI,EAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,WAAW,EAAE,KAAK,CAAC,KAAK,GAAG,iCAAyB,CAAC;QACpH,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;IAChC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,IAAI,GAAG,CAAC,KAAK,KAAK,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,UAAU,GAAG,CAAC,EAAE,cAAc,GAAG,CAAC,KAAK,6BAA6B,MAAM,EAAE,CAAC,CAAC;QAChI,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC;IACtB,CAAC;IACD,IAAI,MAAM,KAAK,KAAK,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,qBAAqB,MAAM,mCAAmC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;IACjI,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;AACnI,CAAC;AAED,SAAS,WAAW,CAAC,UAAkC,EAAE,MAAc;IACrE,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,UAAU,CAAC,IAAI,kBAAkB,MAAM,GAAG,CAAC,CAAC;IAC9F,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/cs2/roadPieces.d.ts

@@ -0,0 +1,79 @@
+import { type Cs2CompositionParameters, type Cs2GeneratedCompositionManifest, type Cs2GeneratedMeshRecord } from './types';
+export declare const GENERATED_VERTEX_STRIDE = 32;
+/** Ground compositions cluster this close to the terrain; anything farther is deliberate structure (bridges, tunnels). */
+export declare const TERRAIN_CONFORMANCE_LIMIT_METRES = 1.25;
+export declare const TERRAIN_CONFORMANCE_LIFT_METRES = 0.035;
+export interface Cs2GeneratedMesh {
+    record: Cs2GeneratedMeshRecord;
+    bytes: DataView;
+    indices: Uint32Array;
+}
+export interface Cs2RoadPieces {
+    manifest: Cs2GeneratedCompositionManifest;
+    meshes: Cs2GeneratedMesh[];
+    /** Every composition entity id a `roads-v2.json` `compositionRefs` can name, mapped to the mesh that draws it. */
+    byCompositionEntityId: Map<number, Cs2GeneratedMesh>;
+}
+export interface Cs2GeneratedVertex {
+    /** Curve-space lateral coordinate, before the sync remap. */
+    lateral: number;
+    /** Metres, added to Y. */
+    elevation: number;
+    t: number;
+    normal: [number, number, number];
+    packedTangent: number;
+    /** Indices into `matrices`, NOT colour. */
+    colourA: number;
+    colourB: number;
+    /** Low 3 bits pick the sync pair. */
+    flags: number;
+    uv: [number, number];
+}
+export interface Cs2DeformedInstance {
+    positions: Float32Array;
+    normals: Float32Array;
+    /** Triangles are reversed relative to the source: this layer alone ships source winding under a Z mirror. */
+    indices: Uint32Array;
+}
+export interface Cs2TerrainConformance {
+    medianMetres: number;
+    shiftMetres: number;
+    applied: boolean;
+}
+/** Reads `road-pieces/road-composition-generated.json` and its interleaved bin. */
+export declare function readCs2RoadPieces(root: string): Promise<Cs2RoadPieces>;
+/** One vertex of the 32-byte interleaved layout. */
+export declare function decodeVertex(mesh: Cs2GeneratedMesh, vertex: number): Cs2GeneratedVertex;
+/**
+ * Evaluates one instance of a generated composition: the two curve matrices the vertex names, the sync remap, then the
+ * single Z mirror this layer still needs. The mirror flips handedness, so every triangle comes back as (a, c, b).
+ *
+ * A node piece of a one-way or asymmetric composition ships its two halves as strips that stop short of the middle
+ * (e.g. lateral 0..0.56 and 0.44..1 of the full width) and bridges the rest onto the middle curve. Taken literally the
+ * bridge runs straight from the strip's inner edge to the node centre and cuts across the corner point the neighbouring
+ * piece meets, leaving a sliver of ground at every such junction (214 across Granit). Each strip is therefore stretched
+ * so its inner edge lands on its inner curve (1 or 2), the layout the full-span strips of symmetric pieces already have.
+ *
+ * On a NODE piece (`options.nodePiece`) the sync remap is applied progressively along the piece: identity at t = 0,
+ * where the piece continues the edge piece's own lane and kerb columns, full at t = 1, where the targets make it meet
+ * the neighbouring pieces. Applied at full strength from t = 0 the node's kerb line jogs 0.4–1.8 m against the edge's
+ * at every seam; lerped, the two match to the sample size while the corners still close.
+ */
+export interface DeformInstanceOptions {
+    /** A start/end-node part rather than the edge's segment; default false. */
+    nodePiece?: boolean;
+}
+export declare function deformInstance(mesh: Cs2GeneratedMesh, parameters: Cs2CompositionParameters, options?: DeformInstanceOptions): Cs2DeformedInstance;
+/**
+ * CS2 runs a terrain-adjustment stage after deforming a composition. The per-composition median of (vertexY - terrainY)
+ * corrects the sampling datum without flattening kerbs; a median outside +/-1.25 m is a bridge or a tunnel, left alone.
+ */
+export declare function evalTerrainConformance(positions: Float32Array, terrainSampleAt: (x: number, z: number) => number): Cs2TerrainConformance;
+export interface LateralRange {
+    min: number;
+    max: number;
+}
+/** One strip = one (curve A, curve B, sync pair) triple; the key packs the three bytes the vertex carries. */
+export declare function stripKey(vertex: Pick<Cs2GeneratedVertex, 'colourA' | 'colourB' | 'flags'>): number;
+/** The source lateral extent of every strip in a mesh, once per mesh: what says whether a strip reaches the middle. */
+export declare function stripLateralRanges(mesh: Cs2GeneratedMesh): Map<number, LateralRange>;