更新记录

1.0.0（2026-05-10）

• 支持 App Android 和 App iOS 原生 Live2D 模型渲染。
• 支持模型加载、动作播放、表情切换、参数控制、触摸命中。
• 支持语音播放、WAV/音频口型驱动、动作自带声音。
• 支持 AI 实时 PCM16 音频流播放和口型同步。

平台兼容性

uni-app x(5.08)

em-live2d 插件使用文档

em-live2d 是 uni-app UTS 原生组件插件，用于在 App 端渲染 Live2D Cubism 模型。插件支持 Android 和 iOS，可在 nvue/uvue 页面中加载模型、播放动作、切换表情、控制参数、播放语音、驱动口型，并接入 AI 实时语音输出。

支持范围

应用场景

em-live2d 适合需要在 App 内嵌入可交互虚拟角色的场景：

资源放置

建议将 Live2D 模型资源放到应用的 static/live2d 目录：

static/live2d/
  165 204/
    165 204.model3.json
    165 204.moc3
    165 204.physics3.json
    165 204.4096/
      texture_00.png
    motion/
      idle.motion3.json
      dance.motion3.json
    expressions/
      smile.exp3.json
    sounds/
      song.wav

页面中使用 /static/... 路径：

/static/live2d/165 204/165 204.model3.json
/static/live2d/165 204/sounds/song.wav

如果模型是下载到本地的，也可以传绝对本地文件路径。路径必须指向 .model3.json。

基础用法

<template>
  <view class="page">
    <em-live2d
      ref="avatar"
      class="avatar"
      model="/static/live2d/165 204/165 204.model3.json"
      :autoIdle="true"
      :enableMotionSound="true"
      :voiceVolume="1"
      @modelLoaded="onModelLoaded"
      @modelLoadFailed="onModelLoadFailed"
      @motionFinished="onMotionFinished"
      @voiceEnded="onVoiceEnded"
      @nativeError="onNativeError"
    />
  </view>
</template>

<script>
export default {
  methods: {
    onModelLoaded(event) {
      console.log('Live2D model loaded', event)
    },
    onModelLoadFailed(error) {
      console.log('Live2D model load failed', error)
    },
    onMotionFinished(event) {
      console.log('Live2D motion finished', event)
    },
    onVoiceEnded(event) {
      console.log('Live2D voice ended', event)
    },
    onNativeError(error) {
      console.log('Live2D native error', error)
    }
  }
}
</script>

<style>
.page {
  flex: 1;
}

.avatar {
  width: 750rpx;
  height: 980rpx;
}
</style>

Props

加载模型

通过 model 属性加载：

<em-live2d ref="avatar" model="/static/live2d/165 204/165 204.model3.json" />

也可以手动加载：

this.$refs.avatar.loadModel('/static/live2d/165 204/165 204.model3.json')

模型加载成功会触发 modelLoaded，失败会触发 modelLoadFailed。

动作

动作必须在 .model3.json 的 FileReferences.Motions 中声明。调用时使用动作组名和索引：

this.$refs.avatar.startMotion('Dance', 0, 3)
this.$refs.avatar.startRandomMotion('Idle', 1)
this.$refs.avatar.stopAllMotions()

优先级建议：

如果动作没有播放，先确认：

• .model3.json 中存在该 motion group。
• index 没有越界。
• motion 文件路径正确并已打包。
• 当前动作优先级没有被更高优先级动作占用。

表情和参数

表情必须在 .model3.json 的 Expressions 中声明：

this.$refs.avatar.setExpression('smile')
this.$refs.avatar.setRandomExpression()

参数控制：

this.$refs.avatar.setParameter('ParamAngleX', 15)
this.$refs.avatar.addParameter('ParamAngleY', 5, 1)
this.$refs.avatar.multiplyParameter('ParamEyeLOpen', 0.8, 1)
this.$refs.avatar.setParametersBatch(['ParamAngleX', 'ParamAngleY'], [10, -5])

const value = this.$refs.avatar.getParameter('ParamAngleX')

只有模型 .moc3 中真实存在的参数才会生效。

语音和口型

手动控制口型

this.$refs.avatar.setLipSyncValue(1)
this.$refs.avatar.setLipSyncValue(0)
this.$refs.avatar.setLipSyncValues([0.2, 0.8, 0.1])

播放音频并驱动口型

this.$refs.avatar.startLipSyncFromWav('/static/live2d/165 204/sounds/song.wav')
this.$refs.avatar.startLipSyncFromAudio('/static/live2d/165 204/sounds/song.wav')
this.$refs.avatar.stopLipSync()

