更新记录

1.0.0（2026-07-22）

ms-live2d

跨平台 Live2D 模型渲染与交互插件，适用于 uni-app x (UTS)。

功能

• 模型加载 — 支持 Cubism 4/6 (.model3.json) 模型加载，支持本地路径和网络 URL
• 网络加载 — 全平台支持从 HTTP/HTTPS URL 加载模型，自动下载并缓存到本地
• 能力自动发现 — 加载完成后自动检测并返回模型所有能力（表情、动作组、参数、部件、口型同步参数、HitArea）
• 指令执行 — 播放动作、播放表情、设置参数、设置部件透明度、重置参数、视线跟随
• 点击事件 — 支持模型 HitArea 命中检测，返回命中区域名称和坐标
• 批量指令 — 通过 executeCommands 一次性执行多条指令

平台支持

安装

将 ms-live2d 目录放入项目 uni_modules/ 下即可（easycom 自动注册）。

基本用法

<template>
  <ms-live2d
    :modelPath="modelPath"
    :width="300"
    :height="400"
    @loaded="onModelLoaded"
    @hit="onModelHit"
    @error="onModelError"
    ref="live2dRef"
  />
</template>

<script setup lang="uts">
import type { Live2DModelCapabilities, Live2DTouchEvent } from '@/uni_modules/ms-live2d'

const modelPath = '/static/live2d/model/model.model3.json'
const live2dRef = ref(null)

function onModelLoaded(caps : Live2DModelCapabilities) {
  console.log('表情列表:', caps.expressions)
  console.log('动作组:', caps.motionGroups)
  console.log('参数:', caps.parameters)
  console.log('部件:', caps.parts)
  console.log('口型参数:', caps.lipSyncParams)
}

function onModelHit(event : Live2DTouchEvent) {
  console.log('点击区域:', event.hitArea, '坐标:', event.x, event.y)

  // 根据点击区域执行不同动作
  if (event.hitArea == 'Head') {
    live2dRef.value?.playMotion('TapHead', 0, 2)
  } else if (event.hitArea == 'Body') {
    live2dRef.value?.playMotion('TapBody', 0, 2)
  }
}

function onModelError(err : { message : string }) {
  console.error('模型加载失败:', err.message)
}
</script>

Props

Events

组件方法（ref 调用）

指令格式（executeCommands）

// 播放动作
{ type: 'motion', group: 'Idle', index: 0, priority: 2 }

// 播放表情
{ type: 'expression', expressionIndex: 1 }

// 设置参数
{ type: 'param', paramId: 'ParamMouthOpenY', paramValue: 0.8 }

// 设置部件透明度
{ type: 'part_opacity', partId: 'PartArmL', opacity: 0.5 }

// 重置参数
{ type: 'reset' }

// 视线跟随
{ type: 'look_at', x: 150, y: 200 }

类型定义

Live2DModelCapabilities

type Live2DModelCapabilities = {
  modelPath: string
  expressions: string[]                    // 表情名列表
  motionGroups: Live2DMotionGroup[]        // 动作组（含组内数量）
  parameters: Live2DParameter[]            // 参数（含 min/max/default）
  parts: string[]                          // 部件 ID 列表
  lipSyncParams: string[]                  // 口型同步参数
  canvasSize: { width: number, height: number }
}

Live2DTouchEvent

type Live2DTouchEvent = {
  hitArea: string   // 命中区域名（模型定义的 HitArea 或推断值）
  x: number         // 触摸 X
  y: number         // 触摸 Y
}

原生端开发说明

Android/iOS/HarmonyOS 端需配合 Cubism SDK 原生库。打包时需使用自定义基座。

Android

• 原生类：io.dcloud.uts.mspet.MsPetBridgeJava + MsPetRenderer
• 原生库：mspet.aar（含 libMsPet.so + 着色器 assets）
• uni-app x 不会自动编译 JNI 代码，修改 C++ 后需手动编译 .so 并重新打包 AAR

• 构建命令：

  # 1. 编译 .so
  cmake -DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/android.toolchain.cmake \
      -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-24 \
      -DANDROID_STL=c++_static <jni目录>
  make -j$(nproc)
  
  # 2. 打包 AAR（需包含着色器文件）
  # jni/arm64-v8a/libMsPet.so
  # assets/*.vert, *.frag (来自 CubismSDK/Framework/.../Shaders/StandardES/)

• 着色器文件：Cubism SDK v6 从文件加载着色器，必须将 StandardES/ 目录下全部 .vert / .frag 文件放入 AAR 的 assets/ 目录

iOS

• Swift 类：PetRendererNative（GLKView + 手势）
• ObjC++ 桥接：MsPetBridge.h/.mm
• 着色器文件：需将 Standard/ 目录下着色器文件放入 app bundle 的 FrameworkShaders/ 子目录

HarmonyOS

• NDK C++ 模块：MsPetHarmony（N-API + XComponent）
• 着色器文件：需将 Standard/ 目录下着色器文件放入 rawfile 的 FrameworkShaders/ 子目录

已知限制

• iOS 使用已废弃的 GLKit（Apple 推荐迁移到 Metal），未来版本将适配
• 首次加载较大模型时可能有 2-5 秒延迟（纹理上传 + 着色器编译）
• 网络加载依赖服务端 CORS 配置（Web 端）或网络权限声明（原生端）

平台兼容性

uni-app(5.11)

