ctx.character 同时提供角色定义查询和主舞台立绘控制。

​
API

方法返回值说明
get(id)Character | null按 id 获取角色；不存在时返回 null
list()Character[]获取全部角色定义
show(id, options?)void | Promise<void>显示角色立绘
change(id, options?)void | Promise<void>更改已显示角色的状态
hide(id)void | Promise<void>隐藏角色立绘
useCharacter(id)Character | nullReact Hook；订阅单个角色定义
useAll()Character[]React Hook；订阅角色列表
Character 包含 id、name、avatarUri、portraits、customFields 和 themeColor。 themeColor 是角色在角色编辑器里选的「预设颜色」，三层各有用途：fg 是预设色块上 实际显示、也是选中判定用的那一层（要「跟角色代表色一致」时用它），bg 是浅底， ring 是描边。没选过颜色的角色没有这个字段。

​
案例：读取角色并显示立绘

输入： 项目中存在角色 alice，名称为“爱丽丝”，并包含 smile 立绘。 
const character = ctx.character.get("alice");

if (character) {
  await ctx.character.show(character.id, { expression: "smile" });
}

console.log(character && {
  id: character.id,
  name: character.name,
  portraits: character.portraits.map((item) => item.id),
});
输出： 
{
  "id": "alice",
  "name": "爱丽丝",
  "portraits": ["smile"]
}
同时，主舞台开始显示爱丽丝的 smile 立绘。角色不存在时，get() 输出 null，案例不会调用 show()。