@umituz/web-virtual 1.0.6 → 1.1.1

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.
Files changed (30) hide show
  1. package/assets/ASSET_CREDITS.md +45 -0
  2. package/assets/models/characters/character-female-a.glb +0 -0
  3. package/assets/models/characters/character-female-b.glb +0 -0
  4. package/assets/models/characters/character-male-a.glb +0 -0
  5. package/assets/models/characters/character-male-b.glb +0 -0
  6. package/assets/models/decor/lampRoundFloor.glb +0 -0
  7. package/assets/models/decor/plantSmall1.glb +0 -0
  8. package/assets/models/decor/pottedPlant.glb +0 -0
  9. package/assets/models/decor/trashcan.glb +0 -0
  10. package/assets/models/equipment/computerKeyboard.glb +0 -0
  11. package/assets/models/equipment/computerMouse.glb +0 -0
  12. package/assets/models/equipment/computerScreen.glb +0 -0
  13. package/assets/models/equipment/laptop.glb +0 -0
  14. package/assets/models/furniture/bookcaseOpen.glb +0 -0
  15. package/assets/models/furniture/chairDesk.glb +0 -0
  16. package/assets/models/furniture/desk.glb +0 -0
  17. package/assets/models/furniture/deskCorner.glb +0 -0
  18. package/assets/models/furniture/loungeChair.glb +0 -0
  19. package/assets/models/furniture/loungeSofa.glb +0 -0
  20. package/assets/models/furniture/table.glb +0 -0
  21. package/assets/models/furniture/tableCoffee.glb +0 -0
  22. package/package.json +2 -1
  23. package/src/engine/assetCatalog.test.ts +29 -0
  24. package/src/engine/assetCatalog.ts +222 -0
  25. package/src/engine/index.ts +2 -0
  26. package/src/engine/modelLoader.ts +126 -0
  27. package/src/entities/furniture/DeskBuilder.ts +196 -202
  28. package/src/entities/people/AvatarBuilder.ts +150 -208
  29. package/src/entities/props/PlantBuilder.ts +33 -36
  30. package/src/presets/officePreset.ts +37 -0
