前言：

大家好，我是灰（微博@天外灰仙儿，CSDN@overpara灰），今天给大家介绍一款免费开源的插件：GDCubism，它可以将live2D Cubism制作的live2d模型直接导入Godot4中，且支持最新的Godot4.3版本。本期教程就来大家从部署到插件的使用~如果你希望直接使用插件，不想自己部署的话，可以跳转到第二章并从评论区或者群文件下载部署好的插件。

一、部署

1. 下载插件源码

首先我们打开GDCubism插件所在的Github页面，直接搜MizunagiKB的库即可：

我们往下翻，在README中找到这个build，右键在新的页面里打开（因为一会儿还要用到当前页面）：

在这里有两个语言的版本，看你哪个语言比较熟练，下面我会以英文的页面进行教程：

首先第一步，是获取作者的源代码：

你可以直接按照作者给出的指令来下载源代码到本地，当然也可以直接下载压缩包：

我们注意到，有一个文件夹是蓝色的，意思是我们需要点击这个蓝色的名字（也就是链接）来跳转到另一个文件夹来下载，因为作者只是引用了这个文件夹的地址：

一样的，用指令码来clone或者直接点击下载zip“”

现在你的本地应该已经有了这两个压缩包，或者文件夹：

下一步，我们需要到live2d的官网：

跟着箭头一步步找到Cubism SDK for Native：

同样的，一次勾选同意协议、初次下载、个人下载、填入邮箱、下载最新版：

然后就会获得这个压缩包：

2. 组装源码

我们把刚才一共获得的三个压缩包都解压出来：

首先我们到godot-cpp里到这个地方把这些文件全选并复制：

然后粘贴到gd_cubism_main文件夹里的godot_cpp文件夹中：

接着我们在Cubism的SDK中找到这个地方：

选择这个↑箭头返回上一级，或者直接点击文件夹的名也可以：

复制这个文件夹，同时要确保这个文件夹里面就是散装文件了，不可以这个文件夹里还是一个单独的文件夹：

把这个文件夹直接粘贴到gd_cubism_main里的thirdparty文件夹：

确保这个文件夹层级关系符合规范：

3. 编译工具

接下来我们要下载编译用的工具（后面都以Windows系统为例）：

首先第一个VisualStudio Community在我的Unity教程里第一期有教怎么下载安装，这里就不赘述了，要确保版本至少在2019以上，当然你用其他可以编译c++的工具也可以。

如果你使用VS的话，安装时要勾选上这个使用C++的桌面开发（之前没勾选的话可以在 工具-获取工具和功能 里重新打开这个界面）：

接下来python的话直接从文档里的链接点进去，或者自己找到python的官网下载，3.8版本以上的即可：

安装完之后右键一下开始菜单，选择运行，输入cmd然后确定：

输入where python，如果显示出了python的位置代表安装成功：

我们再where pip，用来确保pip也安装成功，它是用来下载scons等插件的：

接着我们安装scons，首先我们看到插件作者说4.8版本的scons编译这个插件会有bug，建议我们暂时先使用4.7版本，并且给出了安装的指令（如果你已经安装了最新版的scons也可以用这个指令来转换成4.7版本）：

因为我已经安装过了，所以提示已经安装，如果你没装过应该是显示一个安装进度条：

安装完毕后也可以where scons，确保安装成功：

4. 编译并释放

下面我们来正式编译，我们来到gd_cubism-main的这个界面：

在地址栏直接输入cmd，然后回车：

确保这个位置已经变成了当前文件夹：

然后我们复制下来下面指令里的第一行：

右键点击一下就可以自动粘贴，然后按回车：

如果显示下面滚动的蓝字就代表正在编译了：

编译完成后，理论上来说就可以用了，如果为了保险起见，可以把第二行命令也执行一下（其实就是一个debug版一个release版，但是作者好像并没有说这两者的区别是什么）：

