Conversation 对话桥

付费模块

本模块为付费模块。授权由云端平台统一管理：在 cloud.021209.xyz 购买/领取授权后，于「装备模块」页面勾选到对应服务器即可，无需填写 password 或 license.yml。

功能定位

将 Chemdah 对话系统桥接到 ArcartX UI，配合 Adyeshach NPC 实现可视化对话面板。

核心特性

可视化对话面板：替代传统聊天栏对话，ArcartX UI 渲染说话人头像、文本和选项按钮
Chemdah 桥接：自动拦截 Chemdah 对话事件，将对话帧推送到 ArcartX UI
Adyeshach NPC 联动：NPC 检测范围可配置，靠近 NPC 自动触发对话
选项交互：客户端显示对话选项列表，玩家点击后回包触发 Chemdah 后续流程
HUD 自动注册：启动时自动注册对话面板 UI

依赖

类型	依赖	作用	缺少时表现
必需	ArcartX	注册对话面板 UI，并接收玩家点击选项回包	模块无法显示可视化对话
必需	Chemdah	提供任务/对话流程、对话帧和选项执行	模块不会加载
必需	Adyeshach	读取附近 NPC、做 NPC 对话入口和选择器展示、NPC 外观配置	模块不会加载

启用步骤

yaml

modules:
  conversation:
    enabled: true

同时需要在 Chemdah 的对应对话配置中指定 ArcartX-Suite 注册的对话主题：

yaml

theme: 'ArcartXConversation'

没有设置这个 theme 时，Chemdah 仍会使用自己的默认对话主题，Conversation 模块虽然已加载，但玩家不会看到 ArcartX 的可视化对话 UI。

关键配置（`ArcartXConversation.yml`）

yaml

debug:
  enabled: false

theme:
  name: ArcartXConversation

client:
  packet-id: AXS_CONVERSATION
  # 支持列表格式，详见 [多 UI 同时发包](/guide/multi-ui)
  dialog-ui-id: AXS:conversation_menu
  selector-ui-id: AXS:conversation_selector_hud
  register-ui-on-enable: true
  overwrite-ui-files: false

interaction:
  enabled: true
  scan-range: 6.0
  scan-period-ticks: 10
  selector-sticky-ms: 1500
  open-cooldown-ms: 350
  reply-debounce-ms: 250
  suppress-reopen-ms: 500

# 按键已由宿主 config.yml keybinds 节统一注册（AXS_INTERACT / AXS_NAVIGATE_PREV / AXS_NAVIGATE_NEXT）。
# 本模块不再自行注册按键。

NPC 外观配置（`npc-appearances`）

模块启动 / 重载时，自动为指定 Adyeshach NPC 应用 ArcartX 模型与动画，无需手动命令。

依赖 ArcartX 和 Adyeshach 同时可用；npc 字段匹配 NPC 显示名、自定义名或 Adyeshach ID（忽略大小写）。

模式 A — 持久默认动画（`setDefaultState`）

不填 animation-speed，调用 setDefaultState(state, animation)，动画持续生效。

yaml

npc-appearances:
  - npc: "村长老王"
    model: npc_village_elder
    scale: 1.0
    state: idle
    animation: idle_loop

模式 B — 一次性播放（`playAnimation`，带速度控制）

填写 animation-speed > 0，调用 playAnimation(animation, speed, transitionTime, keepTime)。

yaml

npc-appearances:
  - npc: "铁匠张三"
    model: npc_blacksmith
    scale: 1.0
    animation: hammer_swing
    animation-speed: 1.5      # > 0 时启用此模式（1.0 = 正常速度）
    transition-time: 100      # 过渡时间，毫秒，默认 5
    keep-time: -1             # 持续时间，毫秒，-1 = 播放完整动画

字段说明

字段	必填	默认值	说明
`npc`	✓	—	NPC 显示名 / 自定义名 / Adyeshach ID
`model`	✓	—	ArcartX 模型 ID
`scale`		`1.0`	模型缩放比例
`state`		—	模式 A：动画状态名（如 `idle`）
`animation`		—	动画名称（两种模式均用此字段）
`animation-speed`		`0`	> 0 时启用模式 B；模式 A 不填此项
`transition-time`		`5`	模式 B：过渡时间（毫秒）
`keep-time`		`-1`	模式 B：持续时间（毫秒），`-1` 播放完整动画

配置修改后执行 /axs conversation reload 即可重新应用。

电影序列 (Cinematic)

电影序列允许你编排一系列动作（传送、标题、音效、NPC 动画等），按顺序对玩家播放，营造过场动画效果。播放时会自动显示 letterbox 黑边 UI。

配置

yaml

cinematic:
  enabled: true
  letterbox-ui-id: AXS:conversation_letterbox

  # 序列定义（根键为序列 ID）
  cinematics:
    intro:
      name: "开场动画"
      actions:
        - type: lock_movement
          locked: true
          delay-after-ms: 0
        - type: title
          title: "&6第一章"
          subtitle: "&7新的开始"
          fade-in: 10
          stay: 60
          fade-out: 10
          delay-after-ms: 2000
        - type: camera_path
          world: world
          duration-ms: 5000
          ticks-per-frame: 2
          points:
            - { x: 100, y: 70, z: 200, yaw: 0, pitch: 30 }
            - { x: 110, y: 75, z: 210, yaw: 45, pitch: 20 }
          delay-after-ms: 1000
        - type: npc_animation
          npc: "村长老王"
          animation: wave
          speed: 1.0
          transition-time: 5
          keep-time: -1
          delay-after-ms: 2000
        - type: lock_movement
          locked: false
          delay-after-ms: 0

动作类型

