@jgengine/core 0.11.0 → 0.13.0

package/dist/world/minimapBake.js

@@ -0,0 +1,208 @@
+import { pointInPolygon } from "./scatterRegion.js";
+/** The built-in height→color ramp and water color a bake uses when no palette override is given. */
+export const DEFAULT_MINIMAP_PALETTE = {
+    low: "#3f5d34",
+    high: "#cdbb93",
+    water: "#2f5d78",
+};
+function parseHex(hex) {
+    let value = hex.trim().replace(/^#/, "");
+    if (value.length === 3)
+        value = value.split("").map((c) => c + c).join("");
+    const int = Number.parseInt(value, 16);
+    if (!Number.isFinite(int) || value.length !== 6)
+        return { r: 0, g: 0, b: 0 };
+    return { r: (int >> 16) & 0xff, g: (int >> 8) & 0xff, b: int & 0xff };
+}
+function mix(a, b, t) {
+    const k = Math.max(0, Math.min(1, t));
+    return {
+        r: Math.round(a.r + (b.r - a.r) * k),
+        g: Math.round(a.g + (b.g - a.g) * k),
+        b: Math.round(a.b + (b.b - a.b) * k),
+    };
+}
+/**
+ * Rasterizes a top-down terrain image: height maps onto a low→high color ramp (normalized over the
+ * sampled height range), slope darkens the shade, water fills below `waterLevel`, and each zone
+ * polygon tints the ground it covers. Deterministic for a fixed source. The bounds are preserved so
+ * a player-centered minimap pans the image correctly.
+ * @capability minimap-bake rasterize authored terrain + zones into a top-down minimap image
+ */
+export function bakeMinimapImage(source, options = {}) {
+    const resolution = Math.max(8, Math.floor(options.resolution ?? 128));
+    const palette = { ...DEFAULT_MINIMAP_PALETTE, ...options.palette };
+    const low = parseHex(palette.low);
+    const high = parseHex(palette.high);
+    const water = parseHex(palette.water);
+    const { minX, minZ, maxX, maxZ } = source.bounds;
+    const spanX = Math.max(1e-6, maxX - minX);
+    const spanZ = Math.max(1e-6, maxZ - minZ);
+    // Longer world axis gets `resolution` pixels; the other keeps aspect.
+    const width = spanX >= spanZ ? resolution : Math.max(8, Math.round((spanX / spanZ) * resolution));
+    const height = spanZ >= spanX ? resolution : Math.max(8, Math.round((spanZ / spanX) * resolution));
+    const worldX = (px) => minX + ((px + 0.5) / width) * spanX;
+    const worldZ = (py) => minZ + ((py + 0.5) / height) * spanZ;
+    // First pass: height range for a stable ramp.
+    let hMin = Infinity;
+    let hMax = -Infinity;
+    const heights = new Float64Array(width * height);
+    for (let py = 0; py < height; py += 1) {
+        for (let px = 0; px < width; px += 1) {
+            const h = source.sampleHeight(worldX(px), worldZ(py));
+            heights[py * width + px] = h;
+            if (h < hMin)
+                hMin = h;
+            if (h > hMax)
+                hMax = h;
+        }
+    }
+    const hSpan = Math.max(1e-6, hMax - hMin);
+    const pixels = new Uint8ClampedArray(width * height * 4);
+    const zones = source.zones ?? [];
+    for (let py = 0; py < height; py += 1) {
+        for (let px = 0; px < width; px += 1) {
+            const wx = worldX(px);
+            const wz = worldZ(py);
+            const h = heights[py * width + px];
+            let color;
+            if (source.waterLevel !== undefined && h <= source.waterLevel) {
+                color = water;
+            }
+            else {
+                color = mix(low, high, (h - hMin) / hSpan);
+                if (source.sampleNormal !== undefined) {
+                    const n = source.sampleNormal(wx, wz);
+                    const shade = 0.62 + 0.38 * Math.max(0, Math.min(1, n[1]));
+                    color = { r: Math.round(color.r * shade), g: Math.round(color.g * shade), b: Math.round(color.b * shade) };
+                }
+            }
+            for (const zone of zones) {
+                if (pointInPolygon([wx, wz], zone.polygon)) {
+                    color = mix(color, parseHex(zone.color), zone.alpha ?? 0.5);
+                }
+            }
+            const index = (py * width + px) * 4;
+            pixels[index] = color.r;
+            pixels[index + 1] = color.g;
+            pixels[index + 2] = color.b;
+            pixels[index + 3] = 255;
+        }
+    }
+    return { width, height, pixels, bounds: { minX, minZ, maxX, maxZ } };
+}
+// --- Minimal pure PNG encoder (RGBA, stored/uncompressed DEFLATE) ------------------------------
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n += 1) {
+        let c = n;
+        for (let k = 0; k < 8; k += 1)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function crc32(bytes) {
+    let c = 0xffffffff;
+    for (let i = 0; i < bytes.length; i += 1)
+        c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function adler32(bytes) {
+    let a = 1;
+    let b = 0;
+    for (let i = 0; i < bytes.length; i += 1) {
+        a = (a + bytes[i]) % 65521;
+        b = (b + a) % 65521;
+    }
+    return ((b << 16) | a) >>> 0;
+}
+/** Wraps raw bytes in a zlib stream using only stored (uncompressed) DEFLATE blocks. */
+function zlibStore(data) {
+    const blocks = [0x78, 0x01]; // zlib header (no compression)
+    let offset = 0;
+    while (offset < data.length) {
+        const chunk = Math.min(0xffff, data.length - offset);
+        const final = offset + chunk >= data.length ? 1 : 0;
+        blocks.push(final, chunk & 0xff, (chunk >> 8) & 0xff, ~chunk & 0xff, (~chunk >> 8) & 0xff);
+        for (let i = 0; i < chunk; i += 1)
+            blocks.push(data[offset + i]);
+        offset += chunk;
+    }
+    const checksum = adler32(data);
+    blocks.push((checksum >>> 24) & 0xff, (checksum >>> 16) & 0xff, (checksum >>> 8) & 0xff, checksum & 0xff);
+    return Uint8Array.from(blocks);
+}
+function chunk(type, data) {
+    const typeBytes = Uint8Array.from([...type].map((c) => c.charCodeAt(0)));
+    const body = new Uint8Array(typeBytes.length + data.length);
+    body.set(typeBytes, 0);
+    body.set(data, typeBytes.length);
+    const crc = crc32(body);
+    const out = new Uint8Array(4 + body.length + 4);
+    const view = new DataView(out.buffer);
+    view.setUint32(0, data.length);
+    out.set(body, 4);
+    view.setUint32(4 + body.length, crc);
+    return out;
+}
+function base64(bytes) {
+    const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i];
+        const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+        const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+        out += chars[b0 >> 2];
+        out += chars[((b0 & 3) << 4) | (b1 >> 4)];
+        out += i + 1 < bytes.length ? chars[((b1 & 15) << 2) | (b2 >> 6)] : "=";
+        out += i + 2 < bytes.length ? chars[b2 & 63] : "=";
+    }
+    return out;
+}
+/** Encodes an RGBA bake to raw PNG bytes (pure; stored DEFLATE, valid for any decoder). */
+export function encodeBakePng(bake) {
+    const { width, height, pixels } = bake;
+    const ihdr = new Uint8Array(13);
+    const ihdrView = new DataView(ihdr.buffer);
+    ihdrView.setUint32(0, width);
+    ihdrView.setUint32(4, height);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = 6; // color type RGBA
+    // 10,11,12 = compression/filter/interlace = 0
+    // Filtered scanlines: filter byte 0 (none) per row.
+    const raw = new Uint8Array(height * (1 + width * 4));
+    for (let y = 0; y < height; y += 1) {
+        const rowStart = y * (1 + width * 4);
+        raw[rowStart] = 0;
+        raw.set(pixels.subarray(y * width * 4, (y + 1) * width * 4), rowStart + 1);
+    }
+    const signature = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    const parts = [
+        signature,
+        chunk("IHDR", ihdr),
+        chunk("IDAT", zlibStore(raw)),
+        chunk("IEND", new Uint8Array(0)),
+    ];
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+/**
+ * Encodes a bake as a `data:image/png;base64,...` URI — the exact string the `Minimap` /
+ * `WorldMap` `background` prop takes. Deterministic for a fixed bake.
+ * @capability minimap-bake encode a baked minimap as a PNG data URI for the Minimap background
+ */
+export function minimapBakeToPngDataUri(bake) {
+    return `data:image/png;base64,${base64(encodeBakePng(bake))}`;
+}
+/** One-call convenience: rasterize a source and return `{ background, mapBounds }` for a minimap. */
+export function bakeMinimapBackground(source, options = {}) {
+    const bake = bakeMinimapImage(source, options);
+    return { background: minimapBakeToPngDataUri(bake), mapBounds: bake.bounds };
+}

package/dist/world/minimapTrack.d.ts

@@ -0,0 +1,17 @@
+import type { WorldXZ } from "./minimap.js";
+/** A world-space segment defining a linear "track" minimap — points are projected onto the `from`→`to` axis. */
+export interface TrackAxis {
+    from: WorldXZ;
+    to: WorldXZ;
+}
+/**
+ * Project a world point onto the `from`→`to` segment of `axis` and return the
+ * clamped 0..1 fraction of how far along the track it lies (0 at `from`, 1 at
+ * `to`). The linear analogue of `projectToMinimap` — feeds a horizontal
+ * corridor/route progress rail. Accepts XZ (`[x, z]`) or XYZ (`[x, y, z]`)
+ * points (index 0 = x, index 2 when length 3 else index 1 = z). A zero-length
+ * axis returns 0.
+ *
+ * @capability minimap-track project a world point to a 0..1 fraction along a linear track axis
+ */
+export declare function trackFraction(point: WorldXZ | readonly [number, number, number], axis: TrackAxis): number;

package/dist/world/minimapTrack.js

@@ -0,0 +1,22 @@
+/**
+ * Project a world point onto the `from`→`to` segment of `axis` and return the
+ * clamped 0..1 fraction of how far along the track it lies (0 at `from`, 1 at
+ * `to`). The linear analogue of `projectToMinimap` — feeds a horizontal
+ * corridor/route progress rail. Accepts XZ (`[x, z]`) or XYZ (`[x, y, z]`)
+ * points (index 0 = x, index 2 when length 3 else index 1 = z). A zero-length
+ * axis returns 0.
+ *
+ * @capability minimap-track project a world point to a 0..1 fraction along a linear track axis
+ */
+export function trackFraction(point, axis) {
+    const px = point[0];
+    const pz = point.length === 3 ? point[2] : point[1];
+    const ax = axis.to[0] - axis.from[0];
+    const az = axis.to[1] - axis.from[1];
+    const lengthSq = ax * ax + az * az;
+    if (lengthSq === 0)
+        return 0;
+    const dot = (px - axis.from[0]) * ax + (pz - axis.from[1]) * az;
+    const fraction = dot / lengthSq;
+    return fraction < 0 ? 0 : fraction > 1 ? 1 : fraction;
+}

package/dist/world/place.d.ts

@@ -0,0 +1,166 @@
+import type { PhysicsConfig } from "../game/defineGame.js";
+/**
+ * The place model: a world is the place you play in — substrate (ground) plus laws (physics,
+ * surface) — never a dressed diorama. Sky look, foliage scatter, props, and sculpt are content:
+ * they are authored in the editor (or by a content preset that writes into the scene document)
+ * and consumed through the authored-scene seams, not declared on the world.
+ *
+ * Hard rules the API enforces:
+ * - No `seed` anywhere in a world definition. Determinism comes from the runtime: the engine
+ *   derives generator/scatter seeds from the world `id` plus the save/run seed (see
+ *   {@link seedForPlace}), so the same place replays identically without the author owning RNG.
+ * - No sky, vegetation, or theme fields. A world with no authored sky renders the engine
+ *   default sky; "void"/"space" is content, not a world knob.
+ * - No genre or franchise presets. `generator` carries algorithm parameters only.
+ */
+/**
+ * Matter/feel laws of a place's ground that systems, physics, and audio read — restitution for a
+ * metal chamber the pieces ping off, stickiness for a slime pit, a soft felt mat. The same rule
+ * systems play on any surface; swapping the surface (plus content audio) changes the feel without
+ * forking the rules. This is place law, not a theme kit: visual/audio dressing stays in content.
+ */
+export interface SurfaceLaws {
+    /** Named matter of the ground ("metal", "slime", "felt", …) — a label systems and audio cues key off. */
+    matter?: string;
+    /** Sliding friction scalar, 0 (ice) … 1+ (grippy). Interpreted by movement/physics systems. */
+    friction?: number;
+    /** Bounce energy retention, 0 (dead stop) … 1 (perfect bounce). Interpreted by physics/board systems. */
+    restitution?: number;
+    /** Free-form serializable place-law traits game systems read (e.g. `{ stuckTurns: 1 }` for slime). */
+    traits?: Readonly<Record<string, number | string | boolean>>;
+}
+/** Serializable algorithm parameters for a procedural ground generator. Never a genre kit. */
+export interface GroundGenerator {
+    /** Algorithm identifier the game's generation system resolves (e.g. "fbm", "caves", "layers"). */
+    algorithm: string;
+    /**
+     * Algorithm tuning only — amplitudes, frequencies, thresholds, palettes of ids. Never a `seed`
+     * (the engine injects one from world id + save/run) and never a genre/franchise preset name.
+     */
+    params?: Readonly<Record<string, number | string | boolean>>;
+}
+/**
+ * Size of a `flat` ground: extents in world units. `Infinity` on an axis means unbounded — an
+ * endless plain needs no bounds number invented for it. `y` optionally bounds vertical play space.
+ */
+export interface FlatGroundSize {
+    x: number;
+    /** Optional vertical bound of the play volume; omit for open sky. */
+    y?: number;
+    z: number;
+    radius?: never;
+}
+/** Size of a `round` ground: the planet/sphere radius in world units. Nothing else. */
+export interface RoundGroundSize {
+    radius: number;
+    x?: never;
+    y?: never;
+    z?: never;
+}
+/** Size of a `voxel` ground: the generator's domain per axis; axes may be `Infinity` for streaming volumes. */
+export interface VoxelGroundSize {
+    x: number;
+    y: number;
+    z: number;
+    radius?: never;
+}
+/** Size of a `board` ground: a 2D surface you look at, in cells or layout units. */
+export interface BoardGroundSize {
+    x: number;
+    y: number;
+    z?: never;
+    radius?: never;
+}
+/** A 3D walkable plane/slab. `Infinity` axes are unbounded; no separate "infinite" mode exists. */
+export interface FlatGround {
+    mode: "flat";
+    size: FlatGroundSize;
+    surface?: SurfaceLaws;
+    generator?: GroundGenerator;
+}
+/** A planet/sphere you play on the outside of. Sized by `radius` only. */
+export interface RoundGround {
+    mode: "round";
+    size: RoundGroundSize;
+    surface?: SurfaceLaws;
+    generator?: GroundGenerator;
+}
+/** A procedural volume of blocks. `size` is the generator domain; `generator` is algorithm params only. */
+export interface VoxelGround {
+    mode: "voxel";
+    size: VoxelGroundSize;
+    surface?: SurfaceLaws;
+    generator?: GroundGenerator;
+}
+/**
+ * A 2D surface you look at — grid games, solitaire, tabletop. Physics is often zero-gravity or
+ * omitted; the game owns the face it draws on the board.
+ */
+export interface BoardGround {
+    /** `"stage"` is accepted as an alias and normalized to `"board"`. */
+    mode: "board" | "stage";
+    size: BoardGroundSize;
+    surface?: SurfaceLaws;
+}
+/** The substrate of a place, discriminated by `mode` — TS rejects a `radius` on `flat` and `x`/`z` on `round`. */
+export type GroundConfig = FlatGround | RoundGround | VoxelGround | BoardGround;
+/** Canonical ground modes after normalization (`stage` → `board`). */
+export type GroundMode = "flat" | "round" | "voxel" | "board";
+/** {@link BoardGround} with the `stage` alias resolved away. */
+export type ResolvedBoardGround = Omit<BoardGround, "mode"> & {
+    mode: "board";
+};
+/** A place's ground after `world()` normalization. */
+export type ResolvedGround = FlatGround | RoundGround | VoxelGround | ResolvedBoardGround;
+/** Input to {@link world}: place identity, substrate, and the laws of this place. */
+export interface PlaceConfig {
+    /** Place identity — names the world for saves, seeds, and world switching. */
+    id: string;
+    /** The substrate: what you stand on / look at, discriminated by `mode`. */
+    ground: GroundConfig;
+    /**
+     * Laws of THIS place (gravity, jump). Each world carries its own physics, so a game with several
+     * places (a station and a moon) gives each different laws; `defineGameDefinition` resolves the
+     * active world's physics over the game-level default. The engine owns simulation.
+     */
+    physics?: PhysicsConfig;
+}
+/** A declared place — the `world()` result carried on `GameDefinition.world`. */
+export interface PlaceWorldFeature {
+    kind: "place";
+    id: string;
+    ground: ResolvedGround;
+    physics?: PhysicsConfig;
+}
+/**
+ * Declares the place a game is played in: substrate (`ground`) + laws (`physics`, `ground.surface`).
+ * The thin default start — `flat` with `Infinity` axes and default physics, `board` for 2D — is a
+ * complete world; dressing it (sky, foliage, props, sculpt) is editor-authored scene content.
+ * Multiple worlds per game are first-class: declare one `world()` per place, each with its own id,
+ * ground, and physics. Games that are not a spatial place (pure UI/rules) omit `world` entirely.
+ *
+ * @capability world-place declare the place a game happens in — flat/round/voxel/board ground, surface laws, per-place physics
+ */
+export declare function world(config: PlaceConfig): PlaceWorldFeature;
+/**
+ * The engine-side seed derivation for a place: a stable string from the world `id` plus the
+ * save/run seed. Generators and scatter receive this — never a `seed` field in the world
+ * definition — so a save replays its world deterministically and a fresh run can vary by
+ * `runSeed` alone.
+ *
+ * @capability world-seed derive a deterministic generator/scatter seed from world id + save/run seed
+ */
+export declare function seedForPlace(worldId: string, runSeed?: string): string;
+/**
+ * Resolves the physics laws in effect for the active world: a place world's own `physics` wins
+ * field-by-field over the game-level default. Non-place worlds (and games with no world) keep the
+ * game-level config unchanged.
+ */
+export declare function resolveWorldPhysics(worldFeature: {
+    kind: string;
+    physics?: PhysicsConfig;
+} | undefined, base: PhysicsConfig | undefined): PhysicsConfig | undefined;
+/** Type guard for the place-model world feature. */
+export declare function isPlaceWorld(worldFeature: {
+    kind: string;
+} | undefined): worldFeature is PlaceWorldFeature;

package/dist/world/place.js

@@ -0,0 +1,96 @@
+const BANNED_WORLD_KEYS = ["sky", "vegetation", "terrain", "environment", "weather", "seed"];
+function assertNoDressing(config) {
+    const record = config;
+    for (const key of BANNED_WORLD_KEYS) {
+        if (record[key] !== undefined) {
+            throw new Error(key === "seed"
+                ? "world: seed does not belong in a world definition — the engine derives seeds from the world id and the save/run seed (seedForPlace)."
+                : `world: "${key}" does not belong in a world definition — a world is substrate + laws. Author sky, foliage, and dressing in the editor (or a content preset that writes scene data).`);
+        }
+    }
+}
+function assertAxis(mode, axis, value, allowInfinite) {
+    const ok = value > 0 && (allowInfinite ? true : Number.isFinite(value));
+    if (!ok) {
+        throw new Error(`world: ground.size.${axis} for mode "${mode}" must be a positive${allowInfinite ? "" : " finite"} number, got ${value}`);
+    }
+}
+function resolveGround(ground) {
+    if (ground["seed"] !== undefined) {
+        throw new Error("world: seed does not belong on ground — the engine injects seeds into generators (seedForPlace).");
+    }
+    if ("generator" in ground && ground.generator?.params !== undefined && "seed" in ground.generator.params) {
+        throw new Error("world: generator.params.seed is not allowed — the engine injects the seed from world id + save/run (seedForPlace).");
+    }
+    switch (ground.mode) {
+        case "flat": {
+            assertAxis("flat", "x", ground.size.x, true);
+            assertAxis("flat", "z", ground.size.z, true);
+            if (ground.size.y !== undefined)
+                assertAxis("flat", "y", ground.size.y, true);
+            return ground;
+        }
+        case "round": {
+            assertAxis("round", "radius", ground.size.radius, false);
+            return ground;
+        }
+        case "voxel": {
+            assertAxis("voxel", "x", ground.size.x, true);
+            assertAxis("voxel", "y", ground.size.y, true);
+            assertAxis("voxel", "z", ground.size.z, true);
+            return ground;
+        }
+        case "board":
+        case "stage": {
+            assertAxis("board", "x", ground.size.x, false);
+            assertAxis("board", "y", ground.size.y, false);
+            return ground.mode === "board" ? ground : { ...ground, mode: "board" };
+        }
+    }
+}
+/**
+ * Declares the place a game is played in: substrate (`ground`) + laws (`physics`, `ground.surface`).
+ * The thin default start — `flat` with `Infinity` axes and default physics, `board` for 2D — is a
+ * complete world; dressing it (sky, foliage, props, sculpt) is editor-authored scene content.
+ * Multiple worlds per game are first-class: declare one `world()` per place, each with its own id,
+ * ground, and physics. Games that are not a spatial place (pure UI/rules) omit `world` entirely.
+ *
+ * @capability world-place declare the place a game happens in — flat/round/voxel/board ground, surface laws, per-place physics
+ */
+export function world(config) {
+    if (config.id.trim().length === 0) {
+        throw new Error("world: id must be non-empty — it names the place for saves, seeds, and world switching");
+    }
+    assertNoDressing(config);
+    return {
+        kind: "place",
+        id: config.id,
+        ground: resolveGround(config.ground),
+        ...(config.physics === undefined ? {} : { physics: config.physics }),
+    };
+}
+/**
+ * The engine-side seed derivation for a place: a stable string from the world `id` plus the
+ * save/run seed. Generators and scatter receive this — never a `seed` field in the world
+ * definition — so a save replays its world deterministically and a fresh run can vary by
+ * `runSeed` alone.
+ *
+ * @capability world-seed derive a deterministic generator/scatter seed from world id + save/run seed
+ */
+export function seedForPlace(worldId, runSeed = "") {
+    return runSeed.length === 0 ? worldId : `${worldId}:${runSeed}`;
+}
+/**
+ * Resolves the physics laws in effect for the active world: a place world's own `physics` wins
+ * field-by-field over the game-level default. Non-place worlds (and games with no world) keep the
+ * game-level config unchanged.
+ */
+export function resolveWorldPhysics(worldFeature, base) {
+    if (worldFeature === undefined || worldFeature.kind !== "place" || worldFeature.physics === undefined)
+        return base;
+    return base === undefined ? worldFeature.physics : { ...base, ...worldFeature.physics };
+}
+/** Type guard for the place-model world feature. */
+export function isPlaceWorld(worldFeature) {
+    return worldFeature?.kind === "place";
+}

package/dist/world/placeAsset.js

@@ -7,10 +7,12 @@ function normalizePosition(position) {
     const t = position;
     return { x: t[0], y: t[1], z: t[2] };
 }
+let placementSequence = 0;
 function placementId(assetId, explicit) {
     if (explicit !== undefined && explicit.length > 0)
         return explicit;
-    return `placed_${assetId}_${Date.now().toString(36)}`;
+    placementSequence += 1;
+    return `placed_${assetId}_${Date.now().toString(36)}_${placementSequence.toString(36)}`;
 }
 /**
  * Resolve a place-asset intent into a shared payload (editor + games, one verb).

package/dist/world/poleLineKind.d.ts

@@ -0,0 +1,40 @@
+import { type Vec3 } from "./catenary.js";
+import { type ParamSchema, type ParsedParams, type SceneKindObject, type SceneKindResolveContext } from "../scene/sceneKinds.js";
+/**
+ * The editor path kind marking a polyline as a pole/cable run.
+ * @capability pole-line editor-authorable poles + sagging cables along a path
+ */
+export declare const POLE_LINE_KIND = "pole_line";
+/** One placed pole: grounded base position plus facing yaw along the run. */
+export interface Pole {
+    id: string;
+    position: Vec3;
+    yaw: number;
+}
+/** One resolved cable span: a point string to loft into a tube, plus its radius. */
+export interface Cable {
+    id: string;
+    points: Vec3[];
+    radius: number;
+}
+/** The renderable payload the resolver returns and the shell renderer consumes. */
+export interface ResolvedPoleLine {
+    poles: Pole[];
+    cables: Cable[];
+    poleHeight: number;
+    poleAsset: string;
+    /** Wires per span — drives the renderer's crossarm width and insulator count. */
+    wireCount: number;
+    /** Lateral spread between adjacent wires, meters — the renderer hangs insulators at these offsets. */
+    wireSpacing: number;
+}
+/** The pole-line parameter schema — drives the inspector and `meta` parse via the studio seam. */
+export declare const POLE_LINE_SCHEMA: ParamSchema;
+/**
+ * Resolve poles + cables from a document object's points and parsed params. Poles come from the
+ * generic `placeAlongPath` sampler; between each consecutive pair, `wireCount` parallel cables are
+ * strung with lateral offset and quadratic-Bézier `sag` (deeper on longer spans). Pure data.
+ */
+export declare function resolvePoleLine(object: SceneKindObject, params: ParsedParams, context?: SceneKindResolveContext): ResolvedPoleLine;
+/** Registers the pole-line scene kind (schema + resolver + inspector note). Called by `registerBuiltinSceneKinds`. @internal */
+export declare function registerPoleLineKind(): void;

package/dist/world/poleLineKind.js

@@ -0,0 +1,97 @@
+/**
+ * `pole_line` studio: poles + sagging cables strung along an editor-drawn path — power lines, fences,
+ * streetlight runs, ziplines. Pure config here (spacing/height/wire params + a resolver built from the
+ * generic `placeAlongPath` and `sagCurve` primitives); the instanced pole/cable meshes live in the
+ * `shell` renderer. An engine environment kind (like water/grass_field/soil) so wire runs are
+ * drawable and slider-authorable in every editor session and persisted in `editor.scene.json` —
+ * promoted from `examples/studios` for studio/editor parity (#1101).
+ */
+import { placeAlongPath } from "./pathInstances.js";
+import { sagCurve } from "./catenary.js";
+import { registerSceneKind, } from "../scene/sceneKinds.js";
+/**
+ * The editor path kind marking a polyline as a pole/cable run.
+ * @capability pole-line editor-authorable poles + sagging cables along a path
+ */
+export const POLE_LINE_KIND = "pole_line";
+/** The pole-line parameter schema — drives the inspector and `meta` parse via the studio seam. */
+export const POLE_LINE_SCHEMA = {
+    fields: [
+        { type: "text", key: "poleAsset", label: "pole asset", default: "", group: "poles" },
+        { type: "range", key: "spacing", label: "spacing", min: 2, max: 40, step: 0.5, default: 8, unit: "m", group: "poles" },
+        { type: "range", key: "poleHeight", label: "pole height", min: 1, max: 20, step: 0.25, default: 6, unit: "m", group: "poles" },
+        { type: "bool", key: "snapToTerrain", label: "snap to ground", default: true, group: "poles" },
+        { type: "action", key: "randomizePoles", label: "randomize poles", action: "randomize", group: "poles" },
+        { type: "range", key: "wireCount", label: "wires", min: 0, max: 8, step: 1, default: 3, group: "cables" },
+        { type: "range", key: "wireSpacing", label: "wire spread", min: 0, max: 3, step: 0.05, default: 0.5, unit: "m", group: "cables" },
+        { type: "range", key: "cableRadius", label: "cable radius", min: 0.01, max: 0.5, step: 0.01, default: 0.05, unit: "m", group: "cables" },
+        { type: "range", key: "sag", label: "sag", min: 0, max: 6, step: 0.1, default: 0.8, unit: "m", group: "cables" },
+        { type: "range", key: "sagPerMeter", label: "sag / m", min: 0, max: 0.3, step: 0.005, default: 0.04, group: "cables" },
+        { type: "range", key: "cableSegments", label: "cable smoothness", min: 2, max: 48, step: 1, default: 12, group: "cables" },
+        { type: "seed", key: "seed", label: "seed", default: "", group: "cables" },
+        { type: "action", key: "randomizeCables", label: "randomize cables", action: "randomize", group: "cables" },
+    ],
+    groups: [
+        { id: "poles", label: "Poles" },
+        { id: "cables", label: "Cables" },
+    ],
+};
+/**
+ * Resolve poles + cables from a document object's points and parsed params. Poles come from the
+ * generic `placeAlongPath` sampler; between each consecutive pair, `wireCount` parallel cables are
+ * strung with lateral offset and quadratic-Bézier `sag` (deeper on longer spans). Pure data.
+ */
+export function resolvePoleLine(object, params, context) {
+    const spacing = params["spacing"];
+    const poleHeight = params["poleHeight"];
+    const wireCount = Math.round(params["wireCount"]);
+    const wireSpacing = params["wireSpacing"];
+    const cableRadius = params["cableRadius"];
+    const sag = params["sag"];
+    const sagPerMeter = params["sagPerMeter"];
+    const cableSegments = Math.round(params["cableSegments"]);
+    const snap = params["snapToTerrain"];
+    const placed = placeAlongPath(object.points ?? [], {
+        spacing,
+        ...(snap && context?.sampleHeight !== undefined ? { sampleHeight: context.sampleHeight } : {}),
+    });
+    const poles = placed.map((instance) => ({ id: `${object.id}/pole/${instance.index}`, position: instance.position, yaw: instance.yaw }));
+    const cables = [];
+    if (wireCount > 0) {
+        for (let i = 0; i + 1 < poles.length; i += 1) {
+            const a = poles[i];
+            const b = poles[i + 1];
+            const dx = b.position[0] - a.position[0];
+            const dz = b.position[2] - a.position[2];
+            const span = Math.hypot(dx, dz) || 1;
+            const perpX = -dz / span;
+            const perpZ = dx / span;
+            const drop = sag + sagPerMeter * span;
+            const half = (wireCount - 1) / 2;
+            for (let w = 0; w < wireCount; w += 1) {
+                const offset = (w - half) * wireSpacing;
+                const topA = [a.position[0] + perpX * offset, a.position[1] + poleHeight, a.position[2] + perpZ * offset];
+                const topB = [b.position[0] + perpX * offset, b.position[1] + poleHeight, b.position[2] + perpZ * offset];
+                cables.push({ id: `${object.id}/cable/${i}/${w}`, points: sagCurve(topA, topB, drop, cableSegments), radius: cableRadius });
+            }
+        }
+    }
+    return { poles, cables, poleHeight, poleAsset: params["poleAsset"], wireCount, wireSpacing };
+}
+/** Registers the pole-line scene kind (schema + resolver + inspector note). Called by `registerBuiltinSceneKinds`. @internal */
+export function registerPoleLineKind() {
+    registerSceneKind({
+        kind: POLE_LINE_KIND,
+        target: "path",
+        label: "Pole line / cables",
+        pathShape: "line",
+        addCategory: "Studios",
+        accent: "#fbbf24",
+        schema: POLE_LINE_SCHEMA,
+        resolve: (object, params, context) => resolvePoleLine(object, params, context),
+        note: (object, params) => {
+            const resolved = resolvePoleLine(object, params);
+            return `${resolved.poles.length} poles · ${resolved.cables.length} cables`;
+        },
+    });
+}