@umituz/web-virtual 2.0.0 → 2.0.2

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.
@@ -37,6 +37,8 @@ All 3D models integrated into `@umituz/web-virtual` comply with strict open-sour
37
37
  | **Characters** | `character-female-a.glb` | Skinned glTF | 273.4 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/mini-characters |
38
38
  | **Characters** | `character-female-b.glb` | Skinned glTF | 252.1 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/mini-characters |
39
39
 
40
+ > **Character texture note:** the Mini Characters kit ships its models with a shared external `Textures/colormap.png` atlas. That atlas (CC0, same kit) is now **embedded inside each character GLB**, making them fully self-contained — no sidecar files to lose between the package and consumer apps.
41
+
40
42
  ---
41
43
 
42
44
  ## 2. Integration Policy
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umituz/web-virtual",
3
- "version": "2.0.0",
3
+ "version": "2.0.2",
4
4
  "description": "Universal 3D Virtual Environment Engine for Web & React — Offices, Farms, Factories, Schools, Hospitals with 60fps performance, raycasting and interactive entities.",
5
5
  "type": "module",
6
6
  "main": "./src/index.ts",
@@ -0,0 +1,79 @@
1
+ import { describe, it, expect } from 'vitest'
2
+ import * as THREE from 'three'
3
+ import { rebindSkinnedSkeletons } from './modelLoader'
4
+
5
+ /**
6
+ * Synthetic rigged asset: a Group with named bones and a SkinnedMesh bound
7
+ * to them — the same structure Kenney character GLBs produce.
8
+ */
9
+ function makeRiggedGroup(): { root: THREE.Group; mesh: THREE.SkinnedMesh; skeleton: THREE.Skeleton } {
10
+ const root = new THREE.Group()
11
+ root.name = 'character'
12
+
13
+ const boneRoot = new THREE.Bone()
14
+ boneRoot.name = 'root'
15
+ const boneHead = new THREE.Bone()
16
+ boneHead.name = 'head'
17
+ boneRoot.add(boneHead)
18
+ root.add(boneRoot)
19
+
20
+ const mesh = new THREE.SkinnedMesh(
21
+ new THREE.BoxGeometry(1, 1, 1),
22
+ new THREE.MeshStandardMaterial(),
23
+ )
24
+ mesh.name = 'body-mesh'
25
+ root.add(mesh)
26
+
27
+ const skeleton = new THREE.Skeleton([boneRoot, boneHead])
28
+ mesh.bind(skeleton, new THREE.Matrix4())
29
+
30
+ return { root, mesh, skeleton }
31
+ }
32
+
33
+ describe('rebindSkinnedSkeletons', () => {
34
+ it('leaves non-skinned hierarchies untouched', () => {
35
+ const group = new THREE.Group()
36
+ group.add(new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial()))
37
+ const clone = group.clone(true)
38
+ expect(() => rebindSkinnedSkeletons(clone)).not.toThrow()
39
+ expect(clone.children).toHaveLength(1)
40
+ })
41
+
42
+ it('clones share the source skeleton before rebinding (the bug)', () => {
43
+ const { root, mesh, skeleton } = makeRiggedGroup()
44
+ const clone = root.clone(true)
45
+ const cloneMesh = clone.getObjectByName('body-mesh') as THREE.SkinnedMesh
46
+ expect(cloneMesh.skeleton).toBe(skeleton)
47
+ expect(cloneMesh.skeleton.bones[0]).toBe(mesh.skeleton.bones[0])
48
+ })
49
+
50
+ it('rebinds a cloned skinned mesh to the bones inside its own hierarchy', () => {
51
+ const { root, skeleton } = makeRiggedGroup()
52
+ const clone = root.clone(true)
53
+ rebindSkinnedSkeletons(clone)
54
+
55
+ const cloneMesh = clone.getObjectByName('body-mesh') as THREE.SkinnedMesh
56
+ expect(cloneMesh.skeleton).not.toBe(skeleton)
57
+ expect(cloneMesh.skeleton.bones.map((b) => b.name)).toEqual(['root', 'head'])
58
+ for (const bone of cloneMesh.skeleton.bones) {
59
+ // every bound bone must live inside the clone, not the source
60
+ let cur: THREE.Object3D | null = bone
61
+ while (cur) {
62
+ if (cur === clone) break
63
+ cur = cur.parent
64
+ }
65
+ expect(cur).toBe(clone)
66
+ }
67
+ })
68
+
69
+ it('keeps the original bound when a joint is missing from the clone', () => {
70
+ const { root, skeleton } = makeRiggedGroup()
71
+ const clone = root.clone(true)
72
+ // rename a cloned bone so the joint cannot be resolved by name
73
+ clone.getObjectByName('head')!.name = 'renamed'
74
+ rebindSkinnedSkeletons(clone)
75
+
76
+ const cloneMesh = clone.getObjectByName('body-mesh') as THREE.SkinnedMesh
77
+ expect(cloneMesh.skeleton).toBe(skeleton)
78
+ })
79
+ })
@@ -2,6 +2,32 @@ import * as THREE from 'three'
2
2
  import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