最后我们到bin文件夹中，就可以看到编译好的两个dll文件了，一个是debug版本，一个是release版本：

二、使用

1. 获取免费模型

在使用之前，我们先到live2d官网下载一个官方提供的模型，也可以用自己的，但是建议先用官方的跑一遍再用自己的，方便对比错误之类的：

下载解压后，也是找到散装文件的地方，点击箭头或者文件夹名来返回上级文件夹：

把这个文件夹整个复制下来（一定要注意这个文件夹里面就是散装的文件了，里面不可以是一个单独文件夹）：

把它整个粘贴到如图所示的文件夹里：

对应上官方给我们的层级关系：

不过放在这里仅仅是方便我们用官方给的示例场景，如果大家以后自己做游戏的话可以自己安排模型的位置~

2. 使用示例工程

下面我们使用Godot4.3来打开demo文件夹里的project.godot文件：

接下来我们打开如图所示位置的viewer.tscn场景：

然后运行场景，点击上方的黑条，就可以看到我们放进去的模型：

然后我们就可以显示模型，并可以调试动作和表情啦：

3. 创建模型

接下来我们新建一个场景，选择2D场景（其实都可以）：

给根节点改个名字，我就叫L2DTest了：

保存一下，保存在哪都行，我就新建一个Scenes文件夹了：

然后我们新建一个Sprite2D节点：

再在Sprite2D上新建一个GDCubismUserModel节点，也是插件给我们提供的节点：

然后场景中应该是这个关系的：

在UserModel的节点检查器里，我们可以看到Assets属性，点击旁边的按钮可以选择文件：

我们找到模型的文件夹，找到里面的model3.json文件，打开（这里这个模型在什么位置都可以，只有上一节的示例场景才需要把模型放到指定位置，这里模型我就直接放到项目的根目录了）：

可以看到我们的模型已经展示出来了：

然后我们选择Sprite2D节点，在检查器的Texture中，选择新建ViewportTexture：

找到我们刚新建的UserModel节点，然后点确定（这个过程中引擎会一直报错，不用管它，选择完就不会报错了）：

可以看到我们的模型也显示在场景里了：

如果你觉得角色的模型锯齿很多，可以在左下角的文件系统中找到模型的贴图文件，然后选择导入——Mipmap生成勾选上——重新导入：

我们通过调整Sprite2D节点的位置来把角色放到窗口范围里，同时我也调整了游戏窗口的尺寸：

这里尤其注意下，如果你想调整模型的大小，不可以直接修改Spite2D的大小，不然会非常模糊，在这里我们要修改UserModel节点的以下属性，主要是修改Size（要x和y一起改才会变大小），然后用adjust微调：

4. 呼吸和眨眼

接着我们给UserModel节点加上Breath和EyeBlink的节点，以启动呼吸和眨眼：

这是正确的节点关系：

UserModel节点检查器的参数，和Live2D里基本上是一一对应的，大家可以自行一项项研究一下，比如这里可以切换表情和动作：

并且每个子节点都可以通过勾选Active来选择是否生效（比如这个呼吸的节点）：

三、游戏相关

1. 运行时信号

接下来我们进行和游戏有关的部分，我们先给根节点新建一个脚本：

再给UserModel添加一个Custom节点：

这里我们可以看到Custom里有五个信号：

这五个信号其实挺迷的，我自己实验试了一下：

执行顺序是prologue-process-epilogue循环，在首次运行的时候会在第一个prologue后面执行term再执行init，之后是prologue-process-epilogue的无限循环。其实也就差不多是信号名字的字面意思。

不过手册上说term是当live2D停止渲染的时候才会发出这个信号，我试了一下确实在模型清空的时候会发出term，但是它连发了两个term。并且在游戏一开始就会发出一个term信号，这显然不符合我们的需求，所以建议大家暂时别用这个term信号，自己手动定义相关的信号吧！

2. 鼠标跟随

