动作

操作让角色决定在你的场景中做什么。你在连接时声明可用的功能；角色会根据对话决定何时以及要做什么。

1. 配置 actionConfig 在连接时

const client = useConvaiClient({
  apiKey: '...',
  characterId: '...',
  actionConfig: {
    // 角色可以发出的动作名称
    actions: ['Move To', 'Pick Up', 'Drop', 'Follow', 'Wave', 'Attack'],

    // 场景中角色可以作用的对象
    objects: [
      { name: 'sword',  description: '地上的一把锋利钢剑' },
      { name: 'chest',  description: '角落里的一个木制宝箱' },
      { name: 'torch',  description: '墙上的一支燃烧火把' },
    ],

    // 机器人可以引用或作用的其他角色
    characters: [
      { name: 'Player', bio: '当前用户' },
      { name: 'Guard',  bio: '附近的一名守卫 NPC' },
    ],

    // 可选：角色开始时关注的对象
    current_attention_object: 'sword',
  },
});

规则：

• actions, objects、以及 characters 定义了本次会话中唯一有效的可交互项。
• current_attention_object 必须与 objects[].name.
• 如果可用动作或对象集合发生变化，请使用更新后的配置重新连接 actionConfig.

2. 接收 actionResponse

订阅 actionResponse 以在每回合后获取角色的动作决策。

client.on('actionResponse', ({ actions }) => {
  // actions: Array<{ name: string; target?: string }>
  // 空数组是有效的无动作响应
  for (const action of actions) {
    dispatch(action.name, action.target);
  }
});

• 动作有顺序——按顺序执行。
• target 是可选的；某些动作（例如 "Wave"）没有目标。
• 空 actions 数组不是错误——角色只是选择不采取行动。

3. 在运行时更新关注点

使用 updateContext告诉角色玩家当前正在看哪个对象。角色会用它来解析“它”“那个”“这里”。

// 玩家把注意力转到箱子上——静默更新
client.updateContext({
  current_attention_object: 'chest',
  run_llm: 'false',
});

// 更新关注点并让角色作出回应
client.updateContext({
  text: '玩家现在正在看拉杆。',
  current_attention_object: 'lever',
  run_llm: 'auto',
});

// 清除关注对象
client.updateContext({
  current_attention_object: '',
  run_llm: 'false',
});

current_attention_object 必须与 actionConfig.objects[].name.

---

4. 更新描述性场景上下文

使用 updateSceneMetadata 来告知角色其应了解的环境变化。这只是 仅用于描述 ——不会添加新的动作目标。

client.updateSceneMetadata([
  { name: 'fog',  description: '浓雾已经弥漫开来，能见度很低' },
  { name: 'rain', description: '外面正下着大雨' },
]);

如果角色需要对某物采取行动，它必须在 actionConfig.objects.

---

5. 以编程方式触发动作

使用 sendTriggerMessage 让角色在没有用户输入的情况下说话并行动——用于脚本事件或过场动画。

// 在 Convai 控制台中定义的命名触发器
client.sendTriggerMessage('greet_player');

// 带自定义指令的触发器
client.sendTriggerMessage('pickup_item', '捡起剑并把它递给玩家。');

---

完整示例

const client = useConvaiClient({
  apiKey: '...',
  characterId: '...',
  actionConfig: {
    actions: ['Move To', 'Pick Up', 'Drop', 'Follow'],
    objects: [
      { name: 'apple',  description: '木箱上的一个绿色苹果' },
      { name: 'basket', description: '玩家附近的一个柳条篮子' },
    ],
    characters: [{ name: 'Player', bio: '当前用户' }],
    current_attention_object: 'apple',
  },
});

client.on('actionResponse', ({ actions }) => {
  for (const { name, target } of actions) {
    console.log(`[ACTION] ${name}${target ? ` → ${target}` : ''}`);
    // 例如 "Move To → apple"、"Pick Up → apple"、"Drop → basket"
  }
});

// 玩家在界面中选择篮子
client.updateContext({
  current_attention_object: 'basket',
  run_llm: 'false',
});

// 玩家说“把那个放进篮子里”
// 角色将“那个”解析为 apple，并执行：Move To apple → Pick Up apple → Move To basket → Drop apple

---

API 参考

actionConfig （connect 选项）

字段	类型	描述
actions	string[]	角色可以发出的动作名称
objects	{ name, description }[]	场景中的对象
characters	{ name, bio }[]	其他角色
current_attention_object	string?	初始关注对象

actionResponse 事件

client.on('actionResponse', ({ actions }) => { ... });
// actions: Array<{ name: string; target?: string }>

updateContext （attention）

字段	类型	描述
text	string?	可选的上下文文本
mode	"append" | "replace" | "reset"	如何应用文本
run_llm	"true" | "false" | "auto"	是否触发响应
current_attention_object	string?	新的关注对象，或 "" 用于清除

updateSceneMetadata(items)

字段	类型	描述
items	{ name, description }[]	描述性的场景元素

sendTriggerMessage(triggerName?, triggerMessage?)

以编程方式触发角色响应。两个参数都是可选的。