@carbonenginejs/runtime-utils 0.1.0

package/src/model/CjsModelState.js

@@ -0,0 +1,72 @@
+/**
+ * Per-model runtime state. One instance per model at `__state`.
+ *
+ * Ownership and clearing rules (kb section 8):
+ * - `dirty` is the only generically managed member: mutations mark it, and
+ *   `UpdateValues` (the settle) is the only thing that clears it. The
+ *   pipeline is cooperative - anything mutating outside `SetValues`
+ *   (direct writes, Object.assign, reader adapters) owes a `MarkDirty()`
+ *   or an explicit `UpdateValues()` ("I made changes, apply please").
+ * - `flags` holds lazy invalidations ("bounds is stale"). Written at
+ *   mutation time from `@io.flag` field metadata or by class code; cleared
+ *   ONLY by the getter that recomputes the derived value. Never
+ *   auto-cleared - deferring until needed is their whole point.
+ * - `rebuild` holds scheduled work requirements ("vertices need
+ *   rebuilding"). Written at mutation time from `@io.rebuild` field
+ *   metadata or by class code; cleared ONLY by the specific work method
+ *   that succeeds (e.g. RebuildVertices), typically driven from Update /
+ *   per-frame passes. Never auto-cleared.
+ * - Future transient runtime state (lifecycle links, revision counters)
+ *   lands here rather than growing new underscore properties.
+ */
+export class CjsModelState
+{
+
+    /** Something changed; the next settle applies it. @type {boolean} */
+    dirty = false;
+
+    /** Lazy invalidations - consumers clear when they recompute. @type {Set<string>} */
+    flags = new Set();
+
+    /** Scheduled work requirements - work methods clear on success. @type {Set<string>} */
+    rebuild = new Set();
+
+    /** Settle re-entrancy guard. @type {boolean} */
+    updating = false;
+
+    /** Construction/teardown event gate (counted). @type {number} */
+    suppressEvents = 0;
+
+    /**
+     * Checks whether a settle is owed.
+     *
+     * @returns {boolean}
+     */
+    IsDirty()
+    {
+        return this.dirty;
+    }
+
+    /**
+     * Marks the model as changed ("apply at the next settle").
+     *
+     * @returns {CjsModelState} This state.
+     */
+    MarkDirty()
+    {
+        this.dirty = true;
+        return this;
+    }
+
+    /**
+     * Clears the dirty mark. The settle calls this; class code rarely should.
+     *
+     * @returns {CjsModelState} This state.
+     */
+    ClearDirty()
+    {
+        this.dirty = false;
+        return this;
+    }
+
+}

package/src/model/index.js

@@ -0,0 +1,4 @@
+export * from "./CjsModel.js";
+export { CjsModelState } from "./CjsModelState.js";
+export { CjsEventEmitter } from "./CjsEventEmitter.js";
+export * from "./sourceRecordUtils.js";

package/src/model/sourceRecordUtils.js

@@ -0,0 +1,54 @@
+import { CjsModel } from "./CjsModel.js";
+
+export function asArray(value)
+{
+    if (!value) return [];
+    if (value instanceof Map) return Array.from(value.values());
+    return Array.isArray(value) ? value : [value];
+}
+
+export function firstDefined(...values)
+{
+    for (const value of values)
+    {
+        if (value !== undefined && value !== null) return value;
+    }
+    return null;
+}
+
+export function getField(object, ...names)
+{
+    if (!object) return null;
+    for (const name of names)
+    {
+        if (Object.prototype.hasOwnProperty.call(object, name)) return object[name];
+    }
+    return null;
+}
+
+export function objectFromMap(map)
+{
+    return Object.fromEntries(map.entries());
+}
+
+export function collectionValues(value)
+{
+    if (!value) return [];
+    if (value instanceof Map) return Array.from(value.values());
+    if (Array.isArray(value)) return value;
+    if (typeof value === "object") return Object.values(value);
+    return [value];
+}
+
+export function clonePlain(value)
+{
+    if (value instanceof CjsModel) return value.GetValues();
+    if (ArrayBuffer.isView(value)) return Array.from(value);
+    if (value instanceof Map) return new Map(Array.from(value.entries()).map(([key, item]) => [key, clonePlain(item)]));
+    if (Array.isArray(value)) return value.map(clonePlain);
+    if (value && typeof value === "object")
+    {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, clonePlain(item)]));
+    }
+    return value;
+}

