@jgengine/core 0.11.0 → 0.13.0

package/dist/world/terrain.d.ts

@@ -1,4 +1,4 @@
-import type { BiomeBand, EnvironmentWorldFeature, TerrainDetailConfig, TerrainEnvironmentConfig, TerrainEnvironmentDescriptor, TerrainIslandDescriptor, TerrainMaterial, TerrainMaterialMaps, WorldBounds, WorldFeature } from "./features.js";
+import type { BiomeBand, EnvironmentWorldFeature, RoadEnvironmentDescriptor, TerrainDetailConfig, TerrainEnvironmentConfig, TerrainEnvironmentDescriptor, TerrainIslandDescriptor, TerrainMaterial, TerrainMaterialMaps, WorldBounds, WorldFeature } from "./features.js";
 import type { AvoidZone } from "./geometry.js";
 import { type TerrainPathProfile } from "./pathTerrain.js";
 import type { TerraformSnapshot } from "./terraform.js";
@@ -107,6 +107,25 @@ export declare function flattenFieldAround(base: TerrainField, zones: readonly A
  * through the one seam every consumer already reads.
   * @internal
   */
+/**
+ * Drapes each `road()` ribbon's `elevation` onto the ground so a body standing on a road snaps to the
+ * road *surface* the renderer draws (`sampleHeight + elevation`), not the bare terrain beneath it. Without
+ * this the ground field and {@link RoadRibbons}/{@link CityRenderer} disagree by `elevation` per road, and
+ * anything grounded on a road — the player, NPCs, spawns via `groundHeightAt` — sinks by that offset into
+ * the asphalt. Overlapping ribbons (intersections) take the highest lift. Only `sampleHeight` is draped:
+ * the road ribbons are flat, so `sampleNormal` stays the smooth terrain normal — draping it too would spoof
+ * a near-vertical slope at every curb edge and trip slope-slide.
+ * @internal — reached through `environment({ roads })`; not called directly by games.
+ */
+export declare function roadDrapedField(base: TerrainField, roads: readonly RoadEnvironmentDescriptor[]): TerrainField;
+/**
+ * The full ground field for an environment world: base `terrain` composed with any `islands`, then
+ * any authored `sculpt` snapshot, then any `clearings`, then any `roads` draped on top — so an
+ * editor-sculpted heightfield drives both the rendered mesh and player collision, gameplay spots
+ * stay level, and anything grounded on a road stands on the drawn asphalt rather than the bare
+ * terrain beneath it, through the one seam every consumer already reads.
+ * @internal
+ */
 export declare function resolveEnvironmentField(feature: EnvironmentWorldFeature): TerrainField;
 export interface TerrainSlopeSample {
     /** Unit XZ direction pointing downhill; `[0, 0]` on level ground. */
@@ -124,6 +143,51 @@ export declare function sampleSlope(field: TerrainField, x: number, z: number):
   * @internal
   */
 export declare function slopeForce(field: TerrainField, x: number, z: number, scale?: number): readonly [number, number];
+/** XZ region a {@link raycastHeightField} march is clipped to. */
+export interface HeightFieldRayBounds {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+}
+/** Tuning for {@link raycastHeightField}: march resolution and refinement depth. */
+export interface HeightFieldRaycastOptions {
+    /** XZ region to march within; the ray is clipped to it before any sampling. */
+    bounds: HeightFieldRayBounds;
+    /**
+     * March step in world units. Use about half the field's cell size — features narrower than one
+     * step can be skipped. Defaults to 1/256 of the larger bounds span, clamped to `[0.25, 4]`.
+     */
+    step?: number;
+    /** Bisection iterations refining the crossing once found (default 8 ≈ step/256 precision). */
+    refine?: number;
+    /** Stop marching past this ray distance (default: the full bounds crossing). */
+    maxDistance?: number;
+    /**
+     * Hard cap on march samples (default 4096). Bounds the work for rays the XZ slab cannot clip —
+     * a near-vertical ray inside bounds has an enormous slab crossing, and an upward ray never
+     * meets the surface at all; the cap turns both into a prompt miss instead of a stall.
+     */
+    maxSteps?: number;
+}
+/** Where a {@link raycastHeightField} march crossed the surface. */
+export interface HeightFieldRayHit {
+    x: number;
+    y: number;
+    z: number;
+    /** Ray-parameter distance from the origin to the hit (direction is normalized internally). */
+    distance: number;
+}
+/**
+ * Intersects a ray with a `sampleHeight` field by fixed-step raymarching plus bisection — the
+ * O(steps) editor/gameplay picking seam that replaces brute-force triangle raycasts against a
+ * tessellated ground mesh (tens of thousands of triangle tests per pick on a sculpt-sized grid).
+ * The ray is clipped to `bounds` on XZ first, marched at `step`, and the first above→below
+ * crossing is bisected. An origin already under the surface hits immediately at entry. Returns
+ * null when the clipped ray never crosses the surface.
+ * @capability terrain-raycast pick a point on a heightfield along a camera/pointer ray
+ */
+export declare function raycastHeightField(sampleHeight: (x: number, z: number) => number, origin: readonly [number, number, number], direction: readonly [number, number, number], options: HeightFieldRaycastOptions): HeightFieldRayHit | null;
 export interface TerrainPalette {
     low: string;
     high: string;

package/dist/world/terrain.js

@@ -1,5 +1,5 @@
 import { withPathProfiles } from "./pathTerrain.js";
-import { nearestOnPath } from "./roads.js";
+import { isOnRoad, nearestOnPath } from "./roads.js";
 function clamp01(value) {
     return value < 0 ? 0 : value > 1 ? 1 : value;
 }
@@ -174,6 +174,10 @@ export function arenaField(config = {}) {
 export function groundFieldFor(world) {
     if (world !== undefined && world.kind === "environment")
         return resolveEnvironmentField(world);
+    // Place worlds (`world()` from world/place) stand on a flat baseline field: flat/board grounds are
+    // exactly y=0, while round/voxel grounds keep their sampled shape in the game's own generation
+    // systems (the substrate declaration never bakes a heightfield). Editor-authored sculpt still
+    // layers through the environment path above.
     return flatField();
 }
 /** Whether a world declares real terrain (base heightfield or islands) rather than a flat plane — gates terrain-floor sampling in the movement controllers.
@@ -304,15 +308,54 @@ export function flattenFieldAround(base, zones) {
  * through the one seam every consumer already reads.
   * @internal
   */
+/**
+ * Drapes each `road()` ribbon's `elevation` onto the ground so a body standing on a road snaps to the
+ * road *surface* the renderer draws (`sampleHeight + elevation`), not the bare terrain beneath it. Without
+ * this the ground field and {@link RoadRibbons}/{@link CityRenderer} disagree by `elevation` per road, and
+ * anything grounded on a road — the player, NPCs, spawns via `groundHeightAt` — sinks by that offset into
+ * the asphalt. Overlapping ribbons (intersections) take the highest lift. Only `sampleHeight` is draped:
+ * the road ribbons are flat, so `sampleNormal` stays the smooth terrain normal — draping it too would spoof
+ * a near-vertical slope at every curb edge and trip slope-slide.
+ * @internal — reached through `environment({ roads })`; not called directly by games.
+ */
+export function roadDrapedField(base, roads) {
+    if (roads.length === 0)
+        return base;
+    const sampleHeight = (x, z) => {
+        let lift = 0;
+        for (const road of roads) {
+            if (road.elevation > lift && isOnRoad(road.path, road.width, x, z))
+                lift = road.elevation;
+        }
+        return base.sampleHeight(x, z) + lift;
+    };
+    return {
+        sampleHeight,
+        sampleNormal: base.sampleNormal,
+        ...(base.bounds === undefined ? {} : { bounds: base.bounds }),
+        ...(base.waterLevel === undefined ? {} : { waterLevel: base.waterLevel }),
+    };
+}
+/**
+ * The full ground field for an environment world: base `terrain` composed with any `islands`, then
+ * any authored `sculpt` snapshot, then any `clearings`, then any `roads` draped on top — so an
+ * editor-sculpted heightfield drives both the rendered mesh and player collision, gameplay spots
+ * stay level, and anything grounded on a road stands on the drawn asphalt rather than the bare
+ * terrain beneath it, through the one seam every consumer already reads.
+ * @internal
+ */
 export function resolveEnvironmentField(feature) {
     const base = feature.terrain === undefined ? null : resolveTerrainField(feature.terrain);
     const composed = feature.islands === undefined || feature.islands.length === 0
         ? base ?? flatField()
         : composeIslandFields(base, feature.islands);
     const sculpted = feature.sculpt === undefined ? composed : sculptedField(composed, feature.sculpt);
-    return feature.clearings === undefined || feature.clearings.length === 0
+    const cleared = feature.clearings === undefined || feature.clearings.length === 0
         ? sculpted
         : flattenFieldAround(sculpted, feature.clearings);
+    return feature.roads === undefined || feature.roads.length === 0
+        ? cleared
+        : roadDrapedField(cleared, feature.roads);
 }
 /** Local slope from the field's normal — the input for gravity-roll, ski acceleration, and slide checks (#284.6).
  * @internal
@@ -338,6 +381,80 @@ export function slopeForce(field, x, z, scale = 9.8) {
         return [0, 0];
     return [nx * scale, nz * scale];
 }
+/**
+ * Intersects a ray with a `sampleHeight` field by fixed-step raymarching plus bisection — the
+ * O(steps) editor/gameplay picking seam that replaces brute-force triangle raycasts against a
+ * tessellated ground mesh (tens of thousands of triangle tests per pick on a sculpt-sized grid).
+ * The ray is clipped to `bounds` on XZ first, marched at `step`, and the first above→below
+ * crossing is bisected. An origin already under the surface hits immediately at entry. Returns
+ * null when the clipped ray never crosses the surface.
+ * @capability terrain-raycast pick a point on a heightfield along a camera/pointer ray
+ */
+export function raycastHeightField(sampleHeight, origin, direction, options) {
+    const length = Math.hypot(direction[0], direction[1], direction[2]);
+    if (length < 1e-12)
+        return null;
+    const dx = direction[0] / length;
+    const dy = direction[1] / length;
+    const dz = direction[2] / length;
+    const { bounds } = options;
+    // Clip [t0, t1] to the XZ slab of bounds.
+    let t0 = 0;
+    let t1 = options.maxDistance ?? Infinity;
+    for (const [o, d, min, max] of [
+        [origin[0], dx, bounds.minX, bounds.maxX],
+        [origin[2], dz, bounds.minZ, bounds.maxZ],
+    ]) {
+        if (Math.abs(d) < 1e-12) {
+            if (o < min || o > max)
+                return null;
+            continue;
+        }
+        const ta = (min - o) / d;
+        const tb = (max - o) / d;
+        const near = Math.min(ta, tb);
+        const far = Math.max(ta, tb);
+        if (near > t0)
+            t0 = near;
+        if (far < t1)
+            t1 = far;
+    }
+    if (t1 <= t0)
+        return null;
+    const spanX = bounds.maxX - bounds.minX;
+    const spanZ = bounds.maxZ - bounds.minZ;
+    const step = options.step ?? Math.min(4, Math.max(0.25, Math.max(spanX, spanZ) / 256));
+    const refine = options.refine ?? 8;
+    const maxSteps = options.maxSteps ?? 4096;
+    const above = (t) => origin[1] + dy * t - sampleHeight(origin[0] + dx * t, origin[2] + dz * t);
+    let prevT = t0;
+    if (above(t0) <= 0) {
+        return { x: origin[0] + dx * t0, y: origin[1] + dy * t0, z: origin[2] + dz * t0, distance: t0 };
+    }
+    let steps = 0;
+    while (prevT < t1 && steps < maxSteps) {
+        steps += 1;
+        const t = Math.min(prevT + step, t1);
+        if (above(t) <= 0) {
+            let lo = prevT;
+            let hi = t;
+            for (let i = 0; i < refine; i += 1) {
+                const mid = (lo + hi) / 2;
+                if (above(mid) <= 0)
+                    hi = mid;
+                else
+                    lo = mid;
+            }
+            const x = origin[0] + dx * hi;
+            const z = origin[2] + dz * hi;
+            return { x, y: sampleHeight(x, z), z, distance: hi };
+        }
+        if (t >= t1)
+            break;
+        prevT = t;
+    }
+    return null;
+}
 export const DEFAULT_TERRAIN_MATERIAL = "grass";
 export const TERRAIN_MATERIAL_PALETTES = {
     grass: { low: "#30402c", high: "#7f8b50", waterline: "#1d4c6e" },

package/dist/world.d.ts

@@ -22,7 +22,7 @@ export { assignFormationSlots, boxFormation, circleFormation, facingYaw, lineFor
 export { createGlideModel } from "./movement/glideModel.js";
 export { createGrappleSwing } from "./movement/grappleSwing.js";
 export { createLeaderTrail } from "./movement/leaderTrail.js";
-export { MOVEMENT_TUNING } from "./movement/movementModel.js";
+export { MOVEMENT_TUNING, type CollisionObstacle } from "./movement/movementModel.js";
 export { resolvePlayerMovementTuning, stepPlayerMovement } from "./movement/playerMovement.js";
 export { POSE_HITBOX, createPoseState, type MovementPose } from "./movement/poseState.js";
 export { steerYaw } from "./movement/steering.js";
@@ -37,14 +37,17 @@ export { createBuoyantBody } from "./physics/buoyancy.js";
 export { Carryable, carrySpeedMultiplier } from "./physics/carryable.js";
 export { createDamageModel } from "./physics/damageZones.js";
 export { tickDrivableVehicle } from "./physics/drivableVehicle.js";
+export { createAircraftDynamics, type AircraftDynamics, type AircraftKind, type AircraftOptions, type AircraftStep, type AircraftTuning, type FlightControlInput, type FlightControlRates, type FlightVector, } from "./physics/flightDynamics.js";
 export { ForceVolume, PlatformCarry } from "./physics/forceVolume.js";
-export { createKinematicVehicle, type KinematicVehicle, type KinematicVehicleStep, type KinematicVehicleTuning, } from "./physics/kinematicVehicle.js";
+export { combineGravity, pointGravity, uniformGravity, type GravityField, type GravityVector, type PointGravityOptions, } from "./physics/gravityField.js";
+export { createKinematicVehicle, type KinematicChassisTuning, type KinematicDynamicsTuning, type KinematicPowertrainTuning, type KinematicSteeringTuning, type KinematicVehicle, type KinematicVehicleStep, type KinematicVehicleTuning, } from "./physics/kinematicVehicle.js";
 export { PhysicsWorld, SHAPE_BOX, SHAPE_SPHERE, type AddBodyOptions, type CollisionEvent, type PhysicsStats, } from "./physics/physicsWorld.js";
 export { createRagdoll } from "./physics/ragdoll.js";
 export { SpatialGrid } from "./physics/spatialGrid.js";
 export { StructureGraph, type CollapseEvent, type StructureMaterial } from "./physics/structure.js";
 export { Glide, Grapple } from "./physics/traversal.js";
 export { DEFAULT_GRIP_CURVE, createVehicleBody, sampleGripCurve, type GripCurve } from "./physics/vehicleBody.js";
+export { createVehicleObstacleClamp, type VehicleImpact, type VehicleObstacleClamp, } from "./physics/vehicleObstacles.js";
 export { createAssetCatalog, type AssetCatalog, type ModelAssetRef, type ModelDims } from "./scene/assetCatalog.js";
 export { partsBounds, registerAssetGenerator, type GeneratedAsset, type GeneratedPart } from "./scene/assetGenerator.js";
 export { applyRotationPolicy, headingToRotationY, normalizeDegrees, parseAssetSpace, parseRotationPolicy, resolveAnchorOffset, resolveFacingRotationY, rotatedFootprint, rotationYToHeading, snapHeading, toEngineUnits, validateAssetSpace, type AssetAnchor, type AssetSpace, type AssetSpaceIssue, type PlacementRotationPolicy, } from "./scene/assetSpace.js";
@@ -62,7 +65,7 @@ export { MountController, createMountController } from "./scene/mount.js";
 export { objectVisualScale, type ObjectVisual, type SceneObject } from "./scene/objectStore.js";
 export { type PaintStroke } from "./scene/paintLayer.js";
 export { type RosterEntry } from "./scene/roster.js";
-export { parseParams, registerSceneKind, type ParamField, type ParamSchema, type ParsedParams, type SceneKindObject, type SceneKindResolveContext, type WeightedParamEntry, } from "./scene/sceneKinds.js";
+export { findSchemaPreset, parseParams, registerSceneKind, type ParamField, type ParamPreset, type ParamSchema, type ParsedParams, type SceneKindObject, type SceneKindResolveContext, type WeightedParamEntry, } from "./scene/sceneKinds.js";
 export { firstImpact, hitsUntilBlocked, type SceneRaycastApi, type SceneRaycastHit } from "./scene/sceneRaycast.js";
 export { createSelectionSet, isMarquee, screenRect, selectWithinRect, type ScreenRect, type SelectionSet, } from "./scene/selection.js";
 export { createSelectionBookmarks, recallSelectionBookmark, type BookmarkRecallMode, type RecallBookmarkOptions, type SelectionBookmarkSnapshot, type SelectionBookmarks, type SelectionPruneResult, } from "./scene/selectionBookmarks.js";
@@ -89,6 +92,9 @@ export { buildingIndex, type BuildingIndex } from "./world/buildingIndex.js";
 export { type BuildingPaletteOverrides, type BuildingStyle } from "./world/buildings.js";
 export { CarvableField, VoxelVolume, carvableTerrain, type VoxelMaterial } from "./world/carve.js";
 export { catenaryCurve, sagCurve } from "./world/catenary.js";
+export { type CityBlockKind } from "./world/cityBlocks.js";
+export { CITY_LOT_CLASSES, CITY_TREE_SPECIES, type CityLotClass, type CityLotPiece, type CityPieceRole, type CityPieceShape, type CityTreeSpecies, type CityZoneBand, type CityZoneProfile, } from "./world/cityContent.js";
+export { CITY_DEFAULTS, CITY_KIND, CITY_SCHEMA, CITY_ZONE_KIND, CITY_ZONE_SCHEMA, resolveCityObject, type CityBlock, type CityBridge, type CityDriveway, type CityHedge, type CityIntersection, type CityLight, type CityLot, type CityParcel, type CityParcelFrontageOut, type CityPark, type CityParking, type CityResolveContext, type CityRules, type CityStreet, type CityTree, type ResolvedCity, } from "./world/cityKind.js";
 export { snapToNearest, socketWorldPosition, socketsCompatible, worldSockets } from "./world/connectors.js";
 export { createEnvironmentField, type EnvironmentField, type HeatSource } from "./world/envField.js";
 export { resolveStructureBuildings, summarizeEnvironment } from "./world/environmentSummary.js";
@@ -100,14 +106,17 @@ export { GRASS_SCHEMA } from "./world/grassKind.js";
 export { resolveGridInstances } from "./world/gridInstances.js";
 export { createLodScheduler } from "./world/lod.js";
 export { mapLayerColor, type MapCellStates, type MapRoute, type MapZone } from "./world/mapLayers.js";
-export { DEFAULT_MARKER_KINDS, createMarkerSet, markerKindStyle, type MapMarker, type MarkerKindStyle, type MarkerSet, } from "./world/markers.js";
+export { DEFAULT_MARKER_KINDS, createMarkerSet, createMarkerSource, markerKindStyle, type MapMarker, type MarkerCollection, type MarkerKindStyle, type MarkerSet, type MarkerSource, type MarkerSourceOptions, type MarkerView, } from "./world/markers.js";
 export { bearingToCardinal, clampToMinimapEdge, compassBearing, headingToBearing, projectToMinimap, relativeBearing, unprojectFromMinimap, type Cardinal, type MinimapView, type WorldXZ, } from "./world/minimap.js";
+export { DEFAULT_MINIMAP_PALETTE, bakeMinimapBackground, bakeMinimapImage, encodeBakePng, minimapBakeToPngDataUri, type MinimapBake, type MinimapBakeBounds, type MinimapBakeOptions, type MinimapBakePalette, type MinimapBakeSource, type MinimapBakeZone, } from "./world/minimapBake.js";
 export { placeAlongPath } from "./world/pathInstances.js";
 export { withPathProfiles, type PathHeightPolicy, type PathRetaining, type TerrainPathProfile, } from "./world/pathTerrain.js";
+export { isPlaceWorld, resolveWorldPhysics, seedForPlace, world, type BoardGround, type BoardGroundSize, type FlatGround, type FlatGroundSize, type GroundConfig, type GroundGenerator, type GroundMode, type PlaceConfig, type PlaceWorldFeature, type ResolvedGround, type RoundGround, type RoundGroundSize, type SurfaceLaws, type VoxelGround, type VoxelGroundSize, } from "./world/place.js";
 export { placeAssetFromCommit, resolvePlaceAsset, toEditorMarker, toStructureInput, type PlaceAssetResult, } from "./world/placeAsset.js";
 export { createPlacedStructureStore, type PlacedStructure } from "./world/placedStructureStore.js";
 export { validatePlacement, type PlacementRules } from "./world/placement.js";
 export { createPlacementController, quarterTurnsToRotationY, type PlacementCommit, type PlacementController, type PlacementPreview, type SnapMode, } from "./world/placementController.js";
+export { POLE_LINE_SCHEMA, resolvePoleLine, type ResolvedPoleLine } from "./world/poleLineKind.js";
 export { composeRealm } from "./world/realm.js";
 export { createRegionField, isRegionField, type RegionField } from "./world/regions.js";
 export { buildRoadRibbon, dashSegments } from "./world/roads.js";
@@ -116,7 +125,7 @@ export { pickWeighted, scatterItems, type ScatterInstance } from "./world/scatte
 export { SCATTER_PATH_KIND, clearanceZonesFrom, distanceToPolygonEdge, isScatterPath, pointInPolygon, polygonArea, polygonBounds, readScatterPalette, readScatterRules, resolveScatter, resolveScatterRegion, scatterRegionEstimate, scatterRegionFromPath, type ScatterTerrain, } from "./world/scatterRegion.js";
 export { SOIL_KIND, SOIL_SCHEMA, type SoilRules } from "./world/soilKind.js";
 export { annulusRegion, boxRegion, customRegion, discRegion, pointSetRegion, polygonRegion, rectRegion, sampleBatch, samplePoint, sampleStratified, shellRegion, sphereRegion, weightedRegion, type AreaDistribution, type FallbackPolicy, type Point3, type RadialDistribution, type SampleBatchOptions, type SampleBatchResult, type SampleConstraints, type SamplePoint, type SamplePointOptions, type SampleReason, type SampleRegion, type SampleResult, type StratifiedOptions, type VolumeDistribution, type WeightedRegionEntry, } from "./world/spatialSample.js";
-export { furnitureSpots, laneCenters, offsetPath, parkingSpots, sidewalkPoint, sidewalkWidthOf, } from "./world/streets.js";
+export { distanceToRoadEdge, furnitureSpots, laneCenters, offsetPath, parkingSpots, roadSurfaceSampler, sidewalkPoint, sidewalkWidthOf, type RoadSurfaceOptions, } from "./world/streets.js";
 export { solveSupport, toDebrisBodies, type SupportResult } from "./world/support.js";
 export { applyDeltaToSnapshot, applySurfaceDeltaToSnapshot, beginSurfaceStroke, beginTerraformStroke, createEditableTerrain, createTerraformBrush, createTerrainSnapshot, editableTerrainFromSnapshot, migrateTerrainSnapshot, revertDeltaFromSnapshot, revertSurfaceDeltaFromSnapshot, type EditableTerrain, type SurfaceDelta, type SurfaceStroke, type TerraformDelta, type TerraformEdit, type TerraformFalloff, type TerraformMode, type TerraformShape, type TerraformSnapshot, type TerraformStroke, type TerrainMaterialLayer, type TerrainSurfaceRule, } from "./world/terraform.js";
 export { TERRAIN_MATERIAL_PALETTES, applyPathProfiles, type NoiseFieldConfig, type ResolvedTerrainDetail, type TerrainField, type TerrainPalette, } from "./world/terrain.js";

package/dist/world.js

@@ -37,7 +37,9 @@ export { createBuoyantBody } from "./physics/buoyancy.js";
 export { Carryable, carrySpeedMultiplier } from "./physics/carryable.js";
 export { createDamageModel } from "./physics/damageZones.js";
 export { tickDrivableVehicle } from "./physics/drivableVehicle.js";
+export { createAircraftDynamics, } from "./physics/flightDynamics.js";
 export { ForceVolume, PlatformCarry } from "./physics/forceVolume.js";
+export { combineGravity, pointGravity, uniformGravity, } from "./physics/gravityField.js";
 export { createKinematicVehicle, } from "./physics/kinematicVehicle.js";
 export { PhysicsWorld, SHAPE_BOX, SHAPE_SPHERE, } from "./physics/physicsWorld.js";
 export { createRagdoll } from "./physics/ragdoll.js";
@@ -45,6 +47,7 @@ export { SpatialGrid } from "./physics/spatialGrid.js";
 export { StructureGraph } from "./physics/structure.js";
 export { Glide, Grapple } from "./physics/traversal.js";
 export { DEFAULT_GRIP_CURVE, createVehicleBody, sampleGripCurve } from "./physics/vehicleBody.js";
+export { createVehicleObstacleClamp, } from "./physics/vehicleObstacles.js";
 export { createAssetCatalog } from "./scene/assetCatalog.js";
 export { partsBounds, registerAssetGenerator } from "./scene/assetGenerator.js";
 export { applyRotationPolicy, headingToRotationY, normalizeDegrees, parseAssetSpace, parseRotationPolicy, resolveAnchorOffset, resolveFacingRotationY, rotatedFootprint, rotationYToHeading, snapHeading, toEngineUnits, validateAssetSpace, } from "./scene/assetSpace.js";
@@ -62,7 +65,7 @@ export { MountController, createMountController } from "./scene/mount.js";
 export { objectVisualScale } from "./scene/objectStore.js";
 export {} from "./scene/paintLayer.js";
 export {} from "./scene/roster.js";
-export { parseParams, registerSceneKind, } from "./scene/sceneKinds.js";
+export { findSchemaPreset, parseParams, registerSceneKind, } from "./scene/sceneKinds.js";
 export { firstImpact, hitsUntilBlocked } from "./scene/sceneRaycast.js";
 export { createSelectionSet, isMarquee, screenRect, selectWithinRect, } from "./scene/selection.js";
 export { createSelectionBookmarks, recallSelectionBookmark, } from "./scene/selectionBookmarks.js";
@@ -89,6 +92,9 @@ export { buildingIndex } from "./world/buildingIndex.js";
 export {} from "./world/buildings.js";
 export { CarvableField, VoxelVolume, carvableTerrain } from "./world/carve.js";
 export { catenaryCurve, sagCurve } from "./world/catenary.js";
+export {} from "./world/cityBlocks.js";
+export { CITY_LOT_CLASSES, CITY_TREE_SPECIES, } from "./world/cityContent.js";
+export { CITY_DEFAULTS, CITY_KIND, CITY_SCHEMA, CITY_ZONE_KIND, CITY_ZONE_SCHEMA, resolveCityObject, } from "./world/cityKind.js";
 export { snapToNearest, socketWorldPosition, socketsCompatible, worldSockets } from "./world/connectors.js";
 export { createEnvironmentField } from "./world/envField.js";
 export { resolveStructureBuildings, summarizeEnvironment } from "./world/environmentSummary.js";
@@ -100,14 +106,17 @@ export { GRASS_SCHEMA } from "./world/grassKind.js";
 export { resolveGridInstances } from "./world/gridInstances.js";
 export { createLodScheduler } from "./world/lod.js";
 export { mapLayerColor } from "./world/mapLayers.js";
-export { DEFAULT_MARKER_KINDS, createMarkerSet, markerKindStyle, } from "./world/markers.js";
+export { DEFAULT_MARKER_KINDS, createMarkerSet, createMarkerSource, markerKindStyle, } from "./world/markers.js";
 export { bearingToCardinal, clampToMinimapEdge, compassBearing, headingToBearing, projectToMinimap, relativeBearing, unprojectFromMinimap, } from "./world/minimap.js";
+export { DEFAULT_MINIMAP_PALETTE, bakeMinimapBackground, bakeMinimapImage, encodeBakePng, minimapBakeToPngDataUri, } from "./world/minimapBake.js";
 export { placeAlongPath } from "./world/pathInstances.js";
 export { withPathProfiles, } from "./world/pathTerrain.js";
+export { isPlaceWorld, resolveWorldPhysics, seedForPlace, world, } from "./world/place.js";
 export { placeAssetFromCommit, resolvePlaceAsset, toEditorMarker, toStructureInput, } from "./world/placeAsset.js";
 export { createPlacedStructureStore } from "./world/placedStructureStore.js";
 export { validatePlacement } from "./world/placement.js";
 export { createPlacementController, quarterTurnsToRotationY, } from "./world/placementController.js";
+export { POLE_LINE_SCHEMA, resolvePoleLine } from "./world/poleLineKind.js";
 export { composeRealm } from "./world/realm.js";
 export { createRegionField, isRegionField } from "./world/regions.js";
 export { buildRoadRibbon, dashSegments } from "./world/roads.js";
@@ -116,7 +125,7 @@ export { pickWeighted, scatterItems } from "./world/scatterItems.js";
 export { SCATTER_PATH_KIND, clearanceZonesFrom, distanceToPolygonEdge, isScatterPath, pointInPolygon, polygonArea, polygonBounds, readScatterPalette, readScatterRules, resolveScatter, resolveScatterRegion, scatterRegionEstimate, scatterRegionFromPath, } from "./world/scatterRegion.js";
 export { SOIL_KIND, SOIL_SCHEMA } from "./world/soilKind.js";
 export { annulusRegion, boxRegion, customRegion, discRegion, pointSetRegion, polygonRegion, rectRegion, sampleBatch, samplePoint, sampleStratified, shellRegion, sphereRegion, weightedRegion, } from "./world/spatialSample.js";
-export { furnitureSpots, laneCenters, offsetPath, parkingSpots, sidewalkPoint, sidewalkWidthOf, } from "./world/streets.js";
+export { distanceToRoadEdge, furnitureSpots, laneCenters, offsetPath, parkingSpots, roadSurfaceSampler, sidewalkPoint, sidewalkWidthOf, } from "./world/streets.js";
 export { solveSupport, toDebrisBodies } from "./world/support.js";
 export { applyDeltaToSnapshot, applySurfaceDeltaToSnapshot, beginSurfaceStroke, beginTerraformStroke, createEditableTerrain, createTerraformBrush, createTerrainSnapshot, editableTerrainFromSnapshot, migrateTerrainSnapshot, revertDeltaFromSnapshot, revertSurfaceDeltaFromSnapshot, } from "./world/terraform.js";
 export { TERRAIN_MATERIAL_PALETTES, applyPathProfiles, } from "./world/terrain.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "jgengine core — agent-first game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. https://jgengine.com",
   "keywords": [
     "jgengine",

package/skills/game-design/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: game-design
+description: Design, audit, implement, and validate player experience, loops, systems, progression, and balance.
+---
+
+# Game design
+
+## Ownership
+
+Own the intended player experience and the rules that produce it: fantasy, pillars, verbs, decisions, feedback, loops, resources, progression, challenge, failure, onboarding, and social dynamics. Treat design claims as hypotheses proved by play, not a feature inventory or genre imitation — no genre kits, presets, or archetypes; every game is a custom composition of needs (see [AGENTS.md](../../../AGENTS.md)).
+
+Use `level-design` for spatial realization; route implementation to `jgengine-gameplay`, `jgengine-world`, `jgengine-combat`, `jgengine-ui`, `jgengine-multiplayer` once intent is coherent.
+
+Read [references/application-playbook.md](references/application-playbook.md) only when the task explicitly calls for design depth — a design brief, a redesign, or "make this fun/better" work; it is not a mandatory step of creating a game. Read [references/field-guide.md](references/field-guide.md) when the task needs deeper loop, economy, progression, genre, accessibility, or research guidance.
+
+## Choose the mode
+
+Greenfield: produce a vertical-slice contract (promise, pillars, core decision, loops, progression, failure/recovery) and build the smallest slice testing the riskiest assumption — see playbook §1. Existing game: reconstruct what it actually does from code and play, rank root problems by impact/confidence/reach/effort — see playbook §2.
+
+“Improve with game design” is an implementation request, not just an audit: select the highest-leverage intervention, implement it through shared engine seams, and prove the changed player behavior.
+
+## Required output contract
+
+Every design pass yields an observed journey, a north star (promise, pillars, anti-pillars, core decision), a loop/flow model, a ranked bottleneck list with cited evidence, an intervention stack, a chosen design slice, and acceptance evidence. See [references/application-playbook.md](references/application-playbook.md) for the full contract and execution rules (verb->feedback->consequence chains, loop/progression/challenge discipline, upstream ownership).
+
+## Completion
+
+An audit is not completion for a build/improve request. Finish when the slice is playable, a fresh player can state goal/choice/consequence, failure/recovery behave as intended, and evidence supports the pillars. Use `jgengine-verify` and `workflow` to ship.

package/skills/game-design/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Game Design"
+  short_description: "Design coherent game loops and systems"
+  default_prompt: "Use $game-design to audit or design this game, implement its highest-leverage design slice, and prove the changed player behavior."

package/skills/game-design/references/application-playbook.md

@@ -0,0 +1,170 @@
+# Applying game design
+
+Use this playbook to turn a pitch or an existing game into implemented, testable change. Its purpose is to prevent “design work” from ending as generic advice.
+
+## Contents
+
+1. Greenfield procedure
+2. Existing-game audit
+3. Mandatory models
+4. Ranking interventions
+5. Design-slice specification
+6. Implementation and proof
+7. Failure modes
+
+## 1. Greenfield procedure
+
+### Frame the bet
+
+Write a compact contract before broad code or content:
+
+| Field | Required form |
+| --- | --- |
+| audience/context | prior skills, player count, platform/input, session length, accessibility assumptions |
+| player promise | “The player repeatedly [verb/decision] so they feel [specific experience]” |
+| pillars | two or three observable behaviors or feelings |
+| anti-pillars | experiences the game must not drift toward |
+| core decision | situation, known information, viable options, tradeoff, consequence, recurrence |
+| completion proof | one end-to-end scenario a target player can perform and explain |
+| falsifier | observation that would show the design does not work |
+
+### Build the minimum design
+
+1. Model each core verb from cue through future consequence.
+2. Draw moment, encounter, session, and meta loops.
+3. Draw resources and feedback structures.
+4. Map player skills and progression channels.
+5. Define failure, recovery, stopping, and replay.
+6. Create a content grammar: a small set of mechanics crossed with contexts and constraints.
+7. Select the riskiest assumption and build one vertical design slice around it.
+
+Do not build the entire feature list first. A vertical slice contains real input, meaningful state, feedback, one decision that recurs, failure/recovery, and a downstream consequence.
+
+## 2. Existing-game audit
+
+### Reconstruct reality
+
+Inspect actual code, catalogs, scene documents, UI, tests, captures, and live play. Do not infer the game from its title or README.
+
+Trace four journeys when applicable:
+
+- **first minute:** first input, goal, threat, reward, confusion, and reason to continue
+- **first objective:** learning sequence, decisions, failure, recovery, payoff, and next goal
+- **representative session:** loop renewal, variety, resource pressure, build choices, pacing, and stopping point
+- **campaign/meta:** unlock cadence, content reuse, escalation, economy stability, mastery, and ending/replay
+
+For each journey, record timestamps or event order:
+
+`cue -> player belief -> action -> system response -> feedback -> state change -> next choice`
+
+Mark dead time, repeated decisions, forced actions, hidden consequences, false affordances, unexplained failure, and rewards that do not alter later play.
+
+### Build a system-coupling map
+
+Inventory verbs, enemies/problems, items/tools, progression, economy, quests/objectives, world states, social systems, and failure. For each system ask:
+
+- Which pillar does it serve?
+- Which loop consumes its output?
+- What player decision does it create or transform?
+- Where is it taught, tested, combined, and mastered?
+- What happens if it is removed?
+
+Flag systems that are present but disconnected, content whose only variation is numbers or nouns, and rewards that bypass the core play.
+
+### Diagnose decision density
+
+Do not maximize decisions per second. Find long spans where the player executes an already-solved action without new information, tradeoffs, expression, pressure, or mastery. Measure:
+
+- time to first meaningful decision
+- meaningful decisions per encounter/objective
+- time between new information and commitment
+- percentage of objectives using each verb or decision type
+- repeated content before context changes
+- time from failure to a useful retry
+
+## 3. Mandatory models
+
+### Loop table
+
+| Horizon | Cue/goal | Decision/action | Feedback | State changed | Why repeat? | Failure risk |
+| --- | --- | --- | --- | --- | --- | --- |
+
+Reject any row whose “state changed” or “why repeat” is empty.
+
+### Resource-flow table
+
+| Resource | Source | Store/cap | Spend/convert | Sink | Player decision | Feedback/runaway risk |
+| --- | --- | --- | --- | --- | --- | --- |
+
+Include time, health, space, information, attention, action opportunities, and social trust when relevant.
+
+### Progression table
+
+| Unlock/reward | Channel | New decision or capability | Content it recontextualizes | Risk of invalidation/grind | Proof |
+| --- | --- | --- | --- | --- | --- |
+
+Channels are mastery, access, breadth, power, and expression/status. Passive percentages without a changed decision must justify their place.
+
+### Objective/encounter variety matrix
+
+Cross objective verbs with information state, constraints, enemy/problem behavior, topology, resource pressure, failure condition, and consequence. This exposes campaigns where every mission is the same verb with different nouns.
+
+## 4. Ranking interventions
+
+Separate symptoms from root causes. “Quests are boring” is a symptom. “Every quest uses the same kill-count transition and no objective changes space, resources, or strategy” is a testable cause.
+
+Rank each candidate:
+
+| Candidate | Player behavior changed | Pillar impact | Reach | Evidence/confidence | Effort/risk | Dependencies | Shared owner |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+
+Use three horizons:
+
+- **Minimum correction:** remove the largest contradiction or unblock the loop.
+- **Strong target:** make one representative slice deliver the promise end to end.
+- **Multiplier:** expand the proven grammar across content, progression, social play, or replay.
+
+Choose by leverage, not novelty. Prefer a change that improves many encounters or future games over bespoke content with the same underlying decision.
+
+## 5. Design-slice specification
+
+The selected slice must state:
+
+- before behavior and evidence
+- target behavior and player belief
+- mechanics/dynamics expected to cause the change
+- objective/encounter sequence and pacing beats
+- resources, rewards, failure, recovery, and downstream consequence
+- affected catalogs/config, shared package seams, scene semantics, UI feedback, and tests
+- tuning variables with starting hypotheses and safe bounds
+- explicit non-goals and content held constant
+- acceptance scenario and falsifiers
+
+If another game could use the mechanic, define the package primitive first and adopt it here. Keep game-local code for content and feel.
+
+## 6. Implementation and proof
+
+When the user asks to build or improve:
+
+1. Implement the shared primitive or use an existing capability.
+2. Adopt it in one complete game slice.
+3. Author spatial content through `level-design` and the editor.
+4. Add deterministic tests for transitions, resources, failure, and progression.
+5. Exercise the observable scenario with representative input.
+6. Capture before/after evidence for behavior, not only appearance.
+7. Evaluate the falsifier honestly; revise or remove a failed intervention.
+
+Useful evidence includes time to first decision, objective completion, route choice, build choice, resource state, failure cause, retry time, objective-verb distribution, and a player’s ability to explain goal/action/consequence. Metrics need a named hypothesis; do not optimize them in isolation.
+
+## 7. Failure modes
+
+- producing a long GDD instead of a playable slice
+- listing features without naming changed decisions
+- adding content to a shallow objective grammar
+- using passive progression to disguise unchanged play
+- copying a genre’s surface without its causal dynamics
+- treating more rewards as more motivation
+- fixing comprehension only with text or HUD
+- reporting a diagnosis after the user asked for improvement
+- calling deterministic tests proof that the experience works
+- calling a prettier screenshot proof that the loop works