@woosh/meep-engine 3.23.0 → 3.24.0

package/src/engine/graphics3/instantiate_scene_bundle.js

@@ -1,164 +0,0 @@
-import { assert } from "../../core/assert.js";
-import { ShadeAnimationChannel } from "../../shade/renderer/animation/ShadeAnimationChannel.js";
-import { ShadeAnimationClip } from "../../shade/renderer/animation/ShadeAnimationClip.js";
-import { Skin } from "../../shade/renderer/animation/Skin.js";
-import { TransformAuthority } from "../../shade/renderer/scene/TransformAuthority.js";
-
-/**
- * One entity's private copy of a loaded asset: its own node tree, its own skins bound to that
- * tree's joints, and its own clips retargeted onto it.
- *
- * A loader's {@link SceneBundle} is a template. Its skins name Node3Ds and its clip channels
- * target Node3Ds, so two entities showing the same model cannot share it — the second would drive
- * the first one's joints. What they can share is everything read-only: geometry, materials,
- * inverse-bind matrices and the animation curves themselves, which is why the copy is per-node
- * rather than per-byte.
- */
-export class SceneBundleInstance {
-    /**
-     * @type {Node3D[]}
-     */
-    roots = [];
-
-    /**
-     * @type {Skin[]}
-     */
-    skins = [];
-
-    /**
-     * @type {ShadeAnimationClip[]}
-     */
-    clips = [];
-
-    /**
-     * Every node of the instance, by the name the asset gave it — where a socket, an effect anchor
-     * or a projectile spawn is looked up, since all three are authored as names of bones.
-     *
-     * Built here rather than walked per query because the walk is already happening: the tree is
-     * visited once to copy it. A name authored twice keeps the first node the copy reaches, which
-     * is the same answer a search would have returned.
-     *
-     * @type {Map<string,Node3D>}
-     */
-    nodes = new Map();
-}
-
-/**
- * Copy one node without its children, preserving its type.
- *
- * `clone()` cannot be used for this: {@link Node3D.clone} recurses into children while
- * {@link Mesh.clone} does not, so a tree walk built on it silently drops the descendants of any
- * mesh. `copy()` is uniformly shallow, and the two fields it leaves out — `name` and
- * `transform_authority` — are carried here because a joint is found by name and driven by
- * authority.
- *
- * **A node carries across exactly what its own `copy()` implements.** Shade's `Light` and its three
- * subclasses do not implement one, so a light node arrives as the right class holding default
- * colour and intensity. No asset the game loads contains one; a loader that produced them would need
- * those four `copy()` methods first.
- *
- * @param {Node3D} node
- * @returns {Node3D}
- */
-function copy_node(node) {
-    const r = new node.constructor();
-
-    r.copy(node);
-
-    r.name = node.name;
-    r.transform_authority = node.transform_authority;
-
-    return r;
-}
-
-/**
- * @param {Node3D} node
- * @param {Map<Node3D,Node3D>} correspondence written with every node visited
- * @param {Map<string,Node3D>} by_name written with every named node visited, first one wins
- * @returns {Node3D}
- */
-function copy_subtree(node, correspondence, by_name) {
-    const r = copy_node(node);
-
-    correspondence.set(node, r);
-
-    if (r.name !== "" && !by_name.has(r.name)) {
-        by_name.set(r.name, r);
-    }
-
-    const children = node.children;
-
-    for (let i = 0; i < children.length; i++) {
-        r.addChild(copy_subtree(children[i], correspondence, by_name));
-    }
-
-    return r;
-}
-
-/**
- * Instantiate a loaded asset for one owner.
- *
- * Skins and clips come back pointing at the returned tree and nothing else, so they are ready for
- * {@link GPUAnimationManager#register_skin} and {@link GPUAnimationManager#register_clip} as they
- * are. Every node a clip drives is handed to the GPU
- * ({@link TransformAuthority.GPU}): the pose accumulator writes those rows, and a CPU that also
- * wrote them would race the animation it is trying to show. That same rule is what makes the CPU
- * pose evaluator correct, since it reads `transform_local` as the rest pose.
- *
- * Nothing in the bundle is modified.
- *
- * @param {SceneBundle} bundle
- * @returns {SceneBundleInstance}
- */
-export function instantiate_scene_bundle(bundle) {
-    assert.defined(bundle, 'bundle');
-    assert.equal(bundle.isSceneBundle, true, 'bundle.isSceneBundle !== true');
-
-    const r = new SceneBundleInstance();
-
-    /**
-     * @type {Map<Node3D,Node3D>}
-     */
-    const correspondence = new Map();
-
-    const scenes = bundle.scenes;
-
-    for (let i = 0; i < scenes.length; i++) {
-        r.roots.push(copy_subtree(scenes[i], correspondence, r.nodes));
-    }
-
-    const skins = bundle.skins;
-
-    for (let i = 0; i < skins.length; i++) {
-        const skin = skins[i];
-
-        r.skins.push(Skin.from({
-            name: skin.name,
-            joints: skin.joints.map(joint => correspondence.get(joint)),
-            inverse_bind_matrices: skin.inverse_bind_matrices,
-            meshes: skin.meshes.map(mesh => correspondence.get(mesh))
-        }));
-    }
-
-    const clips = bundle.clips;
-
-    for (let i = 0; i < clips.length; i++) {
-        const clip = clips[i];
-
-        const channels = clip.channels.map(channel => {
-            const target = correspondence.get(channel.target);
-
-            target.transform_authority = TransformAuthority.GPU;
-
-            return ShadeAnimationChannel.from({
-                target,
-                property: channel.property,
-                curves: channel.curves
-            });
-        });
-
-        r.clips.push(ShadeAnimationClip.from({ name: clip.name, channels }));
-    }
-
-    return r;
-}

