Build

How to build

Get source code

First, please clone gd_cubism using git.

You can use the latest version as is. If you want to try out any feature extensions or bug fixes, please switch branches as appropriate.

git clone https://github.com/MizunagiKB/gd_cubism.git
cd gd_cubism
git submodule update --init

Preparation of CubismSdkForNative

Next, please obtain the SDK necessary for building from the Live2D official website.

Cubism SDK for Native includes the Cubism Native Framework in addition to the Cusism SDK.

Please extract the downloaded files so that they follow the folder structure below. (If you place the downloaded files in the thirdparty folder and extract them, they should take this form)

./thirdparty
└── CubismSdkForNative-5-r.1
     ├── CHANGELOG.md
     ├── Core
     │   ├── CHANGELOG.md
     │   ├── LICENSE.md
     │   ├── README.ja.md
     │   ├── README.md
     │   ├── RedistributableFiles.txt
     │   ├── dll
     │   ├── include
     │   └── lib
     ├── Framework
     │   ├── CHANGELOG.md
     │   ├── CMakeLists.txt
     │   ├── LICENSE.md
     │   ├── README.ja.md
     │   ├── README.md
     │   ├── TRANSLATION.md
     │   └── src
     ├── LICENSE.md
     ├── NOTICE.ja.md
     ├── NOTICE.md
     ├── README.ja.md
     ├── README.md
     ├── Samples
     │   ├── Cocos2d-x
     │   ├── D3D11
     │   ├── D3D9
     │   ├── Metal
     │   ├── OpenGL
     │   ├── Resources
     │   └── Vulkan
     ├── cubism-info.yml
     ├── logor.png
     └── logos.png

Bug Resolution

Depending on the version and environment of the Godot Engine, a bug causing memory leaks in the non-display state of the Window has been observed.

This bug occurs when using the Vulkan renderer in Forward+, mobile, and although some issues have been addressed, it has not been resolved in the macOS environment.

To address this issue, we have made it possible to specify COUNTERMEASURES_90017_90030 during scons execution.

COUNTERMEASURES_90017_90030=1 (default)

Does not call the rendering process of the Live2D model when the Window is in non-display state.

COUNTERMEASURES_90017_90030=0

Calls the rendering process of the Live2D model regardless of the display state of the Window.

For details on the bug, please refer to the following issues:

Differences in Behavior with CubismEditor

GDCubism, which internally uses CubismNativeFramework, is designed to be able to play Live2D models created with Cubism Editor. However, differences may arise in drawing priority and motion.

The Cubism SDK for Native’s documentation contains differences in operation with Cubism Editor and tips for data creation.

The content of the document is mainly for Unity and Cubism SDK for Native, and there are places where it cannot be used as is, but please refer to it.

Cubism Editor 5
Cubism Editor 5 / Platform Comparison

Customizing CubismNativeFramework

GDCubism uses CubismNativeFramework, which is included in CubismSdkForNative. If you want to use the latest Framework or customize it for your own needs, you can do so by following these steps:

pushd thirdparty
git clone https://github.com/Live2D/CubismNativeFramework.git
popd
This build has priority over the Framework in CubismSdkForNative, so please delete it when it is no longer needed.

Build for Windows

The following items are required for building:

There have been reports that using SCons 4.8 results in build failures.

This issue lies with the Godot Engine and is expected to be resolved in future versions.

For now, please use SCons 4.7.

# You can address this by specifying the version when installing scons.
# If a version higher than 4.8 is installed, you can use this method to revert to 4.7.
pip install scons==4.7
Installing Visual Studio caveats

If installing Visual Studio, make sure to enable C++ in the list of workflows to install.

If you’ve already made the mistake of installing Visual Studio without C++ support, run the installer again; it should present you a Modify button. Running the installer from Add/Remove Programs will only give you a Repair option, which won’t let you install C++ tools.

Godot Engine 4.1 documentation

When ready, run the build with the following command.

scons platform=windows vsproj=yes arch=x86_64 target=template_debug
scons platform=windows vsproj=yes arch=x86_64 target=template_release

When the build is completed, the following files will be generated under demo/addons/gd_cubism/bin.

  • libgd_cubism.windows.debug.x86_64.dll

  • libgd_cubism.windows.release.x86_64.dll

Build for macOS

The following items are required for building:

There have been reports that using SCons 4.8 results in build failures.

This issue lies with the Godot Engine and is expected to be resolved in future versions.

For now, please use SCons 4.7.

