@carbonenginejs/runtime-utils 0.1.0

package/src/document/hydrationAdapter.js

@@ -0,0 +1,129 @@
+import { CjsSchema } from "../schema/index.js";
+
+/**
+ * Hydration adapter seam.
+ *
+ * runtime-utils deliberately does NOT impose a runtime lifecycle
+ * (SetValues / OnValueChanged / Initialize / etc. are one project's rules,
+ * not a contract). The only thing the library guarantees is ORDERING:
+ *
+ *   1. construct   - build every instance (register refs before values, so
+ *                    cycles/back-references resolve)
+ *   2. applyValues - apply each node's field values
+ *   3. finalize    - run once per instance AFTER the whole graph is built,
+ *                    so references are already resolved
+ *
+ * Callers inject HOW their own classes are constructed, populated, and
+ * finalized. Every hook is optional; when absent the built-in default is used
+ * so plain objects / `class {}` need zero configuration.
+ *
+ * Adapter shape (all methods optional):
+ *   construct(kind, ctx)             -> instance | undefined
+ *        Return an instance, or `undefined` to fall back to the caller's
+ *        built-in default construction (registry/class lookup).
+ *   applyValues(instance, values, ctx) -> instance
+ *        Apply `values` ({ fieldName: value }) to the instance. MUST mutate
+ *        the given instance in place (returning a replacement would strip
+ *        already-resolved references in cyclic graphs). Default: Object.assign.
+ *   finalize(instance, ctx)          -> void
+ *        Post-graph initialization. Default: no-op.
+ *
+ * ctx: { kind, shape?, node?, options }
+ *
+ * Options consumed:
+ *   options.adapter  / options.hydrationAdapter : a single adapter object
+ *   options.adapters : { [kind]: adapter } | Map  per-kind override (wins over
+ *                      the single adapter)
+ */
+
+function adapterOwning(perKind, global, kind, name)
+{
+    if (perKind)
+    {
+        const specific = perKind instanceof Map ? perKind.get(kind) : perKind[kind];
+        if (specific && typeof specific[name] === "function") return specific;
+    }
+    if (global && typeof global[name] === "function") return global;
+    return null;
+}
+
+/**
+ * Resolves a normalized adapter from hydration options. The returned object
+ * always exposes construct/applyValues/finalize with the documented defaults.
+ * @param {Object} [options]
+ * @returns {{ construct: Function, applyValues: Function, finalize: Function }}
+ */
+export function resolveHydrationAdapter(options = {})
+{
+    const global = options.adapter || options.hydrationAdapter || null;
+    const perKind = options.adapters || null;
+
+    return {
+        construct(kind, ctx)
+        {
+            const owner = adapterOwning(perKind, global, kind, "construct");
+            return owner ? owner.construct(kind, ctx) : undefined;
+        },
+        applyValues(instance, values, ctx)
+        {
+            const owner = adapterOwning(perKind, global, ctx?.kind, "applyValues");
+            if (owner) return owner.applyValues(instance, values, ctx);
+            return Object.assign(instance, values);
+        },
+        finalize(instance, ctx)
+        {
+            const owner = adapterOwning(perKind, global, ctx?.kind, "finalize");
+            if (owner) owner.finalize(instance, ctx);
+        }
+    };
+}
+
+/**
+ * Optional convenience adapter for callers whose classes follow a
+ * "SetValues + Initialize" convention (Carbon / ccpwgl / CjsModel style).
+ *
+ * This is NOT a default - opt in by passing it as `options.adapter`. Method
+ * names are configurable; pass `false`/`null` to disable a phase. When
+ * SetValues is enabled, applyValues throws if the populated instance does not
+ * implement it; this keeps class population from silently bypassing runtime
+ * validation. Finalize is skipped when the named initialize method is missing.
+ *
+ * @param {Object} [config]
+ * @param {String|false|null} [config.setValues="SetValues"]
+ * @param {String|false|null} [config.initialize="Initialize"]
+ * @param {Function} [config.construct] optional construct hook
+ * @returns {{ construct?: Function, applyValues: Function, finalize: Function }}
+ */
+export function createLifecycleAdapter(config = {})
+{
+    const setValuesName = config.setValues === undefined ? "SetValues" : config.setValues;
+    const initializeName = config.initialize === undefined ? "Initialize" : config.initialize;
+    const construct = typeof config.construct === "function" ? config.construct : null;
+
+    const adapter = {
+        applyValues(instance, values, ctx)
+        {
+            if (setValuesName && instance && typeof instance[setValuesName] === "function")
+            {
+                instance[setValuesName](values, ctx?.options);
+                return instance;
+            }
+            if (setValuesName && instance && typeof instance === "object")
+            {
+                const kind = ctx?.kind ?? CjsSchema.getClassName(instance.constructor) ?? "unknown";
+                throw new TypeError(`${kind} cannot be populated by createLifecycleAdapter: missing ${setValuesName}().`);
+            }
+            return Object.assign(instance, values);
+        },
+        finalize(instance, ctx)
+        {
+            if (initializeName && instance && typeof instance[initializeName] === "function")
+            {
+                instance[initializeName](ctx?.options);
+            }
+        }
+    };
+
+    if (construct) adapter.construct = construct;
+    return adapter;
+}