package/src/engine/graphics3/shade_node_to_entity_composition.js

@@ -1,88 +0,0 @@
-import { Name } from "../ecs/name/Name.js";
-import { EntityNode } from "../ecs/parent/EntityNode.js";
-import { Transform64 } from "../ecs/transform/Transform64.js";
-import { DrawMode } from "../graphics/ecs/mesh-v2/DrawMode.js";
-import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
-
-/**
- * Turn a loaded model's node tree into entities.
- *
- * **This is what a hierarchy is in an ECS** (D47). meep has no scene graph to hand a model to: it
- * has entities, `EntityNode` to parent them, and `ShadedGeometry` for the ones that draw. A model
- * file is therefore not a thing an entity *holds* — it is a shape an entity's descendants take, and
- * this function is where the file stops being the renderer's tree and becomes the dataset's.
- *
- * It is `three_object_to_entity_composition` with the source swapped: the same output, built from
- * Shade's `Node3D`s instead of three's `Object3D`s. The two exist side by side for as long as both
- * renderers do.
- *
- * **Geometry and material are shared, not copied.** Two entities placing the same model name the
- * same `MeshletGeometry` and the same `ShadeMaterial`; what is per-entity is the row each one gets
- * in the scene, which is `ShadedGeometrySystem`'s business. That is the whole reason a static model
- * needs no clone of the bundle at all.
- *
- * **A skinned mesh is not expanded, and that is a boundary rather than an omission.** Its vertices
- * are deformed against a skeleton the renderer owns and the GPU poses, and making those joints
- * entities is a design this program does not do (D47). A `SkinnedMesh` node therefore contributes
- * its transform and its name and no geometry, and whatever placed the model keeps drawing it the way
- * Phase 4 built.
- *
- * @param {Node3D} node
- * @returns {EntityNode}
- */
-export function shade_node_to_entity_composition(node) {
-    const result = new EntityNode();
-
-    // the hierarchy's own transform: what this node is, relative to its parent
-    result.transform.copy(node.transform_local);
-
-    const entity = result.entity;
-
-    // copy() returns nothing, so the transform is built before it is handed over
-    const world = new Transform64();
-
-    world.copy(node.transform_global);
-
-    entity.add(world);
-    entity.add(new Name(node.name));
-
-    if (node.isMesh === true && node.isSkinnedMesh !== true) {
-        entity.add(ShadedGeometry.from(node.geometry, node.material, DrawMode.Triangles));
-    }
-
-    const children = node.children;
-
-    for (let i = 0; i < children.length; i++) {
-        result.addChild(shade_node_to_entity_composition(children[i]));
-    }
-
-    return result;
-}
-
-/**
- * The same, for everything a loader produced.
- *
- * A bundle can carry more than one scene — glTF allows it — and the entity that placed the file owns
- * all of them, so they become children of one root rather than several compositions nobody joins.
- *
- * @param {SceneBundle} bundle
- * @returns {EntityNode}
- */
-export function shade_bundle_to_entity_composition(bundle) {
-    const scenes = bundle.scenes;
-
-    if (scenes.length === 1) {
-        return shade_node_to_entity_composition(scenes[0]);
-    }
-
-    const root = new EntityNode();
-
-    root.entity.add(new Transform64());
-    root.entity.add(new Name(""));
-
-    for (let i = 0; i < scenes.length; i++) {
-        root.addChild(shade_node_to_entity_composition(scenes[i]));
-    }
-
-    return root;
-}