`type`	说明	关键参数
`teleport`	传送玩家到指定坐标	`world`, `x`, `y`, `z`, `yaw`, `pitch`
`camera_path`	沿路径平滑插值传送（模拟摄像机移动）	`world`, `duration-ms`, `ticks-per-frame`, `points`
`title`	显示原版标题/副标题	`title`, `subtitle`, `fade-in`, `stay`, `fade-out`
`action_bar`	显示原版 Action Bar 消息	`text`
`wait`	纯等待（利用 `delay-after-ms`）	—
`sound`	播放原版音效	`sound`, `volume`, `pitch`
`game_mode`	切换游戏模式	`mode`
`npc_animation`	对 Adyeshach NPC 播放动画	`npc`, `animation`, `speed`, `transition-time`, `keep-time`
`npc_model`	对 Adyeshach NPC 设置模型	`npc`, `model`, `scale`
`message`	发送聊天消息	`text`
`command`	执行命令	`command`, `as-console`
`speed`	设置行走/飞行速度	`speed`, `type`
`lock_movement`	锁定/解锁玩家移动（设置速度为 0）	`locked`
`subtitle`	播放 Announcer 字幕组（打字机效果，需 Announcer 模块）	`group-id`
`ui_packet`	发送包到 ArcartX 客户端 UI	`ui-id`, `handler`, `payload`
`arcartx_sound`	播放 ArcartX 资源包自定义音效	`resource-path`, `category`, `at-player`, `pitch`, `keep-time-ms`

每个动作可设 delay-after-ms：执行后等待的毫秒数。

Chemdah 对话主题配置

在需要使用 ArcartX UI 渲染的 Chemdah 对话文件里加入：

yaml

theme: 'ArcartXConversation'

Chemdah的conversation示例：

yaml

__option__:
  theme: 'ArcartXConversation'
  title: '{name}'
欢迎词_0:
  npc id: 'Adyeshach 小师妹'
  npc:
    - '&f&l你好!少侠{{ sender }}'
    - '&f&l欢迎来到流云琼阁'
    - '&7&l(使用&e鼠标&7点击选项即可)'
  format: generic
  player:
    - reply: '&f&l你好!'
      then: |
        goto 欢迎词_0_1
    - reply: '&f&l再见!'
      then: |
        close

ArcartXConversation 必须与 ArcartXConversation.yml 中的 theme.name 保持一致。如果你改了 theme.name，Chemdah 对话文件里的 theme 也要同步修改。

修改后执行：

txt

/axs conversation reload

如果 Chemdah 本身不会热重载对话配置，还需要按你的 Chemdah 管理方式重载 Chemdah 或重启服务器。

常见配置问题

现象	常见原因	处理方式
Conversation 模块已加载，但仍显示 Chemdah 默认聊天栏对话	Chemdah 对话文件没有写 `theme: 'ArcartXConversation'`	给对应对话补上 theme 并重载
控制台显示已注册 `ArcartXConversation`，但某个 NPC 不弹 ArcartX-Suite UI	只有部分对话配置了 theme	检查该 NPC 对应的 Chemdah 对话文件
修改 `ArcartXConversation.yml` 的 `theme.name` 后全部失效	Chemdah 侧仍写旧主题名	两边主题名保持一致

命令

权限：arcartxsuite.admin

命令	说明
`/axs conversation status`	查看对话桥模块状态（交互增强、NPC 桥接等就绪情况）
`/axs conversation reload`	重载对话配置、UI，并重新应用 `npc-appearances`
`/axs conversation adyeshach setModel <名称> <modelID> <scale>`	即时为指定 NPC 设置模型
`/axs conversation adyeshach setAnimation <名称> <state> <animName>`	即时为指定 NPC 设置持久默认动画
`/axs conversation adyeshach playAnimation <名称> <动画名> <速度> [过渡ms] [持续ms]`	即时为指定 NPC 一次性播放动画（可调速度）
`/axs conversation cinematic play <序列ID> [玩家名]`	播放指定电影序列
`/axs conversation cinematic stop`	停止当前正在播放的电影序列
`/axs conversation cinematic list`	列出所有可用的电影序列

UI / Packet

对话 UI ID：AXS:conversation_menu
NPC 选择 HUD ID：AXS:conversation_selector_hud
电影序列黑边 UI ID：AXS:conversation_letterbox
服务端推对话帧（说话人、文本、选项列表），客户端推选项选择回包

NPC 选择器 HUD 特性

常驻 HUD：isHud: true，through: true，不拦截游戏操作
屏幕缩放：screenScale: true，level: 0
Pickup 联动：选择器面板（selector_root）通过 enter / leave 事件控制客户端变量 client.pickup，鼠标悬停在选择器上时置为 false，离开时恢复为 true，避免点击 NPC 选项时误触 Pickup 拾取

Conversation 对话桥 ​

功能定位 ​

核心特性 ​

依赖 ​

启用步骤 ​

关键配置（ArcartXConversation.yml） ​

NPC 外观配置（npc-appearances） ​

模式 A — 持久默认动画（setDefaultState） ​

模式 B — 一次性播放（playAnimation，带速度控制） ​

字段说明 ​

电影序列 (Cinematic) ​

配置 ​

动作类型 ​

Chemdah 对话主题配置 ​

常见配置问题 ​

命令 ​

UI / Packet ​

NPC 选择器 HUD 特性 ​

Conversation 对话桥

功能定位

核心特性

依赖

启用步骤

关键配置（`ArcartXConversation.yml`）

NPC 外观配置（`npc-appearances`）

模式 A — 持久默认动画（`setDefaultState`）

模式 B — 一次性播放（`playAnimation`，带速度控制）

字段说明

电影序列 (Cinematic)

配置

动作类型

Chemdah 对话主题配置

常见配置问题

命令

UI / Packet

NPC 选择器 HUD 特性