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

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

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

　　即厘米游戏为：有用户厘米秀形象的小游戏

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

　　几何模型是厘米秀最主要的部分，分为通用部分和用户自定义部分，由以下几部分组成： 一个通用的骨骼（skeleton） 一个通用的面部（face） 若干件服装（dress）

　　其中每一套 dress 由一个单独的 dressid 标识，对应一套静态资源文件。

　　dress 按照位置区分为上装、下装、鞋，袜，头发、眼镜等等，由用户在换装系统中自行选择，数目不定。每个用户拥有一个 dressids 串，用于标识当前的服装数据。

　　不同位置的服装在数据结构上没有差异，可以一视同仁。 2. 化妆数据

　　化妆数据仅作用于面部，用于丰富面部的效果。没有几何模型，只有贴图。

　　化妆数据同样由 dress 定义。

　　用户的 dressids 串里，一部分是几何模型，一部分是面部模型。二者公用同一套 id 系统，通过 config 文件中的 type 字段区分。 3. 自定义配置

　　用户的捏脸，肤色调整等自定义配置，存储在 face.json 里。

　　捏脸数据作用于面部。

　　肤色调整作用于面部和服装的***出部分。

　　如用户没有进行自定义***作，则使用默认配置文件。 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。杀戮尖塔mod

　　详细代码参照 layabox 官网 demo:https://ldc2.layabox.com/doc/?nav=zh-ts-5-5-1 2. 其他 3D 引擎

　　由于 gltf 为通用格式，非 layabox 引擎也可以自行引入对应的 gltf loader，加载并使用厘米秀几何模型taptap云游戏。

　　但无法读取模型中的材质扩展信息，材质效果会有部分缺失。

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

　　版本：需要使用手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函数的返回值示例 3. dress资源拼装规则

　　该部分较为复杂，开发者需仔细阅读。

　　用户每件的装扮，需要将 dressid 代入 extend_data 中的 dress 资源拼装基础路径获得。

　　每个装扮的属性，由 config.json 定义，其中 type 字段声明了该装扮的类型: 如 type 为 geo，则是几何模型，同目录下存在 dress.gltf 如 type 为 beauty，则是化妆装扮，同目录下存在 dress.json 和 beauty.png

　　开发者拿到 dressid 串后，可以先读取 config.json，拿到当前装扮类型，再根据不同类型，下载不同的资源文件。51talk在线青少儿英语官网下载

　　也可以把每个目录下的文件全部下载，但两类资源并不同时存在，所以要注意判空。

　　用户厘米秀资源，建议在 loading 阶段预加载，通过 FileManager 相关 api 写入用户临时目录 qq.env.USER_DATA_PATHtwitch prime

　　之后即可视为本地路径来引用。 4. 资源按需取舍

　　使用 api，可以获得用户全部厘米秀形象数据，其中除却通用面部和通用骨骼模型，其余都是非必须的，游戏开发者可以根据需求自行取舍。   比如游戏中若无正面特写，则可以省略化妆类型的 dress，省略 face.json 等等。

　　比如游戏若为动作对战类型，也可以省略几何模型中位置为 backornament（背饰）的装扮等等（位置定义在 config 的 slot 字段）

　　开发者可以根据业务需要，自行取舍。

　　厘米秀零号素体模型（包含通用骨骼）: https://share.weiyun.com/lcTu5eXu

　　厘米秀形象假数据示例（接入api下载线上文件之前，可先使用假数据在本地开发调试）: https://share.weiyun.com/eRYL3j6B)三国题材游戏