@jgengine/core 0.10.0 → 0.11.0

package/dist/world/segment.js

@@ -0,0 +1,43 @@
+/** Closest point on the segment `a`→`b` to point `p`, with the clamped parameter `t` (0 at `a`, 1 at `b`). */
+export function closestPointOnSegment(p, a, b) {
+    const abx = b[0] - a[0];
+    const aby = b[1] - a[1];
+    const l2 = abx * abx + aby * aby;
+    const raw = l2 > 0 ? ((p[0] - a[0]) * abx + (p[1] - a[1]) * aby) / l2 : 0;
+    const t = raw < 0 ? 0 : raw > 1 ? 1 : raw;
+    return { point: [a[0] + t * abx, a[1] + t * aby], t };
+}
+/**
+ * Circle (center + `radius`) against a capsule segment `a`→`b` of half-thickness `thickness` (0 for a thin
+ * wall). Returns the contact — surface normal, penetration depth, contact point, and the separated center —
+ * or `null` when they do not overlap. Endpoints are rounded (the segment is a capsule), so a ball never
+ * catches on a corner. Reflect the velocity across `normal` for the bounce; the pure geometry every 2D
+ * ball game (pinball, breakout, air hockey) reimplemented per wall, bumper, and paddle.
+ */
+export function circleVsSegment(center, radius, a, b, thickness = 0) {
+    const { point } = closestPointOnSegment(center, a, b);
+    const dx = center[0] - point[0];
+    const dy = center[1] - point[1];
+    const dist = Math.hypot(dx, dy);
+    const reach = radius + thickness;
+    if (dist >= reach)
+        return null;
+    let nx;
+    let ny;
+    if (dist > 1e-6) {
+        nx = dx / dist;
+        ny = dy / dist;
+    }
+    else {
+        const segLen = Math.hypot(b[0] - a[0], b[1] - a[1]);
+        nx = segLen > 1e-6 ? -(b[1] - a[1]) / segLen : 0;
+        ny = segLen > 1e-6 ? (b[0] - a[0]) / segLen : 1;
+    }
+    const depth = reach - dist;
+    return {
+        normal: [nx, ny],
+        depth,
+        contact: point,
+        resolved: [point[0] + nx * reach, point[1] + ny * reach],
+    };
+}

package/dist/world/soilKind.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `soil` studio: a crack/moss ground-variation patch authored as a box volume — its XZ footprint is
+ * the patch area, its top the ground height (same footprint convention as `grass_field`). Pure config
+ * here (crack scale/intensity/color, moss coverage/color, seed + a footprint resolver); the Worley
+ * (cellular) crack mask and FBM moss mask, injected via `onBeforeCompile` into a soil-patch material
+ * built from the same noise machinery as the terrain detail material, live in the `shell` renderer. An
+ * engine environment kind (like water/grass_field) so cracked, mossy ground is slider-authorable in
+ * the editor and persisted in `editor.scene.json` — the #815 soil studio.
+ */
+import { type ParamSchema, type SceneKindObject } from "../scene/sceneKinds.js";
+/**
+ * The editor volume kind marking a box as a soil crack/moss patch.
+ * @capability soil-patch editor-authorable terrain crack/moss material variation
+ */
+export declare const SOIL_KIND = "soil";
+/** Fully-defaulted soil params parsed from a volume's `meta`. */
+export interface SoilRules {
+    /** Underlying dirt/soil base tint, hex. */
+    baseColor: string;
+    /** Worley cell size in meters — larger cells read as bigger cracked-earth plates. */
+    crackScale: number;
+    /** Crack-line color blended into the cell boundaries, hex. */
+    crackColor: string;
+    /** Crack blend strength, 0..1. */
+    crackIntensity: number;
+    /** Moss patch color, hex. */
+    mossColor: string;
+    /** Fraction of the patch covered by moss, 0..1. */
+    mossCoverage: number;
+    /** Seed string; same seed reproduces the same crack/moss layout. */
+    seed: string;
+}
+/** Soil defaults: sun-cracked dirt with light moss creep. */
+export declare const SOIL_DEFAULTS: SoilRules;
+/** The soil parameter schema — drives the inspector and `meta` parse via the studio seam. */
+export declare const SOIL_SCHEMA: ParamSchema;
+/** Parse a volume's `meta` into fully-defaulted soil rules. @internal */
+export declare function readSoilRules(meta: Record<string, unknown> | undefined): SoilRules;
+/** A resolved soil patch: world-space area center at ground height, footprint size (XZ), and rules. */
+export interface ResolvedSoil {
+    center: readonly [number, number, number];
+    size: readonly [number, number];
+    rules: SoilRules;
+}
+/** Resolve a soil volume into an area footprint (from box half-extents / radius) at the box base. @internal */
+export declare function resolveSoilObject(object: SceneKindObject): ResolvedSoil | null;
+/** Registers the `soil` scene kind (schema + resolver). Called by {@link registerBuiltinSceneKinds}. @internal */
+export declare function registerSoilKind(): void;

