文档

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

# 一、 厘米秀角色格式定义

# 1. 目前采用 spine 格式存储，近期计划支持 dragon bones。
# 2. 某个用户的厘米秀形象，由基础骨骼（role）和若干装扮（dress）拼接而成，基础骨骼所有人通用，装扮由用户自行选择组合，数目不定，动态变化。
# 3. 基础骨骼由三个文件构成：
  • role.json - 包含完整的骨骼（bone）和插槽（slot）定义
  • role.png
  • role.altas

  骨骼本身不包含贴图，故 role.png 为 1x1 空像素，role.altas 也无实际语义，仅为对齐格式用，可根据引擎语法选择是否载入。

# 4. 一套装扮由四个文件组成：
  • dress.json - 定义了若干插槽（slot）的附件（attachments），通常为 skinnedmesh，可随动画延展变化，脸部、气泡等部件为静态贴图
  • dress.png - 附件贴图
  • dress.altas - 贴图位置信息
  • config.json - 装扮配置，仅为厘米秀内部组织数据使用
# 关于插槽：每个装扮使用若干插槽，数目不定，但按照插槽使用范围，可分为以下几类
  • FaceSuit
  • FaceOrnament
  • HairType
  • HeadDress
  • TopSuit
  • BottomSuit
  • BackSuit
  • Bubble
  • Bubble_Name

  由 dress.json 中的 type 字段定义，将所有部件拼装，就是一套完整的 skin 数据。
  游戏加载时，可情况舍弃部分，如对战时不加载气泡（Bubble，BubbleName），背后挂件（BackSuit）等。
  拼装部件的 js demo，可于文末下载地址获取。

  注意：由于厘米秀素材文件导出时间较早，使用了 spine2x 版本，dress.json 中定义的 type：'skinnedmesh' 已经废弃，需要替换成 type：'mesh'，才能在 cocos2.4 以上版本中正常展示。

# 5. 厘米秀形象不包含动画信息，游戏开发者可基于通用基础骨骼，根据游戏实际需要设计动作，导出为 spine 标准格式，配合模型使用。

  注意：由于同上原因，动画中 curve 的属性不支持贝塞尔曲线等复杂插值方式，仅支持线性插值（默认）和 stepped，为避免兼容问题，建议安装 2.1.17 版本的 spine 编辑并导出动画，安装方式可参照：http://zh.esotericsoftware.com/spine-settings#Version

# 二、 厘米秀资源文件存储方式

# 1. 由于用户配置随时可能发生变化，需要采用 运行时动态加载 的方式进行开发。装扮种类繁多，无需在游戏打包时置入资源。
# 2. 基础模型存放路径
# 3. 装扮资源存放路径

  https://i.gtimg.cn/qqshow/admindata/comdata/vipApollo_item_${id}/d.zip
  其中 ${id} 替换为实际装扮的 dressid

# 4. 部分示例 dressids 及对应形象截图

(1) 86,88,14520,14521,14522,14523,14524


(2) 2235,2380,4460,4949,4960,5503,5518


(3) 89,2156,5918,6290,6291,6320,6378


(4) 91,1697,5588,6760,8244,8311,8799

# 三、 厘米秀资源拉取流程

# 1. 鉴权，获取用户身份。
# 2. 使用 SDK 提供的方法，拉取用户对应的 dressids。
# 3. 根据 dressids 存放地址，拉取对应的素材包，并动态解压。
# 4. 拉取基础模型，和用户资源包进行组装，得到完整的用户形象数据。
# 5. 展示，交互，动画……

  原始用户数据即为一串 dressId，请勿使用游戏引擎，把模型进行格式转换/二次导出。
  如运行时加载遇到问题，可联系 QQ 小游戏平台方共同解决。

# 四、 厘米秀资源拉取API

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

# 参数说明

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

  返回值 - Object res
  其中包含了用户的配置信息。

# 五、 厘米秀模型组装示例

  下载地址：https://share.weiyun.com/21iRrybW
  可根据readme文档在本地运行，参考其中的代码实现2d形象的动态装配。

← 使用 3D 形象 →