agentworkshop 0.7.41 → 0.7.46

package/app/composables/workshop/town/useTownSceneInput.ts

@@ -0,0 +1,275 @@
+/**
+ * 小镇视图 — 场景输入接线(相机拖拽/滚轮/拖放)与落点反馈
+ *
+ * 自 TownView.vue 抽出(纯结构搬移,行为与模板契约逐字保持):
+ *   - 2D(Phaser cam.worldView)与 3D(OrbitLite)相机手势与滚轮;
+ *   - 频道坞/数采节点/智控节点/模型库拖放落点;
+ *   - window 级监听器清理登记(卸载统一移除)与落点提示文案。
+ */
+import { computed, onBeforeUnmount, shallowRef } from 'vue'
+import type { ComputedRef, Ref, ShallowRef } from 'vue'
+import type { useDaqStream } from '@/app/composables/workshop/useDaqStream'
+import type { useDcwStream } from '@/app/composables/workshop/useDcwStream'
+import type { DeviceTwinView } from '@/app/composables/workshop/useDeviceTwins'
+import type { TownScene3D } from '@/app/components/workshop/town/TownScene3D'
+import type { TownViewScene } from '@/app/components/workshop/town/TownView.vue'
+import type { DockChannelRow } from './town-view-types'
+
+export function useTownSceneInput(params: {
+  mode: Ref<'browse' | 'edit'>
+  runHint: () => void
+  dockChannels: ComputedRef<DockChannelRow[]>
+  dropChannelAt: (channelId: string, x: number, z: number) => boolean
+  daq: ReturnType<typeof useDaqStream>
+  dcw: ReturnType<typeof useDcwStream>
+  nearestDeviceTwin: (x: number, z: number, maxDist: number) => DeviceTwinView | null
+  bindDaq: (daqId: string, deviceId: string) => void
+  syncSceneDevices: (scene: TownViewScene) => void
+  sceneRef: ShallowRef<TownViewScene | null>
+  errorText: Ref<string>
+}) {
+  const { mode, runHint, dockChannels, dropChannelAt, daq, dcw, nearestDeviceTwin, bindDaq, syncSceneDevices, sceneRef, errorText } = params
+  const { t } = useI18n()
+
+  /**
+   * 自由视角相机 + HTML5 模型拖放。
+   * - 相机:按住左键拖拽平移(避开点选角色),滚轮缩放;
+   * - 拖放:AssetLibrary 的模型卡 dragstart 写入 assetId,落到场景 → 换装/生成。
+   * 由场景 ready 事件调用(canvas 已挂载)。
+   */
+  function bindSceneInput(scene: TownViewScene): void {
+    if ('screenToWorld' in scene) {
+      bindSceneInput3D(scene)
+      return
+    }
+    bindSceneInput2D(scene)
+  }
+  /** window 级监听器清理登记(卸载统一移除;匿名 window 监听器持已销毁场景 = 悬空引用) */
+  const windowCleanups: Array<() => void> = []
+
+  /** 2D(Phaser):用 game.canvas + cam.worldView 反解世界坐标 */
+  function bindSceneInput2D(scene: Exclude<TownViewScene, TownScene3D>): void {
+    const canvas = scene.game.canvas
+    if (!canvas) return
+
+    // 世界坐标 ← 页面坐标反解(经 camera worldView + canvas DOM 缩放)
+    const worldFromPage = (clientX: number, clientY: number): { x: number, y: number } => {
+      const cam = scene.cameras.main
+      const rect = canvas.getBoundingClientRect()
+      const vx = (clientX - rect.left) / rect.width
+      const vy = (clientY - rect.top) / rect.height
+      const wx = cam.worldView.x + vx * cam.worldView.width
+      const wy = cam.worldView.y + vy * cam.worldView.height
+      return { x: wx, y: wy }
+    }
+
+    // ---- 相机拖拽平移(页面像素 → 世界像素 = 页面px / zoom 缩放比) ----
+    let draggingCam = false
+    let lastCX = 0
+    let lastCY = 0
+    canvas.addEventListener('pointerdown', (e: PointerEvent) => {
+      if (e.button !== 0) return
+      draggingCam = true
+      lastCX = e.clientX
+      lastCY = e.clientY
+    })
+    const onCamPointerMove = (e: PointerEvent): void => {
+      if (!draggingCam) return
+      const cam = scene.cameras.main
+      const rect = canvas.getBoundingClientRect()
+      // 页面 px → 世界 px:乘以 (canvas 世界宽 / canvas 页面宽) 再除以 zoom
+      const scale = scene.game.scale.width / rect.width
+      const dx = (e.clientX - lastCX) * scale / cam.zoom
+      const dy = (e.clientY - lastCY) * scale / cam.zoom
+      cam.scrollX -= dx
+      cam.scrollY -= dy
+      lastCX = e.clientX
+      lastCY = e.clientY
+    }
+    const onCamPointerUp = (): void => {
+      draggingCam = false
+    }
+    window.addEventListener('pointermove', onCamPointerMove)
+    window.addEventListener('pointerup', onCamPointerUp)
+    windowCleanups.push(() => window.removeEventListener('pointermove', onCamPointerMove))
+    windowCleanups.push(() => window.removeEventListener('pointerup', onCamPointerUp))
+
+    // ---- 滚轮缩放 ----
+    canvas.addEventListener('wheel', (e: WheelEvent) => {
+      e.preventDefault()
+      const cam = scene.cameras.main
+      const nz = cam.zoom + (e.deltaY < 0 ? 0.08 : -0.08)
+      cam.setZoom(Math.min(2.4, Math.max(0.6, nz)))
+    }, { passive: false })
+
+    // ---- 模型拖放(AssetLibrary.card → scene canvas) ----
+    canvas.addEventListener('dragover', (e: DragEvent) => {
+      e.preventDefault()
+      e.dataTransfer!.dropEffect = 'copy'
+    })
+    canvas.addEventListener('drop', (e: DragEvent) => {
+      e.preventDefault()
+      const assetId = e.dataTransfer?.getData('application/x-aw-model') || e.dataTransfer?.getData('text/plain')
+      if (!assetId) return
+      const world = worldFromPage(e.clientX, e.clientY)
+      const res = scene.dropModelOnWorld(world.x, world.y, assetId)
+      lastDrop.value = res
+    })
+  }
+  /** 3D(Three.js):相机交互 1:1 设计稿 OrbitLite ——
+   *  左键拖拽=环绕 / 中键·右键·Shift+左键=平移 / 滚轮=dolly(乘性);
+   *  实体/领地/手柄拖拽优先,双击实体=flyTo 聚焦(场景内部已实现)。 */
+  function bindSceneInput3D(scene: TownScene3D): void {
+    const canvas = scene.canvas
+    if (!canvas) return
+
+    let camMode = 0 // 0 无 / 1 环绕 / 2 平移
+    let lastCX = 0
+    let lastCY = 0
+    canvas.addEventListener('contextmenu', e => e.preventDefault())
+    canvas.addEventListener('mousedown', (e: MouseEvent) => {
+      if (e.button === 1) e.preventDefault()
+    })
+    canvas.addEventListener('pointerdown', (e: PointerEvent) => {
+      // 变换手柄悬停/拖拽 → 让出(手柄优先)
+      if (scene.isGizmoBusy?.()) return
+      const panGesture = e.button === 1 || e.button === 2 || e.shiftKey
+      if (panGesture) {
+        e.preventDefault()
+        camMode = 2
+        lastCX = e.clientX
+        lastCY = e.clientY
+        return
+      }
+      if (e.button !== 0) return
+      // 编辑模式:实体/领地/范围/边界等场景拖拽接管;未接管(空白处)→ 左键环绕
+      if (scene.tryStartPointerDrag(e.clientX, e.clientY)) return
+      camMode = 1
+      lastCX = e.clientX
+      lastCY = e.clientY
+    })
+    const onScenePointerMove = (e: PointerEvent): void => {
+      if (scene.isGizmoBusy?.()) return
+      if (scene.isPointerDragging()) {
+        scene.movePointerDrag(e.clientX, e.clientY)
+        return
+      }
+      if (!camMode) return
+      const dx = e.clientX - lastCX
+      const dy = e.clientY - lastCY
+      lastCX = e.clientX
+      lastCY = e.clientY
+      if (camMode === 1) scene.orbitBy(dx, dy)
+      else scene.panByScreen(dx, dy)
+    }
+    const onScenePointerUp = (): void => {
+      if (scene.isPointerDragging()) {
+        scene.endPointerDrag()
+        return
+      }
+      camMode = 0
+    }
+    window.addEventListener('pointermove', onScenePointerMove)
+    window.addEventListener('pointerup', onScenePointerUp)
+    windowCleanups.push(() => window.removeEventListener('pointermove', onScenePointerMove))
+    windowCleanups.push(() => window.removeEventListener('pointerup', onScenePointerUp))
+
+    // ---- 滚轮 dolly(设计稿:乘性缩放,任意层级手感一致) ----
+    canvas.addEventListener('wheel', (e: WheelEvent) => {
+      e.preventDefault()
+      scene.zoomBy(e.deltaY > 0 ? 0.12 : -0.11)
+    }, { passive: false })
+
+    // ---- 拖放(频道坞→安放频道;模型库→换装/生成居民) ----
+    canvas.addEventListener('dragover', (e: DragEvent) => {
+      e.preventDefault()
+      e.dataTransfer!.dropEffect = 'copy'
+    })
+    canvas.addEventListener('drop', (e: DragEvent) => {
+      e.preventDefault()
+      const dt = e.dataTransfer
+      if (!dt) return
+      // 运行模式只读:不接受任何场景投放(频道/数采/设备)
+      if (mode.value !== 'edit') {
+        runHint()
+        return
+      }
+      // 1) 频道坞拖入 → 安放频道 + 其 Agent
+      const channelId = dt.getData('application/x-aw-channel') || dt.getData('text/plain')
+      if (channelId && dockChannels.value.some(c => c.channelId === channelId)) {
+        const world = scene.screenToWorld(e.clientX, e.clientY)
+        dropChannelAt(channelId, world.x, world.z)
+        return
+      }
+      // 1.5) 数采节点拖入 → 既有 server 节点落位(PATCH 位置;WS 收敛全端)
+      //      未绑定设备时:落点 ±95 内最近设备自动绑定(已绑定保持不重绑)
+      const daqNodeId = dt.getData('application/x-aw-daq-node')
+      if (daqNodeId) {
+        const n = daq.nodeById(daqNodeId)
+        if (n) {
+          const world = scene.screenToWorld(e.clientX, e.clientY)
+          void daq.patchNode(daqNodeId, { posX: Math.round(world.x), posZ: Math.round(world.z) }).then(() => {
+            if (!n.deviceBindingId) {
+              const near = nearestDeviceTwin(world.x, world.z, 95)
+              if (near) bindDaq(daqNodeId, near.id)
+            }
+          }).catch((err: unknown) => {
+            errorText.value = apiErrorMessage(err)
+          })
+        }
+        return
+      }
+      // 1.6) 智控节点拖入 → 落位 + 未绑定时 ±95 内设备自动绑定(绑定后可直写下发)
+      const dcwNodeId = dt.getData('application/x-aw-dcw-node')
+      if (dcwNodeId) {
+        const n = dcw.nodes.find(x => x.id === dcwNodeId)
+        if (n) {
+          const world = scene.screenToWorld(e.clientX, e.clientY)
+          void dcw.patchNode(dcwNodeId, { posX: Math.round(world.x), posZ: Math.round(world.z) }).then(() => {
+            if (!n.deviceBindingId) {
+              const near = nearestDeviceTwin(world.x, world.z, 95)
+              if (near) {
+                void dcw.bindNode(dcwNodeId, near.id).catch((err: unknown) => {
+                  errorText.value = apiErrorMessage(err)
+                })
+              }
+            }
+            if (sceneRef.value) syncSceneDevices(sceneRef.value)
+          }).catch((err: unknown) => {
+            errorText.value = apiErrorMessage(err)
+          })
+        }
+        return
+      }
+      // 2) 模型拖放 → 换装/生成
+      const assetId = dt.getData('application/x-aw-model') || dt.getData('text/plain')
+      if (assetId) {
+        const world = scene.screenToWorld(e.clientX, e.clientY)
+        const res = scene.dropModelOnWorld(world.x, world.z, assetId)
+        lastDrop.value = res
+      }
+    })
+  }
+  const lastDrop = shallowRef<{ mode: string, agentId?: string, textureKey: string, x: number, y: number } | null>(null)
+
+  /** 模型落点反馈(供 HUD 显示) */
+  const lastDropText = computed(() => {
+    const d = lastDrop.value
+    if (!d) return ''
+    return d.mode === 'rebind'
+      ? t('townView.kgz2nej193', { p0: d.agentId?.slice(0, 8) ?? t('townView.k479op189'), p1: d.textureKey })
+      : t('townView.k5e2460194', { p0: d.textureKey })
+  })
+
+  onBeforeUnmount(() => {
+    for (const fn of windowCleanups) {
+      try {
+        fn()
+      }
+      catch { /* 尽力清理 */ }
+    }
+    windowCleanups.length = 0
+  })
+
+  return { bindSceneInput, lastDropText }
+}