package/src/document/index.js

@@ -0,0 +1,6 @@
+export * from "./CjsCarbonDocument.js";
+export * from "./CjsClassRegistry.js";
+export * from "./CjsDocumentDehydrator.js";
+export * from "./CjsDocumentHydrator.js";
+export * from "./CjsStructRegistry.js";
+export * from "./hydrationAdapter.js";

package/src/geometry/box.js

@@ -0,0 +1,137 @@
+import { vec3 } from "../vec3.js";
+import { toJSON } from "./json.js";
+
+
+/**
+ * Creates a box
+ * @author Three.js converted
+ * @param {Object} [options={}]
+ * @param {Number} [options.width=1]
+ * @param {Number} [options.height=1]
+ * @param {Number} [options.depth=1]
+ * @param {Number} [widthSegments=1]
+ * @param {Number} [heightSegments=1]
+ * @param {Number} [depthSegments=1]
+ * @returns {Object}
+ */
+export function createBox(options = {})
+{
+    let {
+        width = 1,
+        height = 1,
+        depth = 1,
+        widthSegments = 1,
+        heightSegments = 1,
+        depthSegments = 1
+    } = options;
+
+    if (![ width, height, depth ].every(Number.isFinite) ||
+        width === 0 || height === 0 || depth === 0)
+    {
+        throw new Error("Box dimensions must be finite and non-zero");
+    }
+
+    widthSegments = Math.max(1, Math.floor(Number.isFinite(widthSegments) ? widthSegments : 1));
+    heightSegments = Math.max(1, Math.floor(Number.isFinite(heightSegments) ? heightSegments : 1));
+    depthSegments = Math.max(1, Math.floor(Number.isFinite(depthSegments) ? depthSegments : 1));
+
+    const
+        indices = [],
+        positions = [],
+        normals = [],
+        uvs = [];
+
+    let numberOfVertices = 0;
+
+    function buildPlane(u, v, w, udir, vdir, width, height, depth, gridX, gridY)
+    {
+        const
+            segmentWidth = width / gridX,
+            segmentHeight = height / gridY,
+            widthHalf = width / 2,
+            heightHalf = height / 2,
+            depthHalf = depth / 2,
+            gridX1 = gridX + 1,
+            gridY1 = gridY + 1;
+
+        let vertexCounter = 0;
+
+        const vec3_0 = vec3.alloc();
+
+        // generate vertices, normals and uvs
+
+        for (let iy = 0; iy < gridY1; iy++)
+        {
+            const y = iy * segmentHeight - heightHalf;
+
+            for (let ix = 0; ix < gridX1; ix++)
+            {
+                const x = ix * segmentWidth - widthHalf;
+                // set values to correct vec3_0 component
+                vec3_0[u] = x * udir;
+                vec3_0[v] = y * vdir;
+                vec3_0[w] = depthHalf;
+                // now apply vec3_0 to vertex buffer
+                positions.push(vec3_0[0], vec3_0[1], vec3_0[2]);
+                // set values to correct vec3_0 component
+                vec3_0[u] = 0;
+                vec3_0[v] = 0;
+                vec3_0[w] = depth > 0 ? 1 : -1;
+                // now apply vec3_0 to normal buffer
+                normals.push(vec3_0[0], vec3_0[1], vec3_0[2]);
+                // uvs
+                uvs.push(ix / gridX);
+                uvs.push(1 - (iy / gridY));
+                // counters
+                vertexCounter += 1;
+            }
+        }
+
+        vec3.unalloc(vec3_0);
+
+        // indices
+        // 1. you need three indices to draw a single face
+        // 2. a single segment consists of two faces
+        // 3. so we need to generate six (2*3) indices per segment
+        for (let iy = 0; iy < gridY; iy++)
+        {
+            for (let ix = 0; ix < gridX; ix++)
+            {
+                const
+                    a = numberOfVertices + ix + gridX1 * iy,
+                    b = numberOfVertices + ix + gridX1 * (iy + 1),
+                    c = numberOfVertices + (ix + 1) + gridX1 * (iy + 1),
+                    d = numberOfVertices + (ix + 1) + gridX1 * iy;
+                // faces
+                indices.push(a, b, d);
+                indices.push(b, c, d);
+            }
+        }
+
+        // update total number of vertices
+        numberOfVertices += vertexCounter;
+    }
+
+    buildPlane(2, 1, 0, - 1, - 1, depth, height,   width,  depthSegments, heightSegments); // px
+    buildPlane(2, 1, 0,   1, - 1, depth, height, - width,  depthSegments, heightSegments); // nx
+    buildPlane(0, 2, 1,   1,   1, width, depth,    height, widthSegments, depthSegments);  // py
+    buildPlane(0, 2, 1,   1, - 1, width, depth,  - height, widthSegments, depthSegments);  // ny
+    buildPlane(0, 1, 2,   1, - 1, width, height,   depth,  widthSegments, heightSegments); // pz
+    buildPlane(0, 1, 2, - 1, - 1, width, height, - depth,  widthSegments, heightSegments); // nz
+
+    // Normalize
+    const result = toJSON(indices, positions, uvs, normals);
+    result.factory = createBox;
+    result.options = {
+        width,
+        height,
+        depth,
+        widthSegments,
+        heightSegments,
+        depthSegments
+    };
+    result.shape = { factory: result.factory, options: result.options };
+    return result;
+
+}
+

