打造专属BongoCat：零基础模型定制与社区贡献全指南

2026-02-05 04:37:15作者：羿妍玫Ivan

你是否也曾想过让屏幕上的Bongo Cat拥有独特外观？是否希望分享自己设计的猫咪模型却不知从何下手？本文将带你从零开始完成模型定制、格式转换到社区贡献的全流程，让你的创意作品被全球用户看见。

模型定制基础

BongoCat支持三种官方模型类型，分别适配不同交互场景：

标准模型：src-tauri/assets/models/standard - 基础静态展示模型
键盘模型：src-tauri/assets/models/keyboard - 响应键盘输入的互动模型
手柄模型：src-tauri/assets/models/gamepad - 适配游戏手柄操作的模型

每个模型目录包含必要的配置文件和资源：

.model3.json - 模型主配置文件
.moc3 - 模型数据文件
.cdi3.json - 模型物理碰撞配置
texture_*.png - 纹理图片资源
live2d_motion*.motion3.json - 动作配置文件

模型文件结构解析

以标准模型为例，核心文件结构如下：

standard/
├── cat.model3.json       # 模型定义
├── demomodel.moc3        # 模型数据
├── demomodel.cdi3.json   # 碰撞配置
├── demomodel.1024/       # 纹理图集
│   ├── texture_00.png
│   ├── texture_01.png
│   └── texture_02.png
├── live2d_expression*.exp3.json  # 表情配置
└── live2d_motion*.motion3.json   # 动作配置

模型加载逻辑在src/utils/live2d.ts中实现，通过load()方法读取模型配置并初始化：

public async load(path: string) {
  this.initApp()
  this.destroy()
  
  const files = await readDir(path)
  const modelFile = files.find(file => file.name.endsWith('.model3.json'))
  
  if (!modelFile) {
    throw new Error('未找到模型主配置文件，请确认模型文件是否完整。')
  }
  // ...加载模型的后续逻辑
}

自定义模型制作步骤

1. 基础资源准备

纹理图片：建议使用3张2048×2048的PNG图片，按身体部位拆分绘制
动作设计：规划至少3种基础表情和5种互动动作
配置文件：复制官方模型的JSON配置作为模板修改

2. 模型转换流程

若已有其他格式模型，可使用官方提供的在线转换工具： 🔗 BongoCat模型在线转换工具

转换后的文件需验证完整性，确保包含所有必要的配置文件。

3. 本地测试方法

完成模型制作后，通过以下步骤在本地测试：

将模型文件夹放入src-tauri/assets/models目录
启动开发环境：

pnpm install
pnpm tauri dev

在应用设置中切换至自定义模型
测试所有交互动作和表情切换是否正常

模型加载状态管理在src/composables/useModel.ts中实现，通过handleLoad()方法处理模型加载和错误反馈。

社区贡献规范

贡献前准备工作

环境搭建：

# 安装依赖
pnpm install

# 启动开发服务器
pnpm tauri dev

代码规范：

遵循conventional-changelog提交规范
使用ESLint进行代码检查：pnpm lint
确保所有交互功能在三大平台（Windows/macOS/Linux）测试通过

模型提交 checklist

提交模型前请确认：

[ ] 所有文件使用UTF-8编码
[ ] 纹理图片压缩至合理大小（单张不超过2MB）
[ ] 提供完整的动作集（至少包含 idle、press、release 状态）
[ ] 包含模型预览图（200×200像素）
[ ] 填写模型信息文档（作者、版本、说明）

Pull Request 流程

Fork项目仓库
创建特性分支：git checkout -b model/your-model-name
提交模型文件至src-tauri/assets/models/目录
更新模型列表：src/constants/index.ts
提交PR，标题格式：feat: add [model-type] model [model-name]

高级模型优化技巧

性能优化建议

纹理图集合并：将多个小图合并为图集减少绘制调用
动作简化：非关键动作使用简化曲线减少计算量
分层加载：优先加载低分辨率纹理，再异步加载高清资源

交互体验增强

通过src/composables/useModel.ts中的方法可以自定义交互逻辑：

// 设置参数值控制模型状态
public setParameterValue(id: string, value: number | boolean) {
  const coreModel = this.getCoreModel()
  return coreModel?.setParameterValueById?.(id, Number(value))
}