@@ -0,0 +1,45 @@
1
+ # 3D Asset Inventory & Licensing Credits
2
+
3
+ All 3D models integrated into `@umituz/web-virtual` comply with strict open-source and commercial-use licensing requirements.
4
+
5
+ ---
6
+
7
+ ## 1. Primary Asset Source: Kenneynl (CC0 1.0 Universal)
8
+
9
+ - **Author / Studio:** Kenney (Asset Jesus) — [https://kenney.nl](https://kenney.nl)
10
+ - **License:** **CC0 1.0 Universal (Public Domain Dedication)**
11
+ - https://creativecommons.org/publicdomain/zero/1.0/
12
+ - *"You can copy, modify, distribute and perform the work, even for commercial purposes, all without asking permission."*
13
+ - **Source Repository:** [https://github.com/shorepine/kenney](https://github.com/shorepine/kenney)
14
+
15
+ ### Model Catalog:
16
+
17
+ | Category | Model Name | Format | Size | License | Author | Source URL |
18
+ |---|---|---|---|---|---|---|
19
+ | **Furniture** | `desk.glb` | Binary glTF | 15.0 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
20
+ | **Furniture** | `deskCorner.glb` | Binary glTF | 18.0 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
21
+ | **Furniture** | `chairDesk.glb` | Binary glTF | 39.0 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
22
+ | **Furniture** | `table.glb` | Binary glTF | 8.2 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
23
+ | **Furniture** | `tableCoffee.glb` | Binary glTF | 8.3 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
24
+ | **Furniture** | `loungeSofa.glb` | Binary glTF | 9.6 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
25
+ | **Furniture** | `loungeChair.glb` | Binary glTF | 9.6 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
26
+ | **Furniture** | `bookcaseOpen.glb` | Binary glTF | 18.0 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
27
+ | **Equipment** | `computerScreen.glb` | Binary glTF | 6.4 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
28
+ | **Equipment** | `computerKeyboard.glb` | Binary glTF | 3.5 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
29
+ | **Equipment** | `computerMouse.glb` | Binary glTF | 5.9 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
30
+ | **Equipment** | `laptop.glb` | Binary glTF | 5.5 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
31
+ | **Decor** | `pottedPlant.glb` | Binary glTF | 7.6 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
32
+ | **Decor** | `plantSmall1.glb` | Binary glTF | 8.2 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
33
+ | **Decor** | `trashcan.glb` | Binary glTF | 6.5 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
34
+ | **Decor** | `lampRoundFloor.glb` | Binary glTF | 6.6 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/furniture-kit |
35
+ | **Characters** | `character-male-a.glb` | Skinned glTF | 246.9 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/mini-characters |
36
+ | **Characters** | `character-male-b.glb` | Skinned glTF | 247.3 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/mini-characters |
37
+ | **Characters** | `character-female-a.glb` | Skinned glTF | 273.4 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/mini-characters |
38
+ | **Characters** | `character-female-b.glb` | Skinned glTF | 252.1 KB | CC0 1.0 | Kenney | https://kenney.nl/assets/mini-characters |
39
+
40
+ ---
41
+
42
+ ## 2. Integration Policy
43
+
44
+ - No copyrighted, proprietary, or non-commercial (NC) assets are admitted into the engine.
45
+ - Every asset is verified for web optimization (PBR vertex colors or compact texture maps, binary GLB compression, clean mesh topology).
Binary file
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umituz/web-virtual",
3
- "version": "1.0.6",
3
+ "version": "1.1.1",
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",
@@ -20,6 +20,7 @@
20
20
  },
21
21
  "files": [
22
22
  "src",
23
+ "assets",
23
24
  "README.md",
24
25
  "LICENSE"
25
26
  ],
@@ -0,0 +1,29 @@
1
+ import { describe, it, expect } from 'vitest'
2
+ import { ASSET_CATALOG } from './assetCatalog'
3
+ import { ModelLoader } from './modelLoader'
4
+
5
+ describe('Asset Catalog & Model Loader', () => {
6
+ it('registers all required office models in ASSET_CATALOG', () => {
7
+ expect(ASSET_CATALOG['furniture:desk']).toBeDefined()
8
+ expect(ASSET_CATALOG['furniture:chairDesk']).toBeDefined()
9
+ expect(ASSET_CATALOG['equipment:screen']).toBeDefined()
10
+ expect(ASSET_CATALOG['equipment:keyboard']).toBeDefined()
11
+ expect(ASSET_CATALOG['decor:pottedPlant']).toBeDefined()
12
+ expect(ASSET_CATALOG['character:male-a']).toBeDefined()
13
+ expect(ASSET_CATALOG['character:female-a']).toBeDefined()
14
+ })
15
+
16
+ it('verifies CC0 license attribution for all assets', () => {
17
+ for (const [id, meta] of Object.entries(ASSET_CATALOG)) {
18
+ expect(meta.license, `Asset ${id} must have valid license`).toContain('CC0')
19
+ expect(meta.author, `Asset ${id} must have author`).toBe('Kenney')
20
+ expect(meta.path, `Asset ${id} must point to .glb`).toMatch(/\.glb$/)
21
+ }
22
+ })
23
+
24
+ it('initializes ModelLoader singleton', () => {
25
+ const loader1 = ModelLoader.getInstance()
26
+ const loader2 = ModelLoader.getInstance()
27
+ expect(loader1).toBe(loader2)
28
+ })
29
+ })
@@ -0,0 +1,222 @@
1
+ export interface AssetMetadata {
2
+ id: string
3
+ name: string
4
+ category: 'furniture' | 'equipment' | 'decor' | 'characters' | 'architecture'
5
+ path: string
6
+ author: string
7
+ license: string
8
+ dimensions?: [number, number, number]
9
+ defaultScale?: number | [number, number, number]
10
+ defaultRotation?: [number, number, number]
11
+ defaultOffset?: [number, number, number]
12
+ }
13
+
14
+ export const ASSET_CATALOG: Record<string, AssetMetadata> = {
15
+ // Furniture
16
+ 'furniture:desk': {
17
+ id: 'furniture:desk',
18
+ name: 'Modern Office Workstation Desk',
19
+ category: 'furniture',
20
+ path: '/assets/models/furniture/desk.glb',
21
+ author: 'Kenney',
22
+ license: 'CC0 1.0 Universal',
23
+ dimensions: [1.6, 0.75, 0.8],
24
+ defaultScale: 1.0,
25
+ },
26
+ 'furniture:deskCorner': {
27
+ id: 'furniture:deskCorner',
28
+ name: 'Executive Corner Desk',
29
+ category: 'furniture',
30
+ path: '/assets/models/furniture/deskCorner.glb',
31
+ author: 'Kenney',
32
+ license: 'CC0 1.0 Universal',
33
+ dimensions: [2.2, 0.75, 1.8],
34
+ defaultScale: 1.0,
35
+ },
36
+ 'furniture:chairDesk': {
37
+ id: 'furniture:chairDesk',
38
+ name: 'Ergonomic Desk Chair with Casters',
39
+ category: 'furniture',
40
+ path: '/assets/models/furniture/chairDesk.glb',
41
+ author: 'Kenney',
42
+ license: 'CC0 1.0 Universal',
43
+ dimensions: [0.6, 0.9, 0.6],
44
+ defaultScale: 1.0,
45
+ },
46
+ 'furniture:table': {
47
+ id: 'furniture:table',
48
+ name: 'Conference Meeting Table',
49
+ category: 'furniture',
50
+ path: '/assets/models/furniture/table.glb',
51
+ author: 'Kenney',
52
+ license: 'CC0 1.0 Universal',
53
+ dimensions: [2.0, 0.75, 1.0],
54
+ defaultScale: 1.4,
55
+ },
56
+ 'furniture:tableCoffee': {
57
+ id: 'furniture:tableCoffee',
58
+ name: 'Lounge Coffee Table',
59
+ category: 'furniture',
60
+ path: '/assets/models/furniture/tableCoffee.glb',
61
+ author: 'Kenney',
62
+ license: 'CC0 1.0 Universal',
63
+ dimensions: [1.0, 0.4, 0.6],
64
+ defaultScale: 1.0,
65
+ },
66
+ 'furniture:loungeSofa': {
67
+ id: 'furniture:loungeSofa',
68
+ name: 'Breakout Lounge Sofa',
69
+ category: 'furniture',
70
+ path: '/assets/models/furniture/loungeSofa.glb',
71
+ author: 'Kenney',
72
+ license: 'CC0 1.0 Universal',
73
+ dimensions: [1.8, 0.8, 0.8],
74
+ defaultScale: 1.1,
75
+ },
76
+ 'furniture:loungeChair': {
77
+ id: 'furniture:loungeChair',
78
+ name: 'Lounge Armchair',
79
+ category: 'furniture',
80
+ path: '/assets/models/furniture/loungeChair.glb',
81
+ author: 'Kenney',
82
+ license: 'CC0 1.0 Universal',
83
+ dimensions: [0.8, 0.8, 0.8],
84
+ defaultScale: 1.1,
85
+ },
86
+ 'furniture:bookcaseOpen': {
87
+ id: 'furniture:bookcaseOpen',
88
+ name: 'Open Storage Shelves & Bookcase',
89
+ category: 'furniture',
90
+ path: '/assets/models/furniture/bookcaseOpen.glb',
91
+ author: 'Kenney',
92
+ license: 'CC0 1.0 Universal',
93
+ dimensions: [1.0, 1.8, 0.4],
94
+ defaultScale: 1.0,
95
+ },
96
+
97
+ // Equipment
98
+ 'equipment:screen': {
99
+ id: 'equipment:screen',
100
+ name: 'Computer Monitor',
101
+ category: 'equipment',
102
+ path: '/assets/models/equipment/computerScreen.glb',
103
+ author: 'Kenney',
104
+ license: 'CC0 1.0 Universal',
105
+ dimensions: [0.6, 0.4, 0.15],
106
+ defaultScale: 1.0,
107
+ },
108
+ 'equipment:keyboard': {
109
+ id: 'equipment:keyboard',
110
+ name: 'Computer Keyboard',
111
+ category: 'equipment',
112
+ path: '/assets/models/equipment/computerKeyboard.glb',
113
+ author: 'Kenney',
114
+ license: 'CC0 1.0 Universal',
115
+ dimensions: [0.45, 0.02, 0.15],
116
+ defaultScale: 1.0,
117
+ },
118
+ 'equipment:mouse': {
119
+ id: 'equipment:mouse',
120
+ name: 'Computer Mouse',
121
+ category: 'equipment',
122
+ path: '/assets/models/equipment/computerMouse.glb',
123
+ author: 'Kenney',
124
+ license: 'CC0 1.0 Universal',
125
+ dimensions: [0.08, 0.03, 0.12],
126
+ defaultScale: 1.0,
127
+ },
128
+ 'equipment:laptop': {
129
+ id: 'equipment:laptop',
130
+ name: 'Workstation Laptop',
131
+ category: 'equipment',
132
+ path: '/assets/models/equipment/laptop.glb',
133
+ author: 'Kenney',
134
+ license: 'CC0 1.0 Universal',
135
+ dimensions: [0.35, 0.22, 0.25],
136
+ defaultScale: 1.0,
137
+ },
138
+
139
+ // Decor
140
+ 'decor:pottedPlant': {
141
+ id: 'decor:pottedPlant',
142
+ name: 'Large Indoor Office Plant in Pot',
143
+ category: 'decor',
144
+ path: '/assets/models/decor/pottedPlant.glb',
145
+ author: 'Kenney',
146
+ license: 'CC0 1.0 Universal',
147
+ dimensions: [0.5, 1.2, 0.5],
148
+ defaultScale: 1.3,
149
+ },
150
+ 'decor:plantSmall': {
151
+ id: 'decor:plantSmall',
152
+ name: 'Desktop Ficus Plant',
153
+ category: 'decor',
154
+ path: '/assets/models/decor/plantSmall1.glb',
155
+ author: 'Kenney',
156
+ license: 'CC0 1.0 Universal',
157
+ dimensions: [0.25, 0.35, 0.25],
158
+ defaultScale: 1.1,
159
+ },
160
+ 'decor:trashcan': {
161
+ id: 'decor:trashcan',
162
+ name: 'Modern Office Trashcan',
163
+ category: 'decor',
164
+ path: '/assets/models/decor/trashcan.glb',
165
+ author: 'Kenney',
166
+ license: 'CC0 1.0 Universal',
167
+ dimensions: [0.3, 0.4, 0.3],
168
+ defaultScale: 1.0,
169
+ },
170
+ 'decor:lampFloor': {
171
+ id: 'decor:lampFloor',
172
+ name: 'Round Floor Lamp',
173
+ category: 'decor',
174
+ path: '/assets/models/decor/lampRoundFloor.glb',
175
+ author: 'Kenney',
176
+ license: 'CC0 1.0 Universal',
177
+ dimensions: [0.4, 1.5, 0.4],
178
+ defaultScale: 1.1,
179
+ },
180
+
181
+ // Characters
182
+ 'character:male-a': {
183
+ id: 'character:male-a',
184
+ name: 'Employee Avatar Male A',
185
+ category: 'characters',
186
+ path: '/assets/models/characters/character-male-a.glb',
187
+ author: 'Kenney',
188
+ license: 'CC0 1.0 Universal',
189
+ dimensions: [0.4, 1.2, 0.3],
190
+ defaultScale: 0.9,
191
+ },
192
+ 'character:male-b': {
193
+ id: 'character:male-b',
194
+ name: 'Employee Avatar Male B',
195
+ category: 'characters',
196
+ path: '/assets/models/characters/character-male-b.glb',
197
+ author: 'Kenney',
198
+ license: 'CC0 1.0 Universal',
199
+ dimensions: [0.4, 1.2, 0.3],
200
+ defaultScale: 0.9,
201
+ },
202
+ 'character:female-a': {
203
+ id: 'character:female-a',
204
+ name: 'Employee Avatar Female A',
205
+ category: 'characters',
206
+ path: '/assets/models/characters/character-female-a.glb',
207
+ author: 'Kenney',
208
+ license: 'CC0 1.0 Universal',
209
+ dimensions: [0.4, 1.2, 0.3],
210
+ defaultScale: 0.9,
211
+ },
212
+ 'character:female-b': {
213
+ id: 'character:female-b',
214
+ name: 'Employee Avatar Female B',
215
+ category: 'characters',
216
+ path: '/assets/models/characters/character-female-b.glb',
217
+ author: 'Kenney',
218
+ license: 'CC0 1.0 Universal',
219
+ dimensions: [0.4, 1.2, 0.3],
220
+ defaultScale: 0.9,
221
+ },
222
+ }
@@ -5,3 +5,5 @@ export * from './camera'
5
5
  export * from './raycaster'
6
6
  export * from './performance'
7
7
  export * from './renderer'
8
+ export * from './assetCatalog'
9
+ export * from './modelLoader'
@@ -0,0 +1,126 @@
1
+ import * as THREE from 'three'
2
+ import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
3
+ import { ASSET_CATALOG, type AssetMetadata } from './assetCatalog'
4
+
5
+ export class ModelLoader {
6
+ private static instance: ModelLoader | null = null
7
+ private loader: GLTFLoader
8
+ private cache: Map<string, THREE.Group> = new Map()
9
+ private pending: Map<string, Promise<THREE.Group>> = new Map()
10
+ private basePath = ''
11
+
12
+ constructor() {
13
+ this.loader = new GLTFLoader()
14
+ }
15
+
16
+ static getInstance(): ModelLoader {
17
+ if (!ModelLoader.instance) {
18
+ ModelLoader.instance = new ModelLoader()
19
+ }
20
+ return ModelLoader.instance
21
+ }
22
+
23
+ setBasePath(path: string): void {
24
+ this.basePath = path.replace(/\/$/, '')
25
+ }
26
+
27
+ async load(assetIdOrPath: string): Promise<THREE.Group> {
28
+ const meta: AssetMetadata | undefined = ASSET_CATALOG[assetIdOrPath]
29
+ const rawPath = meta ? meta.path : assetIdOrPath
30
+ const resolvedPath = this.basePath ? `${this.basePath}${rawPath}` : rawPath
31
+
32
+ // 1. Return from cache if already loaded
33
+ if (this.cache.has(resolvedPath)) {
34
+ return this.cloneGroup(this.cache.get(resolvedPath)!, meta)
35
+ }
36
+
37
+ // 2. Await in-flight loading promise
38
+ if (this.pending.has(resolvedPath)) {
39
+ const group = await this.pending.get(resolvedPath)!
40
+ return this.cloneGroup(group, meta)
41
+ }
42
+
43
+ // 3. Initiate fetch and GLTF parse
44
+ const loadPromise = new Promise<THREE.Group>((resolve) => {
45
+ this.loader.load(
46
+ resolvedPath,
47
+ (gltf) => {
48
+ const root = gltf.scene
49
+
50
+ // Configure shadows and PBR properties across all child meshes
51
+ root.traverse((node) => {
52
+ if (node instanceof THREE.Mesh) {
53
+ node.castShadow = true
54
+ node.receiveShadow = true
55
+ if (node.material) {
56
+ if (Array.isArray(node.material)) {
57
+ node.material.forEach((m) => {
58
+ m.roughness = 0.4
59
+ m.metalness = 0.1
60
+ })
61
+ } else {
62
+ node.material.roughness = 0.4
63
+ node.material.metalness = 0.1
64
+ }
65
+ }
66
+ }
67
+ })
68
+
69
+ this.cache.set(resolvedPath, root)
70
+ this.pending.delete(resolvedPath)
71
+ resolve(root)
72
+ },
73
+ undefined,
74
+ (err) => {
75
+ console.warn(`[ModelLoader] Failed to load 3D asset at "${resolvedPath}":`, err)
76
+ // Fallback proxy mesh to prevent application crashes
77
+ const fallback = new THREE.Group()
78
+ const box = new THREE.Mesh(
79
+ new THREE.BoxGeometry(0.8, 0.7, 0.8),
80
+ new THREE.MeshStandardMaterial({ color: 0x94a3b8, roughness: 0.5 }),
81
+ )
82
+ box.position.set(0, 0.35, 0)
83
+ fallback.add(box)
84
+ resolve(fallback)
85
+ },
86
+ )
87
+ })
88
+
89
+ this.pending.set(resolvedPath, loadPromise)
90
+ const loaded = await loadPromise
91
+ return this.cloneGroup(loaded, meta)
92
+ }
93
+
94
+ async preload(assetIds: string[]): Promise<void> {
95
+ await Promise.all(assetIds.map((id) => this.load(id)))
96
+ }
97
+
98
+ private cloneGroup(source: THREE.Group, meta?: AssetMetadata): THREE.Group {
99
+ const cloned = source.clone(true)
100
+ if (meta && meta.defaultScale) {
101
+ if (typeof meta.defaultScale === 'number') {
102
+ cloned.scale.setScalar(meta.defaultScale)
103
+ } else {
104
+ cloned.scale.set(meta.defaultScale[0], meta.defaultScale[1], meta.defaultScale[2])
105
+ }
106
+ }
107
+ return cloned
108
+ }
109
+
110
+ clearCache(): void {
111
+ this.cache.forEach((group) => {
112
+ group.traverse((obj) => {
113
+ if (obj instanceof THREE.Mesh) {
114
+ obj.geometry.dispose()
115
+ if (Array.isArray(obj.material)) {
116
+ obj.material.forEach((m) => m.dispose())
117
+ } else if (obj.material) {
118
+ obj.material.dispose()
119
+ }
120
+ }
121
+ })
122
+ })
123
+ this.cache.clear()
124
+ this.pending.clear()
125
+ }
126
+ }