# wx-app-pet

**Repository Path**: itsaysay/wx-app-pet

## Basic Information

- **Project Name**: wx-app-pet
- **Description**: 在微信小程序上跑的3D模型，demo
- **Primary Language**: JavaScript
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 微信小程序 3D宠物互动功能

基于 Three.js 实现的微信小程序 3D宠物互动系统，支持光照、骨骼动画、手势交互。

## ✨ 功能特性

- 🎨 **四点光照系统** - 环境光 + 主方向光 + 轮廓光 + 补光，带实时阴影
- 🎬 **骨骼动画系统** - 支持5种内置动画：Idle、Jump、Spin、Wave、Happy
- ✨ **动画平滑过渡** - 不同动画之间自动淡入淡出切换
- 👆 **手势交互** - 拖拽旋转视角、点击触发动画
- 🌓 **日夜模式切换** - 一键切换光照效果
- 🧪 **测试模型** - 程序生成测试模型，零依赖快速开发
- 📦 **GLB模型支持** - 支持加载标准GLB格式模型

## 📁 项目结构

```
wx-app/
├── app.js / app.json / app.wxss    # 小程序入口
├── package.json                     # 依赖配置
├── IMPLEMENTATION_PLAN.md          # 完整实现方案
├── pages/
│   └── pet-3d/                      # 3D宠物页面
│       ├── index.js
│       ├── index.json
│       ├── index.wxml
│       └── index.wxss
├── components/
│   └── three-canvas/                # 可复用WebGL画布组件
│       ├── index.js
│       ├── index.json
│       ├── index.wxml
│       └── index.wxss
├── utils/
│   ├── three-adapter.js            # Three.js场景/渲染器封装
│   ├── lighting-system.js           # 光照系统
│   ├── test-model-generator.js     # 测试模型生成器
│   ├── animation-controller.js      # 动画控制器
│   ├── interaction-handler.js       # 交互处理器
│   └── gltf-loader-adapter.js      # GLB模型加载器
└── assets/
    └── models/                      # 3D模型资源（GLB格式）
```

## 🚀 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 微信开发者工具配置

1. 打开微信开发者工具，导入项目
2. 点击菜单栏：`工具 -> 构建 npm`
3. 确保 project.config.json 中已开启 `nodeModules: true`

### 3. 运行项目

直接在开发者工具中点击"编译"即可运行。

默认使用**测试模型**（程序生成的简单3D角色），可以直接看到效果。

## 🎮 使用说明

### 基本操作

| 操作 | 效果 |
|-----|------|
| 🖱️ 拖拽屏幕 | 旋转相机，360度查看宠物 |
| 👆 点击宠物 | 触发跳跃动画 |
| → 快速滑动 | 触发旋转动画 |

### 交互按钮

- 🦘 **跳跃** - 触发Jump动画
- 🔄 **旋转** - 触发Spin动画
- 👋 **挥手** - 触发Wave动画
- 😊 **开心** - 触发Happy弹跳动画
- 🔄 **重置视角** - 相机回到初始位置
- 🌙 **日夜模式** - 切换光照效果

## 🎨 组件使用方法

### three-canvas 组件

```xml
<three-canvas
  id="petCanvas"
  use-test-model="{{true}}"
  model-path="assets/models/pet.glb"
  bind:load="onModelLoad"
  bind:error="onModelError"
></three-canvas>
```

### 属性

| 属性 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| useTestModel | Boolean | true | 是否使用程序生成的测试模型 |
| modelPath | String | '' | GLB模型路径（useTestModel=false时生效） |
| width | Number | 0 | 画布宽度，默认屏幕宽度 |
| height | Number | 0 | 画布高度，默认屏幕高度 |
| autoPlay | Boolean | true | 是否自动播放闲置动画 |

### 事件

| 事件 | 参数 | 说明 |
|-----|------|------|
| bind:load | { model, animations } | 模型加载完成 |
| bind:error | { error } | 加载失败 |

### 外部调用方法

```javascript
// 获取组件实例
const canvas = this.selectComponent('#petCanvas');

// 播放指定动画
canvas.playAnimation('Jump', 0.3);

// 触发交互动画
canvas.triggerInteraction('tap'); // 'tap'|'swipe'|'pet'|'feed'

// 重置相机
canvas.resetCamera();

// 切换光照模式
canvas.setLightMode('night'); // 'day' | 'night'

// 获取可用动画列表
const anims = canvas.getAvailableAnimations();
```

