# 3d_dancer

**Repository Path**: bocaicn/3d_dancer

## Basic Information

- **Project Name**: 3d_dancer
- **Description**: 可以导入并浏览 glb/gltf 等3D模型的 鸿蒙App
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HarmonyOS 3D 动作展示 App（起步工程）

从 Blender / 动作库导出的 3D 模型（glTF/GLB）导入鸿蒙 App，展示模型并按预设动作播放舞蹈/动作。
技术栈：**HarmonyOS NEXT（API 12+） + ArkTS + ArkGraphics 3D（`@kit.ArkGraphics3D`）**。

## 已实现能力

- 内置示例模型加载与展示（`Component3D` + `Scene`）
- 按模型内置动作切换播放（动作按钮条，来自 `scene.animations`）
- 动作循环播放（动画结束 `onFinished` 自动重播）
- **多模型同屏**：主页面 2×2 `Grid`，每个 `ModelViewer` 独立加载/渲染/控制
- **本地模型文件导入**：顶部“导入模型”按钮唤起系统文件选择器，选 `.glb` 后拷入沙箱并加载
- **单模型全屏窗口 + 手势**：单指拖动旋转视角、双指捏合缩放（轨道相机）
- 渲染循环用 `setTimeout` 每帧 `scene.renderFrame()` 驱动（动画必须逐帧驱动才会播放；本 SDK 的 `@kit.ArkUI` 未导出 `displaySync`，故用定时器循环，与已验证的 harmony-tetris-3d 工程一致）
- 可见性管理：组件不可见时停止渲染，节省资源、避免上架审核不通过
- 页面退出时 `scene.destroy()` 释放 GPU 资源

## 目录结构

```
harmonyos-3d-dancer/
├─ AppScope/                       # app 级配置与图标
├─ build-profile.json5             # 工程构建（compatible/compile/targetSdkVersion=6.1.1(24)）
├─ oh-package.json5
├─ hvigorfile.ts
└─ entry/
   ├─ build-profile.json5
   ├─ oh-package.json5
   ├─ hvigorfile.ts
   └─ src/main/
      ├─ module.json5              # ability 声明（本地导入走 DocumentViewPicker，无需额外权限）
      ├─ resources/
      │  ├─ base/...               # string / color / main_pages / 占位图标
      │  └─ rawfile/models/        # 把 Fox.glb 放这里（见下方）
      └─ ets/
         ├─ entryability/EntryAbility.ets
         ├─ pages/Index.ets        # 主页：导入按钮 + 2×2 多模型网格
         ├─ components/ModelViewer.ets   # 可复用模型展示+动作组件
         ├─ controller/AnimationController.ets  # 动作控制（播放/暂停/循环/过渡）
         ├─ utils/ModelImport.ets  # 本地 .glb 选择 + 沙箱拷贝
         └─ common/Constants.ets
```

## 运行前置

1. 安装 **DevEco Studio**（最新版），SDK 选择 **HarmonyOS NEXT API 12+**。
2. 用 DevEco 打开本工程根目录（自动识别 `build-profile.json5` / `oh-package.json5`）。
3. 首次打开执行 `File → Sync and Refresh Project`（或 `ohpm install`）拉取依赖。
4. 准备一个模型：
   - 最简：下载 Khronos 官方 **Fox.glb**（含 Survey/Walk/Run 三个动作）放到
     `entry/src/main/resources/rawfile/models/Fox.glb`。
   - 或运行时点“导入模型”从手机选任意 `.glb`。
5. 连接真机（或模拟器）点 Run。没有模型时页面显示“模型无内置动作”属正常。

> 说明：内置图标 `startIcon.png` 仅为 1×1 占位图，请替换为正式图标（AppScope 与
> entry 的 `resources/base/media/` 各一份）。

## 在本机构建与部署（已验证可用）

本机已具备完整工具链：**DevEco Studio（E: 盘）**、**HarmonyOS-SDK（C:\\Users\\shiba\\HarmonyOS-SDK）**、
DevEco 自带 **JDK（jbr）** 与 **node v18**。无需联网即可构建（hvigor 自带全局插件，
ohpm 用本地缓存）。

### 构建（产出签名 HAP）
```bash
cd harmonyos-3d-dancer
node build_launcher.js clean build     # 内部用 DevEco node v18 + jbr + SDK 调 hvigorw assembleHap
```
产物：`entry/build/default/outputs/default/entry-default-signed.hap`

> `build_launcher.js` 已固化环境变量：JAVA_HOME=DevEco jbr、NODE=DevEco v18、
> DEVECO_SDK_HOME=C:\\Users\\shiba\\HarmonyOS-SDK，并清空 `NODE_OPTIONS`
> （避免沙箱注入的 shim 拦截 hvigor 清理 `.hvigor` 缓存导致构建崩溃）。

### 部署到设备（10099 端口）
```bash
bash deploy.sh                          # 默认连 192.168.9.110:10099
# 等价于手动：
#   hdc tconn 192.168.9.110:10099
#   hdc install entry/build/default/outputs/default/entry-default-signed.hap
#   hdc shell aa start -a EntryAbility -b com.example.tetris3d
```