下面一个节点比较重要，TargetPoint，看名字也知道是设置鼠标跟随的：

我们添加这个节点后，可以右键它再选择“打开文档”，可以看到给我们准备好了一段示例代码，点代码右上角的复制标志：

粘贴到我们自己的代码里，可以看到报错了，这是因为我们没有定义pressed变量，先不急，我们把这段修改一下：

首先这个代码的逻辑是，当检测到输入事件时，先判断是不是点击事件，如果是点击事件的话就根据我们鼠标的移动来设置模型的跟随。

这里面对鼠标的坐标进行了一系列的运算，这是因为它最终是需要一个-1到1的数，也就是一个比例值：

那我们先在代码最上方定义一下pressed这个变量：

这段代码就正常了：

我们运行试一试，在按住鼠标左键时模型就可以跟随鼠标了：

当然这段代码的通用性不高，如果你后续对场景进行修改的话肯定会出问题，我带大家来修改一下，首先我们右键场景里UserModel节点和TargetPoint节点，设置为唯一名称：

出现这两个百分号就对了：

然后拖拽到代码里：

同理Sprite2D也这么干，设置为唯一名称再拖拽，当然如果你有多个模型或者多个Sprite2D的话最好给节点改个名字，因为我就一个模型所以就不管了：

这些绿色的地址，都换成我们已经拖拽进来的变量：

修改后：

运行一下应该也是没问题的，如果你不希望鼠标按住才跟随的话就把相关的判断都删了：

3. 触发动作

最后我们来学习一下怎么换动作（motions），换表情也是同理，首先在UserModel的文档里找到get_motions方法的示例代码：

粘贴到我们自己的代码里，这里我设置成点击左键就获取所有的动作（跟过桌宠教程的友友应该很熟悉这个操作了）：

运行后左键点击一下，就可以打印出下列信息，其中group就是动作的分组，no就是动作的编号，可以看到官方的模型就编了两个组，一个是Idle组，另一个没有起名字：

这个编组应该是在Live2D里就编好的，我们拿到一个模型时首先就要这样获取一下都有什么组。

我们在手册里，可以看到start_motion方法，它需要三个参数，第一个就是组名，第二个是编号，第三个是优先级：

前两个我们都知道是干嘛的了，我们来看优先级是啥：

从名字可以看出来，FORCE的优先级是最高的，NONE最低（实际上，NONE优先级的命令压根不会被执行），当发出多个执行动作的命令时，只会执行优先级最高的命令，如果优先级相同的话则只执行先收到的命令（FORCE除外）。

其中，只有FORCE可以打断正在执行的动作，也就是说，IDLE和NORMAL优先级之所以只会执行先收到的命令是因为它们不能打断已经执行的动作。

那么接下来我希望鼠标点击后执行无名组的第五个动作，那就一个参数只填一个双引号，第二个参数是5，第三个参数写FORCE：

运行一下，是可以正常执行的，如果你觉得动画的速度太慢，可以改变UserModel的SpeedScale：

然后，我们注意一下，UserModel节点有两个信号，第一个信号motion_event包含了正在执行的动作的信息，第二个motion_finished则表示动作完成：

我们可以通过等待信号的方式，连续播放两个动作：

四、总结

好啦，掌握了这些功能，这个插件基本已经可以满足live2d在Godot中的开发啦，如果想深入了解一些节点和功能也可以去阅读插件作者的手册，但是很多内容他们写的不是很详细，都要自己去一个个试（比如播放动作的优先级就是我一个一个试出来的）。

另外还有一个很重要的功能就是鼠标点击和模型互动，虽然这个插件也自带一个HitArea节点，但是貌似并没有什么用，Live2D本身也不自带原生的鼠标点击反馈功能，所以我还是推荐大家用Godot的Area2D功能来制作吧~

最后，大家自己做项目的话，直接把addons文件夹整个复制到你的项目根目录就可以：