package/src/shade/renderer/animation/compute_skin_world_bounds.js

@@ -1,146 +0,0 @@
-import { assert } from "../../../core/assert.js";
-import { aabb3_matrix4_project } from "../../../core/geom/3d/aabb/aabb3_matrix4_project.js";
-import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
-import { sphere_matrix4_transform } from "../../../core/geom/3d/sphere/sphere_matrix4_transform.js";
-import {
-    sphere_compute_bounding_of_spheres
-} from "../../../core/geom/packing/sphere_compute_bounding_of_spheres.js";
-
-/**
- * One joint's `joint.global × inverse_bind`, rebuilt per joint. Module-level so a walk over a
- * 65-joint skeleton does not allocate a matrix per joint.
- *
- * @type {Float64Array}
- */
-const _scratch_skin_matrix = new Float64Array(16);
-
-/**
- * One joint's inverse-bind matrix, copied out of the skin's flat array. A `subarray` view would
- * read the same 16 floats but allocate an object per joint per call, and this runs whenever a
- * character moves.
- *
- * @type {Float64Array}
- */
-const _scratch_inverse_bind = new Float64Array(16);
-
-/**
- * One joint's projected AABB, before it is folded into the running union.
- *
- * @type {Float64Array}
- */
-const _scratch_box = new Float64Array(6);
-
-/**
- * One joint's projected sphere, before it is copied into {@link _scratch_spheres}.
- *
- * @type {Float64Array}
- */
-const _scratch_sphere = new Float64Array(4);
-
-/**
- * Per-joint `(cx, cy, cz, r)` spheres, handed to
- * {@link sphere_compute_bounding_of_spheres} in one go. Grown to the largest joint count seen so
- * far and never shrunk.
- *
- * @type {Float64Array}
- */
-let _scratch_spheres = new Float64Array(0);
-
-/**
- * World-space bounds of a mesh deformed by `skin`, in the pose the skin's joint nodes currently
- * hold.
- *
- * **The mesh node's own transform does not appear here, and that is the point.** A skinned vertex
- * lands at `mesh.global × inverse(mesh.global) × joint.global × inverse_bind × v` — the skinning
- * pass applies the leftmost inverse (see `chunk_skin_blend_mesh_local`) and the rasterizer
- * re-applies `mesh.global` afterwards, so the two cancel and the vertex is at
- * `joint.global × inverse_bind × v`. Bounding a skinned mesh by putting its rest-pose geometry
- * under `mesh.transform_global` therefore applies a transform the renderer cancels: on an
- * FBX-derived glTF whose root node carries the file's centimetre→metre scale, it comes out 100×
- * too small.
- *
- * The bound is the union over joints of `joint.global × inverse_bind` applied to the mesh-space
- * geometry bounds. Conservative: each joint's product maps the whole geometry rather than the
- * vertices that joint actually weights, and a skinned vertex is a convex combination of those
- * per-joint images, which the enclosing (convex) AABB contains. In the case that matters it is also
- * *tight* — with every joint at its bind pose `joint.global × inverse_bind` collapses to one and
- * the same matrix, the character's placement in the world, so the union is a single exact box.
- *
- * **Pose freshness is the caller's problem.** Joints driven by the GPU pose accumulator are
- * {@link TransformAuthority.GPU}, and their `transform_global` stays at the rest pose the CPU
- * seeded — so for an animated character this is a rest-pose bound that tracks placement, not the
- * deformed silhouette. The per-frame deformed world box lives in the scene database's `meshes` row,
- * published by the skinning pass's bounds-refresh chain, and anything that needs the real thing
- * reads it there.
- *
- * @param {Skin} skin
- * @param {ArrayLike<number>} mesh_box mesh-space AABB, 6 floats — `(low_x, low_y, low_z, high_x, high_y, high_z)`
- * @param {ArrayLike<number>} mesh_sphere mesh-space sphere, 4 floats — `(x, y, z, radius)`
- * @param {Float32Array|number[]} out_box receives the world AABB, 6 floats
- * @param {Float32Array|number[]} out_sphere receives the world sphere, 4 floats
- */
-export function compute_skin_world_bounds(skin, mesh_box, mesh_sphere, out_box, out_sphere) {
-    assert.defined(skin, 'skin');
-    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
-    assert.isArrayLike(mesh_box, 'mesh_box');
-    assert.isArrayLike(mesh_sphere, 'mesh_sphere');
-    assert.notEqual(out_box, mesh_box, 'out_box and mesh_box must be different objects');
-
-    const joints = skin.joints;
-    const joint_count = joints.length;
-
-    assert.greaterThan(joint_count, 0, 'skin.joints.length');
-
-    const inverse_bind = skin.inverse_bind_matrices;
-
-    assert.greaterThanOrEqual(
-        inverse_bind.length, joint_count * 16,
-        'skin.inverse_bind_matrices.length'
-    );
-
-    if (_scratch_spheres.length < joint_count * 4) {
-        _scratch_spheres = new Float64Array(joint_count * 4);
-    }
-
-    let low_x = Infinity, low_y = Infinity, low_z = Infinity;
-    let high_x = -Infinity, high_y = -Infinity, high_z = -Infinity;
-
-    for (let j = 0; j < joint_count; j++) {
-
-        const inverse_bind_offset = j * 16;
-
-        for (let k = 0; k < 16; k++) {
-            _scratch_inverse_bind[k] = inverse_bind[inverse_bind_offset + k];
-        }
-
-        // a Transform64's matrix starts at element 0, so the transform is its own mat4 argument
-        m4_multiply(_scratch_skin_matrix, joints[j].transform_global, _scratch_inverse_bind);
-
-        aabb3_matrix4_project(_scratch_box, mesh_box, _scratch_skin_matrix);
-
-        if (_scratch_box[0] < low_x) low_x = _scratch_box[0];
-        if (_scratch_box[1] < low_y) low_y = _scratch_box[1];
-        if (_scratch_box[2] < low_z) low_z = _scratch_box[2];
-        if (_scratch_box[3] > high_x) high_x = _scratch_box[3];
-        if (_scratch_box[4] > high_y) high_y = _scratch_box[4];
-        if (_scratch_box[5] > high_z) high_z = _scratch_box[5];
-
-        sphere_matrix4_transform(_scratch_sphere, mesh_sphere, _scratch_skin_matrix);
-
-        const sphere_offset = j * 4;
-
-        _scratch_spheres[sphere_offset] = _scratch_sphere[0];
-        _scratch_spheres[sphere_offset + 1] = _scratch_sphere[1];
-        _scratch_spheres[sphere_offset + 2] = _scratch_sphere[2];
-        _scratch_spheres[sphere_offset + 3] = _scratch_sphere[3];
-    }
-
-    out_box[0] = low_x;
-    out_box[1] = low_y;
-    out_box[2] = low_z;
-    out_box[3] = high_x;
-    out_box[4] = high_y;
-    out_box[5] = high_z;
-
-    sphere_compute_bounding_of_spheres(out_sphere, _scratch_spheres, 0, joint_count, 3);
-}