package/src/geometry/cylinder.js

@@ -0,0 +1,244 @@
+import { vec3 } from "../vec3.js";
+import { vec2 } from "../vec2.js";
+import { toJSON } from "./json.js";
+
+/**
+ * Creates a cylinder
+ * @author Three.js converted
+ **/
+export function createCylinder(options = {})
+{
+    let {
+        radiusTop = 1,
+        radiusBottom = 1,
+        height = 1,
+        radialSegments = 32,
+        heightSegments = 1,
+        openEnded = false,
+        thetaStart = 0,
+        thetaLength = Math.PI * 2
+    } = options;
+
+    if (![ radiusTop, radiusBottom, height, thetaStart, thetaLength ].every(Number.isFinite) ||
+        height === 0 ||
+        thetaLength === 0 ||
+        (radiusTop === 0 && radiusBottom === 0))
+    {
+        throw new Error("Invalid cylinder dimensions");
+    }
+
+    radialSegments = Math.max(3, Math.floor(Number.isFinite(radialSegments) ? radialSegments : 32));
+    heightSegments = Math.max(1, Math.floor(Number.isFinite(heightSegments) ? heightSegments : 1));
+
+    // buffers
+    const
+        indices = [],
+        positions = [],
+        normals = [],
+        uvs = [];
+
+    // helper variables
+    let index = 0;
+
+    const
+        indexArray = [],
+        halfHeight = height / 2;
+
+    // build geometry
+    function generateTorso()
+    {
+        const
+            normal = vec3.alloc(),
+            vertex = vec3.alloc();
+
+        // this will be used to calculate the normal
+        const slope = (radiusBottom - radiusTop) / height;
+
+        // generate positions, normals and uvs
+
+        for (let y = 0; y <= heightSegments; y++)
+        {
+            const
+                indexRow = [],
+                v = y / heightSegments;
+
+            // calculate the radius of the current row
+            const radius = v * (radiusBottom - radiusTop) + radiusTop;
+            for (let x = 0; x <= radialSegments; x++)
+            {
+                const
+                    u = x / radialSegments,
+                    theta = u * thetaLength + thetaStart,
+                    sinTheta = Math.sin(theta),
+                    cosTheta = Math.cos(theta);
+
+                // vertex
+                vertex[0] = radius * sinTheta;
+                vertex[1] = -v * height + halfHeight;
+                vertex[2] = radius * cosTheta;
+                positions.push(vertex[0], vertex[1], vertex[2]);
+
+                // normal
+                normal[0] = sinTheta;
+                normal[1] = slope;
+                normal[2] = cosTheta;
+                vec3.normalize(normal, normal);
+                normals.push(normal[0], normal[1], normal[2]);
+
+                // uv
+                uvs.push(u, 1 - v);
+
+                // save index of vertex in respective row
+                indexRow.push(index++);
+            }
+
+            // now save positions of the row in our index array
+            indexArray.push(indexRow);
+        }
+
+        vec3.unalloc(vertex);
+        vec3.unalloc(normal);
+
+        // generate indices
+        for (let x = 0; x < radialSegments; x++)
+        {
+            for (let y = 0; y < heightSegments; y++)
+            {
+                // we use the index array to access the correct indices
+                const
+                    a = indexArray[y][x],
+                    b = indexArray[y + 1][x],
+                    c = indexArray[y + 1][x + 1],
+                    d = indexArray[y][x + 1],
+                    upperRadius = (y / heightSegments) * (radiusBottom - radiusTop) + radiusTop,
+                    lowerRadius = ((y + 1) / heightSegments) * (radiusBottom - radiusTop) + radiusTop;
+
+                // faces
+                if (upperRadius !== 0) indices.push(a, b, d);
+                if (lowerRadius !== 0) indices.push(b, c, d);
+            }
+        }
+    }
+
+    function generateCap(top)
+    {
+
+        // save the index of the first center vertex
+        const centerIndexStart = index;
+
+        const
+            uv = vec2.alloc(),
+            vertex = vec3.alloc(),
+            radius = (top === true) ? radiusTop : radiusBottom,
+            sign = (top === true) ? 1 : -1;
+
+        // first we generate the center vertex data of the cap.
+        // because the geometry needs one set of uvs per face,
+        // we must generate a center vertex per face/segment
+
+        for (let x = 1; x <= radialSegments; x++)
+        {
+            // vertex
+            positions.push(0, halfHeight * sign, 0);
+
+            // normal
+            normals.push(0, sign, 0);
+
+            // uv
+            uvs.push(0.5, 0.5);
+
+            // increase index
+            index++;
+        }
+
+        // save the index of the last center vertex
+        const centerIndexEnd = index;
+
+        // now we generate the surrounding positions, normals and uvs
+
+        for (let x = 0; x <= radialSegments; x++)
+        {
+            const
+                u = x / radialSegments,
+                theta = u * thetaLength + thetaStart,
+                cosTheta = Math.cos(theta),
+                sinTheta = Math.sin(theta);
+
+            // vertex
+            vertex[0] = radius * sinTheta;
+            vertex[1] = halfHeight * sign;
+            vertex[2] = radius * cosTheta;
+            positions.push(vertex[0], vertex[1], vertex[2]);
+
+            // normal
+            normals.push(0, sign, 0);
+
+            // uv
+            uv[0] = (cosTheta * 0.5) + 0.5;
+            uv[1] = (sinTheta * 0.5 * sign) + 0.5;
+            uvs.push(uv[0], uv[1]);
+
+            // increase index
+            index++;
+        }
+
+        vec2.unalloc(uv);
+        vec3.unalloc(vertex);
+
+        // generate indices
+        for (let x = 0; x < radialSegments; x++)
+        {
+            const
+                c = centerIndexStart + x,
+                i = centerIndexEnd + x;
+
+            if (top === true)
+            {
+                // face top
+                indices.push(i, i + 1, c);
+            }
+            else
+            {
+                // face bottom
+                indices.push(i + 1, i, c);
+            }
+        }
+    }
+
+    // generate geometry
+    generateTorso();
+
+    if (openEnded === false)
+    {
+        if (radiusTop > 0) generateCap(true);
+        if (radiusBottom > 0) generateCap(false);
+    }
+
+    const result = toJSON(indices, positions, uvs, normals);
+    result.factory = createCylinder;
+    result.options = {
+        radiusTop,
+        radiusBottom,
+        height,
+        radialSegments,
+        heightSegments,
+        openEnded,
+        thetaStart,
+        thetaLength
+    };
+    return result;
+}
+
+export function createCone(options={})
+{
+    const { radius = 1 } = options;
+    const result = createCylinder(Object.assign({}, options, {
+        radiusTop: 0,
+        radiusBottom: radius
+    }));
+    result.factory = createCone;
+    Reflect.deleteProperty(result.options, "radiusTop");
+    Reflect.deleteProperty(result.options, "radiusBottom");
+    result.options.radius = radius;
+    return result;
+}

package/src/geometry/helpers/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2016, Mapbox
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.