uni-app x(5.11)

ms-live2d

跨平台 Live2D 模型渲染与交互插件，适用于 uni-app x (UTS)。

功能

• 模型加载 — 支持 Cubism 4/6 (.model3.json) 模型加载，支持本地路径和网络 URL
• 网络加载 — 全平台支持从 HTTP/HTTPS URL 加载模型，自动下载并缓存到本地
• 能力自动发现 — 加载完成后自动检测并返回模型所有能力（表情、动作组、参数、部件、口型同步参数、HitArea）
• 指令执行 — 播放动作、播放表情、设置参数、设置部件透明度、重置参数、视线跟随
• 点击事件 — 支持模型 HitArea 命中检测，返回命中区域名称和坐标
• 批量指令 — 通过 executeCommands 一次性执行多条指令

平台支持

安装

将 ms-live2d 目录放入项目 uni_modules/ 下即可（easycom 自动注册）。

基本用法

<template>
  <ms-live2d
    :modelPath="modelPath"
    :width="300"
    :height="400"
    @loaded="onModelLoaded"
    @hit="onModelHit"
    @error="onModelError"
    ref="live2dRef"
  />
</template>

<script setup lang="uts">
import type { Live2DModelCapabilities, Live2DTouchEvent } from '@/uni_modules/ms-live2d'

const modelPath = '/static/live2d/model/model.model3.json'
const live2dRef = ref(null)

function onModelLoaded(caps : Live2DModelCapabilities) {
  console.log('表情列表:', caps.expressions)
  console.log('动作组:', caps.motionGroups)
  console.log('参数:', caps.parameters)
  console.log('部件:', caps.parts)
  console.log('口型参数:', caps.lipSyncParams)
}

function onModelHit(event : Live2DTouchEvent) {
  console.log('点击区域:', event.hitArea, '坐标:', event.x, event.y)

  // 根据点击区域执行不同动作
  if (event.hitArea == 'Head') {
    live2dRef.value?.playMotion('TapHead', 0, 2)
  } else if (event.hitArea == 'Body') {
    live2dRef.value?.playMotion('TapBody', 0, 2)
  }
}

function onModelError(err : { message : string }) {
  console.error('模型加载失败:', err.message)
}
</script>

Props

Events

组件方法（ref 调用）

指令格式（executeCommands）

// 播放动作
{ type: 'motion', group: 'Idle', index: 0, priority: 2 }

// 播放表情
{ type: 'expression', expressionIndex: 1 }

// 设置参数
{ type: 'param', paramId: 'ParamMouthOpenY', paramValue: 0.8 }

// 设置部件透明度
{ type: 'part_opacity', partId: 'PartArmL', opacity: 0.5 }

// 重置参数
{ type: 'reset' }

// 视线跟随
{ type: 'look_at', x: 150, y: 200 }

类型定义

Live2DModelCapabilities

type Live2DModelCapabilities = {
  modelPath: string
  expressions: string[]                    // 表情名列表
  motionGroups: Live2DMotionGroup[]        // 动作组（含组内数量）
  parameters: Live2DParameter[]            // 参数（含 min/max/default）
  parts: string[]                          // 部件 ID 列表
  lipSyncParams: string[]                  // 口型同步参数
  canvasSize: { width: number, height: number }
}

Live2DTouchEvent

type Live2DTouchEvent = {
  hitArea: string   // 命中区域名（模型定义的 HitArea 或推断值）
  x: number         // 触摸 X
  y: number         // 触摸 Y
}

原生端开发说明

Android/iOS/HarmonyOS 端需配合 Cubism SDK 原生库。打包时需使用自定义基座。

Android

• 原生类：io.dcloud.uts.mspet.MsPetBridgeJava + MsPetRenderer
• 原生库：mspet.aar（含 libMsPet.so + 着色器 assets）
• uni-app x 不会自动编译 JNI 代码，修改 C++ 后需手动编译 .so 并重新打包 AAR

• 构建命令：

  # 1. 编译 .so
  cmake -DCMAKE_TOOLCHAIN_FILE=$NDK/build/cmake/android.toolchain.cmake \
      -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-24 \
      -DANDROID_STL=c++_static <jni目录>
  make -j$(nproc)
  
  # 2. 打包 AAR（需包含着色器文件）
  # jni/arm64-v8a/libMsPet.so
  # assets/*.vert, *.frag (来自 CubismSDK/Framework/.../Shaders/StandardES/)

• 着色器文件：Cubism SDK v6 从文件加载着色器，必须将 StandardES/ 目录下全部 .vert / .frag 文件放入 AAR 的 assets/ 目录

iOS

• Swift 类：PetRendererNative（GLKView + 手势）
• ObjC++ 桥接：MsPetBridge.h/.mm
• 着色器文件：需将 Standard/ 目录下着色器文件放入 app bundle 的 FrameworkShaders/ 子目录

HarmonyOS

• NDK C++ 模块：MsPetHarmony（N-API + XComponent）
• 着色器文件：需将 Standard/ 目录下着色器文件放入 rawfile 的 FrameworkShaders/ 子目录

已知限制

• iOS 使用已废弃的 GLKit（Apple 推荐迁移到 Metal），未来版本将适配
• 首次加载较大模型时可能有 2-5 秒延迟（纹理上传 + 着色器编译）
• 网络加载依赖服务端 CORS 配置（Web 端）或网络权限声明（原生端）