package/app/composables/workshop/town/useTownSceneRuntime.ts

@@ -0,0 +1,390 @@
+/**
+ * 小镇视图 — 场景运行时(引导/事件总线/输入接线/设备轮询/布局收敛)
+ *
+ * 自 TownView.vue 抽出(纯结构搬移,行为与模板契约逐字保持)。
+ * 依赖经参数对象显式注入(父组件仍是共享状态唯一持有者):
+ *   - 2D?render=2d(Phaser)/ 3D(Three.js)引导与公共事件订阅;
+ *   - townBus → 场景增量收敛(snapshot/device/scene.layout);
+ *   - 设备孪生轮询、布局版本幂等收敛、E2E 钩子。
+ */
+import { onBeforeUnmount, onMounted } from 'vue'
+import type { ComputedRef, Ref, ShallowRef } from 'vue'
+import type Phaser from 'phaser'
+import type { useEntitiesStore } from '@/app/stores/workshop/entities'
+import type { useSceneLayouts } from '@/app/composables/workshop/useSceneLayouts'
+import type { useCharacterAssets } from '@/app/composables/workshop/useCharacterAssets'
+import type { useDeviceTwins, DeviceTwinView } from '@/app/composables/workshop/useDeviceTwins'
+import type { useDaqStream } from '@/app/composables/workshop/useDaqStream'
+import type { useTownBus } from '@/app/composables/workshop/useTownBus'
+import type { ChannelLayout, AgentRangeLayout, TownScene3D } from '@/app/components/workshop/town/TownScene3D'
+import type { TownEntityInput } from '@/app/components/workshop/town/TownScene'
+import type { CommonTownScene, TownViewScene } from '@/app/components/workshop/town/TownView.vue'
+import { mapEnvelopeToIntent } from '#shared/town-protocol'
+import type { QualityMode } from './useTownSceneControl'
+
+export function useTownSceneRuntime(params: {
+  props: { channelId: string, allChannels?: boolean }
+  entities: ReturnType<typeof useEntitiesStore>
+  sceneLayouts: ReturnType<typeof useSceneLayouts>
+  characterAssets: ReturnType<typeof useCharacterAssets>
+  deviceTwins: ReturnType<typeof useDeviceTwins>
+  townBus: ReturnType<typeof useTownBus>
+  daq: ReturnType<typeof useDaqStream>
+  sceneRef: ShallowRef<TownViewScene | null>
+  scene3dRef: ShallowRef<TownScene3D | null>
+  gameRef: ShallowRef<Phaser.Game | null>
+  hostRef: Ref<HTMLDivElement | null>
+  render3d: boolean
+  ready: Ref<boolean>
+  fps: Ref<number>
+  agentCount: Ref<number>
+  blockCount: Ref<number>
+  activity: Ref<{ channelId: string, agentName: string, text: string } | null>
+  selected: Ref<{ kind: 'agent' | 'device', id: string, scale: number, rotation: number } | null>
+  errorText: Ref<string>
+  saveState: Ref<{ state: 'idle' | 'dirty' | 'saving' | 'saved' | 'error', at: number } | null>
+  fpsCap: Ref<'60' | '120' | '0'>
+  qualityMode: Ref<QualityMode>
+  selectedChannel: Ref<string | null>
+  boundaryDraft: Ref<ChannelLayout | null>
+  agentRangeDraft: Ref<{ radiusX: number, radiusZ: number, shape: 'ellipse' | 'rect' } | null>
+  onSelectChannel: (cid: string | null) => void
+  buildTownInput: () => TownEntityInput[]
+  updateAgentHome: (agentId: string, channelId: string, x: number, z: number) => Promise<unknown>
+  updateAgentRange: (agentId: string, channelId: string, range: AgentRangeLayout | null) => Promise<unknown>
+  sceneTwinPool: ComputedRef<DeviceTwinView[]>
+  sceneTwinById: (id: string) => DeviceTwinView | undefined
+  syncSceneDevices: (scene: TownViewScene) => void
+  appendLiveChat: (agentId: string, kind: string, text: string, atRaw: number | string | undefined, seq?: number) => void
+  bindSceneInput: (scene: TownViewScene) => void
+  dockRev: Ref<number>
+}) {
+  const { props, entities, sceneLayouts, characterAssets, deviceTwins, townBus, daq, sceneRef, scene3dRef, gameRef, hostRef, render3d, ready, fps, agentCount, blockCount, activity, selected, errorText, saveState, fpsCap, qualityMode, selectedChannel, boundaryDraft, agentRangeDraft, onSelectChannel, buildTownInput, updateAgentHome, updateAgentRange, sceneTwinPool, sceneTwinById, syncSceneDevices, appendLiveChat, bindSceneInput, dockRev } = params
+  const { t } = useI18n()
+
+  let devicePollTimer: ReturnType<typeof setInterval> | null = null
+
+  function syncSceneModels(scene: TownViewScene | null): void {
+    if (!scene || !('registerModelsFromList' in scene)) return
+    if ('screenToWorld' in scene) {
+      scene.registerModelsFromList(characterAssets.models.map(m => ({ id: m.id, file: m.file, name: m.name, kind: m.kind, hFactor: m.hFactor ?? 1 })))
+    }
+    else {
+      scene.registerModelsFromList(characterAssets.models.map(m => ({ id: m.id, file: m.file, name: m.name })))
+    }
+  }
+  // 签名对比替代 deep 监听:模型资产任何字段变化都曾触发全量 syncSceneModels;
+  // 实际只有增删/换文件才需要同步(id+file 签名)
+  watch(() => characterAssets.models.map(m => `${m.id}:${m.file}`).join('|'), () => syncSceneModels(sceneRef.value))
+
+  async function boot() {
+    if (sceneRef.value || !hostRef.value) return
+    if (render3d) {
+      await boot3D()
+    }
+    else {
+      await boot2D()
+    }
+  }
+  /** 3D 引导(默认):Three.js TownScene3D */
+  async function boot3D(): Promise<void> {
+    const host = hostRef.value
+    if (!host) return
+    // 布局加载不阻塞场景 ready:先建空场地,布局异步到达后 apply + rebuild。
+    // 若加载失败(401/网络),keep catch 静默 → 场景保持空场地,用户手动拖入频道。
+    const [{ TownScene3D: Scene3D }] = await Promise.all([import('@/app/components/workshop/town/TownScene3D')])
+    const scene = new Scene3D(buildTownInput(), host as HTMLDivElement)
+    scene.resolveTaskAssignee = (taskId: string) => {
+      const task = (entities.tasks as Record<string, Array<{ id: string, assigneeId: string }>>)[props.channelId]?.find(t => t.id === taskId)
+      return task?.assigneeId ?? null
+    }
+    // 注入数字孪生设备 API(拖 dev 模型进场景时创建设备;场景 transform 变更落库)
+    scene.devices = {
+      async create(input) {
+        const t = await deviceTwins.create({
+          name: input.name,
+          modelRef: input.modelRef,
+          kind: input.kind,
+          controls: input.controls,
+          posX: input.posX,
+          posZ: input.posZ,
+          scale: input.scale,
+        })
+        return { id: t.id }
+      },
+      async update(id, patch) {
+        // 数采节点伪孪生 → 场景落点走 daq REST(节点实体在 server)
+        if (daq.nodeById(id)) {
+          await daq.saveTransform(id, patch.posX, patch.posZ)
+          return undefined
+        }
+        await deviceTwins.update(id, patch)
+        return undefined
+      },
+      async remove(id) {
+        if (daq.nodeById(id)) {
+          await daq.removeNode(id)
+          return
+        }
+        await deviceTwins.remove(id)
+      },
+      async control(id, command, args) {
+        return deviceTwins.control(id, command, args)
+      },
+    }
+    // 注入管理员布局:持久化角色落点 + 独立活动范围
+    scene.agentApi = {
+      async updateHome(agentId, channelId, x, z) {
+        return updateAgentHome(agentId, channelId, x, z)
+      },
+      async updateRange(agentId, channelId, range) {
+        return updateAgentRange(agentId, channelId, range)
+      },
+    }
+    // 注入频道布局持久化:频道整体拖拽 / 边界手柄调整后经 useSceneLayouts 落库
+    scene.channelApi = {
+      async save(channelId, layout) {
+        return sceneLayouts.save(channelId, layout)
+      },
+    }
+    sceneRef.value = scene
+    syncSceneModels(scene)
+    scene3dRef.value = scene
+    // 应用持久化的帧率上限与画质档(渲染配置;数据消费不受影响)
+    scene.setFpsCap(Number(fpsCap.value))
+    scene.setQualityMode(qualityMode.value)
+
+    wireCommon(scene)
+
+    // 选中(3D 专用):点选 Agent/设备 → 弹缩放/旋转滑杆
+    scene.on('select', (v) => {
+      selected.value = v
+    })
+    // 保存状态(布局落库进度 → HUD 徽标)
+    scene.on('saveState', (v) => {
+      saveState.value = v
+    })
+    // 点选频道 → 打开边界编辑面板
+    scene.on('selectChannel', (cid) => {
+      onSelectChannel(cid)
+    })
+    // 频道被拖拽/手柄调整 → 边界面板草稿即时跟随(避免保存时回退旧值)
+    scene.on('channelResized', (e) => {
+      if (!e) return
+      if (selectedChannel.value === e.channelId) boundaryDraft.value = e.layout
+    })
+    // Agent 活动范围被框选绘制/整框移动/手柄调整/清除 → 对象面板草稿即时跟随
+    scene.on('agentRangeChanged', (e) => {
+      if (!e) return
+      if (selected.value?.kind === 'agent' && selected.value.id === e.agentId) {
+        const r = scene3dRef.value?.getAgentRange?.(e.agentId)
+        agentRangeDraft.value = r ? { radiusX: r.radiusX, radiusZ: r.radiusZ, shape: r.shape } : null
+      }
+    })
+
+    // 3D 立即可交互(canvas 同步挂载)
+    ready.value = true
+    bindSceneInput(scene)
+    // 轮询设备遥测 → 驱动 3D 设备节点状态/颜色
+    devicePollTimer = bindDevicePoll(scene)
+
+    // 布局异步加载:到达后按数据库元数据统一实例化并初始化场景内全部实例
+    // (频道布局 + 实体基线 + 设备孪生 → hydrate;仅放置的频道呈现)。
+    // 健壮性:composable 内部已 3 次退避重试;此处再兜底 —— 失败浮出错误并定时重拉,
+    // rev-watch 会在数据到达后自动收敛重建,任何时序下频道都不会"消失"。
+    void sceneLayouts.load().then(() => {
+      scene.hydrate(buildTownInput(), Object.values(sceneLayouts.layouts), sceneTwinPool.value)
+      syncChannelDock()
+    }).catch((err) => {
+      errorText.value = t('townView.k1hmf2ut192', { p0: apiErrorMessage(err) })
+      window.setTimeout(() => {
+        void sceneLayouts.load()
+      }, 2500)
+    })
+  }
+  /** 2D 引导(?render=2d):Phaser TownScene */
+  async function boot2D(): Promise<void> {
+    const host = hostRef.value
+    if (!host) return
+    const [Phaser, { TownScene: Scene }] = await Promise.all([
+      import('phaser'),
+      import('@/app/components/workshop/town/TownScene'),
+    ])
+    const scene = new Scene(buildTownInput())
+    sceneRef.value = scene
+    syncSceneModels(scene)
+    scene.resolveTaskAssignee = (taskId: string) => {
+      const task = (entities.tasks as Record<string, Array<{ id: string, assigneeId: string }>>)[props.channelId]?.find(t => t.id === taskId)
+      return task?.assigneeId ?? null
+    }
+    const game = new Phaser.Game({
+      type: Phaser.AUTO,
+      parent: host.id || 'town-host',
+      width: 1100,
+      height: 700,
+      backgroundColor: '#eceae4',
+      pixelArt: true,
+      antialias: false,
+      roundPixels: true,
+      powerPreference: 'high-performance',
+      physics: { default: 'arcade', arcade: { gravity: { x: 0, y: 0 }, debug: false } },
+      scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH },
+      scene,
+    })
+    gameRef.value = game
+
+    wireCommon(scene)
+
+    // 场景 ready 后 canvas 才挂载 → 再绑交互
+    scene.on('ready', () => {
+      ready.value = true
+      bindSceneInput(scene)
+    })
+  }
+  /** 两种渲染器共享:事件订阅 + HUD 事件 + E2E 钩子 */
+  function wireCommon(scene: CommonTownScene): void {
+    // 事件订阅:两场景的 on 签名不同,这里用场景实例类型 + 具体事件名调用
+    const s = scene as TownScene3D
+    s.on('fps', (v: number) => {
+      fps.value = v
+    })
+    s.on('agentCount', (v: number) => {
+      agentCount.value = v
+    })
+    s.on('blockCount', (v: number) => {
+      blockCount.value = v
+      dockRev.value++
+    })
+    s.on('lastActivity', (v) => {
+      activity.value = v
+    })
+
+    // 事件总线 → 场景(channel.snapshot 重建;其它实时事件驱动)
+    const off = townBus.subscribe((e) => {
+      try {
+        if (e.type === 'channel.snapshot') {
+          scene.rebuild(buildTownInput())
+          // rebuild 内部 resetAll 清掉全部设备/数采节点,必须立即按全量池恢复
+          if (sceneRef.value) syncSceneDevices(sceneRef.value)
+          if (props.channelId) scene.focusChannel(props.channelId)
+          return
+        }
+        // 设备场景事件:updated(含遥测直推,1s 节流)走增量合并;
+        // created 走全量重拉(新孪生需完整字段);deleted 本地移除
+        if (e.type === 'device.updated') {
+          deviceTwins.applyRemote((e.payload as unknown as DeviceTwinView))
+          if (sceneRef.value) syncSceneDevices(sceneRef.value)
+          return
+        }
+        if (e.type === 'device.created') {
+          void deviceTwins.load().then(() => {
+            if (sceneRef.value) syncSceneDevices(sceneRef.value)
+          })
+          return
+        }
+        if (e.type === 'device.deleted') {
+          deviceTwins.removeRemote((e.payload as { id: string }).id)
+          if (sceneRef.value) syncSceneDevices(sceneRef.value)
+          return
+        }
+        // 频道布局事件(他人编辑边界/移入移除):重拉布局 → 场景即时收敛
+        if (e.type === 'scene.layout.saved' || e.type === 'scene.layout.removed') {
+          void sceneLayouts.load().then(() => {
+            syncSceneLayouts(sceneRef.value)
+            syncChannelDock()
+          })
+          return
+        }
+        // 会话台实时缓冲:气泡意图 → 所属角色的近实时消息(与头顶气泡同语义;
+        // 独立于事件日志 30 条上限,选中角色的消息不会被其他角色刷屏挤掉)
+        const bub = mapEnvelopeToIntent(e)?.bubble
+        if (bub?.agentId) appendLiveChat(bub.agentId, bub.kind, bub.text, e.at, e.seq)
+        scene.handleTownEvent(e)
+      }
+      catch (err) {
+        errorText.value = apiErrorMessage(err)
+      }
+    })
+    ;(sceneRef as unknown as { _off?: () => void })._off = off
+
+    // E2E 调试钩子
+    if (import.meta.client) {
+      ;(window as unknown as Record<string, unknown>).__town = {
+        get scene() { return sceneRef.value },
+        get game() { return gameRef.value },
+        buildInput: buildTownInput,
+        get characterAssets() { return characterAssets },
+      }
+    }
+  }
+  // 布局数据版本 → 幂等收敛:load 晚到/save/remove/他人编辑后,场景一律重建对齐
+  // (hydrates 是 resetAll+rebuild,幂等;这是"每次进场都能从数据库实例化"的最终保证)
+  watch(() => sceneLayouts.rev, (rev) => {
+    const scene = scene3dRef.value
+    if (!scene || !sceneLayouts.loaded || rev === 0) return
+    // 设备输入必须是全量池(含 DAQ 投影):hydrate→syncDevices 按清单对账,漏 daq 会清场
+    scene.hydrate(buildTownInput(), Object.values(sceneLayouts.layouts), sceneTwinPool.value)
+    syncChannelDock()
+  })
+
+  /** 用频道布局清单收敛场景(已放置频道存在性/边界;供 WS 事件后即时同步) */
+  function syncSceneLayouts(scene: TownViewScene | null): void {
+    if (!scene || !('applySceneLayouts' in scene)) return
+    const s = scene as TownScene3D
+    // 先应用全部布局到场景(新增/变更/移除),再 rebuild 实体基线(仅放置的频道呈现)
+    s.applySceneLayouts(Object.values(sceneLayouts.layouts))
+    s.rebuild(buildTownInput())
+  }
+
+  /** 频道坞已放置/未放置标记刷新(布局变化后) */
+  function syncChannelDock(): void {
+    void sceneLayouts.load().finally(() => {
+      // 由场景 hasChannel 反映;以下依赖已完成加载
+    })
+  }
+
+  /** 设备控制台行点击 → 场景镜头聚焦该实体并选中(工业 HMI 联动手感) */
+  function onFocusDevice(t: { id: string, posX?: number, posZ?: number }): void {
+    const s = scene3dRef.value
+    if (!s) return
+    if (typeof t.posX === 'number' && typeof t.posZ === 'number') s.focusTo(t.posX, t.posZ)
+    ;(s as unknown as { setSelected?: (x: { kind: 'device', id: string }) => void }).setSelected?.({ kind: 'device', id: t.id })
+  }
+  /** 轮询设备孪生 → 场景节点同步 + 状态环颜色(设备节点由 dev 模型拖入/服务端恢复生成) */
+  function bindDevicePoll(scene: TownScene3D): ReturnType<typeof setInterval> {
+    // 5s 兜底轮询:遥测/状态主通道是 WS device.updated 直推(server 1s 节流),
+    // 轮询仅覆盖断线窗口(useDeviceTwins.load 已 in-flight 去重)
+    return setInterval(() => {
+      void deviceTwins.load().then(() => {
+        if (sceneRef.value !== scene) return
+        scene.syncDevices(sceneTwinPool.value)
+        for (const node of scene.getDeviceNodes()) {
+          const twin = sceneTwinById(node.twinId)
+          if (twin) scene.updateDeviceNode(node.twinId, twin.state, twin.telemetry)
+        }
+      })
+    }, 5000)
+  }
+  /** 首次挂载即建一次(若 entities 已有数据) */
+  onMounted(() => {
+    boot()
+    // 若快照尚未到达,稍后 snapshot 事件会触发 rebuild;这里先发一次初始基线
+    const seed = buildTownInput()
+    if (seed.length > 0 && sceneRef.value) {
+      sceneRef.value.rebuild(seed)
+    }
+  })
+  onBeforeUnmount(() => {
+    if (devicePollTimer) clearInterval(devicePollTimer)
+    devicePollTimer = null
+    const off = (sceneRef as unknown as { _off?: () => void })._off
+    off?.()
+    scene3dRef.value?.dispose()
+    scene3dRef.value = null
+    gameRef.value?.destroy(true)
+    gameRef.value = null
+    sceneRef.value = null
+  })
+
+  return { onFocusDevice, syncSceneLayouts }
+}