如何使用 Live2D Cubism Native SDK：從下載到 iOS App

an iOS simulator that runs the Live2D Native demo app. 圖. 在 iOS 模擬器上運行 Live2D Demo App。

amiverse 在 iOS 模擬器跑不起來

自從 iPhone Duo 上市以後，App Store Connect 開始警告宣導你各位開發者，要加上 app 在 iPhone Duo 上的螢幕截圖。由於手邊沒有實體機器，小編我最近又重新研究了如何讓 amiverse 在 iOS 模擬器中執行。藉此機會，這篇文章大概分享一下如何使用 Live2D Cubism SDK for Native 與其官方範例，製作能在 iOS 模擬器中運行的 Live2D app 🧑‍💻。

Live2D Cubism Core（Live2D 的閉源核心程式庫）針對 iOS 實體機與模擬器分別提供了不同版本，對應 SDK 中的 iphoneos 與 iphonesimulator。目前 amiverse 專案只引用了實體機版本的程式庫，專案的建置設定也是以此為基礎來堆疊，因此無法直接編譯給 iOS 模擬器執行。

amiverse 的程式基礎，是小編我早期從零開始學習 iOS 開發時建立的。當時小編先研究 Live2D Cubism SDK 內的 iOS 範例，再手動重建 Xcode 專案、挑選需要的程式檔案，最後包裝成 SwiftUI 程式。因為是邊做邊學，整個專案累積了不少雜亂的設定。加上當時同時要處理 Objective-C、C++ 與 Swift 三種程式語言之間的整合，Xcode 專案不斷出現警告與編譯失敗。最後考量到時程與個人能力，小編就放棄了模擬器版本，專心用 Live2D Cubism Core 的 iphoneos 程式庫，完全依賴實體 iPhone 開發。到現在，這完全變成了技術債。為了節省經費，不買 iPhone Duo，只好花點心力回頭整理 🫠。

學習目標

這篇主要目標是把官方範例成功跑起來，不是把 Cubism SDK 當成一個套件拖進 Swift 專案就結束。Native SDK 裡有 C++ Framework、平台專用的 Core 函式庫和 Metal 繪圖程式；官方 iOS 範例也用 CMake 產生 Xcode 專案。先跑通範例，之後要整合到自己的 app 才比較知道問題出在哪裡。

下載 Live2D Cubism SDK 並認識其組成元件。
透過官方範例建置 Xcode 專案並在 iOS 模擬器上運行。
討論未來要基於該範例持續開發時的幾個考量。

如何建置並運行官方 iOS 範例

步驟 1. 下載並認識 Live2D Cubism SDK

Live2D Cubism SDK 的各個版本都可以在官方網站找到。要下載 SDK：

開啟這個頁面後，點選 "Download Cubism SDK for Native" 的按鈕。
閱讀並接受授權跟使用條款後，點選 "Download for the first time" (第一次下載)。
輸入你的 email 就可以點選下載。
如果前一步選了 "Download for update"，他就不會叫你輸入 email，可以直接下載。這裡就依據你的狀況來選擇。

ℹ️ 如果希望販售你的成品，請詳讀 Software License Agreement (軟體授權協議) 以及 SDK Release License (Publication License Agreement) (發行授權協議)。確定自己的產品有在許可發行的範圍裡。

Cubism SDK for Native (Native SDK) 主要以 C++ 構成，用於製作跨平台的 Live2D 應用程式。Native SDK 需要開發人員用撰寫程式碼的方式來設計功能與畫面。如果你想用可以看見畫面的方式來設計功能和畫面，Cubism SDK for Unity (Unity SDK) 可能才是正確的選擇。Unity SDK 可以讓開發人員透過 Unity 遊戲引擎與編輯器引用 Live2D 相關功能，並透過拖拉等比較直覺的途徑來製作應用程式。此外，如果本來就有使用 Unity，還可以使用 Unity 素材庫以及其他遊戲多媒體素材來幫忙開發。如果在選擇上有困難，可以參考官方文件的流程圖 (Unity? Native? SDK Selection Flowchart) 看看怎麼選。

