@umicat/three-sdk 1.17.1 → 1.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -7,6 +7,89 @@ import { applyAttachments } from './Attachments.js';
7
7
  function toVec(v, d = 0) {
8
8
  return new THREE.Vector3(v?.x ?? d, v?.y ?? d, v?.z ?? d);
9
9
  }
10
+ /**
11
+ * Collect everything an entity RENDERS into the vertex + index buffers
12
+ * `Rapier.ColliderDesc.trimesh` wants — the collider that follows a concave
13
+ * shape instead of shrink-wrapping it, which is the whole reason the schema
14
+ * offers `trimesh` for static geometry. A convex hull seals every opening: a
15
+ * cave you can see into and not enter, an arch with no gap under it.
16
+ *
17
+ * Vertices come out in the entity ROOT's local frame WITH its authored scale
18
+ * baked in, because that is the frame the rigid body is placed in: the body
19
+ * carries the entity's position and rotation (see the caller) but Rapier
20
+ * bodies have no scale, so unlike `box`/`sphere` — whose authored half-extents
21
+ * already describe final size — a trimesh must carry the scaling itself.
22
+ *
23
+ * `S(root.scale) * inv(root.matrixWorld) * mesh.matrixWorld` is that frame:
24
+ * inverting the root's world matrix removes its position, rotation AND scale,
25
+ * and the scale is then put back deliberately.
26
+ *
27
+ * Returns null when the entity renders no triangles at all, so the caller can
28
+ * skip one collider rather than fail the scene.
29
+ */
30
+ function trimeshData(root, otherEntities) {
31
+ root.updateWorldMatrix(true, true);
32
+ const toRootLocal = new THREE.Matrix4().copy(root.matrixWorld).invert();
33
+ const rescale = new THREE.Matrix4().makeScale(root.scale.x, root.scale.y, root.scale.z);
34
+ const verts = [];
35
+ const idx = [];
36
+ const toCollider = new THREE.Matrix4();
37
+ const v = new THREE.Vector3();
38
+ // Hand-rolled instead of `root.traverse`, because traverse cannot be
39
+ // pruned: a scene can PARENT one entity to another (`Entity3D.parent`),
40
+ // and parenting runs before colliders are built, so a traversal would
41
+ // happily fold a prop's geometry into the scenery it sits on — silently
42
+ // doubling that prop's collision (it owns a collider of its own) and
43
+ // bloating the host's trimesh. A model's own sub-meshes are a different
44
+ // thing entirely and MUST be included, and the only way to tell the two
45
+ // apart is that one of them is itself a registered entity.
46
+ const walk = (o) => {
47
+ if (o !== root && otherEntities.has(o))
48
+ return;
49
+ visit(o);
50
+ for (const child of o.children)
51
+ walk(child);
52
+ };
53
+ const visit = (o) => {
54
+ const mesh = o;
55
+ if (!mesh.isMesh || !mesh.geometry)
56
+ return;
57
+ // Visibility is respected for DESCENDANTS and ignored for the ROOT, and
58
+ // the asymmetry is deliberate. A hidden sub-mesh inside a model is art
59
+ // the author switched off (a variant, an LOD) and must not collide. But
60
+ // an entity hidden in its entirety and given a trimesh collider is the
61
+ // INVISIBLE COLLISION PROXY pattern — real scenes ship exactly that
62
+ // (the editor's `pickEntityAt` has a comment about picking around them)
63
+ // — and skipping it would leave that author with no collider at all,
64
+ // which is the silent-nothing this whole phase exists to remove.
65
+ if (o !== root && mesh.visible === false)
66
+ return;
67
+ const pos = mesh.geometry.getAttribute('position');
68
+ if (!pos)
69
+ return;
70
+ toCollider.copy(toRootLocal).multiply(mesh.matrixWorld).premultiply(rescale);
71
+ const base = verts.length / 3;
72
+ for (let i = 0; i < pos.count; i++) {
73
+ v.fromBufferAttribute(pos, i).applyMatrix4(toCollider);
74
+ verts.push(v.x, v.y, v.z);
75
+ }
76
+ const index = mesh.geometry.getIndex();
77
+ if (index) {
78
+ for (let i = 0; i < index.count; i++)
79
+ idx.push(base + index.getX(i));
80
+ }
81
+ else {
82
+ // Non-indexed geometry is already triangle soup — every three
83
+ // consecutive vertices form a face.
84
+ for (let i = 0; i < pos.count; i++)
85
+ idx.push(base + i);
86
+ }
87
+ };
88
+ walk(root);
89
+ if (idx.length < 3)
90
+ return null;
91
+ return { vertices: new Float32Array(verts), indices: new Uint32Array(idx) };
92
+ }
10
93
  /** `Rapier.ColliderDesc.convexHull` wants a flat `[x,y,z, x,y,z, ...]` buffer. */