# You can address this by specifying the version when installing scons.
# If a version higher than 4.8 is installed, you can use this method to revert to 4.7.
pip install scons==4.7

When ready, run the build with the following command.

# for x86_64(intel mac)
scons platform=macos arch=x86_64 target=template_debug
scons platform=macos arch=x86_64 target=template_release
# for arm64(Apple Silicon mac)
scons platform=macos arch=arm64 target=template_debug
scons platform=macos arch=arm64 target=template_release

When the build is completed, the following files will be generated under demo/addons/gd_cubism/bin.

  • libgd_cubism.macos.debug.framework

  • libgd_cubism.macos.release.framework

Building as a universal binary

If you want to build as a universal binary, you need to create link files as follows before running scons.

pushd thirdparty/CubismSdkForNative-5-r.1/Core/lib/macos
mkdir universal
lipo -create arm64/libLive2DCubismCore.a x86_64/libLive2DCubismCore.a -output universal/libLive2DCubismCore.a
popd

# for universal
scons platform=macos arch=universal target=template_debug
scons platform=macos arch=universal target=template_release

Build for Linux

The following items are required for building:

For Linux, additional packages may be required for each distribution. Please refer to the Godot Engine documentation to find out what distributions require. (I checked on Ubuntu 22.04 Desktop)

When ready, run the build with the following command.

scons platform=linux arch=x86_64 target=template_debug
scons platform=linux arch=x86_64 target=template_release

When the build is completed, the following files will be generated under demo/addons/gd_cubism/bin.

  • libgd_cubism.linux.debug.x86_64.so

  • libgd_cubism.linux.release.x86_64.so

Build for Others

The following two have only been verified to be buildable, and have not been tested for operation.

Please use them as a reference when trying to run them in each environment.

Build for iOS

The following items are required for building:

In cases where Xcode is used only from the command line, there may be instances where the build for iphoneos does not start.

In such cases, you can get the build to proceed by re-specifying the path to Xcode as follows:

sudo xcode-select --switch /Applications/Xcode.app

When ready, run the build with the following command.

# for arm64
scons platform=ios arch=arm64 target=template_debug
scons platform=ios arch=arm64 target=template_release
# for universol
scons platform=ios arch=universal target=template_debug
scons platform=ios arch=universal target=template_release

When the build is completed, the following files will be generated under demo/addons/gd_cubism/bin.

  • libgd_cubism.ios.debug.arm64.dylib

  • libgd_cubism.ios.release.arm64.dylib

  • libgd_cubism.ios.debug.universal.dylib

  • libgd_cubism.ios.release.universal.dylib

Build for Android

The following items are required for building:

Assuming that you have installed Android Studio on a Windows 10 environment, follow these steps:

Launch Android Studio and open the SDK Manager. You can access the SDK Manager from the More Actions menu on the Welcome to Android Studio screen that appears when you start Android Studio.

Once the SDK Manager is open, check the following items and download them.

  • SDK Platforms

    • Android API 34

    • Android 10("Q")

  • SDK Tools

    • Android SDK Build-Tools 34

    • NDK (Side by side)

    • Android SDK Command-line Tools (latest)

    • CMake

    • Android Emulator

    • Android SDK Platform-Tools

    • Android SDK Tools (Obsolete)

When ready, run the build with the following command.

scons platform=android target=template_debug arch=armv7
scons platform=android target=template_release arch=armv7
scons platform=android target=template_debug arch=arm64v8
scons platform=android target=template_release arch=arm64v8

If the build does not start, try setting the following environment variables:

  • ANDROID_SDK_ROOT …​ The location where the items selected by the SDK Manager are installed

  • ANDROID_HOME …​ The location where the items selected by the SDK Manager are installed

  • ANDROID_NDK_HOME …​ The location where the NDK installed by the SDK Manager is located

  • ANDROID_NDK_ROOT …​ The location where the NDK installed by the SDK Manager is located

example
set ANDROID_SDK_ROOT=D:\Android\sdk
set ANDROID_HOME=D:\Android\sdk
set ANDROID_NDK_HOME=%ANDROID_SDK_ROOT%\ndk\26.0.10792818
set ANDROID_NDK_ROOT=%ANDROID_SDK_ROOT%\ndk\26.0.10792818

When the build is completed, the following files will be generated under demo/addons/gd_cubism/bin.

  • libgd_cubism.android.debug.arm32.so

  • libgd_cubism.android.release.arm32.so

  • libgd_cubism.android.debug.arm64.so

  • libgd_cubism.android.release.arm64.so