ℹ️ 小編個人是覺得，如果希望做到跨平台跟方便編輯，選 Unity SDK 就好了。

下載後，會得到一個 zip 檔案 (如 CubismSdkForNative-5-r.5)。解壓縮後可以看到像這樣的內容：

.
├── Core
│   ├── dll
│   ├── include
│   └── lib
├── Framework
│   └── src
└── Samples
    ├── Common
    ├── D3D11
    ├── D3D9
    ├── Metal
    │   ├── Demo
    │   └── thirdParty
    ├── OpenGL
    ├── Resources
    └── Vulkan

資料夾的結構基本上分成三個部分：Core, Framework, 以及 Samples。這三塊對應到 Cubism 應用程式的構成方式：

Core: Live2D 的閉源核心程式庫，負責 .moc3 模型檔案解析、頂點運算、不透明運算等
Framework: C++ 寫成的開源框架，負責模型檔案外的資料解析與處理、動作與物理運算等。
Application：串起上述兩者，負責運行和 GPU 繪圖的程式。不同平台或 GPU 程式有不同的寫法，如 Windows 上的 Direct3D、iOS 上的 Metal、或跨平台的 Vulkan。

Cubism Core API. Adapted from live2d.com 圖. Cubism Core API 關係圖。取自 Cubism Core API Reference。

步驟 2. 產生 Xcode 專案

這篇教學裡我們用基於 Metal 的官方的範例。你可以在 Samples/Metal 資料夾裡找到範例程式碼。首先，請先安裝 Xcode，並確認 Xcode Command Line Tools 已完成設定。這個範例還需要 CMake；若你使用 Homebrew，可以在 Terminal 執行：

brew install cmake

官方的 Metal 範例使用 ios-cmake 產生 iOS 專案。Samples 已附上安裝腳本，在專案根目錄執行：

./Samples/Metal/thirdParty/scripts/setup_ios_cmake

ℹ️ 這個腳本基本上就是去 GitHub 把特定版本的 ios-cmake 下載下來。也可以自己到 GitHub leetal/ios-cmake 下載、解壓縮、重新命名成 ios-cmake 後放到 ./Samples/Metal/thirdParty。

有了 cmake 和 ios-cmake 後，執行範例中的 Xcode 專案產生腳本：

./Samples/Metal/Demo/proj.ios.cmake/scripts/proj_xcode

你的 terminal 會列出平台選項:

1) iphoneOS (arm64)             3) iphoneOS Simulator (x86_64)
2) iphoneOS Simulator (arm64)   4) Mac Catalyst
Select the platform number to use: 2

要在 iPhone 或 iPad 實機執行，選 iphoneOS (arm64)；要在模擬器執行，Apple Silicon Mac 通常選 iphoneOS Simulator (arm64)，Intel Mac 則選 iphoneOS Simulator (x86_64)。

腳本完成後，Xcode 專案會產生在 Samples/Metal/Demo/proj.ios.cmake/build/ 底下，資料夾名稱會依你選的平台而略有不同。

ℹ️ 如果跑 proj_xcode 的時候噴出像這樣的錯誤: "error: The iOS Simulator deployment target 'IPHONEOS_DEPLOYMENT_TARGET' is set to 13.0, but the range of supported deployment target versions is 15.0 to 27.2.x."，可以試試這個做法：

到 leetal/ios-cmake 下載 ios-cmake 4.6.1。
解壓縮後，移動資料夾到 ./Samples/Metal/thirdParty/ios-cmake。
刪除前一次殘留的檔案 Samples/Metal/Demo/proj.ios.cmake/build。
再跑一次 proj_xcode。

資料夾的結構供參：

Samples/Metal
├── Demo
│   └── proj.ios.cmake
│       ├── CMakeLists.txt
│       ├── build             // 跑 proj_xcode 前全部刪掉
│       ├── scripts
│       └── src
└── thirdParty
  ├── ios-cmake               // 下載回來的 ios-cmake
  │   ├── LICENSE.md
  │   ├── README.md
  │   ├── example
  │   └── ios.toolchain.cmake
  ├── scripts
  │   └── setup_ios_cmake
  └── stb