3
3
  import { ASSET_CATALOG, type AssetMetadata } from './assetCatalog'
4
4
 
5
+ /**
6
+ * Rebind skinned meshes in a cloned hierarchy to the clone's own bones.
7
+ *
8
+ * `Object3D.clone()` copies the hierarchy, but cloned `SkinnedMesh`es keep
9
+ * referencing the ORIGINAL skeleton's bones. With several clones in a scene
10
+ * every instance deforms against the source's (frozen) bone matrices —
11
+ * all but one render at the wrong transform or not at all. Rebinding each
12
+ * clone to the same-named bones inside its own hierarchy makes every
13
+ * instance render (and animate) independently.
14
+ */
15
+ export function rebindSkinnedSkeletons(cloned: THREE.Object3D): void {
16
+ cloned.traverse((node) => {
17
+ const skinned = node as THREE.SkinnedMesh
18
+ if (!skinned.isSkinnedMesh || !skinned.skeleton) return
19
+ const bones = skinned.skeleton.bones
20
+ .map((bone) => cloned.getObjectByName(bone.name))
21
+ .filter((b): b is THREE.Bone => !!b && (b as THREE.Bone).isBone === true)
22
+ // Only rebind when every joint maps to a bone inside this clone
23
+ if (bones.length !== skinned.skeleton.bones.length) return
24
+ skinned.bind(
25
+ new THREE.Skeleton(bones, skinned.skeleton.boneInverses),
26
+ skinned.bindMatrix,
27
+ )
28
+ })
29
+ }
30
+
5
31
  export class ModelLoader {
6
32
  private static instance: ModelLoader | null = null
7
33
  private loader: GLTFLoader
@@ -97,6 +123,9 @@ export class ModelLoader {
97
123
 
98
124
  private cloneGroup(source: THREE.Group, meta?: AssetMetadata): THREE.Group {
99
125
  const cloned = source.clone(true)
126
+ // Skinned meshes cannot share a skeleton across clones — rebind each
127
+ // clone to the bones inside its own hierarchy (see rebindSkinnedSkeletons).
128
+ rebindSkinnedSkeletons(cloned)
100
129
  if (meta && meta.defaultScale) {
101
130
  if (typeof meta.defaultScale === 'number') {
102
131
  cloned.scale.setScalar(meta.defaultScale)
@@ -1335,6 +1335,10 @@
1335
1335
  flex: 1;
1336
1336
  width: 100%;
1337
1337
  height: 100%;
1338
+ /* Flex items default to min-width:auto, so the pixel-sized 3D canvas
1339
+ inside blocks shrinking and pushes the roster sidebar off-screen.
1340
+ Allow the wrapper to shrink so sidebars stay in the viewport. */
1341
+ min-width: 0;
1338
1342
  }
1339
1343
 
1340
1344
  .wv-hq-loading-overlay {