@umicat/three-sdk 1.17.0 → 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.
package/README.md CHANGED
@@ -40,6 +40,15 @@ middle-mouse pan, F-to-focus, or Studio's comma/period ring-rotate.
40
40
  > each of those arrived. A status line is the first thing anyone reads and the
41
41
  > last thing anyone updates.
42
42
 
43
+ **Multiplayer is in the layer below, and it has rules worth reading before you
44
+ design anything around it** — the room type is always `'lobby'`, and the server
45
+ is authoritative about identity and ownership rather than about your game's
46
+ rules (so shared, contended state has no referee, and secret state is not
47
+ possible yet). It is written up in `@umicat/platform-sdk`'s README, under
48
+ "`rooms`: what the server guarantees, and what it does not". **A 3D game shipped
49
+ the wrong room type because that write-up used to live only in the Phaser SDK's
50
+ guide**, which nothing here points at.
51
+
43
52
  ```
44
53
  @umicat/platform-sdk identity · saves · gameData · rooms · ai · voice · dialogue
45
54
  ▲ (shared with @umicat/phaser-sdk)
@@ -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
  }
@@ -269,7 +269,10 @@ export async function runEditorDesignPlayer3D(renderer, opts = {}) {
269
269
  // preserve the 0.37 forever, and the visible seam with it.
270
270
  let snapEnabled = true;
271
271
  let snapStep = 1;
272
- let snapRotateRad = Math.PI / 2;
272
+ // 45 degrees, matching Roblox Studio. Multiples of 45 REACH every 90-degree
273
+ // orientation while also permitting diagonals, so it is strictly more
274
+ // reachable than a 90 default at no cost — which is why Studio picked it.
275
+ let snapRotateRad = Math.PI / 4;
273
276
  const snap1 = (v) => Math.round(v / snapStep) * snapStep;
274
277
  /**
275
278
  * Round a WORLD-space position onto the grid. Always called BEFORE the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umicat/three-sdk",
3
- "version": "1.17.0",
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",