小編個人測試中，從 GitHub 下載回來的 ios-cmake 4.6 可以成功，但是用 setup_ios_cmake 下載回來的會失敗。給有需要的同學參考看看。

步驟 3. 在 Xcode 編譯並運行程式

找到剛產生的 Demo.xcodeproj (如 .../build/proj_xcode_iphonesimulator_arm64/Demo.xcodeproj):

用 Xcode 打開 Demo.xcodeproj
上方選擇 Demo scheme，再選擇要使用的 iOS 模擬器，如 iPhone Duo
選好執行目標後，按下 Run（或使用 ⌘R）
官方範例附有可切換的示範模型；若模型能正常顯示並播放動作，代表 Xcode 專案、Core、Framework 與 Metal 範例已經串起來了。

Xcode and iOS Simulator that runs the demo app 圖. Xcode 設定與 iOS 模擬器運行 Live2D Native Demo App。

要繼續開發時的考量: 清理 Xcode 專案並打包成 SwiftUI

官方範例的範例很適合來確認會不會動。但要把它直接拿來當成你的 app 基礎，有滿多管理問題的...

資源載入的路徑

範例預設從固定的 Resources 位置讀檔。整合進自己的 app 後，要確認模型檔案實際被包進 Bundle (或是從其他地方下載)，並讓載入程式使用正確的路徑。如果你的角色是動態下載或可更換的，這部分一開始就要設計好。

CMake 產生的 Xcode 專案是產物，不是原始碼的一部分

Demo.xcodeproj 是腳本產生的。你在裡面改的設定，下次重跑 proj_xcode 就會被洗掉。此外，這個 Demo 專案有很多從 CMake 設定出來的內容，在 Xcode 裡面非常難維護（例如，小編自己測試，常常設定按一按就當機）。

為了後續開發方便維護，小編自己的做法是參考 Demo 專案的設定跟組成，重新把 Core、Framework、和 App 的範例程式碼整理成習慣的結構。此外，小編也重新建立 Xcode 專案，只留下需要的內容。

同學也是可以考慮直接維護現有的 CMake 內容。雖然建置的流程和 Xcode 專案設定會混在一起，但就不需要從頭研究怎麼搞 Xcode。

用 Swift 橋接，隔開 C++ 與 Objective-C

小編相信現在才學 iOS 程式開發的同學應該都是用 Swift 與 SwiftUI。除非有什麼特殊的需求，否則對傳統 Obj-C/UIKit 的 app 流程，或者 C++ 相關程式碼，可能不是這麼熟悉。

目前 Native SDK 給的範例程式碼是使用傳統的 ObjC + UIKit 的結構來寫的。若要讓後續開發更容易，同學可以考慮寫一個橋接介面，包裝 Live2D 的 view controller，再透過 Swift 設定跟呼叫。此外，也可以把高階的模型操作，如載入模型、播放動作、套用表情等重新用 Swift 寫過，方便未來的模型操作，也避免碰到 Cubism Framework 那些 C++ 程式碼。這樣未來 Live2D 的底層要升級或調整時，影響範圍可以被控制住。

不過這件事情，說起來容易，做起來卻很多麻煩的地方。未來有機會再和同學分享 amiverse 是怎麼做的 🫠。

結語

使用 Cubism Native SDK 的第一步，是先把各種亂七八糟的程式碼整理好。先用官方的範例確認真的會動，加入自己的模型試試看，最後再想辦法整理成比較好寫的 SwiftUI。回頭看 amiverse 當初的開發方式，除非同學對 iOS 原生 UI 情有獨鍾，否則小編覺得新 app 直接考慮用 Cubism Unity SDK 可能是更快的作法，對美術也比較友善 🤪。

總得來說，希望這篇整理能讓同樣在摸索 Live2D 與 iOS 的開發者少踩幾個坑。如果你也在用 Cubism Native SDK 開發 iOS app，或是在建置的過程中遇到奇怪的問題，歡迎透過 Threads / 脆和我們交流。也歡迎到 App Store 下載 amiverse app 玩玩看，看看這些技術債背後的成果。

感恩感恩。