> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/getting-started/setup/add-lip-sync-to-your-character/lip-sync-profiles-and-mappings/creating-a-custom-map.md).

# 创建自定义映射

## 简介

A **口型同步映射** 定义传入的 Lip Sync 通道如何路由到特定角色网格上的混合形状。

当你的角色不遵循内置的混合形状命名规范，或者你希望更精细地控制特定通道的行为时，就需要自定义映射。

本页将逐步介绍映射检查器，并展示如何从头构建自定义映射。

## 开始之前

在创建映射之前，请确保你已经知道你的角色使用的是哪种受支持的配置文件格式。

当前受支持的配置文件格式有：

* `arkit`
* `mha`
* `cc4_extended`

你的映射必须针对正确的配置文件。只有当映射的目标配置文件与角色设置中使用的活动 Lip Sync 配置文件匹配时，它才能正常工作。

## 了解映射检查器

当你选择一个 `ConvaiLipSyncMapAsset`时，检查器会分为几个部分。

<figure><img src="/files/773ae5e6ab58a1954439906a8cb137e5af552878" alt=""><figcaption></figcaption></figure>

### Header

在检查器顶部，你会看到当前映射状态的摘要。

<figure><img src="/files/0afea71658a80fc2800b810aace9936257222ad9" alt=""><figcaption></figcaption></figure>

| 计数器     | 含义            |
| ------- | ------------- |
| **总计**  | 映射条目总数        |
| **已启用** | 启用的条目数        |
| **已映射** | 至少分配了一个目标的条目数 |
| **覆盖率** | 已映射启用条目的百分比   |

配置文件徽章会显示此映射的目标配置文件。

### 配置部分

此部分定义映射的身份和全局行为。

<figure><img src="/files/a3d0c96d579f3b376e04aeb09f6644136560b8b2" alt=""><figcaption></figcaption></figure>

#### 目标配置文件

选择此映射所对应的配置文件。

这必须与 Lip Sync 组件使用的配置文件一致。

#### 说明

一个可选的仅编辑器备注，用于你自己的项目组织。

#### 全局修饰

这些设置会影响整个映射的输出。

| 设置     | 说明            |
| ------ | ------------- |
| **倍率** | 缩放所有输出值       |
| **偏移** | 为所有输出值添加一个固定值 |

全局倍率设置为 `0.8` 通常是许多骨架上获得自然效果的良好起点。

#### 允许未映射

启用后，没有显式条目的通道可以直接转发，使用源通道名称作为目标混合形状名称。

这在搭建或测试阶段很有用，尤其是当你的角色已经遵循了大部分预期命名规范时。

### 工具部分

此部分有助于更快地填充或导入映射。

<figure><img src="/files/772f9db96db620ba613bb86e8e244e6b67516d68" alt=""><figcaption></figcaption></figure>

#### 从网格自动检测

这是为真实角色生成映射的最快方式。

1. 使用一个预览网格添加 `SkinnedMeshRenderer`
2. 选择一种匹配模式
3. 运行 **从网格自动检测**

SDK 会将网格混合形状名称与配置文件源通道进行比较，并尝试自动匹配它们。

**匹配模式**

| 模式     | 行为             |
| ------ | -------------- |
| **精确** | 名称必须完全匹配，忽略大小写 |
| **包含** | 一个名称可以包含另一个名称  |
| **模糊** | 比较前会去除常见的骨架前缀  |

推荐工作流程：

1. 从以下开始 **精确**
2. 如果覆盖率较低，请尝试 **包含**
3. 如有需要，请尝试 **模糊**

#### 从映射文本

你也可以从 JSON 导入映射数据。

可用选项包括：

* 导入映射文件
* 直接粘贴映射文本
* 将当前映射复制为 JSON

这对团队协作、备份和迁移都很有用。

#### 映射操作

| Action        | 结果                 |
| ------------- | ------------------ |
| **初始化默认值**    | 为所选配置文件创建原始名称风格的条目 |
| **全部清除**      | 移除所有条目             |
| **按 A-Z 排序**  | 按字母顺序排列条目          |
| **复制映射 JSON** | 将当前映射复制为 JSON      |

### 批量操作

批量工具可帮助你快速管理大型映射。

<figure><img src="/files/38f13cc054e88975bf2c0ded2ed666bc2e0d951d" alt=""><figcaption></figcaption></figure>

| Action    | 结果                |
| --------- | ----------------- |
| **全部启用**  | 启用每个条目            |
| **全部禁用**  | 禁用每个条目            |
| **重置倍率**  | 将所有条目的倍率重置为 `1.0` |
| **重置偏移**  | 将所有条目的偏移重置为 `0`   |
| **仅启用眼部** | 仅启用与眼睛相关的通道       |
| **仅启用嘴部** | 仅启用与嘴部相关的通道       |
| **仅启用眉部** | 仅启用与眉毛相关的通道       |

