@fundamental-engine/core 0.4.0

package/dist/forces/extended.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Designed extended forces (§20.3, implementation class [A]).
+ *
+ * Like the canonical nine (§6) these are *designed* — finite range, soft falloff,
+ * tuned for legibility — but they live outside the core nine as opt-in enrichments.
+ * Class [A] means each acts on a single particle from the shared per-frame `env`,
+ * needing no neighbour or grid services, so they register and test exactly like the
+ * nine. Opt-in via `data-body="lens"` etc.; a page that doesn't ask is unaffected.
+ */
+import type { Force } from '../core/types.ts';
+import type { Registry } from '../core/registry.ts';
+/**
+ * §20.3 — `lens`: rotate the velocity, preserving its magnitude. A gravitational
+ * lens bends a path without adding energy, so this is a pure rotation by an angle
+ * that grows as a particle nears the body: `θ = θ_max·(1 − d/d_max)·sign`, then
+ * `v ← rotate(v, θ)`. `strength` is θ_max (radians), `spin` the sign of the bend.
+ */
+export declare const lens: Force;
+/**
+ * §20.3 — `gate`: a one-way membrane. Along its heading `n = (cosθ, sinθ)` matter
+ * passes freely; matter crossing the *wrong* way (`v·n < 0`) is reflected across the
+ * membrane, `v −= 2(v·n)·n`, so its normal component flips to travel with `n`. Sized
+ * by the element box (like `wall`, §6.4); `data-angle` sets `n`.
+ */
+export declare const gate: Force;
+export declare const buoyancy: Force;
+/**
+ * §20.3 — `shear`: a laminar velocity gradient (Couette flow). Speed along the flow
+ * axis `n = (cosθ, sinθ)` grows with a particle's *perpendicular* offset from the
+ * body: `v_∥ += S·(offset_⊥/d_max)·(1 − d/d_max)`. Matter on one side of the axis is
+ * dragged forward, the other side back — laminae sliding past each other.
+ * `data-angle` sets the flow axis; `strength` is S.
+ */
+export declare const shear: Force;
+export declare const crystallize: Force;
+/**
+ * §20.3 — `align`: steer velocity toward a target heading `ĥ` while preserving speed,
+ * `v += (ĥ·|v| − v)·k_align`. Unifies both spec variants: `[B]` uses the **mean of
+ * neighbours' headings** when `p` has any (boids alignment), and falls back to `[A]`,
+ * the body's own `data-angle` heading, when it's alone. `strength` is `k_align`.
+ */
+export declare const align: Force;
+/**
+ * A smooth divergence-free flow field (§20.3) — the curl of a sinusoidal stream-
+ * function `ψ = sin(a)·cos(b)`, with `a = x·s + 0.2t`, `b = y·s − 0.2t`. The velocity
+ * `(∂ψ/∂y, −∂ψ/∂x)` is divergence-free by construction (`∇·curl ≡ 0`), so it stirs
+ * without compressing. Closed-form (no RNG) → deterministic and exactly testable.
+ * `s` is the spatial scale of the eddies.
+ */
+export declare function curlNoise(x: number, y: number, t: number, s: number): {
+    x: number;
+    y: number;
+};
+export declare const wind: Force;
+export declare const cohesion: Force;
+export declare const pressure: Force;
+/**
+ * §20.3 — `hunt` (class [B], over `env.neighbors`): a two-species pursuit. A particle's
+ * `species` sets its role: predators (species `0`) accelerate toward the nearest particle
+ * of another species; prey (species ≠ `0`) accelerate directly away from the nearest
+ * predator. `range` is the perception radius; `strength` the seek/flee gain. So a field of
+ * two species chases and scatters — schooling/fleeing motion. The Lotka–Volterra
+ * *population* cycle (births and deaths) is an emergent simulation concern, not this
+ * per-particle motion law; `hunt` is the chase itself, honestly.
+ */
+export declare const hunt: Force;
+export declare const link: Force;
+export declare const morph: Force;
+/**
+ * §20.1/§20.2 — `spawn` (class [S], the source *atom*): the one force that *creates*
+ * matter rather than moving it. While its body is engaged it emits particles each frame
+ * at the body centre, launched along the heading `(ux, uy)` within a soft cone. This
+ * deliberately breaks conservation (§2.4), so every spawned particle is **mortal**: it
+ * carries a finite `age` and despawns when it expires (the integrator's [S] sink), and
+ * the engine caps the pool besides — a budgeted source, per the §20.1 conservation note.
+ * `strength` sets the emission rate; `angle` the direction. `fountain` is the preset that
+ * names a continuous upward spawn; `supernova` is its one-shot cousin (the conserved
+ * absorb→release event is the everyday path — reach for [S] only when creation is the
+ * point). A pure source: `apply` is a no-op, the work is in `source()`.
+ */
+export declare const SPAWN_LIFE = 90;
+export declare const spawn: Force;
+export declare const resonate: Force;
+export declare const spotlight: Force;
+/**
+ * Workover v0.3 — `screen`: a quiet zone / shield (truth mode: designed). A body carrying
+ * `screen` damps the magnitude of OTHER bodies' forces on matter inside its `data-range`,
+ * by `screenFactor` (`core/math.ts`) — text shielded from a noisy field, a calm pocket in a
+ * busy page.
+ * Cross-body by definition, so the work happens in the integrator's force pass (the only
+ * place per-particle, per-body forces compose); this module is the registered token, the
+ * passported identity, and the pure math. `apply` is a no-op — like `spotlight`/`resonate`
+ * it is a modifier, but one that modifies its *neighbors*, not its own siblings. Initial
+ * mode is `local` (the only shipped mode; `data-screen-mode` inside/outside/behind are
+ * future work). Probe-style diagnostic samplers (`forceAt`, the Lab's frame-0 delta) read
+ * raw forces and do not apply screen attenuation — the integrator is the contract.
+ */
+export declare const screen: Force;
+/**
+ * §20.8 — `pigment` (class [E], particle attribute `color`): conserved color
+ * transport. A particle that overlaps a pigment body takes on the body's tint
+ * (`data-color`) and carries it away — the section *stains* the field, and the
+ * color advects with the matter instead of being re-tinted globally. Opt-in and
+ * inert without a tint, so a normal field is untouched.
+ */
+export declare const pigment: Force;
+export declare const fieldflow: Force;
+/** The designed extended forces, in spec order (§20.3). */
+/**
+ * §22.3 — `warp`: a wormhole throat. Matter that enters the throat (within `absorbR`) is
+ * *relocated* — conserved, not created or destroyed — to the paired body's throat, emerging just
+ * outside it moving outward, with its local offset and velocity rotated by `data-twist` and scaled by
+ * `data-scale`. The pairing (`data-pair="#other"`) and the live target centre are resolved by the
+ * engine into `b.warpHas` / `b.warpX` / `b.warpY`; the force no-ops with no resolved target. Marked
+ * `kinematic` so it sets position/velocity outright (a teleport), unscaled by inertia.
+ */
+export declare const warp: Force;
+export declare const extendedForces: readonly Force[];
+/** Register the designed extended forces on a registry (§4) — opt-in, alongside the nine. */
+export declare function registerExtendedForces(reg: Registry): void;
+//# sourceMappingURL=extended.d.ts.map