startLipSyncFromWav(path) 会播放 WAV 并根据音频 RMS 驱动嘴部。startLipSyncFromAudio(path) 用当前平台音频能力播放并驱动口型。

只播放语音

this.$refs.avatar.playVoice('/static/live2d/165 204/sounds/song.wav', false)
this.$refs.avatar.stopVoice()

播放语音并驱动口型

this.$refs.avatar.playVoice('/static/live2d/165 204/sounds/song.wav', true)

语音相关事件：

<em-live2d
  @voiceStarted="onVoiceStarted"
  @voiceEnded="onVoiceEnded"
  @voiceError="onVoiceError"
/>

动作自带声音

如果 motion 条目包含 Sound，并且组件 enableMotionSound 为 true，播放该动作时会自动播放声音：

{
  "File": "motions/touch_01.motion3.json",
  "Sound": "sounds/haru_talk_13.wav"
}

Sound 路径相对于当前模型目录。

AI 实时语音输出

插件只负责 AI 语音输出的播放和口型驱动；用户麦克风采集、WebSocket、AI 协议由业务层或其他插件处理。

AI 服务返回 PCM16 音频流时，按下面流程推给 Live2D：

this.$refs.avatar.startRealtimeVoice(24000, 1, 'pcm16')
this.$refs.avatar.pushAudioChunk(base64Pcm16Chunk)
this.$refs.avatar.stopRealtimeVoice()

实时音频要求：

如果 AI 服务已经计算好音量或口型权重，可以直接驱动：

this.$refs.avatar.pushAudioLevel(0.65)
this.$refs.avatar.pushViseme('ParamMouthOpenY', 0.65)

触摸、拖拽和命中区域

this.$refs.avatar.setDrag(x, y)
this.$refs.avatar.tap(x, y)

命中区域通过 hitArea 事件返回：

<em-live2d @hitArea="onHitArea" />

onHitArea(event) {
  console.log('hit area', event.message)
}

获取模型信息

getModelInfo() 返回 JSON 字符串，可用于查看当前模型的动作组、表情、参数和命中区域：

const raw = this.$refs.avatar.getModelInfo()
const info = JSON.parse(raw)
console.log(info)

停止和释放

常见停止逻辑：

this.$refs.avatar.stopRealtimeVoice()
this.$refs.avatar.stopVoice()
this.$refs.avatar.stopLipSync()
this.$refs.avatar.stopAllMotions()
this.$refs.avatar.startRandomMotion('Idle', 1)

页面销毁时通常组件会跟随页面释放。需要主动释放时：

this.$refs.avatar.releaseLive2D()

方法总表

事件总表

事件 payload 通常包含：

{
  type: 'motionFinished',
  code: null,
  message: 'Dance'
}

不同事件的 message 可能是模型路径、动作组、音频路径、命中区域或错误描述。

常见问题

模型加载失败

检查：

• model 是否指向 .model3.json。
• /static/... 路径和真实文件名是否完全一致。
• .model3.json 引用的 .moc3、贴图、动作、表情文件是否存在。
• 模型目录或文件名有空格时，传入路径也必须完全一致。

动作无法播放

常见原因：

• .model3.json 没有对应 motion group。
• index 越界。
• motion 文件路径错误。
• 当前动作优先级更高。

可尝试：

this.$refs.avatar.stopAllMotions()
this.$refs.avatar.startMotion('Dance', 0, 3)

动作开始了但模型不动

动作文件里的参数 ID 必须存在于模型 .moc3。如果 motion 修改的是模型不存在的参数，动作会被播放，但视觉上不会变化。

嘴不动

检查 .model3.json 是否存在 Groups -> LipSync，并且包含当前模型实际嘴部参数，常见参数是 ParamMouthOpenY。

没声音

检查：

• 音频路径是否正确。
• voiceVolume 是否大于 0。
• 是否收到 voiceError。
• 当前平台是否支持该音频格式。
• 实时流是否为 PCM16 little-endian。

调试日志

Android 模型、动作、音频加载问题：

adb logcat -c
adb logcat -v time | grep -E "HylLive2D|NativePrint|model|moc|texture|motion|Live2D"

Android 崩溃和原生错误：

adb logcat -c
adb logcat -v time | grep -E "AndroidRuntime|FATAL|SIGSEGV|NativePrint|Live2D|HylLive2D|em_live2d"

iOS 可在 Xcode 的 Devices and Simulators -> Open Console 或 macOS Console 中按进程名、Bundle ID、EmLive2D、NativePrint 过滤日志。