## 📦 切换到真实GLB模型

当你有真实的宠物GLB模型时，只需两步切换：

### 1. 放置模型文件

将你的 `.glb` 文件放到：
```
assets/models/your-pet-model.glb
```

### 2. 修改页面配置

在 `pages/pet-3d/index.wxml` 中：

```xml
<three-canvas
  id="petCanvas"
  use-test-model="{{false}}"          <!-- 关闭测试模型 -->
  model-path="assets/models/your-pet-model.glb"  <!-- 指定模型路径 -->
  bind:load="onModelLoad"
  bind:error="onModelError"
></three-canvas>
```

## 🎬 动画命名约定

为了让GLB模型能正确识别动画类型，建议使用以下命名：

| 动画类型 | 推荐命名 | 说明 |
|---------|---------|------|
| 闲置动画 | `Idle`, `Breath`, `Idle_*` | 自动循环播放 |
| 跳跃 | `Jump` | 点击/喂食触发 |
| 旋转 | `Spin` | 滑动触发 |
| 挥手 | `Wave`, `Head_Pat` | 抚摸触发 |
| 开心 | `Happy`, `Eat` | 喂食触发 |

闲置动画只要名称包含 "idle"（不区分大小写）就会被自动识别。

## 🔧 工具类说明

### ThreeAdapter
- 负责初始化 Three.js 场景、相机、渲染器
- 管理渲染循环和动画混合器
- 处理资源清理

### LightingSystem
- 实现专业的四点光照方案
- 支持白天/黑夜模式切换
- 自动配置阴影参数

### TestModelGenerator
- 程序生成简单的3D角色（身体+头部+四肢）
- 内置5个测试动画
- 零外部依赖，快速开发

### AnimationController
- 管理所有动画状态
- 实现动画间平滑过渡
- 自动识别闲置/交互类型动画

### InteractionHandler
- 处理触摸事件
- 相机轨道旋转控制
- 射线检测点击命中
- 点击视觉特效

### MiniProgramGLTFLoader
- 适配微信文件系统的GLB加载器
- 支持本地文件和CDN加载
- 自动归一化模型尺寸和位置

## 📊 性能优化建议

### 模型优化
- 面数：建议控制在 5000-10000 三角形
- 贴图：最大 1024x1024，使用纹理图集
- 骨骼：小于 50 根骨骼

### 渲染优化
- 已默认限制像素比：`Math.min(devicePixelRatio, 2)`
- 阴影贴图分辨率优化
- 视锥体剔除

### 内存管理
- 页面退出时自动 dispose 所有资源
- 后台时暂停渲染

## 🎯 验收清单

- [x] 页面加载后显示3D宠物
- [x] 宠物自动播放闲置呼吸动画
- [x] 拖拽屏幕可360度旋转视角
- [x] 点击宠物触发跳跃动画
- [x] 动画切换平滑无跳变
- [x] 光照正确，地面有实时阴影
- [x] 点击交互按钮正常响应
- [x] 日夜模式切换正常
- [x] 反复进出页面无内存泄漏
- [x] 小程序切后台后暂停渲染

## 📝 开发说明

### 测试模型 vs 真实模型

开发阶段强烈建议使用测试模型，优点：
- ✅ 无需准备3D模型文件
- ✅ 快速验证代码逻辑
- ✅ 方便调试光照、动画、交互
- ✅ 一行代码即可切换到真实模型

### 动画过渡时间建议

| 场景 | 过渡时间 | 效果 |
|-----|---------|------|
| 闲置 → 互动 | 0.2s | 响应灵敏 |
| 互动 → 闲置 | 0.5s | 自然回落 |
| 闲置间切换 | 0.5s | 柔和自然 |

## 🐛 常见问题

### Q: 报错 "找不到 @threejs-miniprogram/threejs"
A: 确保已执行 `npm install`，并在微信开发者工具中执行 "构建 npm"

### Q: 模型显示为黑色
A: 检查GLB模型是否包含材质和贴图，或调整光照系统参数

### Q: 动画播放异常
A: 确认GLB文件中确实包含动画，且动画命名符合约定

### Q: 小程序后台后重新进入白屏
A: 已在 pageLifetimes 中处理了后台暂停/恢复逻辑

## 📄 许可证

MIT License