文档

# 厘米秀 3D 形象接入小游戏

# 一、 厘米游戏概述

  1. 厘米秀介绍：厘米秀为手机 QQ 内备受用户喜爱的虚拟形象，目前在 QQ 内渗透率超过 40%，且用户一直保持较高留存。厘米秀 3D 形象视觉风格如下所示:

  2. 厘米游戏的本质：平台通过api的方式将用户的厘米秀形象提供给小游戏开发者，小游戏开发者将厘米秀形象作为用户在游戏中的形象。
    即厘米游戏为：有用户厘米秀形象的小游戏

# 二、 3D厘米秀形象构成

  3D厘米秀形象由几何模型、化妆装扮和自定义配置三部分组成。

# 1. 几何模型

  几何模型是厘米秀最主要的部分，分为通用部分和用户自定义部分，由以下几部分组成：

  • 一个通用的骨骼（skeleton）
  • 一个通用的面部（face）
  • 若干件服装（dress）

  其中每一套 dress 由一个单独的 dressid 标识，对应一套静态资源文件。
  dress 按照位置区分为上装、下装、鞋，袜，头发、眼镜等等，由用户在换装系统中自行选择，数目不定。每个用户拥有一个 dressids 串，用于标识当前的服装数据。
  不同位置的服装在数据结构上没有差异，可以一视同仁。

# 2. 化妆数据

  化妆数据仅作用于面部，用于丰富面部的效果。没有几何模型，只有贴图。
  化妆数据同样由 dress 定义。
  用户的 dressids 串里，一部分是几何模型，一部分是面部模型。二者公用同一套 id 系统，通过 config 文件中的 type 字段区分。

# 3. 自定义配置

  用户的捏脸，肤色调整等自定义配置，存储在 face.json 里。
  捏脸数据作用于面部。
  肤色调整作用于面部和服装的露出部分。
  如用户没有进行自定义操作，则使用默认配置文件。

# 三、 3D厘米秀数据结构

# 1. 几何模型结构

  为方便跨平台跨引擎接入，几何模型统一使用开源交换格式 gltf。（关于标准gltf结构定义，参见 https://www.khronos.org/gltf/ )
  厘米秀的 gltf 文件遵循标准，只有材质部分增加了 extra 结构，用来存储厘米秀自定义材质的信息。
  gltf 中引用的二进制文件和贴图文件均采用内联方式存储，读取一个文件即可获取所有信息，贴图为 png 格式。

# 2. 化妆装扮结构

  化妆装扮结构较简单，由 dress.json 和 beauty.png 组成。
  dress.json 中声明了贴图的坐标信息。

# 3. 自定义配置

  存储为 face.json 文件，每个用户都拥有一套自定义配置。
  肤色配置存储为 HSV 值，作用于通用面部模型、和用户自选的服装模型（露出皮肤的部分）。
  捏脸数据存储为 blendshape 通道权重，作用于通用面部模型。

# 四、 角色动画

  厘米秀形象仅包含供静态模型，游戏中的角色动画由开发者自行设计。
  设计师可使用厘米秀提供的 0 号模型的 fbx 素材，进行角色动画的开发。

# 五、 引擎兼容性

# 1. Layabox

  目前 layabox 3d 小游戏开发引擎，对厘米秀模型做了定制化支持。

  • 能够解析几何模型，展示完整的材质效果。
  • 能够解析出化妆装扮，应用于面部。
  • 能够将每个用户的自定义配置应用于模型。

  使用时只需要预先下载素材文件，置入对应的结构，即可得到一个 layaSprite。
  详细代码参照 layabox 官网 demo:https://ldc2.layabox.com/doc/?nav=zh-ts-5-5-1

# 2. 其他 3D 引擎

  由于 gltf 为通用格式，非 layabox 引擎也可以自行引入对应的 gltf loader，加载并使用厘米秀几何模型。
  但无法读取模型中的材质扩展信息，材质效果会有部分缺失。
  且无法读取化妆装扮，也无法应用自定义配置。

# 六、 小游戏内使用厘米秀形象流程

  1. 调用 qq.login() 鉴权，获取用户 openid。
  2. 调用 qq.getCMShowInfo()，获取用户当前装扮信息（dressids串），以及资源存放地址规则。
  3. 根据 dressids 和存放地址规则，拉取对应的素材资源，放入临时资源目录。
  4. 解析素材，组装模型，得到完整的用户厘米秀形象。
  5. 给厘米秀形象套用动作，展示，交互……

# 七、 厘米秀资源拉取API

  版本：需要使用手Q 8.4.10 以上版本，开发时选择基础库版本大于 1.20。
  JS Api: qq.getCMShowInfo(Object object)

# 1. 入参说明

属性 类型 默认值 必填 说明
openid string 是 用户openid
engineType string 是 引擎类型
engineVersion string 是 引擎版本
avatarType string 2D 否 厘米秀形象类型，不传则为2D
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）
# object.engineType 的合法值：
属性值 说明
laya LayaBox
egret 白鹭引擎
cocos Cocos

# 2. 返回值说明

  下面为avatarType传入3D时，success函数的返回值示例

{
  avtr：[{
    avatar3D: {
      role_id //基础角色id，游戏开发者可不用处理
      dress_ids:[], //重要！用户当前装扮列表
      face_data: //为zip压缩包地址，需动态解压后得到face.json。如用户并未进行过自定义操作，则该字段可能为空。
    }
  }],
  extend_data: {
    url3d: {
      base:{
        face //通用面部模型资源地址
        skeleton //通用骨骼模型资源地址
        facejson //默认面部自定义配置zip资源地址，需动态解压
      },
      config //dress资源拼装基础路径
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 3. dress资源拼装规则

  该部分较为复杂，开发者需仔细阅读。
  用户每件的装扮，需要将 dressid 代入 extend_data 中的 dress 资源拼装基础路径获得。
  每个装扮的属性，由 config.json 定义，其中 type 字段声明了该装扮的类型:

  • 如 type 为 geo，则是几何模型，同目录下存在 dress.gltf
  • 如 type 为 beauty，则是化妆装扮，同目录下存在 dress.json 和 beauty.png

  开发者拿到 dressid 串后，可以先读取 config.json，拿到当前装扮类型，再根据不同类型，下载不同的资源文件。
也可以把每个目录下的文件全部下载，但两类资源并不同时存在，所以要注意判空。

  用户厘米秀资源，建议在 loading 阶段预加载，通过 FileManager 相关 api 写入用户临时目录 qq.env.USER_DATA_PATH
之后即可视为本地路径来引用。

# 4. 资源按需取舍

  使用 api，可以获得用户全部厘米秀形象数据，其中除却通用面部和通用骨骼模型，其余都是非必须的，游戏开发者可以根据需求自行取舍。   比如游戏中若无正面特写，则可以省略化妆类型的 dress，省略 face.json 等等。
  比如游戏若为动作对战类型，也可以省略几何模型中位置为 backornament（背饰）的装扮等等（位置定义在 config 的 slot 字段）
开发者可以根据业务需要，自行取舍。

# 八、 相关资源下载

← 判断是否已安装微端 →