这些操作在调试或隔离面部骨架的某一部分时尤其有用。

### 映射部分

这是映射的主路由表。

每一行都是一个映射条目，它将一个源通道连接到一个或多个目标混合形状。

<figure><img src="/files/e25f1ce29fbc8f1dd1bc0f6470a1249bc81969f4" alt=""><figcaption></figcaption></figure>

| 列         | 说明            |
| --------- | ------------- |
| **源混合形状** | 传入的通道名称       |
| **目标名称**  | 一个或多个网格混合形状目标 |
| **倍率**    | 条目级倍率         |
| **偏移**    | 条目级偏移         |

你可以搜索列表、按启用条目筛选，并隔离未映射项，以更快完成设置。

### 映射条目行为

每个映射条目都可以包含除可见表格字段之外的附加控制项。

<figure><img src="/files/4c1e8e68ec3b96c846fd4d263697ea2777b86d4e" alt=""><figcaption></figcaption></figure>

| 字段              | 说明           |
| --------------- | ------------ |
| **已启用**         | 启用或停用该条目     |
| **使用覆盖值**       | 用固定值替换传入值    |
| **覆盖值**         | 启用覆盖时使用的固定值  |
| **忽略全局修饰**      | 跳过整个映射的倍率和偏移 |
| **限制最小值 / 最大值** | 限制最终输出范围     |

单个源通道也可以驱动多个目标混合形状。当一个表情需要影响网格上的多个形状时，这很有用。

## 输出处理顺序

最终输出值按以下顺序计算：

```
rawValue -> 条目级倍率 -> 条目级偏移 -> 限制
         -> 全局倍率 -> 全局偏移
```

如果 **忽略全局修饰** 已启用，则该条目的最后两步会被跳过。

## 创建自定义映射

{% stepper %}
{% step %}
**创建映射资源**

在项目窗口中，创建一个新的映射资源：

```
Create > Convai > LipSync > Map Asset
```

使用如下这类描述性名称：

```
LipSyncMap_MyCharacter
```

{% endstep %}

{% step %}
**选择目标配置文件**

在 **配置** 部分，将 **目标配置文件** 设置为你的角色所使用的配置文件。
{% endstep %}

{% step %}
**填充条目**

你可以选择两种常见工作流程之一。

**选项 A：从网格自动检测**

1. 添加你的 `SkinnedMeshRenderer` 作为预览网格
2. 选择 **精确** 模式
3. 运行 **从网格自动检测**
4. 查看表头覆盖结果
5. 如有需要，请使用 **包含** 或 **模糊**

**选项 B：初始化默认值并手动编辑**

1. 单击 **初始化默认值**
2. 查看生成的原始名称风格条目
3. 在你的网格使用不同混合形状名称的地方替换目标名称
   {% endstep %}

{% step %}
**调校运动**

调整映射，直到角色表现自然。

常见调整包括：

* 如果表情感觉太强，可降低全局倍率
* 为诸如张口之类的通道添加条目级限制
* 禁用骨架不应使用的通道
* 当一个源应驱动多个目标时，使用分发映射
  {% endstep %}

{% step %}
**分配映射**

一旦映射准备就绪，请将其分配到 **口型同步映射** 字段中，位于角色的 Lip Sync 组件上。

当分配了有效的自定义映射且其目标配置文件匹配时，它会优先于内置默认映射。
{% endstep %}
{% endstepper %}

## 实用技巧

#### 将覆盖率作为设置指标

覆盖率是判断映射完成度最快的方法之一。

#### 从简单开始

先从原始映射或自动检测开始，然后只微调真正需要调整的条目。

#### 禁用骨架不支持的内容

如果你的角色没有某个通道对应的目标，禁用该条目通常比保留半配置状态更清晰。

#### 仔细调整下颌运动

与下颌相关的通道通常适合添加限制，这样说话既能保持表现力，又不会显得夸张。

## 结论

自定义映射让你可以精确控制受支持的 Lip Sync 通道如何驱动特定角色网格。一旦目标配置文件设置正确，映射就会成为将传入面部数据转换为 Unity 中稳定、角色专属动画的那一层。

{% hint style="info" %}
**需要帮助？** 如有疑问，请访问 [**Convai 开发者论坛**](https://forum.convai.com/).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/getting-started/setup/add-lip-sync-to-your-character/lip-sync-profiles-and-mappings/creating-a-custom-map.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.