spoint 0.1.584 → 0.1.586

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spoint",
-  "version": "0.1.584",
+  "version": "0.1.586",
   "description": "Physics and netcode SDK for multiplayer game servers",
   "type": "module",
   "workspaces": [

package/src/terrain/GrassPlacement.js

@@ -46,6 +46,7 @@ export function classify(x, z, frame, anchorField, h, cellIx, cellIz) {
   const temp = clim && Number.isFinite(clim.temp) ? clim.temp : 0.5
   const humidity = clim && Number.isFinite(clim.humidity) ? clim.humidity : 0.5
   if (clim && Number.isFinite(clim.seaBias) && clim.seaBias < GRASS.SEA_REJECT) return null
+  if (clim && clim.blocked === 'road') return null
 
   const ix = (cellIx !== undefined) ? cellIx : Math.round(x / GRASS.CELL)
   const iz = (cellIz !== undefined) ? cellIz : Math.round(z / GRASS.CELL)

package/src/terrain/RockPlacement.js

@@ -124,6 +124,7 @@ export function classify(x, z, frame, anchorField, h, cellIx, cellIz) {
   const erosion = clim && Number.isFinite(clim.erosion) ? clim.erosion : 0.3
   const humidity = clim && Number.isFinite(clim.humidity) ? clim.humidity : 0.5
   if (clim && Number.isFinite(clim.seaBias) && clim.seaBias < ROCK.SEA_REJECT) return null
+  if (clim && clim.blocked) return null
 
   // shares VEG.TREELINE (not a separately-hardcoded 4000) so rock elevation banding and tree treeline
   // normalization never silently diverge -- see ARIDITY_LINE/RELIEF_CALIBRATION_BASELINE above for the

package/src/terrain/SplineCarve.js

@@ -1,22 +1,3 @@
-// SplineCarve.js -- Catmull-Rom spline-based heightfield carving for rivers and roads.
-//
-// DESIGN: takes a sequence of control points, evaluates a Catmull-Rom spline through
-// them, and carves a channel of configurable width/depth into the heightfield along
-// the spline. Additionally marks the carved cells with a climate flag so vegetation
-// placement can skip them (no trees on roads/rivers; roads double as AI nav hints).
-//
-// This is a BAKE-TIME pass (runs once per world seed, not per-frame). The spline
-// evaluation is deterministic for a given set of control points.
-//
-// CLIMATE FLAGS: carved cells are recorded in a per-cell climate mask (a Set of packed
-// integer cell keys using the same cellKey scheme as HeightDelta.js/BiomeOverride.js)
-// so the existing ClimateCache/BiomeOverride pipeline can query them. A separate
-// `isCarved(key)` function is exported for placement code to check.
-
-// Packed integer cell key, matching HeightDelta.js/BiomeOverride.js convention.
-// CELL_M = 8 metres (matches ClimateCache.SECTOR_M and BiomeOverride.CELL_M for
-// sector-level granularity -- a road/river carve at this resolution is visible
-// at the same scale vegetation placement already samples climate).
 const CELL_M = 8
 const BIG = 1 << 23
 const OFF = BIG >> 1
@@ -25,11 +6,6 @@ function cellKey(cx, cz) {
   return (cx + OFF) * BIG + (cz + OFF)
 }
 
-/**
- * Evaluate a Catmull-Rom spline at parameter t (0..1 per segment).
- * Control points are {x, z} or [x, z] pairs.
- * Returns {x, z} interpolated point.
- */
 function catmullRom(p0, p1, p2, p3, t) {
   const getX = (p) => Array.isArray(p) ? p[0] : p.x
   const getZ = (p) => Array.isArray(p) ? p[1] : p.z
@@ -37,7 +13,6 @@ function catmullRom(p0, p1, p2, p3, t) {
   const t2 = t * t
   const t3 = t2 * t
 
-  // Catmull-Rom basis matrix
   const x = 0.5 * (
     (2 * getX(p1)) +
     (-getX(p0) + getX(p2)) * t +
@@ -54,15 +29,6 @@ function catmullRom(p0, p1, p2, p3, t) {
   return { x, z }
 }
 
-/**
- * Sample the spline at a uniform step size, returning an array of {x, z} points.
- * The spline is closed if `closed` is true (last point connects back to first).
- *
- * @param {Array} controlPoints - Array of {x,z} or [x,z] control points.
- * @param {number} stepSize - World-space distance between sampled points.
- * @param {boolean} [closed=false] - Whether the spline is closed.
- * @returns {Array<{x:number, z:number}>} Sampled spline points.
- */
 export function sampleSpline(controlPoints, stepSize, closed = false) {
   if (!controlPoints || controlPoints.length < 2) return []
   const pts = controlPoints
@@ -88,7 +54,6 @@ export function sampleSpline(controlPoints, stepSize, closed = false) {
     }
   }
 
-  // Add the final point if not closed
   if (!closed) {
     const last = pts[pts.length - 1]
     samples.push({ x: Array.isArray(last) ? last[0] : last.x, z: Array.isArray(last) ? last[1] : last.z })
@@ -97,22 +62,6 @@ export function sampleSpline(controlPoints, stepSize, closed = false) {
   return samples
 }
 
-/**
- * Carve a spline-based channel (river or road) into a heightfield.
- *
- * @param {Float32Array} heights - Input heightfield, width*width elements, row-major.
- * @param {number} width - Grid dimension (square).
- * @param {number} spacing - World-space distance between adjacent cells (metres).
- * @param {number} cornerX - World X of the heightfield corner (cell 0,0).
- * @param {number} cornerZ - World Z of the heightfield corner (cell 0,0).
- * @param {Array} controlPoints - Array of {x,z} or [x,z] control points.
- * @param {number} carveWidth - World-space width of the channel (metres).
- * @param {number} carveDepth - How deep to carve (metres, positive = lower).
- * @param {object} [opts] - Options.
- * @param {number} [opts.bankWidth=0] - Extra width for bank/shoulder feathering.
- * @param {string} [opts.flag='river'] - Climate flag: 'river' or 'road'.
- * @returns {{heights: Float32Array, carvedCells: Set<number>}} New heightfield and carved cell keys.
- */
 export function carveSpline(heights, width, spacing, cornerX, cornerZ, controlPoints, carveWidth, carveDepth, opts = {}) {
   if (!heights || width < 2 || !Number.isFinite(spacing) || spacing <= 0) return { heights, carvedCells: new Set() }
   if (!controlPoints || controlPoints.length < 2) return { heights, carvedCells: new Set() }
@@ -123,7 +72,6 @@ export function carveSpline(heights, width, spacing, cornerX, cornerZ, controlPo
   const out = new Float32Array(heights)
   const carvedCells = new Set()
 
-  // Sample the spline at half-cell spacing for dense coverage
   const sampleStep = spacing * 0.5
   const splinePoints = sampleSpline(controlPoints, sampleStep)
 
@@ -132,20 +80,18 @@ export function carveSpline(heights, width, spacing, cornerX, cornerZ, controlPo
   const halfWidth = carveWidth / 2
   const totalHalfWidth = halfWidth + bankWidth
 
-  // For each cell in the heightfield, check distance to the nearest spline point
   for (let iz = 0; iz < n; iz++) {
     for (let ix = 0; ix < n; ix++) {
       const wx = cornerX + ix * spacing
       const wz = cornerZ + iz * spacing
 
-      // Find minimum distance to spline
       let minDist = Infinity
       for (const sp of splinePoints) {
         const dx = wx - sp.x
         const dz = wz - sp.z
         const dist = Math.sqrt(dx * dx + dz * dz)
         if (dist < minDist) minDist = dist
-        if (minDist <= totalHalfWidth) break // early exit
+        if (minDist <= totalHalfWidth) break
       }
 
       if (minDist > totalHalfWidth) continue
@@ -153,17 +99,15 @@ export function carveSpline(heights, width, spacing, cornerX, cornerZ, controlPo
       const idx = iz * n + ix
       if (!Number.isFinite(out[idx])) continue
 
-      // Compute falloff: 1 inside carve width, cosine feather in bank region
       let falloff = 1
       if (minDist > halfWidth && bankWidth > 0) {
         falloff = 0.5 * (1 + Math.cos(((minDist - halfWidth) / bankWidth) * Math.PI))
       } else if (minDist > halfWidth) {
-        continue // no bank, hard edge
+        continue
       }
 
       out[idx] -= carveDepth * falloff
 
-      // Mark climate cells
       const cx = Math.floor(wx / CELL_M)
       const cz = Math.floor(wz / CELL_M)
       carvedCells.add(cellKey(cx, cz))
@@ -173,30 +117,111 @@ export function carveSpline(heights, width, spacing, cornerX, cornerZ, controlPo
   return { heights: out, carvedCells, flag }
 }
 
-/**
- * Check if a cell key is marked as carved (for use by vegetation placement code).
- * @param {Set<number>} carvedCells - Set of packed cell keys from carveSpline.
- * @param {number} cx - Cell X coordinate (in CELL_M units).
- * @param {number} cz - Cell Z coordinate (in CELL_M units).
- * @returns {boolean}
- */
 export function isCarved(carvedCells, cx, cz) {
   return carvedCells && carvedCells.has(cellKey(cx, cz))
 }
 
-/**
- * Create a climate-flag-aware wrapper for vegetation density queries.
- * Returns a function that, given a climate sample and cell coordinates,
- * returns the climate sample with density zeroed if the cell is carved.
- *
- * @param {Set<number>} carvedCells - Set of packed cell keys.
- * @returns {function} climateFilter(climate, cx, cz) -> climate | null
- */
 export function createCarvedClimateFilter(carvedCells) {
   if (!carvedCells || carvedCells.size === 0) return null
   return function carvedClimateFilter(climate, cx, cz) {
     if (!climate) return null
-    if (carvedCells.has(cellKey(cx, cz))) return null // exclude vegetation
+    if (carvedCells.has(cellKey(cx, cz))) return null
     return climate
   }
-}
+}
+
+export function createSplineCarveLayer() {
+  const cells = new Map()
+  const appliedSplines = []
+
+  function carve(controlPoints, width, depth, kind, baseHeightFn) {
+    if (!Array.isArray(controlPoints) || controlPoints.length < 2) return { touched: 0 }
+    if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(depth)) return { touched: 0 }
+    if (kind !== 'river' && kind !== 'road') return { touched: 0 }
+    const stepSize = Math.max(1, width * 0.5)
+    const spinePoints = sampleSpline(controlPoints, stepSize)
+    if (spinePoints.length === 0) return { touched: 0 }
+    const halfWidth = width * 0.5
+    let touched = 0
+    for (const sp of spinePoints) {
+      const sx = sp.x, sz = sp.z
+      const cx0 = Math.floor((sx - halfWidth) / CELL_M), cx1 = Math.ceil((sx + halfWidth) / CELL_M)
+      const cz0 = Math.floor((sz - halfWidth) / CELL_M), cz1 = Math.ceil((sz + halfWidth) / CELL_M)
+      for (let cz = cz0; cz <= cz1; cz++) {
+        for (let cx = cx0; cx <= cx1; cx++) {
+          const ccx = cx * CELL_M + CELL_M * 0.5, ccz = cz * CELL_M + CELL_M * 0.5
+          const dx = ccx - sx, dz = ccz - sz
+          const d = Math.hypot(dx, dz)
+          if (d > halfWidth) continue
+          const falloff = 0.5 * (1 + Math.cos((d / halfWidth) * Math.PI))
+          const key = cellKey(cx, cz)
+          const base = typeof baseHeightFn === 'function' ? baseHeightFn(ccx, ccz) : null
+          const targetDelta = Number.isFinite(base) ? -depth * falloff : 0
+          const prev = cells.get(key)
+          const nextDelta = prev ? Math.min(prev.delta, targetDelta) : targetDelta
+          const nextKind = prev && prev.kind === 'river' ? 'river' : kind
+          cells.set(key, { delta: nextDelta, kind: nextKind })
+          touched++
+        }
+      }
+    }
+    if (touched > 0) appliedSplines.push({ controlPoints: controlPoints.map(p => Array.isArray(p) ? [p[0], p[1]] : [p.x, p.z]), width, depth, kind })
+    return { touched }
+  }
+
+  function deltaAt(x, z) {
+    if (cells.size === 0) return 0
+    const cx = Math.floor(x / CELL_M), cz = Math.floor(z / CELL_M)
+    const c = cells.get(cellKey(cx, cz))
+    return c ? c.delta : 0
+  }
+
+  function kindAt(x, z) {
+    if (cells.size === 0) return null
+    const cx = Math.floor(x / CELL_M), cz = Math.floor(z / CELL_M)
+    const c = cells.get(cellKey(cx, cz))
+    return c ? c.kind : null
+  }
+
+  function wrapHeightFn(baseHeightFn) {
+    if (typeof baseHeightFn !== 'function') return baseHeightFn
+    return function splineCarveWrappedHeightFn(x, z) {
+      const base = baseHeightFn(x, z)
+      if (!Number.isFinite(base)) return base
+      return base + deltaAt(x, z)
+    }
+  }
+
+  function wrapClimateField(baseField) {
+    if (!baseField || typeof baseField.climateAtLocal !== 'function') return baseField
+    return {
+      ...baseField,
+      climateAtLocal(x, z) {
+        const base = baseField.climateAtLocal(x, z)
+        const kind = kindAt(x, z)
+        if (!kind) return base
+        return base ? { ...base, blocked: kind } : { blocked: kind }
+      },
+    }
+  }
+
+  function toJSON() { return { version: 1, cellM: CELL_M, splines: appliedSplines.slice() } }
+
+  function clear() { cells.clear(); appliedSplines.length = 0 }
+
+  return {
+    carve, deltaAt, kindAt, wrapHeightFn, wrapClimateField, toJSON, clear,
+    get cellCount() { return cells.size }, get splineCount() { return appliedSplines.length },
+  }
+}
+
+export function loadSplineCarveLayer(json, baseHeightFn) {
+  const layer = createSplineCarveLayer()
+  if (json && Array.isArray(json.splines)) {
+    for (const s of json.splines) {
+      if (!s || !Array.isArray(s.controlPoints) || !Number.isFinite(s.width) || !Number.isFinite(s.depth)) continue
+      layer.carve(s.controlPoints, s.width, s.depth, s.kind, baseHeightFn)
+    }
+  }
+  return layer
+}

package/src/terrain/TerrainPhysics.js

@@ -5,6 +5,7 @@ import { createPlanetFrame, DEFAULT_PATCH_MAX_LEVEL } from './PlanetFrame.js'
 import { createCachedAnchorField } from './ClimateCache.js'
 import { createHeightDelta, loadHeightDelta } from './HeightDelta.js'
 import { createBiomeOverride, loadBiomeOverride } from './BiomeOverride.js'
+import { loadSplineCarveLayer } from './SplineCarve.js'
 
 const _now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now())
 
@@ -234,7 +235,7 @@ async function createGpuPatchHeightFn({ frame, tcfg, offsetY }) {
 // (re)build -- kept strictly separate from tcfg/seed (never merged into it) so seeds stay shareable.
 // biomeOverrideJSON (optional): a previously-serialized src/terrain/BiomeOverride.js toJSON() payload
 // (paint-biome strokes), same replay discipline as heightDeltaJSON.
-export async function setupTerrainStreaming({ physics, playerManager, worldDef, terrain, heightDeltaJSON, biomeOverrideJSON }) {
+export async function setupTerrainStreaming({ physics, playerManager, worldDef, terrain, heightDeltaJSON, biomeOverrideJSON, splineCarveJSON }) {
   // accepts either the terrain app's merged tcfg directly, or legacy worldDef.terrain.
   const tcfg = terrain || (worldDef && worldDef.terrain) || null
   if (!tcfg || tcfg.enabled === false || !physics || typeof physics.addHeightField !== 'function') return null
@@ -249,7 +250,8 @@ export async function setupTerrainStreaming({ physics, playerManager, worldDef,
   // streamers below so a painted biome changes which species/how-dense a server collider places, not
   // just a cosmetic client-only readout.
   const biomeOverride = loadBiomeOverride(biomeOverrideJSON)
-  const paintedAnchorField = biomeOverride.wrapClimateField(cachedAnchorField)
+  const splineCarve = loadSplineCarveLayer(splineCarveJSON, (x, z) => frame.groundHeightLocal(x, z))
+  const paintedAnchorField = splineCarve.wrapClimateField(biomeOverride.wrapClimateField(cachedAnchorField))
   const offsetY = tcfg.offsetY || 0
   // preferred: live GPU patch baker (whole-planet, exact, nothing stored); falls back to baked .hf, then live CPU sampler.
   const gpuPatch = (tcfg.gpuPatchCollider !== false)
@@ -283,7 +285,7 @@ export async function setupTerrainStreaming({ physics, playerManager, worldDef,
   // stays byte-identical, sculpting is purely an on-top layer. heightDeltaJSON (if any) replays prior
   // strokes so a rebuild (reseed/streamer restart) keeps existing sculpting intact.
   const heightDelta = loadHeightDelta(heightDeltaJSON, baseHeightFn)
-  const heightFn = heightDelta.wrapHeightFn(baseHeightFn)
+  const heightFn = splineCarve.wrapHeightFn(heightDelta.wrapHeightFn(baseHeightFn))
   const getCenter = () => {
     let sx = 0, sz = 0, n = 0
     const players = playerManager && playerManager.players
@@ -359,6 +361,7 @@ export async function setupTerrainStreaming({ physics, playerManager, worldDef,
   // clearChunkCache header) since it memoizes classify() output for world lifetime and would otherwise
   // keep serving pre-paint species/density for already-visited territory.
   streamer.biomeOverride = biomeOverride
+  streamer.splineCarve = splineCarve
   streamer.repaintBiome = async function repaintBiome() {
     // Re-cook the FULL current multi-player ring (not just one point) so every connected player's
     // territory picks up the repaint, matching this row's "around each player" streaming policy.

package/src/terrain/VegPlacement.js

@@ -124,6 +124,7 @@ export function classify(x, z, frame, anchorField, h, cellIx, cellIz) {
   const humidity = clim && Number.isFinite(clim.humidity) ? clim.humidity : 0.5
   const erosion = clim && Number.isFinite(clim.erosion) ? clim.erosion : 0.3
   if (clim && Number.isFinite(clim.seaBias) && clim.seaBias < VEG.SEA_REJECT) return null
+  if (clim && clim.blocked) return null
 
   const base = baseDensity(temp, humidity, erosion)
   const ix = (cellIx !== undefined) ? cellIx : Math.round(x / VEG.CELL)