@jgengine/core 0.18.0 → 0.19.0

package/dist/world/terraform.d.ts

@@ -262,5 +262,13 @@ export interface TerraformBrush {
     config(): Required<Omit<TerraformBrushConfig, "surface">> & {
         surface: string | undefined;
     };
+    /** The retunable brush settings; the terrain keeps its own `snapshot()`. */
+    snapshot(): TerraformBrushState;
+    restore(next: TerraformBrushState): void;
+}
+/** Plain JSON state of a {@link TerraformBrush}. */
+export interface TerraformBrushState {
+    radius: number;
+    strength: number;
 }
 export declare function createTerraformBrush(terrain: Pick<EditableTerrain, "apply">, config?: TerraformBrushConfig): TerraformBrush;

package/dist/world/terraform.js

@@ -787,5 +787,12 @@ export function createTerraformBrush(terrain, config = {}) {
         config() {
             return { radius, strength, falloff, surface };
         },
+        snapshot() {
+            return { radius, strength };
+        },
+        restore(next) {
+            radius = next.radius;
+            strength = next.strength;
+        },
     };
 }

package/dist/world/terrain.d.ts

@@ -203,9 +203,13 @@ export interface ResolvedTerrainDetailMaterial {
     tint: number;
 }
 /** A {@link TerrainDetailConfig} with every field resolved to a concrete value — the shape the shell's detail material consumes. */