### 关于签名（重要）
本工程复用了本机已有的调试签名（harmony-tetris-3d 的 debug 证书/profile），
因此 `AppScope/app.json5` 的 bundleName 暂为 **`com.example.tetris3d`**，
部署时会覆盖设备上原有的 tetris3d 应用。
如需独立 bundleName（如 `com.example.dancer3d`），请在 DevEco 中对该工程执行一次
「自动签名」（File → Project Structure → Signing Configs → Automatically generate signature），
生成专属 profile 后把 bundleName 改回即可。

## Mixamo 动作库 + Blender 绑定导出（你的动作来源）

目标：把 Mixamo 的免费人物动作，绑定到你自己的/标准骨架角色，再导出带多个动作 clip 的 GLB。

1. **准备带骨架的角色**
   - 在 Mixamo 选一个角色（如 “Y Bot”），下载 **FBX（with skin）**；
   - 或用自己的角色，在 Blender 里用 **Auto Rig Pro / Rigify** 绑定骨架。
2. **获取动作**
   - 在 Mixamo 选动作（跳舞、挥手、走路…），下载 **FBX（without skin）**；
   - 在 Blender 里 `File → Import → FBX` 把动作套到同一骨架（勾选 `Import Animations`）。
3. **整理成多个 Action**
   - 切到 **Dope Sheet → Action Editor**，每个动作是一个 Action；
   - 用 **NLA Editor** 或直接在导出面板，让每个 Action 成为一个独立的动画轨道。
4. **导出 GLB**
   - `File → Export → glTF 2.0`；格式选 **glTF Binary (.glb)**；
   - **务必取消 “Compression”（即 Draco 网格压缩）勾选**——ArkGraphics 3D 不支持 Draco，
     带压缩的 GLB 会直接报 `Scene Creation failed`；也不要勾 KHR_mesh_quantization 等非常规扩展；
   - 勾选 **Animation**；Include 里确保 **+ARMATURE / Deform Bones** 被导出；
   - 贴图 ≤ 2K、面数控制在移动端合理范围（角色建议 < 5 万面）。
5. **进 App**
   - 放入 `rawfile/models/` 并改 `ModelViewer.ets` 里 `rawResource` 默认路径；
   - 或直接用“导入模型”按钮加载。模型内每个 Action 会自动变成一条动作按钮。

## 模型导入排障（Creation failed / 加载异常）

导入 `.glb` 后若只在日志里看到原生 `Scene Creation failed`、或 App 提示“加载异常”，按以下顺序排查：

1. **优先怀疑 Draco 压缩**：ArkGraphics 3D 的 glTF 解析器不支持 `KHR_draco_mesh_compression`，
   Blender 导出时若勾了 “Compression” 就会触发。→ 重新导出，**取消 Compression**、
   也不要选网格量化扩展，导出为纯 `.glb`。
2. **文件不是合法 GLB**：若导入的是 `.gltf`（JSON 文本），它通常依赖同目录的 `.bin`/贴图，
   单独拷一个 `.gltf` 必失败。改为导出 **glTF Binary (.glb)** 单文件。
3. **App 已内置文件头校验**：加载前会读取前 12 字节校验 `glTF` 魔数与版本 2，
   非法文件会直接提示“不是有效的 GLB”“模型为空或过小”，不会再走到 `Scene.load`。
4. **路径问题（较少见）**：`Scene.load(localPath)` 用沙箱绝对路径（App 自己 `fileIo` 写入），
   官方文档确认支持；若仍报 Creation failed 且文件头校验通过，多半是上述 1/2 的内容问题。

> 提示：本 SDK 的 `Scene.load` 失败时是 **reject 字符串**（不是 Error 对象），旧代码取
> `.message` 会得到 `undefined`；工程已用 `errMsg()` 统一处理，并在失败时附 Draco 嫌疑提示。

## 已知限制 / 下一步

- **动作平滑过渡（crossfade）**：ArkGraphics 3D 当前没有暴露骨骼混合权重，
  `AnimationController.transitionTo()` 目前是“先停旧、再播新”的硬切换。
  真正的加权融合需改用 **Cocos Creator / Unity**（均支持导出到 HarmonyOS）。
- **多模型同屏性能**：每个 `ModelViewer` 是一个独立 `Component3D` 表面，同屏数量过多
  会增加 GPU/合成开销；需要时可将多个模型合并进同一个 `Scene` 作为不同 Node 渲染。
- **本地导入路径**：`Scene.load(localPath)` 接受沙箱绝对路径；个别 SDK 版本若对路径
  解析更严格，可改在导入后拷贝进 `rawfile` 重建（运行时无法写 rawfile，故走沙箱）。
- 相机目前是固定机位（z=5 看向原点）；可扩展为拖拽旋转/缩放（监听手势改 `cam.position`）。
- 动作循环用 `onFinished` 重启；若要“播完即停”把 `AnimationController.play` 的 `loop` 设为 false。