@umituz/web-virtual 1.1.2 → 2.0.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.
@@ -37,12 +37,12 @@ export function WorldControls({
37
37
  fps,
38
38
  }: WorldControlsProps): ReactNode {
39
39
  return (
40
- <div className="wv-controls-toolbar" role="toolbar" aria-label="3D Görünüm Kontrolleri">
40
+ <div className="wv-controls-toolbar" role="toolbar" aria-label="3D view controls">
41
41
  {/* Camera Presets */}
42
42
  <button
43
43
  type="button"
44
44
  className="wv-btn wv-btn-icon"
45
- title="İzometrik Görünüm"
45
+ title="Isometric view"
46
46
  onClick={() => onSelectCameraPreset('isometric')}
47
47
  >
48
48
  <Compass size={16} />
@@ -51,16 +51,16 @@ export function WorldControls({
51
51
  <button
52
52
  type="button"
53
53
  className="wv-btn"
54
- title="Üstten Bakış"
54
+ title="Top-down view"
55
55
  onClick={() => onSelectCameraPreset('top')}
56
56
  >
57
- Üst
57
+ Top
58
58
  </button>
59
59
 
60
60
  <button
61
61
  type="button"
62
62
  className="wv-btn wv-btn-icon"
63
- title="Kamerayı Sıfırla"
63
+ title="Reset camera"
64
64
  onClick={onResetCamera}
65
65
  >
66
66
  <RotateCcw size={15} />
@@ -72,27 +72,27 @@ export function WorldControls({
72
72
  <button
73
73
  type="button"
74
74
  className={`wv-btn ${pinMode === 'pins' ? 'is-active' : ''}`}
75
- title="Minimal İğneler (Sayılar)"
75
+ title="Minimal pins (numbers)"
76
76
  onClick={() => onChangePinMode('pins')}
77
77
  >
78
78
  <MapPin size={14} style={{ marginRight: 4 }} />
79
- İğneler
79
+ Pins
80
80
  </button>
81
81
 
82
82
  <button
83
83
  type="button"
84
84
  className={`wv-btn ${pinMode === 'labels' ? 'is-active' : ''}`}
85
- title="Detaylı Kartlar"
85
+ title="Detailed label cards"
86
86
  onClick={() => onChangePinMode('labels')}
87
87
  >
88
88
  <Tag size={14} style={{ marginRight: 4 }} />
89
- Etiketler
89
+ Labels
90
90
  </button>
91
91
 
92
92
  <button
93
93
  type="button"
94
94
  className={`wv-btn wv-btn-icon ${pinMode === 'off' ? 'is-active' : ''}`}
95
- title="Etiketleri Gizle"
95
+ title="Hide labels"
96
96
  onClick={() => onChangePinMode('off')}
97
97
  >
98
98
  <EyeOff size={15} />
@@ -104,7 +104,7 @@ export function WorldControls({
104
104
  <button
105
105
  type="button"
106
106
  className="wv-btn wv-btn-icon"
107
- title={nightMode ? 'Gündüz Moduna Geç' : 'Gece Moduna Geç'}
107
+ title={nightMode ? 'Switch to day mode' : 'Switch to night mode'}
108
108
  onClick={onToggleNightMode}
109
109
  >
110
110
  {nightMode ? <Sun size={16} color="#f59e0b" /> : <Moon size={16} />}
@@ -115,7 +115,7 @@ export function WorldControls({
115
115
  <button
116
116
  type="button"
117
117
  className="wv-btn wv-btn-icon"
118
- title={isFullscreen ? 'Tam Ekrandan Çık' : 'Tam Ekran'}
118
+ title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}
119
119
  onClick={onToggleFullscreen}
120
120
  >
121
121
  {isFullscreen ? <Minimize2 size={16} /> : <Maximize2 size={16} />}
@@ -1,9 +1,15 @@
1
- import { describe, it, expect } from 'vitest'
2
- import { createEnvironment, validateEnvironment } from './environment'
3
- import { officePreset, farmPreset, factoryPreset, schoolPreset, hospitalPreset } from '../presets/index'
1
+ import { describe, it, expect, vi } from 'vitest'
2
+ import {
3
+ createEnvironment,
4
+ validateEnvironment,
5
+ placeEntitiesOnSlots,
6
+ deriveDepartmentsFromZones,
7
+ } from './environment'
8
+ import type { EntityDraft } from './types'
9
+ import { officePreset, farmPreset, factoryPreset, OFFICE_SLOTS, FARM_SLOTS } from '../presets/index'
4
10
 
5
11
  describe('Environment Factory & Presets', () => {
6
- it('creates an environment using officePreset', () => {
12
+ it('creates an office environment with architecture but no occupants', () => {
7
13
  const world = createEnvironment({
8
14
  preset: officePreset,
9
15
  name: 'Nexora Agency HQ',
@@ -13,28 +19,106 @@ describe('Environment Factory & Presets', () => {
13
19
  expect(world.type).toBe('office')
14
20
  expect(world.dimensions.width).toBe(36)
15
21
  expect(world.zones.length).toBe(6)
16
- expect(world.entities.length).toBe(17)
22
+ expect(world.entities).toEqual([])
17
23
  })
18
24
 
19
- it('creates an environment using farmPreset', () => {
25
+ it('auto-places consumer occupants onto preset slots in order', () => {
26
+ const occupants: EntityDraft[] = [
27
+ { id: 'gm', type: 'person', name: 'Ayşe Yıldız', role: 'CEO', status: 'idle' },
28
+ { id: 'dev', type: 'person', name: 'Mehmet Kaya', role: 'Developer', status: 'running' },
29
+ ]
30
+
20
31
  const world = createEnvironment({
21
- preset: farmPreset,
22
- name: 'Organic Farm Valley',
32
+ preset: officePreset,
33
+ name: 'Team HQ',
34
+ entities: occupants,
23
35
  })
24
36
 
25
- expect(world.type).toBe('farm')
26
- expect(world.zones.length).toBe(3)
27
- expect(world.entities.length).toBe(3)
37
+ expect(world.entities).toHaveLength(2)
38
+ expect(world.entities[0]!.slotId).toBe('slot-1')
39
+ expect(world.entities[0]!.position).toEqual(OFFICE_SLOTS[0]!.position)
40
+ expect(world.entities[0]!.zoneId).toBe('executive')
41
+ expect(world.entities[0]!.pinNumber).toBe(1)
42
+ expect(world.entities[0]!.avatarColor).toBe(OFFICE_SLOTS[0]!.avatarColor)
43
+ expect(world.entities[1]!.slotId).toBe('slot-2')
44
+ expect(world.entities[1]!.position).toEqual(OFFICE_SLOTS[1]!.position)
45
+ // Omitted fields inherit the slot's architectural suggestion
46
+ expect(world.entities[1]!.avatarColor).toBe(OFFICE_SLOTS[1]!.avatarColor)
47
+ expect(world.entities[1]!.zoneId).toBe('growth')
28
48
  })
29
49
 
30
- it('creates an environment using factoryPreset', () => {
50
+ it('lets consumer fields override slot suggestions', () => {
31
51
  const world = createEnvironment({
32
- preset: factoryPreset,
33
- name: 'Auto Plant 4',
52
+ preset: officePreset,
53
+ name: 'HQ',
54
+ entities: [{ id: 'slot-1', type: 'person', name: 'GM', avatarColor: '#ff0055', zoneId: 'meeting' }],
34
55
  })
35
56
 
36
- expect(world.type).toBe('factory')
37
- expect(world.entities.length).toBe(3)
57
+ expect(world.entities[0]!.avatarColor).toBe('#ff0055')
58
+ expect(world.entities[0]!.zoneId).toBe('meeting')
59
+ expect(world.entities[0]!.position).toEqual(OFFICE_SLOTS[0]!.position)
60
+ })
61
+
62
+ it('pins an occupant to a specific slot via slotId and keeps explicit positions', () => {
63
+ const occupants: EntityDraft[] = [
64
+ { id: 'founder', slotId: 'slot-17', type: 'person', name: 'Founder' },
65
+ { id: 'visitor', type: 'person', name: 'Visitor', position: [0, 0, 0] },
66
+ ]
67
+
68
+ const world = createEnvironment({ preset: officePreset, name: 'HQ', entities: occupants })
69
+
70
+ expect(world.entities[0]!.slotId).toBe('slot-17')
71
+ expect(world.entities[0]!.position).toEqual(OFFICE_SLOTS[16]!.position)
72
+ // Explicit positions pass through untouched and do not consume a slot
73
+ expect(world.entities[1]!.position).toEqual([0, 0, 0])
74
+ expect(world.entities[1]!.slotId).toBeUndefined()
75
+ })
76
+
77
+ it('skips occupants when no free slot is left and warns', () => {
78
+ const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {})
79
+ try {
80
+ const slots = FARM_SLOTS.slice(0, 1)
81
+ const placed = placeEntitiesOnSlots(
82
+ [
83
+ { id: 'a', type: 'person', name: 'A' },
84
+ { id: 'b', type: 'person', name: 'B' },
85
+ ],
86
+ slots,
87
+ )
88
+ expect(placed).toHaveLength(1)
89
+ expect(placed[0]!.slotId).toBe('slot-1')
90
+ expect(consoleWarn).toHaveBeenCalledTimes(1)
91
+ } finally {
92
+ consoleWarn.mockRestore()
93
+ }
94
+ })
95
+
96
+ it('keeps farm and factory presets slot-based and occupant-free', () => {
97
+ const farm = createEnvironment({ preset: farmPreset, name: 'Agromera Farm' })
98
+ expect(farm.type).toBe('farm')
99
+ expect(farm.zones.length).toBe(3)
100
+ expect(farm.entities).toEqual([])
101
+
102
+ const factory = createEnvironment({ preset: factoryPreset, name: 'Auto Plant 4' })
103
+ expect(factory.type).toBe('factory')
104
+ expect(factory.entities).toEqual([])
105
+ })
106
+
107
+ it('derives neutral departments from zones with their slots', () => {
108
+ const departments = deriveDepartmentsFromZones(
109
+ [
110
+ { id: 'greenhouse', name: 'Greenhouse', color: '#22c55e' },
111
+ { id: 'barn', name: 'Barn' },
112
+ ],
113
+ [
114
+ { id: 'slot-1', label: 'Greenhouse station', position: [0, 0, 0], zoneId: 'greenhouse' },
115
+ { id: 'slot-2', label: 'Barn station', position: [1, 0, 0], zoneId: 'barn' },
116
+ ],
117
+ )
118
+
119
+ expect(departments).toHaveLength(2)
120
+ expect(departments[0]).toMatchObject({ slug: 'greenhouse', name: 'Greenhouse', color: '#22c55e', slotIds: ['slot-1'] })
121
+ expect(departments[1]).toMatchObject({ slug: 'barn', slotIds: ['slot-2'] })
38
122
  })
39
123
 
40
124
  it('validates environment entity ids and positions', () => {
@@ -2,8 +2,93 @@ import type {
2
2
  WorldDefinition,
3
3
  CreateEnvironmentOptions,
4
4
  WorldEntity,
5
+ EntityDraft,
6
+ WorldSlot,
7
+ WorldZone,
8
+ DepartmentInfo,
5
9
  } from './types'
6
10
 
11
+ /**
12
+ * Place entities onto preset anchor slots. Entities that already carry an
13
+ * explicit `position` are kept as-is. Otherwise each entity is matched to a
14
+ * slot by `slotId` (or its own `id`), falling back to the next free slot in
15
+ * declaration order. Slot data (position, rotation, zoneId, pinNumber,
16
+ * avatarColor) fills in any fields the entity left empty, so consumers only
17
+ * describe WHO sits somewhere — never WHERE.
18
+ */
19
+ export function placeEntitiesOnSlots(
20
+ entities: EntityDraft[],
21
+ slots: WorldSlot[],
22
+ ): WorldEntity[] {
23
+ const placed: WorldEntity[] = []
24
+
25
+ if (slots.length === 0) {
26
+ for (const entity of entities) {
27
+ if (!entity.position) {
28
+ console.warn(
29
+ `[web-virtual] Entity "${entity.id}" has no position and the preset has no slots — it was skipped.`,
30
+ )
31
+ continue
32
+ }
33
+ placed.push(entity as WorldEntity)
34
+ }
35
+ return placed
36
+ }
37
+
38
+ const slotsById = new Map(slots.map((s) => [s.id, s]))
39
+ const used = new Set<string>()
40
+
41
+ for (const entity of entities) {
42
+ if (entity.position) {
43
+ placed.push(entity as WorldEntity)
44
+ continue
45
+ }
46
+
47
+ const slot = (entity.slotId && slotsById.get(entity.slotId)) || slotsById.get(entity.id)
48
+ const resolved = slot && !used.has(slot.id) ? slot : slots.find((s) => !used.has(s.id))
49
+
50
+ if (!resolved) {
51
+ console.warn(
52
+ `[web-virtual] No free slot left for entity "${entity.id}" — it was skipped. ` +
53
+ `Pass an explicit position or add more slots to the preset.`,
54
+ )
55
+ continue
56
+ }
57
+
58
+ used.add(resolved.id)
59
+ placed.push({
60
+ ...entity,
61
+ slotId: resolved.id,
62
+ position: resolved.position,
63
+ rotation: entity.rotation ?? resolved.rotation,
64
+ zoneId: entity.zoneId ?? resolved.zoneId,
65
+ pinNumber: entity.pinNumber ?? resolved.pinNumber,
66
+ avatarColor: entity.avatarColor ?? resolved.avatarColor,
67
+ })
68
+ }
69
+
70
+ return placed
71
+ }
72
+
73
+ /**
74
+ * Neutral department grouping derived from preset zones — used when the
75
+ * consumer passes no `departments`. One group per zone, keyed by zone id.
76
+ */
77
+ export function deriveDepartmentsFromZones(
78
+ zones: WorldZone[],
79
+ slots: WorldSlot[] = [],
80
+ ): DepartmentInfo[] {
81
+ return zones.map((zone) => ({
82
+ id: `zone-${zone.id}`,
83
+ name: zone.name,
84
+ slug: zone.id,
85
+ description: zone.description,
86
+ color: zone.color,
87
+ zoneId: zone.id,
88
+ slotIds: slots.filter((s) => s.zoneId === zone.id).map((s) => s.id),
89
+ }))
90
+ }
91
+
7
92
  export function createEnvironment(options: CreateEnvironmentOptions): WorldDefinition {
8
93
  const preset = options.preset
9
94
 
@@ -66,13 +151,14 @@ export function createEnvironment(options: CreateEnvironmentOptions): WorldDefin
66
151
 
67
152
  const zones = options.zones || preset?.zones || []
68
153
 
69
- // If user provided entities, use them; otherwise if preset has defaults, use those
70
- let entities: WorldEntity[] = []
71
- if (options.entities && options.entities.length > 0) {
72
- entities = options.entities
73
- } else if (preset?.defaultEntities) {
74
- entities = preset.defaultEntities
75
- }
154
+ // Occupants come from the consumer. If none are given, an optional preset
155
+ // default may supply demo occupants. Either way, entities without an
156
+ // explicit position are auto-placed onto the preset's architectural slots.
157
+ const sourceEntities: EntityDraft[] =
158
+ options.entities && options.entities.length > 0
159
+ ? options.entities
160
+ : (preset?.defaultEntities ?? [])
161
+ const entities = placeEntitiesOnSlots(sourceEntities, preset?.slots ?? [])
76
162
 
77
163
  const world: WorldDefinition = {
78
164
  id,
package/src/core/types.ts CHANGED
@@ -30,6 +30,10 @@ export interface WorldEntity {
30
30
  zoneId?: string
31
31
  description?: string
32
32
  status?: EntityStatus
33
+ /**
34
+ * Anchor slot this entity was placed on (mirrors `WorldPreset.slots` ids).
35
+ */
36
+ slotId?: string
33
37
  position: Vector3Tuple
34
38
  rotation?: Vector3Tuple
35
39
  scale?: Vector3Tuple
@@ -41,6 +45,34 @@ export interface WorldEntity {
41
45
  metadata?: Record<string, unknown>
42
46
  }
43
47
 
48
+ /**
49
+ * Occupant input accepted by `createEnvironment` — a full `WorldEntity` minus
50
+ * the required placement fields. If `position` is omitted the entity is
51
+ * auto-placed onto a preset slot (by `slotId`, by matching `id`, or the next
52
+ * free slot in order), inheriting the slot's position, rotation, zoneId,
53
+ * pinNumber and suggested avatarColor.
54
+ */
55
+ export type EntityDraft = Omit<WorldEntity, 'position'> & { position?: Vector3Tuple }
56
+
57
+ /**
58
+ * Architectural anchor point on a preset where a consumer entity can be
59
+ * placed — a desk, workstation, field station, machine bay, etc. Slots carry
60
+ * no occupant data: who (or what) sits there always comes from the consumer.
61
+ */
62
+ export interface WorldSlot {
63
+ id: string
64
+ /** Neutral architectural label, e.g. "Executive desk", "Workstation 4". */
65
+ label: string
66
+ position: Vector3Tuple
67
+ rotation?: Vector3Tuple
68
+ zoneId?: string
69
+ pinNumber?: number
70
+ /** Suggested avatar color — consumer entities may override. */
71
+ avatarColor?: string
72
+ /** Free-form architecture hints, e.g. `{ desk: 'workstation', dualMonitor: true }`. */
73
+ metadata?: Record<string, unknown>
74
+ }
75
+
44
76
  export interface WorldZone {
45
77
  id: string
46
78
  name: string
@@ -139,10 +171,26 @@ export interface CreateEnvironmentOptions {
139
171
  lighting?: Partial<LightingConfiguration>
140
172
  theme?: Partial<WorldTheme>
141
173
  zones?: WorldZone[]
142
- entities?: WorldEntity[]
174
+ entities?: EntityDraft[]
143
175
  metadata?: Record<string, unknown>
144
176
  }
145
177
 
178
+ /**
179
+ * Consumer-supplied grouping shown in the roster filter and the operations
180
+ * dashboard. Pure org data — the package never ships defaults; when the
181
+ * consumer passes none, groups are derived neutrally from preset zones.
182
+ */
183
+ export interface DepartmentInfo {
184
+ id: string
185
+ name: string
186
+ slug?: string
187
+ description?: string
188
+ color?: string
189
+ slotIds?: string[]
190
+ zoneId?: string
191
+ iconName?: 'briefcase' | 'palette' | 'megaphone' | 'shield' | 'globe'
192
+ }
193
+
146
194
  export interface WorldPreset {
147
195
  id: string
148
196
  name: string
@@ -157,7 +205,10 @@ export interface WorldPreset {
157
205
  lighting: LightingConfiguration
158
206
  theme: WorldTheme
159
207
  zones: WorldZone[]
160
- defaultEntities?: WorldEntity[]
208
+ /** Architectural anchor points for consumer entities (no occupant data). */
209
+ slots?: WorldSlot[]
210
+ /** Optional demo occupants — shipped presets deliberately leave this empty. */
211
+ defaultEntities?: EntityDraft[]
161
212
  buildScene?: (scene: import('three').Scene, options: { nightMode?: boolean; theme?: WorldTheme }) => void
162
213
  }
163
214
 
@@ -13,6 +13,7 @@ export interface WorldEngineOptions {
13
13
  onSelectEntity?: (event: EntitySelectedEvent) => void
14
14
  onHoverEntity?: (entity: WorldEntity | null) => void
15
15
  onFpsUpdate?: (fps: number) => void
16
+ onContextLost?: () => void
16
17
  }
17
18
 
18
19
  export class WorldEngine {
@@ -30,6 +31,7 @@ export class WorldEngine {
30
31
 
31
32
  private isDisposed = false
32
33
  private animationFrameId: number | null = null
34
+ private visibilityHandler: (() => void) | null = null
33
35
  private clock = new THREE.Clock()
34
36
  private hoveredEntityId: string | null = null
35
37
 
@@ -64,9 +66,41 @@ export class WorldEngine {
64
66
  this.projector = new DirectDOMProjector()
65
67
 
66
68
  this.initEventListeners(canvas)
69
+ this.initContextLossHandling(canvas)
67
70
  this.startLoop()
68
71
  }
69
72
 
73
+ /**
74
+ * Hot-sync the world data (entities, theme, zones) without rebuilding the scene.
75
+ * Raycast lookups, label projection and camera focus immediately use the new data.
76
+ */
77
+ public updateWorld(world: WorldDefinition): void {
78
+ this.options.world = world
79
+ }
80
+
81
+ /** Pause rendering while the tab is hidden to save battery/CPU. */
82
+ private initContextLossHandling(canvas: HTMLCanvasElement): void {
83
+ canvas.addEventListener(
84
+ 'webglcontextlost',
85
+ (e) => {
86
+ e.preventDefault()
87
+ this.stopLoop()
88
+ if (this.options.onContextLost) this.options.onContextLost()
89
+ },
90
+ false,
91
+ )
92
+ }
93
+
94
+ /** Resume the render loop after a pause (tab visible again or context restored). */
95
+ public resumeLoop(): void {
96
+ if (this.isDisposed) return
97
+ if (this.animationFrameId === null) {
98
+ // Flush the accumulated delta so animations do not jump after the pause
99
+ this.clock.getDelta()
100
+ this.startLoop()
101
+ }
102
+ }
103
+
70
104
  private initEventListeners(canvas: HTMLCanvasElement): void {
71
105
  let pointerDownX = 0
72
106
  let pointerDownY = 0
@@ -171,6 +205,19 @@ export class WorldEngine {
171
205
  }
172
206
 
173
207
  private startLoop(): void {
208
+ // Pause the render loop while the document is hidden (saves battery/CPU)
209
+ if (this.visibilityHandler === null) {
210
+ this.visibilityHandler = () => {
211
+ if (this.isDisposed) return
212
+ if (document.hidden) {
213
+ this.stopLoop()
214
+ } else {
215
+ this.resumeLoop()
216
+ }
217
+ }
218
+ document.addEventListener('visibilitychange', this.visibilityHandler)
219
+ }
220
+
174
221
  const loop = () => {
175
222
  if (this.isDisposed) return
176
223
 
@@ -212,10 +259,19 @@ export class WorldEngine {
212
259
  this.animationFrameId = requestAnimationFrame(loop)
213
260
  }
214
261
 
215
- public dispose(): void {
216
- this.isDisposed = true
262
+ private stopLoop(): void {
217
263
  if (this.animationFrameId !== null) {
218
264
  cancelAnimationFrame(this.animationFrameId)
265
+ this.animationFrameId = null
266
+ }
267
+ }
268
+
269
+ public dispose(): void {
270
+ this.isDisposed = true
271
+ this.stopLoop()
272
+ if (this.visibilityHandler) {
273
+ document.removeEventListener('visibilitychange', this.visibilityHandler)
274
+ this.visibilityHandler = null
219
275
  }
220
276
 
221
277
  this.unbindEvents()
@@ -0,0 +1,75 @@
1
+ import { describe, it, expect, vi } from 'vitest'
2
+ import * as THREE from 'three'
3
+ import { createStylizedAvatar } from './AvatarBuilder'
4
+ import { MaterialPalette } from '../../engine/materials'
5
+ import type { WorldEntity } from '../../core/types'
6
+
7
+ // GLB assets cannot be fetched in the Node test environment — resolve to null so
8
+ // the placeholder geometry path is exercised instead.
9
+ vi.mock('../../engine/modelLoader', () => ({
10
+ ModelLoader: {
11
+ getInstance: () => ({
12
+ load: async () => null,
13
+ }),
14
+ },
15
+ }))
16
+
17
+ const baseEntity: WorldEntity = {
18
+ id: 'test-1',
19
+ type: 'person',
20
+ name: 'Test worker',
21
+ position: [0, 0, 0],
22
+ status: 'idle',
23
+ pinNumber: 1,
24
+ }
25
+
26
+ function findStatusHalo(group: THREE.Group): THREE.Mesh {
27
+ let halo: THREE.Mesh | null = null
28
+ group.traverse((obj) => {
29
+ if (!halo && obj instanceof THREE.Mesh && (obj.geometry as THREE.BufferGeometry).type === 'RingGeometry') {
30
+ halo = obj
31
+ }
32
+ })
33
+ if (!halo) throw new Error('Status halo mesh not found on avatar')
34
+ return halo
35
+ }
36
+
37
+ describe('createStylizedAvatar hot-sync', () => {
38
+ it('updates the status halo color without rebuilding the avatar', () => {
39
+ const materials = new MaterialPalette()
40
+ const { group, update } = createStylizedAvatar(baseEntity, materials)
41
+
42
+ const halo = findStatusHalo(group)
43
+ const before = halo.material as THREE.MeshBasicMaterial
44
+ expect(before.color.getHex()).toBe(0x22c55e) // idle = green
45
+
46
+ update({ ...baseEntity, status: 'running' })
47
+ const after = halo.material as THREE.MeshBasicMaterial
48
+ expect(after.color.getHex()).toBe(0x3b82f6) // running = blue
49
+
50
+ update({ ...baseEntity, status: 'awaiting_approval' })
51
+ const awaiting = halo.material as THREE.MeshBasicMaterial
52
+ expect(awaiting.color.getHex()).toBe(0xf59e0b) // awaiting = amber
53
+ })
54
+
55
+ it('updates the avatar transform in place', () => {
56
+ const materials = new MaterialPalette()
57
+ const { group, update } = createStylizedAvatar(baseEntity, materials)
58
+
59
+ update({ ...baseEntity, position: [5, 0, -3], rotation: [0, Math.PI / 2, 0] })
60
+
61
+ expect(group.position.x).toBe(5)
62
+ expect(group.position.z).toBe(-3)
63
+ expect(group.rotation.y).toBeCloseTo(Math.PI / 2)
64
+ })
65
+
66
+ it('is a no-op material-wise when the status does not change', () => {
67
+ const materials = new MaterialPalette()
68
+ const { group, update } = createStylizedAvatar(baseEntity, materials)
69
+
70
+ const halo = findStatusHalo(group)
71
+ const materialBefore = halo.material
72
+ update({ ...baseEntity, status: 'idle' })
73
+ expect(halo.material).toBe(materialBefore)
74
+ })
75
+ })
@@ -6,6 +6,8 @@ import { ModelLoader } from '../../engine/modelLoader'
6
6
  export interface CreatedAvatar {
7
7
  group: THREE.Group
8
8
  animate: (delta: number, elapsed: number) => void
9
+ /** Hot-sync entity data (status / position / rotation) without rebuilding the avatar. */
10
+ update: (entity: WorldEntity) => void
9
11
  }
10
12
 
11
13
  export function createStylizedAvatar(
@@ -158,8 +160,10 @@ export function createStylizedAvatar(
158
160
 
159
161
  // 6. Realistic Procedural Animation Function
160
162
  const baseTorsoY = 0.6
161
- const isWorking = entity.status === 'running' || entity.status === 'working'
162
- const isAwaiting = entity.status === 'awaiting_approval'
163
+ // Mutable status flags so hot-synced updates can change animation behaviour live
164
+ let isWorking = entity.status === 'running' || entity.status === 'working'
165
+ let isAwaiting = entity.status === 'awaiting_approval'
166
+ let currentStatus = entity.status || 'idle'
163
167
  const breathFreq = 1.3 + (seed % 0.4)
164
168
  const glanceFreq = 0.22 + ((seed * 3) % 0.15)
165
169
 
@@ -227,5 +231,21 @@ export function createStylizedAvatar(
227
231
  group.rotation.set(entity.rotation[0], entity.rotation[1], entity.rotation[2])
228
232
  }
229
233
 
230
- return { group, animate }
234
+ // 7. Hot-sync: apply live entity data changes without rebuilding the avatar
235
+ const update = (next: WorldEntity) => {
236
+ const nextStatus = next.status || 'idle'
237
+ if (nextStatus !== currentStatus) {
238
+ currentStatus = nextStatus
239
+ isWorking = nextStatus === 'running' || nextStatus === 'working'
240
+ isAwaiting = nextStatus === 'awaiting_approval'
241
+ statusHalo.material = materials.getStatusGlow(nextStatus)
242
+ }
243
+
244
+ group.position.set(next.position[0], next.position[1], next.position[2])
245
+ if (next.rotation) {
246
+ group.rotation.set(next.rotation[0], next.rotation[1], next.rotation[2])
247
+ }
248
+ }
249
+
250
+ return { group, animate, update }
231
251
  }