package/src/noise.js

@@ -0,0 +1,310 @@
+import { vec3 } from "./vec3.js";
+import { vec4 } from "./vec4.js";
+
+export const noise = {};
+
+/**
+ * Generates turbulent noise
+ *
+ * @param {vec4} out
+ * @param {number} pos_0
+ * @param {number} pos_1
+ * @param {number} pos_2
+ * @param {number} pos_3
+ * @param {number} power
+ * @returns {vec4} out
+ */
+noise.turbulence = (function()
+{
+    const
+        s_noiseLookup = [],
+        s_permutations = [],
+        s_globalNoiseTemps = [];
+
+    let s_initialized = false;
+
+    /**
+     * Initializes noise
+     */
+    function initialize()
+    {
+        for (let i = 0; i < 256; i++)
+        {
+            s_noiseLookup[i] = vec4.fromValues(Math.random() - 0.5, Math.random() - 0.5, Math.random() - 0.5, Math.random() - 0.5);
+            s_permutations[i] = i;
+        }
+
+        let i = 256;
+        while (--i)
+        {
+            const
+                tmp = s_permutations[i],
+                index = Math.floor(Math.random() * 256);
+
+            s_permutations[i] = s_permutations[index];
+            s_permutations[index] = tmp;
+        }
+
+        for (let i = 0; i < 256; i++)
+        {
+            s_permutations[256 + i] = s_permutations[i];
+            s_noiseLookup[256 + i] = s_noiseLookup[i];
+            s_noiseLookup[256 * 2 + i] = s_noiseLookup[i];
+        }
+
+        for (let i = 0; i < 15; ++i)
+        {
+            s_globalNoiseTemps[i] = vec3.create();
+        }
+
+        s_initialized = true;
+    }
+
+    return function turbulence(out, pos_0, pos_1, pos_2, pos_3, power)
+    {
+        if (!s_initialized) initialize();
+
+        pos_0 += 4096;
+        pos_1 += 4096;
+        pos_2 += 4096;
+        pos_3 += 4096;
+
+        let a_0 = Math.floor(pos_0),
+            a_1 = Math.floor(pos_1),
+            a_2 = Math.floor(pos_2),
+            a_3 = Math.floor(pos_3);
+
+        const
+            t_0 = pos_0 - a_0,
+            t_1 = pos_1 - a_1,
+            t_2 = pos_2 - a_2,
+            t_3 = pos_3 - a_3;
+
+        a_0 &= 255;
+        a_1 &= 255;
+        a_2 &= 255;
+        a_3 &= 255;
+
+        const
+            b_0 = a_0 + 1,
+            b_1 = a_1 + 1,
+            b_2 = a_2 + 1,
+            b_3 = a_3 + 1;
+
+        const
+            i = s_permutations[a_0],
+            j = s_permutations[b_0];
+
+        const
+            b00 = s_permutations[i + a_1],
+            b10 = s_permutations[j + a_1],
+            b01 = s_permutations[i + b_1],
+            b11 = s_permutations[j + b_1];
+
+        let c00 = vec3.lerp(s_globalNoiseTemps[0], s_noiseLookup[b00 + a_2 + a_3], s_noiseLookup[b10 + a_2 + a_3], t_0);
+        let c10 = vec3.lerp(s_globalNoiseTemps[1], s_noiseLookup[b01 + a_2 + a_3], s_noiseLookup[b11 + a_2 + a_3], t_0);
+        let c01 = vec3.lerp(s_globalNoiseTemps[2], s_noiseLookup[b00 + b_2 + a_3], s_noiseLookup[b10 + b_2 + a_3], t_0);
+        let c11 = vec3.lerp(s_globalNoiseTemps[3], s_noiseLookup[b01 + b_2 + a_3], s_noiseLookup[b11 + b_2 + a_3], t_0); // Carbon Noise4D: b01/b11 corners (fixed 2026-07-23)
+        let c0 = vec3.lerp(s_globalNoiseTemps[4], c00, c10, t_1);
+        let c1 = vec3.lerp(s_globalNoiseTemps[5], c01, c11, t_1);
+        const c = vec3.lerp(s_globalNoiseTemps[6], c0, c1, t_2);
+
+        c00 = vec3.lerp(s_globalNoiseTemps[7], s_noiseLookup[b00 + a_2 + b_3], s_noiseLookup[b10 + a_2 + b_3], t_0);
+        c10 = vec3.lerp(s_globalNoiseTemps[8], s_noiseLookup[b01 + a_2 + b_3], s_noiseLookup[b11 + a_2 + b_3], t_0);
+        c01 = vec3.lerp(s_globalNoiseTemps[9], s_noiseLookup[b00 + b_2 + b_3], s_noiseLookup[b10 + b_2 + b_3], t_0);
+        c11 = vec3.lerp(s_globalNoiseTemps[10], s_noiseLookup[b01 + b_2 + b_3], s_noiseLookup[b11 + b_2 + b_3], t_0); // Carbon Noise4D: b01/b11 corners (fixed 2026-07-23)
+        c0 = vec3.lerp(s_globalNoiseTemps[11], c00, c10, t_1);
+        c1 = vec3.lerp(s_globalNoiseTemps[12], c01, c11, t_1);
+        const d = vec3.lerp(s_globalNoiseTemps[13], c0, c1, t_2);
+        const r = vec3.lerp(s_globalNoiseTemps[14], c, d, t_3);
+
+        out[0] += r[0] * power;
+        out[1] += r[1] * power;
+        out[2] += r[2] * power;
+        return out;
+    };
+})();
+
+/**
+ * Creates Carbon's seeded one-dimensional Perlin-noise utility.
+ *
+ * This ports `TriPerlinNoise` from `TriMath.cpp`: gradients are generated by
+ * `std::mt19937`, sampling uses Carbon's cubic S-curve, and the returned
+ * object owns the native class's otherwise-private gradient table.
+ *
+ * @param {number} [seed]
+ * @returns {{ sample: (x: number) => number, fractalSum: (x: number, octaves: number, amplitudeScale?: number, frequencyScale?: number) => number }}
+ */
+noise.createPerlinNoise1D = function(seed = Math.floor(Math.random() * 0x100000000))
+{
+    const state = new Uint32Array(624);
+    state[0] = Number(seed) >>> 0;
+    for (let index = 1; index < state.length; index++)
+    {
+        const previous = state[index - 1] ^ (state[index - 1] >>> 30);
+        state[index] = (Math.imul(1812433253, previous) + index) >>> 0;
+    }
+
+    let cursor = state.length;
+    const twist = () =>
+    {
+        for (let index = 0; index < state.length; index++)
+        {
+            const bits = (state[index] & 0x80000000) | (state[(index + 1) % state.length] & 0x7fffffff);
+            state[index] = state[(index + 397) % state.length] ^ (bits >>> 1) ^ (bits & 1 ? 0x9908b0df : 0);
+        }
+        cursor = 0;
+    };
+    const next = () =>
+    {
+        if (cursor >= state.length) twist();
+        let value = state[cursor++];
+        value ^= value >>> 11;
+        value ^= (value << 7) & 0x9d2c5680;
+        value ^= (value << 15) & 0xefc60000;
+        value ^= value >>> 18;
+        return value >>> 0;
+    };
+    const gradients = Float64Array.from(
+        { length: 256 },
+        () => ((next() % 512) - 256) / 256
+    );
+
+    const sample = x =>
+    {
+        const floor = Math.floor(x),
+            first = floor & 255,
+            second = (first + 1) & 255,
+            x0 = x - floor,
+            x1 = x0 - 1,
+            value0 = x0 * gradients[first],
+            value1 = x1 * gradients[second],
+            curve = x0 * x0 * (3 - 2 * x0);
+
+        return value0 + curve * (value1 - value0);
+    };
+    const fractalSum = (x, octaves, amplitudeScale = 0.5, frequencyScale = 2) =>
+    {
+        let sum = 0,
+            scale = 1;
+        const count = Number.isFinite(octaves) ? Math.max(0, Math.trunc(octaves)) : 0;
+
+        for (let index = 0; index < count; index++)
+        {
+            sum += sample(x) * scale;
+            scale *= amplitudeScale;
+            x *= frequencyScale;
+        }
+        return sum;
+    };
+
+    return Object.freeze({ sample, fractalSum });
+};
+
+const s_fixedPerlinNoise1D = noise.createPerlinNoise1D(0);
+
+/**
+ * Evaluates Carbon's global fixed-seed `PerlinNoise1D` function.
+ *
+ * @param {number} x
+ * @param {number} inverseAmplitude
+ * @param {number} frequency
+ * @param {number} octaves
+ * @returns {number}
+ */
+noise.carbonPerlin1D = function(x, inverseAmplitude, frequency, octaves)
+{
+    return s_fixedPerlinNoise1D.fractalSum(x, octaves, 1 / inverseAmplitude, frequency);
+};
+
+/**
+ * Legacy ccpwgl `Perlin_noise1` helper.
+ *
+ * This intentionally remains separate from Carbon's fixed-seed
+ * `TriPerlinNoise` implementation above.
+ *
+ * @param {number} a
+ * @returns {number}
+ */
+noise.perlin1 = (function()
+{
+    let initialized = false,
+        permutations = null,
+        gradients = null;
+
+    function initialize()
+    {
+        permutations = new Array(514);
+        gradients = new Array(514);
+        let index = 0;
+
+        for (; index < 256; index++)
+        {
+            permutations[index] = index;
+            gradients[index] = Math.random() * 2 - 1;
+        }
+
+        while (--index)
+        {
+            const value = permutations[index],
+                randomIndex = Math.floor(Math.random() * 256);
+            permutations[index] = permutations[randomIndex];
+            permutations[randomIndex] = value;
+        }
+
+        for (index = 0; index < 258; index++)
+        {
+            permutations[256 + index] = permutations[index];
+            gradients[256 + index] = gradients[index];
+        }
+        initialized = true;
+    }
+
+    return function perlin1(a)
+    {
+        if (!initialized) initialize();
+
+        const position = a + 4096,
+            first = Math.floor(position) & 255,
+            second = (first + 1) & 255,
+            x0 = position - Math.floor(position),
+            x1 = x0 - 1,
+            curve = x0 * x0 * (3 - 2 * x0),
+            value0 = x0 * gradients[permutations[first]],
+            value1 = x1 * gradients[permutations[second]];
+
+        return value0 + curve * (value1 - value0);
+    };
+})();
+
+/**
+ * Legacy ccpwgl fractal sum built on randomized `perlin1`.
+ *
+ * @param {number} x
+ * @param {number} alpha
+ * @param {number} beta
+ * @param {number} octaves
+ * @returns {number}
+ */
+noise.perlin1D = function(x, alpha, beta, octaves)
+{
+    let sum = 0,
+        position = x,
+        scale = 1;
+
+    for (let index = 0; index < octaves; index++)
+    {
+        sum += noise.perlin1(position) / scale;
+        scale *= alpha;
+        position *= beta;
+    }
+    return sum;
+};
+
+export const {
+    turbulence,
+    createPerlinNoise1D,
+    carbonPerlin1D,
+    perlin1,
+    perlin1D
+} = noise;