11
94
  function flattenPoints(points) {
12
95
  const out = new Float32Array(points.length * 3);
@@ -557,16 +640,48 @@ export async function loadScene3D(scene3d, manifest, opts = {}) {
557
640
  desc.setTranslation(p.x + off.x, p.y + off.y, p.z + off.z);
558
641
  const q = e.transform.rotation ?? IDENTITY_QUAT;
559
642
  desc.setRotation({ x: q[0], y: q[1], z: q[2], w: q[3] });
560
- const body = world.createRigidBody(desc);
561
643
  const s = collider.shape;
562
- const shape = s.kind === 'box' ? R.ColliderDesc.cuboid(s.halfExtents.x, s.halfExtents.y, s.halfExtents.z)
563
- : s.kind === 'sphere' ? R.ColliderDesc.ball(s.radius)
564
- : s.kind === 'capsule' ? R.ColliderDesc.capsule(s.halfHeight, s.radius)
565
- : s.kind === 'cylinder' ? R.ColliderDesc.cylinder(s.halfHeight, s.radius)
566
- : s.kind === 'convexHull' ? R.ColliderDesc.convexHull(flattenPoints(s.points))
567
- : null;
568
- if (!shape)
569
- throw new Error(`entity '${e.id}': trimesh colliders are not supported yet`);
644
+ // Built BEFORE the rigid body, so a collider that cannot be built
645
+ // leaves nothing behind. `trimesh` needs the entity's actual geometry,
646
+ // which every other shape does not — its numbers are authored.
647
+ let shape = null;
648
+ if (s.kind === 'box')
649
+ shape = R.ColliderDesc.cuboid(s.halfExtents.x, s.halfExtents.y, s.halfExtents.z);
650
+ else if (s.kind === 'sphere')
651
+ shape = R.ColliderDesc.ball(s.radius);
652
+ else if (s.kind === 'capsule')
653
+ shape = R.ColliderDesc.capsule(s.halfHeight, s.radius);
654
+ else if (s.kind === 'cylinder')
655
+ shape = R.ColliderDesc.cylinder(s.halfHeight, s.radius);
656
+ else if (s.kind === 'convexHull')
657
+ shape = R.ColliderDesc.convexHull(flattenPoints(s.points));
658
+ else if (s.kind === 'trimesh') {
659
+ const obj = entities.get(e.id);
660
+ const data = obj ? trimeshData(obj, new Set(entities.values())) : null;
661
+ if (data) {
662
+ const triangles = data.indices.length / 3;
663
+ if (triangles > 50000) {
664
+ console.warn(`[umicat/scene3d] entity '${e.id}' builds a ${triangles.toLocaleString()}-triangle trimesh collider. `
665
+ + 'That is fine for static scenery but it is built once per load and never simplified — '
666
+ + 'consider a low-poly collision mesh if load time suffers.');
667
+ }
668
+ shape = R.ColliderDesc.trimesh(data.vertices, data.indices);
669
+ }
670
+ else {
671
+ console.warn(`[umicat/scene3d] entity '${e.id}' asks for a trimesh collider but renders no triangles — skipping its collider.`);
672
+ }
673
+ }
674
+ // One unbuildable collider must never take the whole scene down. That
675
+ // was the old behaviour for `trimesh` (a hard throw out of
676
+ // `loadScene3D`) even though `validateScene` explicitly ALLOWS a static
677
+ // trimesh and only rejects it on a dynamic body — so authored data the
678
+ // validator blessed produced a blank screen instead of one prop with no
679
+ // physics.
680
+ if (!shape) {
681
+ console.warn(`[umicat/scene3d] entity '${e.id}': collider kind '${s.kind}' could not be built — the entity renders, but nothing collides with it.`);
682
+ continue;
683
+ }
684
+ const body = world.createRigidBody(desc);
570
685
  world.createCollider(shape, body);
571
686
  bodies.set(e.id, body);
572
687
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.17.1",
3
+ "version": "1.18.0",
4
4
  "description": "Three.js runtime for Umicat games: the scene3d design format, its loader with physics, a kinematic character controller, and the Umicat platform via @umicat/platform-sdk.",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",