package/dist/world/soilKind.js

@@ -0,0 +1,92 @@
+/**
+ * `soil` studio: a crack/moss ground-variation patch authored as a box volume — its XZ footprint is
+ * the patch area, its top the ground height (same footprint convention as `grass_field`). Pure config
+ * here (crack scale/intensity/color, moss coverage/color, seed + a footprint resolver); the Worley
+ * (cellular) crack mask and FBM moss mask, injected via `onBeforeCompile` into a soil-patch material
+ * built from the same noise machinery as the terrain detail material, live in the `shell` renderer. An
+ * engine environment kind (like water/grass_field) so cracked, mossy ground is slider-authorable in
+ * the editor and persisted in `editor.scene.json` — the #815 soil studio.
+ */
+import { registerSceneKind } from "../scene/sceneKinds.js";
+/**
+ * The editor volume kind marking a box as a soil crack/moss patch.
+ * @capability soil-patch editor-authorable terrain crack/moss material variation
+ */
+export const SOIL_KIND = "soil";
+/** Soil defaults: sun-cracked dirt with light moss creep. */
+export const SOIL_DEFAULTS = {
+    baseColor: "#8a7256",
+    crackScale: 3,
+    crackColor: "#42301f",
+    crackIntensity: 0.65,
+    mossColor: "#5c7a3a",
+    mossCoverage: 0.22,
+    seed: "",
+};
+/** The soil parameter schema — drives the inspector and `meta` parse via the studio seam. */
+export const SOIL_SCHEMA = {
+    fields: [
+        { type: "color", key: "baseColor", label: "base color", default: SOIL_DEFAULTS.baseColor },
+        { type: "range", key: "crackScale", label: "crack scale", min: 0.5, max: 12, step: 0.25, default: SOIL_DEFAULTS.crackScale, unit: "m" },
+        { type: "color", key: "crackColor", label: "crack color", default: SOIL_DEFAULTS.crackColor },
+        { type: "range", key: "crackIntensity", label: "crack intensity", min: 0, max: 1, step: 0.02, default: SOIL_DEFAULTS.crackIntensity },
+        { type: "color", key: "mossColor", label: "moss color", default: SOIL_DEFAULTS.mossColor },
+        { type: "range", key: "mossCoverage", label: "moss coverage", min: 0, max: 1, step: 0.02, default: SOIL_DEFAULTS.mossCoverage },
+        { type: "seed", key: "seed", label: "seed", default: "" },
+    ],
+};
+function metaNumber(meta, key, fallback) {
+    const value = meta?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function metaString(meta, key, fallback) {
+    const value = meta?.[key];
+    return typeof value === "string" ? value : fallback;
+}
+/** Parse a volume's `meta` into fully-defaulted soil rules. @internal */
+export function readSoilRules(meta) {
+    return {
+        baseColor: metaString(meta, "baseColor", SOIL_DEFAULTS.baseColor),
+        crackScale: Math.max(0.1, metaNumber(meta, "crackScale", SOIL_DEFAULTS.crackScale)),
+        crackColor: metaString(meta, "crackColor", SOIL_DEFAULTS.crackColor),
+        crackIntensity: Math.min(1, Math.max(0, metaNumber(meta, "crackIntensity", SOIL_DEFAULTS.crackIntensity))),
+        mossColor: metaString(meta, "mossColor", SOIL_DEFAULTS.mossColor),
+        mossCoverage: Math.min(1, Math.max(0, metaNumber(meta, "mossCoverage", SOIL_DEFAULTS.mossCoverage))),
+        seed: metaString(meta, "seed", SOIL_DEFAULTS.seed),
+    };
+}
+function axis(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** Resolve a soil volume into an area footprint (from box half-extents / radius) at the box base. @internal */
+export function resolveSoilObject(object) {
+    const center = object.center ?? object.position;
+    if (center === undefined)
+        return null;
+    const he = object.halfExtents;
+    const radius = object.radius;
+    const halfX = axis(he?.x) ?? radius ?? 6;
+    const halfZ = axis(he?.z) ?? radius ?? 6;
+    const halfY = axis(he?.y) ?? 0;
+    return {
+        center: [center.x, center.y - halfY, center.z],
+        size: [Math.max(0.5, halfX * 2), Math.max(0.5, halfZ * 2)],
+        rules: readSoilRules(object.meta),
+    };
+}
+/** Registers the `soil` scene kind (schema + resolver). Called by {@link registerBuiltinSceneKinds}. @internal */
+export function registerSoilKind() {
+    registerSceneKind({
+        kind: SOIL_KIND,
+        target: "volume",
+        label: "Soil patch",
+        addCategory: "Studios",
+        accent: "#8a6d4a",
+        schema: SOIL_SCHEMA,
+        resolve: (object) => resolveSoilObject(object),
+        note: (object) => {
+            const resolved = resolveSoilObject(object);
+            return resolved === null ? "Give the volume a box footprint." : `${Math.round(resolved.size[0])}×${Math.round(resolved.size[1])} m patch`;
+        },
+    });
+}

package/dist/world/spatialSample.d.ts

@@ -0,0 +1,241 @@
+import { type Aabb, type Vec2 } from "./geometry.js";
+/**
+ * Deterministic spatial sampling — draw one or many positions from a geometric region under
+ * explicit constraints, with an injected RNG, bounded attempts, and a structured pass/fail result.
+ *
+ * The three concerns stay separate on purpose (issue #940): a {@link SampleRegion} owns *where and
+ * how* candidates are drawn (its distribution policy — area- vs radial-uniform, edge-biased, weighted
+ * subregions); {@link SampleConstraints} own *which* candidates survive (include/exclude regions,
+ * keep-out distance via disc/sphere exclusions, caller predicates, surface projection, minimum
+ * separation); and {@link samplePoint}/{@link sampleBatch} own *how hard we try* (attempt budget and
+ * fallback policy). Nothing silently accepts an invalid point — exhaustion is reported, not hidden.
+ */
+/** A 3D point `[x, y, z]` — the volume/surface counterpart to {@link Vec2}. */
+export type Point3 = readonly [number, number, number];
+/** A sampled point: 2D `[x, z]` or 3D `[x, y, z]`. Every point in one run shares its dimensionality. */
+export type SamplePoint = readonly number[];
+/**
+ * A geometric region a sampler can draw from. Built-ins cover point sets, rect/box, circle/sphere,
+ * annulus/shell, polygon, and weighted composites; {@link customRegion} wraps a caller-defined
+ * sampler + bounds. `sample` draws one raw candidate under the region's own distribution policy;
+ * `contains` is the membership test reused for include/exclude constraints and rejection.
+ */
+export interface SampleRegion<P extends SamplePoint = SamplePoint> {
+    /** 2 for planar regions (`[x, z]`), 3 for volumetric/surface regions (`[x, y, z]`). */
+    readonly dimensions: 2 | 3;
+    /** True when the region can never yield a point (degenerate size, empty set) — reported, not sampled. */
+    readonly isEmpty: boolean;
+    /** Draw one raw candidate using `rng` (may still fail constraints). Consumes a fixed number of draws. */
+    sample(rng: () => number): P;
+    /** Membership test on the XZ (or XYZ) footprint — powers include gates and exclude keep-outs. */
+    contains(point: P): boolean;
+}
+/**
+ * Post-draw gates a candidate must clear. All are optional; an empty constraint set accepts every
+ * in-region draw. `exclude` discs/spheres are the keep-out distance primitive ("no closer than R to
+ * this center"); `accept` is a free-form caller predicate (biome, slope, ownership); `project` snaps
+ * a candidate onto a surface/navmesh before validation and may reject by returning `null`.
+ */
+export interface SampleConstraints<P extends SamplePoint = SamplePoint> {
+    /** Candidate must lie inside *every* listed region (intersection); omit for no inclusion gate. */
+    include?: readonly SampleRegion<P>[];
+    /** Candidate must lie outside *every* listed region — the keep-out/exclusion set. */
+    exclude?: readonly SampleRegion<P>[];
+    /** Extra caller acceptance test applied last; `false` rejects the candidate. */
+    accept?: (point: P) => boolean;
+    /** Optional surface/navmesh projection applied before validation; `null` rejects the candidate. */
+    project?: (point: P) => P | null;
+    /** Reject a candidate within this Euclidean distance of an already-accepted point in the same run. */
+    minSeparation?: number;
+}
+/**
+ * What to return when the attempt budget is exhausted. `"none"` yields no point (honest failure);
+ * `"last-candidate"` returns the final rejected draw (post-projection); `{ point }` returns a caller
+ * fixed fallback (a hand-placed safe spot). Explicit, so a caller never mistakes a fallback for a hit.
+ */
+export type FallbackPolicy<P extends SamplePoint = SamplePoint> = "none" | "last-candidate" | {
+    readonly point: P;
+};
+/** Why a sample ended: a clean hit, budget exhausted, or the region was degenerate. */
+export type SampleReason = "accepted" | "exhausted" | "empty-region";
+/** Structured single-sample outcome — never a bare point, so failure and fallback are visible. */
+export interface SampleResult<P extends SamplePoint = SamplePoint> {
+    /** True only for `"accepted"` — a genuine in-constraints hit (fallbacks are never `ok`). */
+    readonly ok: boolean;
+    /** The accepted point, or the fallback point, or `null` when no fallback applied. */
+    readonly point: P | null;
+    /** How many candidates were drawn (0 for an empty region). */
+    readonly attempts: number;
+    /** Outcome classification. */
+    readonly reason: SampleReason;
+    /** True when `point` came from the fallback policy rather than a passing draw. */
+    readonly usedFallback: boolean;
+}
+/** Inputs for a single {@link samplePoint} draw. */
+export interface SamplePointOptions<P extends SamplePoint = SamplePoint> {
+    region: SampleRegion<P>;
+    /** Injected deterministic RNG in `[0, 1)`; same stream → same result. */
+    rng: () => number;
+    constraints?: SampleConstraints<P>;
+    /** Maximum candidates to draw before giving up. Default 30. Bounds the work. */
+    maxAttempts?: number;
+    /** What to return on exhaustion. Default `"none"`. */
+    fallback?: FallbackPolicy<P>;
+    /** Already-placed points the new point must respect `minSeparation` against (batch threads this). */
+    placed?: readonly P[];
+}
+/**
+ * Draw one point from `region` that clears every constraint, retrying up to `maxAttempts` times with
+ * the injected `rng`, then apply the `fallback` policy. Returns a structured {@link SampleResult} —
+ * a clean hit is `ok: true`; exhaustion or a degenerate region is reported with the attempt count and
+ * an explicit fallback flag, never a silently-accepted bad point.
+ *
+ * @capability spatial-sample draw one deterministic position from a region under include/exclude/distance constraints
+ */
+export declare function samplePoint<P extends SamplePoint>(options: SamplePointOptions<P>): SampleResult<P>;
+/** Inputs for a {@link sampleBatch} draw of many spaced points. */
+export interface SampleBatchOptions<P extends SamplePoint = SamplePoint> {
+    region: SampleRegion<P>;
+    rng: () => number;
+    /** How many points to place. */
+    count: number;
+    constraints?: SampleConstraints<P>;
+    /** Attempt budget **per point**. Default 30. */
+    maxAttempts?: number;
+}
+/** Structured batch outcome: the placed points plus whether the full count was met. */
+export interface SampleBatchResult<P extends SamplePoint = SamplePoint> {
+    /** Accepted points in deterministic draw order. */
+    readonly points: readonly P[];
+    /** The requested count. */
+    readonly requested: number;
+    /** How many were actually placed (`<= requested`). */
+    readonly placed: number;
+    /** True when `placed === requested`. */
+    readonly complete: boolean;
+    /** Total candidates drawn across all points. */
+    readonly attempts: number;
+}
+/**
+ * Place up to `count` points from `region`, each clearing the shared constraints and honoring
+ * `minSeparation` against every point already placed in this batch (via a spatial hash, not an
+ * O(n²) scan). Order is deterministic for a given `rng` stream. Batches never silently under-fill:
+ * the result reports `placed`, `complete`, and the total attempt count.
+ *
+ * @capability spatial-sample-batch place many deterministic spaced points from a region with minimum separation
+ */
+export declare function sampleBatch<P extends SamplePoint>(options: SampleBatchOptions<P>): SampleBatchResult<P>;
+/** Fill policy for a circle/ring: `"area"` = area-uniform (even density); `"radial"` = radius-uniform (clumps toward center). */
+export type RadialDistribution = "area" | "radial";
+/** Fill policy for a sphere/shell: `"volume"` = volume-uniform (even density); `"radial"` = radius-uniform. */
+export type VolumeDistribution = "volume" | "radial";
+/** Fill policy for a rect/box: `"uniform"` = even coverage; `"edge"` = biased to a boundary band. */
+export type AreaDistribution = "uniform" | "edge";
+/** A weighted member of a {@link weightedRegion} composite. */
+export interface WeightedRegionEntry<P extends SamplePoint = SamplePoint> {
+    region: SampleRegion<P>;
+    /** Relative selection weight; non-positive entries are never chosen. */
+    weight: number;
+}
+/**
+ * A fixed set of candidate points sampled by (optionally weighted) selection — the "spawn point
+ * table" region. `contains` is exact membership. Empty when the set is empty.
+ *
+ * @capability spatial-region-point-set sample from a fixed, optionally weighted candidate point table
+ */
+export declare function pointSetRegion(points: readonly Vec2[], options?: {
+    weights?: readonly number[];
+}): SampleRegion<Vec2>;
+/**
+ * An axis-aligned rectangle on the XZ plane. `"uniform"` spreads evenly (draws x then z);
+ * `"edge"` biases onto a boundary band of `edgeThickness` meters (perimeter-weighted side, then
+ * inward depth) — the two are never conflated, the caller opts in.
+ */
+export declare function rectRegion(area: Aabb, options?: {
+    distribution?: AreaDistribution;
+    edgeThickness?: number;
+}): SampleRegion<Vec2>;
+/**
+ * A filled circle. `"area"` is area-uniform (√-corrected radius, even density); `"radial"` is
+ * radius-uniform (clumps toward the center). Angle is drawn first, then radius — matching the common
+ * `angle = rng()·2π; r = rng()·R` idiom so migrations keep their stream.
+ */
+export declare function discRegion(center: Vec2, radius: number, options?: {
+    distribution?: RadialDistribution;
+}): SampleRegion<Vec2>;
+/**
+ * A ring (annulus) between `innerRadius` and `outerRadius`. `"area"` fills the band with even
+ * density; `"radial"` spreads uniformly in radius. Angle first, then radius.
+ */
+export declare function annulusRegion(center: Vec2, innerRadius: number, outerRadius: number, options?: {
+    distribution?: RadialDistribution;
+}): SampleRegion<Vec2>;
+/**
+ * An arbitrary closed polygon on the XZ plane. Candidates are drawn uniformly from the polygon's
+ * bounding box and gated by point-in-polygon `contains`, so a run's draw count stays fixed (the
+ * sampler's attempt budget bounds the rejection, not a hidden inner loop).
+ *
+ * @capability spatial-region-polygon sample within an arbitrary closed polygon on the XZ plane
+ */
+export declare function polygonRegion(polygon: readonly Vec2[]): SampleRegion<Vec2>;
+/**
+ * A composite that first picks one member by weight, then delegates to its sampler — the
+ * "weighted subregions" distribution policy. `contains` is true when any member contains the point.
+ *
+ * @capability spatial-region-weighted compose sub-regions behind a weighted selection policy
+ */
+export declare function weightedRegion<P extends SamplePoint>(entries: readonly WeightedRegionEntry<P>[]): SampleRegion<P>;
+/**
+ * Wrap a caller-defined sampler and bounds test as a {@link SampleRegion} — the escape hatch for
+ * regions the built-ins do not cover (a navmesh cell, a heightfield mask, a spline tube).
+ *
+ * @capability spatial-region-custom wrap a caller-defined sampler and bounds test as a region
+ */
+export declare function customRegion<P extends SamplePoint>(spec: {
+    dimensions: 2 | 3;
+    sample: (rng: () => number) => P;
+    contains: (point: P) => boolean;
+    isEmpty?: boolean;
+}): SampleRegion<P>;
+/**
+ * An axis-aligned box `[min..max]` in 3D. Uniform density; draws x, y, z in order.
+ *
+ * @capability spatial-region-box sample uniformly within an axis-aligned 3D box
+ */
+export declare function boxRegion(min: Point3, max: Point3): SampleRegion<Point3>;
+/**
+ * A filled ball. `"volume"` is volume-uniform (∛-corrected radius); `"radial"` is radius-uniform.
+ * Direction is drawn first (two draws), then radius.
+ *
+ * @capability spatial-region-sphere sample within a filled 3D ball, volume- or radius-uniform
+ */
+export declare function sphereRegion(center: Point3, radius: number, options?: {
+    distribution?: VolumeDistribution;
+}): SampleRegion<Point3>;
+/**
+ * A spherical shell between `innerRadius` and `outerRadius`. `"volume"` fills the shell with even
+ * density; `"radial"` spreads uniformly in radius. Direction first, then radius.
+ *
+ * @capability spatial-region-shell sample within a 3D spherical shell, volume- or radius-uniform
+ */
+export declare function shellRegion(center: Point3, innerRadius: number, outerRadius: number, options?: {
+    distribution?: VolumeDistribution;
+}): SampleRegion<Point3>;
+/** Inputs for {@link sampleStratified}: a grid over `area` with one jittered point per cell. */
+export interface StratifiedOptions {
+    area: Aabb;
+    rng: () => number;
+    /** Grid columns (X) and rows (Z). */
+    cols: number;
+    rows: number;
+    /** Cell jitter 0..1 — 0 is a rigid lattice, 1 fills the whole cell. Default 1. */
+    jitter?: number;
+}
+/**
+ * Stratified 2D sampling: one jittered point per grid cell over `area`, in deterministic row-major
+ * order. Unlike pure rejection sampling this guarantees even coverage (no clumps, no gaps) — the
+ * distinct "stratified" distribution policy, kept separate from area-uniform draws.
+ *
+ * @capability spatial-sample-stratified evenly cover an area with one jittered point per grid cell, deterministic
+ */
+export declare function sampleStratified(options: StratifiedOptions): Vec2[];