package/dist/forces/extended.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extended.d.ts","sourceRoot":"","sources":["../../src/forces/extended.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAY,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGpD;;;;;GAKG;AACH,eAAO,MAAM,IAAI,EAAE,KAelB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,IAAI,EAAE,KAclB,CAAC;AAeF,eAAO,MAAM,QAAQ,EAAE,KAStB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,EAAE,KAYnB,CAAC;AAUF,eAAO,MAAM,WAAW,EAAE,KAazB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,KAAK,EAAE,KAkCnB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAK9F;AASD,eAAO,MAAM,IAAI,EAAE,KAUlB,CAAC;AAWF,eAAO,MAAM,QAAQ,EAAE,KA+BtB,CAAC;AAcF,eAAO,MAAM,QAAQ,EAAE,KA+BtB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,EAAE,KA+BlB,CAAC;AAaF,eAAO,MAAM,IAAI,EAAE,KAsBlB,CAAC;AAoBF,eAAO,MAAM,KAAK,EAAE,KA0BnB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,eAAO,MAAM,KAAK,EAAE,KA+BnB,CAAC;AASF,eAAO,MAAM,QAAQ,EAAE,KAQtB,CAAC;AASF,eAAO,MAAM,SAAS,EAAE,KAUvB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,EAAE,KAKpB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,EAAE,KASrB,CAAC;AAoBF,eAAO,MAAM,SAAS,EAAE,KAuCvB,CAAC;AAEF,2DAA2D;AAC3D;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,EAAE,KA+BlB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,SAAS,KAAK,EAoB1C,CAAC;AAEF,6FAA6F;AAC7F,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAE1D"}