agentworkshop 0.7.44 → 0.7.47

package/app/components/workshop/town/scene/town-scene3d-agents.ts

@@ -0,0 +1,308 @@
+/**
+ * AgentTeam RPG 小镇(Three.js 3D 表现层)— 角色节点层与模型库挂载。
+ *
+ * 自 TownScene3D.ts 抽出:
+ *  - ensureAgent:按实体元数据实例化 Agent3D(落点钳制 / 活动范围 / 身份光环 / 名牌);
+ *  - mountModel:GLB 加载 → 归一化 scale/贴地 → mixer(失败回退程序化机器人,永不白屏);
+ *  - registerModelsFromList:模型清单增量登记,并把晚到资产挂到已存在的 Agent/设备;
+ *  - swapAgentModel / setAnimPref / getAgentModel|Name|Clips:模型与动作绑定公开面;
+ *  - dropModelOnWorld / spawnResident / swapTexture / nearestAgent:拖拽落点换装或生成居民。
+ *
+ * 宿主契约:场景类实现 AgentLayerHost(只列本模块触达的成员)。
+ */
+import * as THREE from 'three'
+import type { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
+import { GROUND_Y, UNITS, clampToBoundary, type AgentRangeLayout } from '#shared/town-scene-math'
+import type { TownBubbleKind } from '#shared/town-protocol'
+import { hexOf, makeFallbackBot, makeLabel } from './town-scene3d-factory'
+import { loadGltf } from './town-scene3d-models'
+import { Agent3D, type DeviceNode } from './town-scene3d-nodes'
+import type { AgentHost, DeviceTwinSync, ModelInfo, TownEntityInput, TownEventMap } from './town-scene3d-types'
+
+/** 角色层模块的宿主契约(继承节点侧 AgentHost,保证 agent.host 注入可编译期校验) */
+export interface AgentLayerHost extends AgentHost {
+  readonly scene: THREE.Scene
+  readonly agents: Map<string, Agent3D>
+  readonly deviceNodes: Map<string, DeviceNode>
+  /** 已登记模型(id → file) */
+  readonly modelsById: Map<string, ModelInfo>
+  /** GLTF 缓存(避免重复加载) */
+  readonly gltfCache: Map<string, { file: string, scene: THREE.Group, height: number }>
+  /** 模型动画 clip 缓存(file → clips) */
+  readonly agentAnimClips: Map<string, THREE.AnimationClip[]>
+  readonly gltfLoader: GLTFLoader
+  /** 服务端已有但模型资产尚未注册的设备孪生 */
+  readonly pendingDeviceTwins: Map<string, DeviceTwinSync>
+  /** 已销毁(模型清单登记中止) */
+  readonly disposed: boolean
+  /** 组装可缩放目标并恢复初始化缩放 */
+  registerScalable(kind: 'agent' | 'device', id: string, holder: THREE.Group, initialScale?: number): void
+  /** 模型 PBR 材质增强 */
+  enhancePbrMaterials(root: THREE.Object3D, kind: 'device' | 'character'): void
+  /** 数字孪生设备节点:拖 dev 模型进场景生成 */
+  spawnDeviceNode(x: number, z: number, texKey: string, file: string, name: string): string
+  /** 按设备孪生记录重建场景节点 */
+  recreateDeviceNode(t: DeviceTwinSync): void
+  /** 设备换模型:按 modelRef 重挂 GLB 到 holder */
+  swapDeviceModelSprite(dev: DeviceNode, modelRef: string): void
+  /** 实时信息入队(换装/生成提示) */
+  enqueueBubble(channelId: string, agentId: string | undefined, kind: TownBubbleKind, text: string, ttlMs: number): void
+  /** 场景 → Vue HUD 事件 */
+  emit<K extends keyof TownEventMap>(event: K, e: TownEventMap[K]): void
+  /** 请求下一帧重绘 */
+  markDirty(): void
+}
+
+export function ensureAgent(host: AgentLayerHost, a: TownEntityInput['agents'][number] & { channelId: string }, cx: number, cz: number, color: number): void {
+  const key = a.agentId
+  if (host.agents.has(key)) return
+  // 管理员布局落点(来自 config.homeX/homeZ)优先;缺省按领地内排布;整体钳制在频道边界内
+  const layout = host.blockLayoutOf(a.channelId)
+  let homeX = a.homeX ?? cx
+  let homeZ = a.homeZ ?? cz
+  if (layout) {
+    const clamped = clampToBoundary(layout, homeX, homeZ, 20)
+    homeX = clamped.x
+    homeZ = clamped.z
+  }
+  // 管理员布局活动范围(来自 config.range;缺省 null = 沿用频道边界);收进频道边界
+  const range: AgentRangeLayout | null = a.range ?? null
+  const root = new THREE.Group()
+  root.position.set(homeX, GROUND_Y, homeZ)
+  const nameSprite = makeLabel(host.scene, a.name, homeX, 48, homeZ, hexOf(color))
+  // 默认模型(内置二次元角色 hero-anime-1「樱叶少女」;模型库换装可覆盖)
+  const texKey = a.modelRef || 'hero-anime-1'
+  const model = new THREE.Group()
+  root.add(model)
+  host.scene.add(root)
+  const agent = new Agent3D({
+    channelId: a.channelId,
+    agentId: key,
+    name: a.name,
+    role: a.role,
+    root,
+    model,
+    mixer: null,
+    clips: [],
+    colorNum: color,
+    nameSprite,
+    bubble: null,
+    bubbleText: null,
+    bubbleTimer: null,
+    state: a.state,
+    progress: a.currentTaskProgress ?? null,
+    dragging: false,
+    homeX,
+    homeZ,
+    range,
+    rangeLine: null,
+    textureKey: texKey,
+    modelRef: a.modelRef ?? '',
+    behavior: { mode: 'idle', roamTarget: null, targetId: null, waitUntil: 0, pauseUntil: 0, engaged: false },
+  })
+  agent.host = host
+  agent.attachAura(color, a.role)
+  host.agents.set(key, agent)
+  // 载入模型(GLB);模型库注册先于/晚于挂载都能正确解析(内置二次元角色按 id 直取文件)
+  const info = host.modelsById.get(texKey)
+    ?? (texKey.startsWith('hero-anime-')
+      ? { id: texKey, file: `/assets/game/character/${texKey}.glb`, name: '二次元角色' }
+      : (host.modelsById.get('hero-3d') ?? { id: 'hero-3d', file: '/assets/game/character/hero-3d.glb', name: '标准员工模型' }))
+  void mountModel(host, agent, info.file, info.name)
+  agent.renderRangeLine()
+  host.emit('agentCount', host.agents.size)
+}
+
+/**
+ * 绑定模型到 Agent(GLTFLoader 加载 → 归一化 scale/锚点贴地 → 若有动画则 mixer)。
+ * 缺失/失败 → 回退内置 hero-3d,永不白屏。
+ */
+export async function mountModel(host: AgentLayerHost, asp: Agent3D, file: string, name: string): Promise<void> {
+  const cached = host.gltfCache.get(file)
+  let loaded: THREE.Group
+  let height: number
+  if (cached) {
+    loaded = cached.scene.clone(true)
+    height = cached.height
+  }
+  else {
+    try {
+      const gltf = await loadGltf(host.gltfLoader, file)
+      loaded = gltf.scene
+      const box = new THREE.Box3().setFromObject(loaded)
+      height = Math.max(0.5, box.max.y - box.min.y)
+      host.gltfCache.set(file, { file, scene: loaded, height })
+      // 缓存动画 clip(供 mixer 状态切换;GLTFLoader 动画必须在解析层保留)
+      host.agentAnimClips.set(file, gltf.animations)
+    }
+    catch {
+      // 加载失败回退程序化「孪生机器人」(胶囊躯干 + 发光核心 + 天线),角色永不隐形
+      loaded = makeFallbackBot()
+      height = 1.4
+    }
+  }
+  // 归一化 scale(使模型高度≈UNITS 世界单位)并贴地(模型大小自适应)
+  loaded.position.y = 0
+  loaded.scale.setScalar(UNITS / height)
+  // 真实投影 + PBR 增强:模型网格 cast/receiveShadow(体积感) + 分级环境反射(角色质感)
+  loaded.traverse((o) => {
+    if ((o as THREE.Mesh).isMesh) o.castShadow = true
+  })
+  host.enhancePbrMaterials(loaded, 'character')
+  // 清掉旧模型子节点与 mixer
+  asp.model.clear()
+  asp.model.add(loaded)
+  // 客制化:注册可缩放目标并恢复用户缩放(套在 asp.model 上,作为自适应之上的倍率层)
+  host.registerScalable('agent', asp.agentId, asp.model)
+  asp.mixer = null
+  asp.activeAction = null
+  const clips = host.agentAnimClips.get(file) ?? []
+  const firstClip = clips[0]
+  if (firstClip) {
+    asp.mixer = new THREE.AnimationMixer(loaded)
+    asp.clips = clips
+    const firstAction = asp.mixer.clipAction(firstClip)
+    firstAction.play()
+    asp.activeAction = firstAction
+  }
+  void name
+  host.markDirty()
+}
+
+/** 注册模型清单，并将晚到资产挂载到已存在的 Agent/设备。 */
+export function registerModelsFromList(host: AgentLayerHost, list: Array<{ id: string, file: string, name: string, kind?: string, hFactor?: number }>): void {
+  if (host.disposed) return
+  const changed = new Set<string>()
+  for (const model of list) {
+    const previous = host.modelsById.get(model.id)
+    if (!previous || previous.file !== model.file || previous.name !== model.name || previous.kind !== model.kind || previous.hFactor !== (model.hFactor ?? 1)) {
+      host.modelsById.set(model.id, { ...model, hFactor: model.hFactor ?? 1 })
+      changed.add(model.id)
+    }
+  }
+  if (changed.size > 0) {
+    for (const agent of host.agents.values()) {
+      if (!agent.modelRef || !changed.has(agent.modelRef)) continue
+      const model = host.modelsById.get(agent.modelRef)
+      if (model) void mountModel(host, agent, model.file, model.name)
+    }
+    for (const device of host.deviceNodes.values()) {
+      if (changed.has(device.modelRef)) host.swapDeviceModelSprite(device, device.modelRef)
+    }
+  }
+  for (const twin of [...host.pendingDeviceTwins.values()]) {
+    const isDaq = twin.kind === 'daq' || (twin.modelRef ?? '').startsWith('daq-')
+    if (!isDaq && !host.modelsById.get(twin.modelRef)?.file) continue
+    host.pendingDeviceTwins.delete(twin.id)
+    host.recreateDeviceNode(twin)
+  }
+}
+
+/** 为指定角色换装模型(选择器绑定;要求实体已在场景,否则仅记录) */
+export function swapAgentModel(host: AgentLayerHost, agentId: string, modelRef: string): void {
+  const asp = host.agents.get(agentId)
+  if (!asp) return
+  const info = host.modelsById.get(modelRef)
+  const file = info?.file ?? '/assets/game/character/hero-3d.glb'
+  asp.modelRef = modelRef
+  asp.textureKey = modelRef
+  void mountModel(host, asp, file, info?.name ?? modelRef)
+}
+
+/** 动作绑定:为某 Agent 指定动画 clip(按名称 idle/walk/work 或索引)。供 AssetLibrary 选择动作后调用。 */
+export function setAnimPref(host: AgentLayerHost, agentId: string, clipName: string): void {
+  const asp = host.agents.get(agentId)
+  if (!asp || asp.clips.length === 0 || !asp.mixer) return
+  // 解析:优先名称匹配,否则 idle→0/walk→1/work→末帧
+  let idx = asp.clips.findIndex(c => c.name.toLowerCase().includes(clipName.toLowerCase()))
+  if (idx < 0) idx = clipName === 'work' ? asp.clips.length - 1 : clipName === 'walk' ? Math.min(1, asp.clips.length - 1) : 0
+  const clip = asp.clips[idx]
+  if (!clip) return
+  asp.mixer.stopAllAction()
+  asp.mixer.clipAction(clip).reset().play()
+}
+
+/** 角色当前绑定模型 id(供模型选择器高亮) */
+export function getAgentModel(host: AgentLayerHost, agentId: string): string | null {
+  const asp = host.agents.get(agentId)
+  return asp?.modelRef ?? null
+}
+
+/** 角色名字(供模型选择器标题) */
+export function getAgentName(host: AgentLayerHost, agentId: string): string {
+  return host.agents.get(agentId)?.name ?? agentId.slice(0, 8)
+}
+
+/** 角色动画 clip 名列表(供 UI 展示可绑定动作;无则空) */
+export function getAgentClips(host: AgentLayerHost, agentId: string): Array<{ name: string, duration: number }> {
+  const asp = host.agents.get(agentId)
+  if (!asp) return []
+  return asp.clips.map(c => ({ name: c.name, duration: Math.round(c.duration * 10) / 10 }))
+}
+
+export function dropModelOnWorld(host: AgentLayerHost, x: number, z: number, assetId: string): { mode: 'rebind' | 'spawn', agentId?: string, textureKey: string, x: number, y: number } {
+  const near = nearestAgent(host, x, z, 80)
+  const model = host.modelsById.get(assetId)
+  const texKey = model?.id ?? assetId
+  // 数字孪生实体模型(kind=dev):拖入场景生成"设备节点" + 绑定 device twin
+  if (model?.kind === 'dev') {
+    const twinId = host.spawnDeviceNode(x, z, texKey, model.file, model.name)
+    return { mode: 'spawn', agentId: twinId, textureKey: texKey, x: Math.round(x), y: Math.round(z) }
+  }
+  if (near) {
+    swapTexture(host, near, texKey)
+    host.enqueueBubble(near.channelId, near.agentId, 'info', `换装 → ${model?.name ?? assetId}`, 2200)
+    return { mode: 'rebind', agentId: near.agentId, textureKey: texKey, x: Math.round(near.root.position.x), y: Math.round(near.root.position.z) }
+  }
+  // 落点生成居民
+  const info = model ?? { id: assetId, file: '', name: assetId }
+  spawnResident(host, x, z, texKey, info.name)
+  return { mode: 'spawn', textureKey: texKey, x: Math.round(x), y: Math.round(z) }
+}
+
+export function nearestAgent(host: AgentLayerHost, x: number, z: number, maxDist: number): Agent3D | undefined {
+  let best: Agent3D | undefined
+  let bestD = maxDist
+  for (const a of host.agents.values()) {
+    const d = Math.hypot(a.root.position.x - x, a.root.position.z - z)
+    if (d < bestD) {
+      best = a
+      bestD = d
+    }
+  }
+  return best
+}
+
+export function swapTexture(host: AgentLayerHost, asp: Agent3D, texKey: string): void {
+  const info = host.modelsById.get(texKey)
+  const file = info?.file ?? resolveFile(host, texKey) ?? '/assets/game/character/hero-3d.glb'
+  asp.modelRef = texKey
+  asp.textureKey = texKey
+  void mountModel(host, asp, file, info?.name ?? texKey)
+}
+
+export function spawnResident(host: AgentLayerHost, x: number, z: number, texKey: string, name: string): void {
+  const root = new THREE.Group()
+  root.position.set(x, GROUND_Y, z)
+  const model = new THREE.Group()
+  root.add(model)
+  const nameSprite = makeLabel(host.scene, name, x, 48, z, hexOf(0xffe9c4))
+  host.scene.add(root)
+  const resident = new Agent3D({
+    channelId: '', agentId: `resident-${Date.now().toString(36)}`, name,
+    role: 'worker', root, model, mixer: null, clips: [], colorNum: 0xffe9c4, nameSprite,
+    bubble: null, bubbleText: null, bubbleTimer: null, state: 'idle', progress: null,
+    dragging: false, homeX: x, homeZ: z, range: null, rangeLine: null, textureKey: texKey, modelRef: texKey,
+    behavior: { mode: 'idle', roamTarget: null, targetId: null, waitUntil: 0, pauseUntil: 0, engaged: false },
+  })
+  resident.host = host
+  resident.attachAura(0xffe9c4, 'worker')
+  host.agents.set(resident.agentId, resident)
+  const info = host.modelsById.get(texKey)
+  void mountModel(host, resident, info?.file ?? '/assets/game/character/hero-3d.glb', info?.name ?? name)
+}
+
+/** 模型库文件反查(短 modelRef 兜底) */
+function resolveFile(host: AgentLayerHost, id: string): string {
+  return host.modelsById.get(id)?.file ?? ''
+}

package/app/components/workshop/town/scene/town-scene3d-blocks.ts

@@ -0,0 +1,297 @@
+/**
+ * AgentTeam RPG 小镇(Three.js 3D 表现层)— 频道领地放置层。
+ *
+ * 自 TownScene3D.ts 抽出(布局驱动放置:只呈现「已放置」的频道;未放置不进场景):
+ *  - buildBlocks / placeChannel / layoutAgentsInBlock:实体基线 → Block3D + 边界内铺放 Agent;
+ *  - applySceneLayouts / hasChannel / blockLayout / placedChannels / getChannelLayout / trackLayout;
+ *  - dropChannelOnWorld:频道坞拖入落点建领地(缺省布局按 Agent 数匹配);
+ *  - updateChannelLayout / removeChannel / getAllChannelLayouts / applyLayoutToBlock;
+ *  - getCameraTarget:频道坞首放落点。
+ *
+ * 宿主契约:场景类实现 BlockLayerHost(只列本模块触达的成员)。
+ */
+import type * as THREE from 'three'
+import { channelColorNum, normLayout, type ChannelLayout } from '#shared/town-scene-math'
+import { applyPadToBlock, makeBlock, makeLabel } from './town-scene3d-factory'
+import { Block3D, makeBoundary, type Agent3D } from './town-scene3d-nodes'
+import type {
+  AgentRangeHandle, BlockHost, ChannelMessageReceiver, ChannelResizeHandle, TownEntityInput, TownEventMap,
+} from './town-scene3d-types'
+
+/** 领地层模块的宿主契约(继承节点侧 BlockHost,保证 block.host 注入可编译期校验) */
+export interface BlockLayerHost extends BlockHost {
+  readonly scene: THREE.Scene
+  readonly blocks: Map<string, Block3D>
+  /** 频道领地布局(channelId → 放置);驱动 buildBlocks/边界约束 */
+  readonly layouts: Map<string, ChannelLayout>
+  /** 频道实体基线(channelId → seed;供 dropChannelOnWorld 即时铺放) */
+  readonly entityIndex: Map<string, TownEntityInput>
+  readonly agents: Map<string, Agent3D>
+  /** 频道信息接收器(channelId → FIFO 队列) */
+  readonly receivers: Map<string, ChannelMessageReceiver>
+  readonly resizeHandles: ChannelResizeHandle[]
+  readonly agentRangeHandles: AgentRangeHandle[]
+  /** 框选绘制目标 agent(非空 = 编辑模式正在为该角色拉动矩形框) */
+  readonly rangeDrawAgent: string | null
+  /** 当前选中频道(供边界编辑面板) */
+  selectedChannel: string | null
+  /** 相机注视目标(供频道坞首放落点/聚焦) */
+  readonly camTarget: { x: number, z: number }
+  /** 场景 → Vue HUD 事件 */
+  emit<K extends keyof TownEventMap>(event: K, e: TownEventMap[K]): void
+  /** 请求下一帧重绘 */
+  markDirty(): void
+  /** 按实体元数据实例化 Agent3D */
+  ensureAgent(a: TownEntityInput['agents'][number] & { channelId: string }, cx: number, cz: number, color: number): void
+  /** 退出框选绘制模式(清理预览与状态) */
+  cancelRangeDraw(): void
+  /** 刷新 Agent 活动范围手柄 */
+  refreshAgentRangeHandles(): void
+  /** 缓动聚焦某世界点 */
+  focusTo(x: number, z: number): void
+  /** 释放对象树内所有 Canvas 纹理 */
+  disposeCanvasTextures(root: THREE.Object3D | null): void
+  /** 释放单个 agent 的实例资源 */
+  disposeAgentAssets(a: { nameSprite?: THREE.Sprite | null, bubble?: THREE.Sprite | null, rangeLine?: THREE.Line | null, aura?: THREE.Group | null }): void
+  /** 频道边界变化后把成员活动范围一并收进新边界 */
+  clampAgentsToBoundary(channelId: string): void
+}
+
+/**
+ * 用频道实体基线同步领地/角色。仅放置已保存布局的频道(布局来自 useSceneLayouts,
+ * 经 applySceneLayouts 注入);未放置频道只出现在频道坞,不进 3D。
+ */
+export function buildBlocks(host: BlockLayerHost, seeds: TownEntityInput[]): void {
+  host.entityIndex.clear()
+  for (const ch of seeds) {
+    host.entityIndex.set(ch.channelId, ch)
+    const layout = host.layouts.get(ch.channelId)
+    if (!layout) continue
+    placeChannel(host, ch, layout)
+  }
+  host.emit('blockCount', host.blocks.size)
+  host.emit('agentCount', host.agents.size)
+}
+
+/** 按布局放置一个频道领地(面向对象:Block3D 实例)+ 在其边界内铺放全部 Agent */
+export function placeChannel(host: BlockLayerHost, ch: TownEntityInput, rawLayout: ChannelLayout): void {
+  const layout = normLayout(rawLayout)
+  const color = channelColorNum(ch.channelId)
+  const pad = makeBlock(host.scene, ch.channelName, color, layout)
+  const block = new Block3D({
+    channelId: ch.channelId, name: ch.channelName,
+    x: layout.x, z: layout.z,
+    radiusX: layout.radiusX, radiusZ: layout.radiusZ,
+    shape: layout.shape, rotationY: layout.rotationY,
+    color,
+    platform: pad.platform,
+    padRing: pad.padRing,
+    beacon: pad.beacon,
+    boundary: makeBoundary(layout.shape, layout.radiusX, layout.radiusZ, color),
+    label: makeLabel(host.scene, ch.channelName, layout.x, 30, layout.z),
+  })
+  block.host = host
+  block.boundary.position.set(layout.x, 0.3, layout.z)
+  block.boundary.rotation.y = layout.rotationY * Math.PI / 180
+  host.scene.add(block.boundary)
+  host.blocks.set(ch.channelId, block)
+  // 在边界内铺放该频道的全部 Agent(lead 居中心,worker 左右展开;钳在边界内)
+  layoutAgentsInBlock(host, ch, block)
+  // 面向对象聚合:把该频道全部成员挂到 Block3D.members(供整体移动/边界钳制批量处理)
+  for (const a of host.agents.values()) {
+    if (a.channelId === ch.channelId && !block.members.includes(a)) block.members.push(a)
+  }
+}
+
+/** 在频道领地里铺放全部 Agent(按边界内分布;客户自定 home 优先) */
+export function layoutAgentsInBlock(host: BlockLayerHost, ch: TownEntityInput, block: Block3D): void {
+  const { x, z, radiusX, radiusZ } = block
+  const inner = 0.6 // 内缩比例:agent 铺在边界内侧
+  const n = Math.max(1, ch.agents.length)
+  ch.agents.forEach((a, i) => {
+    // 若该 agent 有 persisted home(且在边界附近)则用之;否则沿长轴均匀铺放
+    let px: number
+    let pz: number
+    if (typeof a.homeX === 'number' && typeof a.homeZ === 'number') {
+      px = a.homeX
+      pz = a.homeZ
+    }
+    else {
+      const t = n <= 1 ? 0 : (i / (n - 1)) * 2 - 1
+      px = x + t * radiusX * inner * 0.8
+      pz = z + (a.role === 'lead' ? 0 : (i % 2 === 0 ? -1 : 1) * radiusZ * inner * 0.4)
+    }
+    host.ensureAgent({ ...a, channelId: ch.channelId }, px, pz, block.color)
+  })
+}
+
+/**
+ * 注入频道领地布局(来自 useSceneLayouts)。构建场景前必须调用;
+ * 未放置的频道会在 rebuild 时被跳过(只停留在频道坞)。
+ */
+export function applySceneLayouts(host: BlockLayerHost, layouts: ChannelLayout[]): void {
+  host.layouts.clear()
+  for (const l of layouts) {
+    const n = normLayout(l)
+    host.layouts.set(n.channelId, n)
+  }
+}
+
+/** 频道是否已放入场景(供频道坞标记已放置/未放置) */
+export function hasChannel(host: BlockLayerHost, channelId: string): boolean {
+  return host.blocks.has(channelId)
+}
+
+/** 频道当前布局(供边界约束;未放置返回空) */
+export function blockLayout(host: BlockLayerHost, channelId: string): ChannelLayout | null {
+  const b = host.blocks.get(channelId)
+  return b ? b.layout() : null
+}
+
+/** 已放入场景的频道集(供频道坞/选中面板) */
+export function placedChannels(host: BlockLayerHost): string[] {
+  return [...host.blocks.keys()]
+}
+
+/** 频道当前布局(供边界编辑面板初始化) */
+export function getChannelLayout(host: BlockLayerHost, channelId: string): ChannelLayout | null {
+  const b = host.blocks.get(channelId)
+  return b ? b.layout() : null
+}
+
+/** 记录频道当前布局到场景布局表(移动/缩放后由 Block3D 调用) */
+export function trackLayout(host: BlockLayerHost, b: Block3D): void {
+  host.layouts.set(b.channelId, b.normLayout())
+}
+
+/** 相机注视目标(供频道坞首放落点/聚焦) */
+export function getCameraTarget(host: BlockLayerHost): { x: number, z: number } {
+  return { x: Math.round(host.camTarget.x), z: Math.round(host.camTarget.z) }
+}
+
+/**
+ * 频道拖入场景:在落点建领地 + 铺放其全部 Agent(钳在边界内)。
+ * 频道 id 需已在实体基线中;返回落点世界坐标(供 HUD 提示)。
+ */
+export function dropChannelOnWorld(host: BlockLayerHost, x: number, z: number, channelId: string, channelName: string, agentCount: number): { x: number, z: number, channelId: string, name: string } {
+  const existing = host.blocks.get(channelId)
+  if (existing) {
+    host.focusTo(existing.x, existing.z)
+    return { x: Math.round(existing.x), z: Math.round(existing.z), channelId, name: existing.name }
+  }
+  // 缺省布局:以落点为中心、与 Agent 数匹配的边界
+  const rx = Math.max(120, 110 + agentCount * 18)
+  const rz = Math.max(80, 70 + agentCount * 14)
+  const layout: ChannelLayout = { channelId, x, z, radiusX: rx, radiusZ: rz, shape: 'ellipse', rotationY: 0 }
+  host.layouts.set(channelId, normLayout(layout))
+  // 从实体基线取该频道 agents(由 TownView ensureChannelPresent 提前放置)
+  const seed = host.entityIndex.get(channelId)
+  if (seed) {
+    placeChannel(host, seed, layout)
+  }
+  else {
+    // 无实体基线(频道坞拖入,数据尚未到达):只建空领地占位
+    const color = channelColorNum(channelId)
+    const pad = makeBlock(host.scene, channelName, color, layout)
+    const block = new Block3D({
+      channelId, name: channelName, x, z,
+      radiusX: layout.radiusX, radiusZ: layout.radiusZ,
+      shape: layout.shape, rotationY: layout.rotationY, color,
+      platform: pad.platform,
+      padRing: pad.padRing,
+      beacon: pad.beacon,
+      boundary: makeBoundary(layout.shape, layout.radiusX, layout.radiusZ, color),
+      label: makeLabel(host.scene, channelName, x, 30, z),
+    })
+    block.host = host
+    block.boundary.position.set(x, 0.3, z)
+    host.scene.add(block.boundary)
+    host.blocks.set(channelId, block)
+  }
+  host.emit('blockCount', host.blocks.size)
+  host.emit('agentCount', host.agents.size)
+  return { x: Math.round(x), z: Math.round(z), channelId, name: channelName }
+}
+
+/** 更新频道布局(编辑边界后本地即时生效;持久化由 TownView 经 useSceneLayouts.save 落库) */
+export function updateChannelLayout(host: BlockLayerHost, channelId: string, patch: Partial<ChannelLayout>): void {
+  const b = host.blocks.get(channelId)
+  if (!b) return
+  if (patch.x !== undefined) b.x = patch.x
+  if (patch.z !== undefined) b.z = patch.z
+  if (patch.radiusX !== undefined) b.radiusX = Math.max(60, patch.radiusX)
+  if (patch.radiusZ !== undefined) b.radiusZ = Math.max(40, patch.radiusZ)
+  if (patch.shape !== undefined) b.shape = patch.shape
+  if (patch.rotationY !== undefined) b.rotationY = patch.rotationY
+  const layout = normLayout({ channelId, x: b.x, z: b.z, radiusX: b.radiusX, radiusZ: b.radiusZ, shape: b.shape, rotationY: b.rotationY })
+  host.layouts.set(channelId, layout)
+  // 重建领地平台/边界/名牌
+  host.scene.remove(b.boundary)
+  applyPadToBlock(b)
+  b.boundary = makeBoundary(layout.shape, layout.radiusX, layout.radiusZ, b.color)
+  b.boundary.position.set(layout.x, 0.3, layout.z)
+  b.boundary.rotation.y = layout.rotationY * Math.PI / 180
+  host.scene.add(b.boundary)
+  // 频道边界变化后把成员活动范围一并收进新边界(面板滑杆编辑路径)
+  host.clampAgentsToBoundary(channelId)
+  host.markDirty()
+}
+
+/** 移除频道放置(从场景撤走领地及其 Agent) */
+export function removeChannel(host: BlockLayerHost, channelId: string): void {
+  const b = host.blocks.get(channelId)
+  if (!b) return
+  host.scene.remove(b.platform)
+  host.scene.remove(b.padRing)
+  host.scene.remove(b.beacon)
+  if (b.boundary) host.scene.remove(b.boundary)
+  host.scene.remove(b.label)
+  for (const [aid, a] of [...host.agents.entries()]) {
+    if (a.channelId === channelId) {
+      host.scene.remove(a.root)
+      if (a.nameSprite) host.scene.remove(a.nameSprite)
+      if (a.bubble) host.scene.remove(a.bubble)
+      if (a.rangeLine) host.scene.remove(a.rangeLine)
+      host.disposeAgentAssets(a)
+      host.agents.delete(aid)
+    }
+  }
+  if (b.label) host.disposeCanvasTextures(b.label)
+  if (host.rangeDrawAgent && host.agents.get(host.rangeDrawAgent) === undefined) host.cancelRangeDraw()
+  host.blocks.delete(channelId)
+  host.layouts.delete(channelId)
+  host.receivers.delete(channelId)
+  for (const hl of host.resizeHandles) hl.mesh.visible = false
+  for (const hl of host.agentRangeHandles) hl.mesh.visible = false
+  if (host.selectedChannel === channelId) {
+    host.selectedChannel = null
+    host.emit('selectChannel', null)
+  }
+  host.emit('blockCount', host.blocks.size)
+  host.emit('agentCount', host.agents.size)
+  host.markDirty()
+}
+
+/** 当前场景内全部频道布局(供「保存全部布局」/E2E) */
+export function getAllChannelLayouts(host: BlockLayerHost): ChannelLayout[] {
+  return [...host.blocks.values()].map(b => ({
+    channelId: b.channelId, x: b.x, z: b.z,
+    radiusX: b.radiusX, radiusZ: b.radiusZ,
+    shape: b.shape, rotationY: b.rotationY,
+  }))
+}
+
+/** 按当前 Block 字段重建领地几何(平台刻度/边界线框/朝向),供缩放与移动共用 */
+export function applyLayoutToBlock(host: BlockLayerHost, b: Block3D): void {
+  const layout = { channelId: b.channelId, x: b.x, z: b.z, radiusX: b.radiusX, radiusZ: b.radiusZ, shape: b.shape, rotationY: b.rotationY }
+  host.layouts.set(b.channelId, normLayout(layout))
+  b.platform.position.set(b.x, 0.16, b.z)
+  b.padRing.position.set(b.x, 0.34, b.z)
+  applyPadToBlock(b)
+  if (b.boundary) host.scene.remove(b.boundary)
+  b.boundary = makeBoundary(b.shape, b.radiusX, b.radiusZ, b.color)
+  b.boundary.position.set(b.x, 0.3, b.z)
+  b.boundary.rotation.y = b.rotationY * Math.PI / 180
+  host.scene.add(b.boundary)
+  host.markDirty()
+}