-export type ResolvedTerrainDetail = Required<Omit<TerrainDetailConfig, "waterLevel" | "material">> & {
+export type ResolvedTerrainDetail = Required<Omit<TerrainDetailConfig, "waterLevel" | "material" | "sweeps">> & {
     waterLevel: number;
     material?: ResolvedTerrainDetailMaterial;
+    sweeps: {
+        dry: readonly [number, number, number];
+        wet: readonly [number, number, number];
+    };
 };
 /** Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level.
  * @internal

package/dist/world/terrain.js

@@ -475,6 +475,7 @@ const DEFAULT_TERRAIN_DETAIL = {
     macroScale: 45,
     roughness: 0.9,
     strength: 1,
+    sweeps: { dry: [1.14, 1.05, 0.76], wet: [0.78, 1.0, 0.86] },
 };
 const DEFAULT_TERRAIN_MATERIAL_REPEAT = 4;
 const DEFAULT_TERRAIN_MATERIAL_STRENGTH = 1;
@@ -493,6 +494,10 @@ export function resolveTerrainDetail(config, terrainWaterLevel = 0) {
         macroScale: config.macroScale ?? DEFAULT_TERRAIN_DETAIL.macroScale,
         roughness: config.roughness ?? DEFAULT_TERRAIN_DETAIL.roughness,
         strength: clamp01(config.strength ?? DEFAULT_TERRAIN_DETAIL.strength),
+        sweeps: {
+            dry: config.sweeps?.dry ?? DEFAULT_TERRAIN_DETAIL.sweeps.dry,
+            wet: config.sweeps?.wet ?? DEFAULT_TERRAIN_DETAIL.sweeps.wet,
+        },
         waterLevel: config.waterLevel ?? terrainWaterLevel,
         ...(config.material === undefined
             ? {}

package/dist/world/territory.d.ts

@@ -0,0 +1,97 @@
+import type { GameRuntimeSnapshot } from "../runtime/snapshot.js";
+import type { Aabb } from "./geometry.js";
+/** Integer cell coordinates used for ownership on the ground plane. */
+export type TerritoryCell = {
+    x: number;
+    z: number;
+};
+/** Cell size, foreign-owner gap, growth price, currency and starter-grant policy. */
+export type TerritoryPolicy = {
+    gapCells?: number;
+    cellSize?: number;
+    chunkSize?: number;
+    currency?: string;
+    price?: (ownedCount: number) => number;
+    starterBlock?: number;
+    nowMs?: number;
+};
+/** Atomic claim outcome with the replacement snapshot and total charge. */
+export type TerritoryResult = {
+    ok: true;
+    snapshot: GameRuntimeSnapshot;
+    cost: number;
+} | {
+    ok: false;
+    reason: "territory.blocked" | "territory.unaffordable";
+};
+/** Read-only footprint quote or a blocked/insufficient-balance rejection. */
+export type TerritoryPlan = {
+    ok: true;
+    cells: TerritoryCell[];
+    cost: number;
+} | {
+    ok: false;
+    reason: "territory.blocked" | "territory.unaffordable";
+};
+/** Host-owned snapshot access used by the territory facade. */
+export interface TerritoryStorage {
+    get(): GameRuntimeSnapshot;
+    set(snapshot: GameRuntimeSnapshot): void;
+}
+/**
+ * Persisted chunk key containing one territory cell.
+ * @capability territory-cell-chunk Map ownership cells to persisted world chunks.
+ */
+export declare function territoryChunkKey(cell: TerritoryCell, policy?: TerritoryPolicy): string;
+/**
+ * Exact chunks needed to validate a footprint and its foreign-owner gap.
+ * @capability territory-read-scope Load the footprint and foreign-owner gap without scanning the world.
+ */
+export declare function territoryChunkKeys(cells: readonly TerritoryCell[], policy?: TerritoryPolicy): string[];
+/**
+ * Owner of a loaded cell; hosts load the target and gap neighborhood before evaluating claims.
+ * @capability territory-owner-query Read a loaded land cell owner for authoritative placement checks.
+ */
+export declare function territoryOwnerOf(snapshot: GameRuntimeSnapshot, cell: TerritoryCell, policy?: TerritoryPolicy): string | null;
+/**
+ * Cells touched by a placement, excluding cells that only touch its outer edge.
+ * @capability territory-footprint Resolve exactly the ownership cells touched by a placement footprint.
+ */
+export declare function territoryFootprintCells(bounds: Aabb, cellSize?: number): TerritoryCell[];
+/** Price and validate a footprint without mutating or charging; reuse for placement previews. */
+export declare function planFootprintClaims(snapshot: GameRuntimeSnapshot, userId: string, footprint: readonly TerritoryCell[], policy?: TerritoryPolicy): TerritoryPlan;
+/** Atomically buy every unowned footprint cell, leaving the input untouched on failure. */
+export declare function claimTerritory(snapshot: GameRuntimeSnapshot, userId: string, cells: readonly TerritoryCell[], policy?: TerritoryPolicy): TerritoryResult;
+/**
+ * Placement transaction: rejected object placement also rolls back territory and its charge.
+ * @capability territory-placement Purchase footprint cells atomically with object placement.
+ */
+export declare function placeWithTerritory(snapshot: GameRuntimeSnapshot, userId: string, bounds: Aabb, policy: TerritoryPolicy, place: (snapshot: GameRuntimeSnapshot) => {
+    ok: true;
+    snapshot: GameRuntimeSnapshot;
+} | {
+    ok: false;
+    reason: string;
+}): {
+    ok: true;
+    snapshot: GameRuntimeSnapshot;
+    cost: number;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Snapshot-backed territory facade with host-owned storage and live policy.
+ * @capability territory-ownership Claim, release and query land through host-owned snapshot storage.
+ */
+export declare function createTerritory(storage: TerritoryStorage, policy?: () => TerritoryPolicy): {
+    snapshot: () => GameRuntimeSnapshot;
+    restore: (snapshot: GameRuntimeSnapshot) => void;
+    ownerOf: (cell: TerritoryCell) => string | null;
+    canUse: (userId: string, cell: TerritoryCell) => boolean;
+    claim(userId: string, cells: readonly TerritoryCell[]): TerritoryResult;
+    release(userId: string, cell: TerritoryCell): boolean;
+    grantStarter(userId: string, center: TerritoryCell): TerritoryResult;
+};
+/** Snapshot-backed claim, release, owner and starter-grant operations. */
+export type Territory = ReturnType<typeof createTerritory>;

package/dist/world/territory.js

@@ -0,0 +1,182 @@
+import { chunkKeyAt, updateChunk } from "../runtime/worldChunks.js";
+function checked(policy) {
+    if (policy.nowMs !== undefined && !Number.isFinite(policy.nowMs))
+        throw new RangeError("Invalid territory timestamp");
+    const gapCells = policy.gapCells ?? 0, cellSize = policy.cellSize ?? 1, chunkSize = policy.chunkSize ?? 64;
+    if (!Number.isSafeInteger(gapCells) || gapCells < 0 || gapCells > 128 || !Number.isFinite(cellSize) || cellSize <= 0 || !Number.isFinite(chunkSize) || chunkSize <= 0)
+        throw new RangeError("Invalid territory policy");
+    return { gapCells, cellSize, chunkSize };
+}
+function key(cell) {
+    if (!Number.isSafeInteger(cell.x) || !Number.isSafeInteger(cell.z))
+        throw new RangeError("Invalid territory cell");
+    return `${cell.x},${cell.z}`;
+}
+/**
+ * Persisted chunk key containing one territory cell.
+ * @capability territory-cell-chunk Map ownership cells to persisted world chunks.
+ */
+export function territoryChunkKey(cell, policy = {}) {
+    key(cell);
+    const { cellSize, chunkSize } = checked(policy);
+    return chunkKeyAt([cell.x * cellSize, 0, cell.z * cellSize], chunkSize);
+}
+/**
+ * Exact chunks needed to validate a footprint and its foreign-owner gap.
+ * @capability territory-read-scope Load the footprint and foreign-owner gap without scanning the world.
+ */
+export function territoryChunkKeys(cells, policy = {}) {
+    const { gapCells } = checked(policy);
+    const chunks = new Set();
+    if (cells.length * (2 * gapCells + 1) ** 2 > 1_000_000)
+        throw new RangeError("Territory neighborhood is too large");
+    for (const cell of cells) {
+        key(cell);
+        for (let x = cell.x - gapCells; x <= cell.x + gapCells; x++) {
+            for (let z = cell.z - gapCells; z <= cell.z + gapCells; z++)
+                chunks.add(territoryChunkKey({ x, z }, policy));
+        }
+    }
+    return [...chunks];
+}
+/**
+ * Owner of a loaded cell; hosts load the target and gap neighborhood before evaluating claims.
+ * @capability territory-owner-query Read a loaded land cell owner for authoritative placement checks.
+ */
+export function territoryOwnerOf(snapshot, cell, policy = {}) {
+    return snapshot.chunks[territoryChunkKey(cell, policy)]?.territory?.[key(cell)] ?? null;
+}
+/**
+ * Cells touched by a placement, excluding cells that only touch its outer edge.
+ * @capability territory-footprint Resolve exactly the ownership cells touched by a placement footprint.
+ */
+export function territoryFootprintCells(bounds, cellSize = 1) {
+    if (!Number.isFinite(cellSize) || cellSize <= 0 || !Object.values(bounds).every(Number.isFinite) || bounds.maxX <= bounds.minX || bounds.maxZ <= bounds.minZ)
+        throw new RangeError("Invalid territory footprint");
+    const cells = [];
+    const minX = Math.floor(bounds.minX / cellSize), maxX = Math.ceil(bounds.maxX / cellSize) - 1;
+    const minZ = Math.floor(bounds.minZ / cellSize), maxZ = Math.ceil(bounds.maxZ / cellSize) - 1;
+    if ((maxX - minX + 1) * (maxZ - minZ + 1) > 65536)
+        throw new RangeError("Territory footprint is too large");
+    for (let x = minX; x <= maxX; x++)
+        for (let z = minZ; z <= maxZ; z++)
+            cells.push({ x, z });
+    return cells;
+}
+/** Price and validate a footprint without mutating or charging; reuse for placement previews. */
+export function planFootprintClaims(snapshot, userId, footprint, policy = {}) {
+    const { gapCells } = checked(policy);
+    if (footprint.length * (2 * gapCells + 1) ** 2 > 1_000_000)
+        throw new RangeError("Territory neighborhood is too large");
+    const player = snapshot.players[userId];
+    if (!player)
+        return { ok: false, reason: "territory.blocked" };
+    const cells = [], seen = new Set();
+    let cost = 0;
+    const owned = Number(player.territoryOwnedCount ?? 0);
+    if (!Number.isSafeInteger(owned) || owned < 0)
+        throw new RangeError("Invalid territory owned count");
+    for (const cell of footprint) {
+        const cellKey = key(cell);
+        if (seen.has(cellKey))
+            continue;
+        seen.add(cellKey);
+        const owner = territoryOwnerOf(snapshot, cell, policy);
+        if (owner === userId)
+            continue;
+        if (owner !== null)
+            return { ok: false, reason: "territory.blocked" };
+        for (let x = cell.x - gapCells; x <= cell.x + gapCells; x++)
+            for (let z = cell.z - gapCells; z <= cell.z + gapCells; z++) {
+                const neighbor = territoryOwnerOf(snapshot, { x, z }, policy);
+                if (neighbor !== null && neighbor !== userId)
+                    return { ok: false, reason: "territory.blocked" };
+            }
+        const price = policy.price?.(owned + cells.length) ?? 0;
+        if (!Number.isFinite(price) || price < 0)
+            throw new RangeError("Invalid territory price");
+        cost += price;
+        if (!Number.isFinite(cost))
+            throw new RangeError("Invalid territory cost");
+        cells.push(cell);
+    }
+    if (cost > 0 && (!policy.currency || (player.economy[policy.currency] ?? 0) < cost))
+        return { ok: false, reason: "territory.unaffordable" };
+    return { ok: true, cells, cost };
+}
+/** Atomically buy every unowned footprint cell, leaving the input untouched on failure. */
+export function claimTerritory(snapshot, userId, cells, policy = {}) {
+    const plan = planFootprintClaims(snapshot, userId, cells, policy);
+    if (!plan.ok)
+        return plan;
+    let next = snapshot;
+    for (const [index, cell] of plan.cells.entries())
+        next = updateChunk(next, territoryChunkKey(cell, policy), chunk => ({
+            ...chunk,
+            territory: { ...chunk.territory, [key(cell)]: userId },
+            territoryReceipts: { ...chunk.territoryReceipts, [key(cell)]: { claimedAt: policy.nowMs ?? 0, costPaid: policy.price?.(Number(snapshot.players[userId]?.territoryOwnedCount ?? 0) + index) ?? 0 } },
+        }));
+    if (plan.cells.length === 0)
+        return { ok: true, snapshot, cost: 0 };
+    const player = snapshot.players[userId];
+    next = { ...next, players: { ...next.players, [userId]: { ...player, territoryOwnedCount: Number(player.territoryOwnedCount ?? 0) + plan.cells.length, ownedTerritoryChunkKeys: [...new Set([...(player.ownedTerritoryChunkKeys ?? []), ...plan.cells.map(cell => territoryChunkKey(cell, policy))])], economy: policy.currency ? { ...player.economy, [policy.currency]: (player.economy[policy.currency] ?? 0) - plan.cost } : player.economy } }, dirty: { ...next.dirty, players: [...new Set([...next.dirty.players, userId])] } };
+    return { ok: true, snapshot: next, cost: plan.cost };
+}
+/**
+ * Placement transaction: rejected object placement also rolls back territory and its charge.
+ * @capability territory-placement Purchase footprint cells atomically with object placement.
+ */
+export function placeWithTerritory(snapshot, userId, bounds, policy, place) {
+    const claimed = claimTerritory(snapshot, userId, territoryFootprintCells(bounds, policy.cellSize), policy);
+    if (!claimed.ok)
+        return claimed;
+    const placed = place(claimed.snapshot);
+    return placed.ok ? { ...placed, cost: claimed.cost } : placed;
+}
+/**
+ * Snapshot-backed territory facade with host-owned storage and live policy.
+ * @capability territory-ownership Claim, release and query land through host-owned snapshot storage.
+ */
+export function createTerritory(storage, policy = () => ({})) {
+    return {
+        snapshot: () => storage.get(),
+        restore: (snapshot) => storage.set(snapshot),
+        ownerOf: (cell) => territoryOwnerOf(storage.get(), cell, policy()),
+        canUse: (userId, cell) => territoryOwnerOf(storage.get(), cell, policy()) === userId,
+        claim(userId, cells) {
+            const result = claimTerritory(storage.get(), userId, cells, policy());
+            if (result.ok)
+                storage.set(result.snapshot);
+            return result;
+        },
+        release(userId, cell) {
+            const snapshot = storage.get(), config = policy();
+            if (territoryOwnerOf(snapshot, cell, config) !== userId || !snapshot.players[userId])
+                return false;
+            let next = updateChunk(snapshot, territoryChunkKey(cell, config), chunk => {
+                const territory = { ...chunk.territory }, territoryReceipts = { ...chunk.territoryReceipts };
+                delete territory[key(cell)];
+                delete territoryReceipts[key(cell)];
+                return { ...chunk, territory, territoryReceipts };
+            });
+            const player = next.players[userId];
+            next = { ...next, players: { ...next.players, [userId]: { ...player, territoryOwnedCount: Math.max(0, Number(player.territoryOwnedCount ?? 0) - 1), ownedTerritoryChunkKeys: (player.ownedTerritoryChunkKeys ?? []).filter(chunkKey => chunkKey !== territoryChunkKey(cell, config) || Object.values(next.chunks[chunkKey]?.territory ?? {}).includes(userId)) } }, dirty: { ...next.dirty, players: [...new Set([...next.dirty.players, userId])] } };
+            storage.set(next);
+            return true;
+        },
+        grantStarter(userId, center) {
+            const config = policy(), width = config.starterBlock ?? 3;
+            if (!Number.isSafeInteger(width) || width < 1 || width > 128)
+                throw new RangeError("Invalid starter block");
+            const snapshot = storage.get();
+            if (Number(snapshot.players[userId]?.territoryOwnedCount ?? 0) > 0)
+                return { ok: true, snapshot, cost: 0 };
+            const startX = center.x - Math.floor(width / 2), startZ = center.z - Math.floor(width / 2);
+            const cells = territoryFootprintCells({ minX: startX, minZ: startZ, maxX: startX + width, maxZ: startZ + width });
+            const result = claimTerritory(snapshot, userId, cells, { ...config, price: () => 0 });
+            if (result.ok)
+                storage.set(result.snapshot);
+            return result;
+        },
+    };
+}

package/dist/world/walls.d.ts

@@ -50,6 +50,11 @@ export interface SurfacePaintStore {
 }
 /** @internal */
 export declare function createSurfacePaint(): SurfacePaintStore;
+/** Plain JSON state of a {@link WallDrawTool}: the drawn points and whether the loop is closed. */
+export interface WallDrawToolState {
+    points: Vec2[];
+    closed: boolean;
+}
 export interface WallDrawTool {
     addPoint(point: Vec2, snap?: number): Vec2;
     undo(): void;
@@ -60,6 +65,8 @@ export interface WallDrawTool {
     isClosed(): boolean;
     footprint(): EnclosedFootprint | null;
     roof(config?: RoofConfig): RoofPlan | null;
+    snapshot(): WallDrawToolState;
+    restore(next: WallDrawToolState): void;
 }
 /** @internal */
 export declare function createWallDrawTool(config?: {

package/dist/world/walls.js

@@ -220,6 +220,13 @@ export function createWallDrawTool(config = {}) {
             const fp = this.footprint();
             return fp === null ? null : autoRoof(fp, roofConfig);
         },
+        snapshot() {
+            return { points: pts.map((point) => [point[0], point[1]]), closed };
+        },
+        restore(next) {
+            pts = next.points.map((point) => [point[0], point[1]]);
+            closed = next.closed;
+        },
     };
 }
 /** @internal */

package/dist/world/worldSolids.d.ts

@@ -0,0 +1,84 @@
+import type { GeneratedBuilding } from "./buildings.js";
+import type { EnvironmentWorldFeature } from "./features.js";
+import type { Aabb } from "./geometry.js";
+import type { WallSegment } from "./walls.js";
+/** One solid box in world space: the collision half of generated or authored world geometry. */
+export interface WorldSolid {
+    center: readonly [number, number, number];
+    halfExtents: readonly [number, number, number];
+    /** Yaw about `center`, radians, in the engine's `rotationY` convention. Default `0`. */
+    rotationY?: number;
+}
+/** Serializable contents of a {@link WorldSolids}: every layer's solids by layer id. */
+export interface WorldSolidsState {
+    layers: Record<string, readonly WorldSolid[]>;
+}
+/**
+ * Static collision for world geometry that is not a scene object: generated buildings, studio
+ * volumes like `city`, wall runs. Solids live in named layers so a feature can replace or drop its
+ * own set without touching the rest. `solidObstaclesNear` (player and NPC movement),
+ * `syncWorldColliders` (physics backends) and `populateNavGridFromSolids` all read this one store.
+ */
+export interface WorldSolids {
+    /** Replace a layer's solids; an empty list removes the layer. */
+    set(layer: string, solids: readonly WorldSolid[]): void;
+    remove(layer: string): void;
+    /** Run several `set`/`remove` calls as one change: one index rebuild, one notification. */
+    batch(apply: () => void): void;
+    /** Solids in one layer, empty when absent. */
+    layer(layer: string): readonly WorldSolid[];
+    layers(): readonly string[];
+    /** Every solid whose world AABB overlaps `min`..`max`. Bounded by a uniform XZ hash grid. */
+    inBox(min: readonly [number, number, number], max: readonly [number, number, number]): WorldSolid[];
+    /** Every solid in every layer. */
+    all(): WorldSolid[];
+    count(): number;
+    /** Bumps on every change; cheap cache key for consumers. */
+    version(): number;
+    subscribe(listener: () => void): () => void;
+    snapshot(): WorldSolidsState;
+    restore(state: WorldSolidsState): void;
+}
+/**
+ * Yaw-expanded world AABB of an oriented solid box.
+ * @capability world-solid-bounds world AABB and nav footprint of a world solid
+ */
+export declare function worldSolidBounds(solid: WorldSolid): {
+    min: [number, number, number];
+    max: [number, number, number];
+};
+/**
+ * XZ footprint of a solid's world AABB, for 2D consumers such as nav grids.
+ * @capability world-solid-bounds world AABB and nav footprint of a world solid
+ */
+export declare function worldSolidFootprint(solid: WorldSolid): Aabb;
+/**
+ * A store of static world solids in named layers.
+ * @capability world-solids collision for generated and authored world geometry (buildings, city lots, walls)
+ */
+export declare function createWorldSolids(options?: {
+    cellSize?: number;
+}): WorldSolids;
+/**
+ * One solid per generated building: its `bounds` footprint turned by `rotationY` about `center`,
+ * from the ground under its center up through its floors. `groundHeight` defaults to flat `0`.
+ * @capability world-solids-from-data derive collision boxes from generated buildings and wall runs
+ */
+export declare function buildingSolids(buildings: readonly GeneratedBuilding[], groundHeight?: (x: number, z: number) => number): WorldSolid[];
+/**
+ * Solids for every `structures` descriptor on an environment feature, skipping any marked `solid: false`.
+ * @capability world-solids-from-data derive collision boxes from generated buildings and wall runs
+ */
+export declare function structureSolids(world: EnvironmentWorldFeature, groundHeight?: (x: number, z: number) => number): WorldSolid[];
+/** Wall height, thickness and base for {@link wallSolids}. */
+export interface WallSolidOptions {
+    height: number;
+    thickness: number;
+    /** Ground height under a point; the wall stands on it at each segment's midpoint. Default flat `0`. */
+    groundHeight?: (x: number, z: number) => number;
+}
+/**
+ * One oriented solid per wall segment (see `wallSegments` in `world/walls`).
+ * @capability world-solids-from-data derive collision boxes from generated buildings and wall runs
+ */
+export declare function wallSolids(segments: readonly WallSegment[], options: WallSolidOptions): WorldSolid[];