戰(zhàn)：從環(huán)境配置到運(yùn)行調(diào)試的完整避坑指南)
1. 為什么我要自己編譯 ArmorPaintArmorPaint 這個(gè)軟件圈內(nèi)人應(yīng)該不陌生。它是一個(gè)開(kāi)源的 3D 模型紋理繪制工具主打 PBR 材質(zhì)繪制支持直接在模型表面畫(huà)貼圖功能上對(duì)標(biāo) Substance Painter 那一類商業(yè)軟件。官方提供的是付費(fèi)下載的預(yù)編譯版本源碼托管在公開(kāi)倉(cāng)庫(kù)里采用比較特殊的授權(quán)模式——源碼開(kāi)放但官方編譯好的二進(jìn)制包需要付費(fèi)購(gòu)買。這就意味著如果你不想花錢(qián)或者想自己改點(diǎn)東西那就得自己從源碼編譯。我最初接觸 ArmorPaint 是因?yàn)榻恿艘粋€(gè)獨(dú)立游戲的外包需要給一批低模角色畫(huà)手繪風(fēng)格的貼圖。Substance Painter 的訂閱費(fèi)對(duì)我來(lái)說(shuō)有點(diǎn)肉疼Blender 自帶的紋理繪制功能又太基礎(chǔ)圖層混合和筆刷系統(tǒng)都不夠用。找了一圈ArmorPaint 是最合適的選擇。但官方編譯版要花錢(qián)而且我后來(lái)發(fā)現(xiàn)官方版本在某些 Linux 發(fā)行版上跑起來(lái)有問(wèn)題顯卡驅(qū)動(dòng)兼容性也不太好。于是我就動(dòng)了自己編譯的念頭。這一編譯就踩了整整三天的坑。從環(huán)境配置到依賴?yán)木幾g報(bào)錯(cuò)到運(yùn)行閃退幾乎每個(gè)環(huán)節(jié)都卡過(guò)我。網(wǎng)上關(guān)于 ArmorPaint 編譯的中文資料少得可憐官方文檔寫(xiě)得也比較簡(jiǎn)略很多細(xì)節(jié)要靠自己摸索。所以我把整個(gè)編譯過(guò)程整理出來(lái)包括我遇到的所有問(wèn)題和解決方案希望能幫到后面想自己編譯的朋友。這篇文章適合幾類人一是想白嫖 ArmorPaint 但不想付費(fèi)的開(kāi)發(fā)者二是需要在特定平臺(tái)上運(yùn)行 ArmorPaint 的用戶比如某些 Linux 發(fā)行版或者老版本的 Windows三是想自己修改源碼、定制功能的進(jìn)階玩家。如果你只是想在 Windows 上隨便用用那直接買官方版可能更省事。但如果你有編譯需求或者想深入了解這個(gè)軟件的架構(gòu)那這篇內(nèi)容應(yīng)該能幫你省下不少時(shí)間。2. 編譯前的環(huán)境準(zhǔn)備與工具選型2.1 硬件與操作系統(tǒng)的選擇ArmorPaint 的編譯對(duì)硬件要求不算特別高但也不是隨便一臺(tái)機(jī)器就能跑。我實(shí)測(cè)下來(lái)編譯過(guò)程主要吃 CPU 和內(nèi)存顯卡反而不是編譯階段的瓶頸。我的主力機(jī)是 AMD Ryzen 7 5800X32GB 內(nèi)存編譯一次大概需要 8 到 12 分鐘。如果你用的是筆記本低壓 U比如 i5-10210U 這種編譯時(shí)間可能會(huì)拉長(zhǎng)到 20 分鐘以上而且內(nèi)存如果只有 8GB大概率會(huì)在鏈接階段爆內(nèi)存。操作系統(tǒng)方面官方主要支持 Windows、Linux 和 macOS。我三個(gè)平臺(tái)都試過(guò)Windows 上編譯最省心因?yàn)楣俜教峁┝祟A(yù)編譯的依賴庫(kù)Linux 上最折騰不同發(fā)行版的包管理器和庫(kù)版本差異很大macOS 上介于兩者之間但 Xcode 的版本兼容性需要注意。如果你只是想快速得到一個(gè)可用的編譯版我建議在 Windows 上操作用 Visual Studio 2022 作為編譯工具鏈。具體來(lái)說(shuō)Windows 10 或 Windows 11 都可以但要注意系統(tǒng)版本不能太老。我試過(guò)在 Windows 8.1 上編譯結(jié)果因?yàn)槿鄙倌承┫到y(tǒng) API 導(dǎo)致編譯失敗。Linux 方面Ubuntu 20.04 和 22.04 是比較穩(wěn)妥的選擇Arch 系雖然包新但滾動(dòng)更新容易導(dǎo)致依賴版本對(duì)不上。macOS 建議用 12 以上的版本Xcode 命令行工具要裝好。2.2 編譯工具鏈的安裝與配置ArmorPaint 是用 Haxe 語(yǔ)言寫(xiě)的然后通過(guò) Kha 框架跨平臺(tái)編譯。所以你需要的不只是 C 編譯器還要裝 Haxe 工具鏈和 Kha 的相關(guān)依賴。這是很多人第一次編譯時(shí)最容易懵的地方——以為是個(gè)普通的 C 項(xiàng)目結(jié)果發(fā)現(xiàn)構(gòu)建系統(tǒng)完全不是那回事。首先說(shuō) Haxe。你需要去 Haxe 官網(wǎng)下載對(duì)應(yīng)平臺(tái)的安裝包版本建議用 4.2.5 或 4.3.0太新的版本有時(shí)候會(huì)和 Kha 的某些庫(kù)不兼容。安裝完之后打開(kāi)終端或命令行輸入haxe -version確認(rèn)安裝成功。然后需要安裝 Haxelib這是 Haxe 的包管理器類似 Node.js 的 npm 或者 Python 的 pip。裝好 Haxelib 之后你需要通過(guò)它安裝 Kha 框架。Kha 的安裝命令是haxelib install kha但這里有個(gè)坑——Kha 的版本更新很快而 ArmorPaint 的源碼可能只兼容特定版本的 Kha。我建議先去看 ArmorPaint 源碼根目錄下的khafile.js或者h(yuǎn)axelib.json里面會(huì)寫(xiě)明依賴的 Kha 版本。如果沒(méi)有寫(xiě)明那就用haxelib install kha裝最新版然后祈禱能編譯通過(guò)。我試過(guò)用 Kha 的最新版編譯 ArmorPaint 0.9 的源碼結(jié)果報(bào)了一堆 API 不兼容的錯(cuò)誤后來(lái)回退到 Kha 22.10 才搞定。除了 Haxe 和 Kha你還需要一個(gè) C 編譯器。Windows 上用 Visual Studio 2022 的 MSVC 工具鏈安裝的時(shí)候記得勾選“使用 C 的桌面開(kāi)發(fā)”工作負(fù)載。Linux 上用 GCC 或 Clang 都行但要注意版本GCC 9 以上比較穩(wěn)妥。macOS 上用 Xcode 自帶的 Clang。另外Git 也是必須的因?yàn)槟阈枰獜膫}(cāng)庫(kù)拉取源碼和子模塊。2.3 依賴庫(kù)的拉取與版本管理ArmorPaint 的依賴庫(kù)不少包括但不限于SDL2、OpenGL 或 Vulkan 的 SDK、各種圖像編解碼庫(kù)如 stb_image、物理引擎如 Bullet 或 ODE用于某些碰撞檢測(cè)功能。這些依賴大部分可以通過(guò) Kha 的構(gòu)建系統(tǒng)自動(dòng)拉取但有些需要你手動(dòng)安裝。在 Windows 上Kha 會(huì)自動(dòng)下載預(yù)編譯的依賴庫(kù)你基本不用操心。但在 Linux 上你需要通過(guò)包管理器安裝一些系統(tǒng)級(jí)的庫(kù)比如libsdl2-dev、libgl1-mesa-dev、libopenal-dev等等。具體缺哪些編譯報(bào)錯(cuò)的時(shí)候會(huì)告訴你。我建議在 Ubuntu 上先把這一串裝上sudo apt-get install libsdl2-dev libgl1-mesa-dev libopenal-dev libx11-dev libxext-dev libxrandr-dev libxi-dev libxcursor-dev libxinerama-dev libasound2-dev libpulse-devmacOS 上相對(duì)簡(jiǎn)單大部分庫(kù)系統(tǒng)自帶但你可能需要裝 SDL2 和 OpenAL。用 Homebrew 裝就行brew install sdl2 openal-soft。這里有個(gè)經(jīng)驗(yàn)依賴庫(kù)的版本不要盲目追新。我試過(guò)在 Ubuntu 22.04 上用系統(tǒng)自帶的 SDL2 2.26結(jié)果編譯出來(lái)的 ArmorPaint 運(yùn)行時(shí)報(bào)錯(cuò)說(shuō)某個(gè)符號(hào)找不到。后來(lái)?yè)Q成 SDL2 2.0.20 的源碼自己編譯安裝問(wèn)題就解決了。所以如果你在 Linux 上遇到奇怪的鏈接錯(cuò)誤先檢查一下依賴庫(kù)的版本。3. 源碼獲取與編譯參數(shù)詳解3.1 從倉(cāng)庫(kù)拉取源碼的正確姿勢(shì)ArmorPaint 的源碼托管在 GitHub 上倉(cāng)庫(kù)地址是https://github.com/armory3d/armorpaint。但你不能直接git clone就完事因?yàn)樗昧俗幽Ksubmodule。如果你直接 clone 主倉(cāng)庫(kù)很多依賴目錄是空的編譯的時(shí)候會(huì)報(bào)找不到文件。正確的做法是git clone --recursive https://github.com/armory3d/armorpaint.git如果你已經(jīng) clone 了但忘了加--recursive可以進(jìn)入目錄后執(zhí)行g(shù)it submodule update --init --recursive這一步會(huì)拉取 Kha、Iron、Armory 等子模塊。網(wǎng)絡(luò)狀況不好的話可能會(huì)卡住或者失敗。我建議在拉取之前先配置一下 Git 的代理或者用國(guó)內(nèi)的一些鏡像源。不過(guò)要注意子模塊的版本必須和主倉(cāng)庫(kù)的 commit 對(duì)應(yīng)不要手動(dòng)去改子模塊的版本否則編譯大概率出問(wèn)題。拉取完成后檢查一下目錄結(jié)構(gòu)。根目錄下應(yīng)該有Sources、Assets、Kha、Libraries等文件夾。如果Kha文件夾是空的說(shuō)明子模塊沒(méi)拉下來(lái)需要重新執(zhí)行上面的命令。3.2 編譯目標(biāo)平臺(tái)與架構(gòu)的選擇ArmorPaint 支持編譯到多個(gè)平臺(tái)Windows、Linux、macOS、Android、HTML5 等。但不同平臺(tái)的編譯流程和依賴差異很大。我主要關(guān)注桌面端所以這里只講 Windows、Linux 和 macOS 的編譯。在編譯之前你需要確定目標(biāo)架構(gòu)。Windows 上一般是 x64Linux 上也是 x64macOS 上現(xiàn)在有 x64 和 arm64Apple Silicon兩種。如果你用的是 M1 或 M2 的 Mac編譯的時(shí)候需要指定 arm64 架構(gòu)否則編譯出來(lái)的程序在 Rosetta 下跑性能會(huì)打折扣。Kha 的構(gòu)建系統(tǒng)通過(guò)khafile.js來(lái)配置編譯目標(biāo)。你可以在根目錄下找到這個(gè)文件里面有一行l(wèi)et target ...默認(rèn)可能是windows或linux。如果你想編譯到其他平臺(tái)需要修改這個(gè)變量。不過(guò)更推薦的方式是通過(guò)命令行參數(shù)來(lái)指定比如node Kha/make.js --target windows --arch x64這樣不會(huì)污染源碼文件也方便切換。3.3 關(guān)鍵編譯參數(shù)的解讀與設(shè)置Kha 的構(gòu)建系統(tǒng)提供了一系列參數(shù)常用的有--target指定目標(biāo)平臺(tái)如windows、linux、macos、android、html5。--arch指定架構(gòu)如x64、arm64、x86。--debug編譯 Debug 版本包含調(diào)試符號(hào)運(yùn)行速度慢但方便排查問(wèn)題。--release編譯 Release 版本開(kāi)啟優(yōu)化運(yùn)行速度快但調(diào)試信息少。--graphics指定圖形 API如opengl、vulkan、direct3d11。這個(gè)參數(shù)很關(guān)鍵選錯(cuò)了可能導(dǎo)致程序無(wú)法啟動(dòng)。我一般先用 Debug 模式編譯一次確認(rèn)能跑起來(lái)再用 Release 模式編譯最終版本。圖形 API 方面Windows 上推薦direct3d11或openglLinux 上推薦opengl或vulkanmacOS 上只能用opengl或metal但 Kha 對(duì) Metal 的支持不太完善建議用 OpenGL。還有一個(gè)參數(shù)是--kha用來(lái)指定 Kha 的路徑。如果你把 Kha 放在非標(biāo)準(zhǔn)位置需要手動(dòng)指定。一般情況下不用管構(gòu)建腳本會(huì)自動(dòng)找到。編譯命令的完整形式大概是這樣的node Kha/make.js --target windows --arch x64 --graphics opengl --release執(zhí)行這個(gè)命令后Kha 會(huì)先調(diào)用 Haxe 編譯器把 Haxe 代碼編譯成 C 代碼然后再調(diào)用 C 編譯器把 C 代碼編譯成可執(zhí)行文件。整個(gè)過(guò)程可能需要幾分鐘到十幾分鐘取決于你的機(jī)器性能。4. 實(shí)操編譯全流程與踩坑記錄4.1 Windows 平臺(tái)編譯實(shí)錄我在 Windows 上編譯過(guò)三次第一次花了整整一個(gè)下午后面兩次就快多了。下面是我總結(jié)的完整流程。第一步安裝 Visual Studio 2022。去官網(wǎng)下載 Community 版安裝的時(shí)候勾選“使用 C 的桌面開(kāi)發(fā)”確保 MSVC 編譯器和 Windows SDK 都裝上。安裝完成后打開(kāi)“Developer Command Prompt for VS 2022”后續(xù)的編譯命令都在這個(gè)命令行里執(zhí)行因?yàn)樗鼤?huì)自動(dòng)配置好環(huán)境變量。第二步安裝 Haxe 和 Haxelib。去 Haxe 官網(wǎng)下載 Windows 安裝包一路下一步就行。裝完后打開(kāi)命令行輸入haxe -version確認(rèn)。然后輸入haxelib setup指定一個(gè)目錄存放 Haxelib 的包默認(rèn)是C:\HaxeToolkit\haxelib或者用戶目錄下的haxelib文件夾。第三步安裝 Kha。在命令行里執(zhí)行haxelib install kha如果網(wǎng)絡(luò)慢可以加上--always參數(shù)跳過(guò)確認(rèn)。裝完后執(zhí)行haxelib list確認(rèn) Kha 已經(jīng)安裝。第四步拉取 ArmorPaint 源碼。找個(gè)合適的目錄執(zhí)行g(shù)it clone --recursive https://github.com/armory3d/armorpaint.git這一步可能會(huì)比較慢因?yàn)樽幽K不少。如果卡在某個(gè)子模塊上可以按 CtrlC 中斷然后進(jìn)入 ArmorPaint 目錄手動(dòng)執(zhí)行g(shù)it submodule update --init --recursive多試幾次。第五步編譯。進(jìn)入 ArmorPaint 目錄執(zhí)行node Kha/make.js --target windows --arch x64 --graphics opengl --release然后就是等待。編譯過(guò)程中會(huì)輸出大量日志如果看到紅色的錯(cuò)誤信息就要停下來(lái)排查。我第一次編譯的時(shí)候報(bào)錯(cuò)說(shuō)找不到SDL2.h原因是 Kha 沒(méi)有自動(dòng)下載 SDL2 的預(yù)編譯庫(kù)。解決辦法是手動(dòng)去 Kha 的Kinc目錄下執(zhí)行g(shù)it submodule update --init --recursive把 Kinc 的子模塊也拉下來(lái)。編譯成功后可執(zhí)行文件會(huì)生成在build\x64\Release目錄下名字叫ArmorPaint.exe。雙擊運(yùn)行如果能看到界面說(shuō)明編譯成功了。4.2 Linux 平臺(tái)編譯實(shí)錄Linux 上的編譯比 Windows 麻煩一些主要是依賴庫(kù)的問(wèn)題。我用的是 Ubuntu 22.04下面是我踩過(guò)的坑。首先Haxe 和 Haxelib 的安裝。Ubuntu 的 apt 源里有 Haxe但版本可能比較老。我建議去 Haxe 官網(wǎng)下載 Linux 的二進(jìn)制包解壓后把haxe和haxelib加到 PATH 里?；蛘哂?snap 安裝sudo snap install haxe。但 snap 版本的 Haxelib 有時(shí)候會(huì)有權(quán)限問(wèn)題我最后還是用了官網(wǎng)的二進(jìn)制包。然后安裝 Khahaxelib install kha。這一步和 Windows 一樣。接下來(lái)是依賴庫(kù)。Ubuntu 上需要裝一堆開(kāi)發(fā)庫(kù)前面已經(jīng)列過(guò)了。但有個(gè)坑Ubuntu 22.04 的libsdl2-dev版本是 2.0.20而 Kha 可能期望的是 2.0.18 或更早的版本。我編譯的時(shí)候報(bào)錯(cuò)說(shuō)SDL_GetWindowDisplayIndex符號(hào)找不到后來(lái)發(fā)現(xiàn)是 SDL2 版本太新某些 API 變了。解決辦法是去 SDL2 官網(wǎng)下載 2.0.18 的源碼自己編譯安裝wget https://www.libsdl.org/release/SDL2-2.0.18.tar.gz tar -xzf SDL2-2.0.18.tar.gz cd SDL2-2.0.18 ./configure --prefix/usr/local make -j$(nproc) sudo make install然后重新編譯 ArmorPaint問(wèn)題解決。還有一個(gè)坑是 OpenGL 的驅(qū)動(dòng)。如果你用的是 NVIDIA 顯卡需要裝好閉源驅(qū)動(dòng)否則編譯出來(lái)的程序運(yùn)行時(shí)會(huì)報(bào)Failed to create OpenGL context。AMD 和 Intel 的核顯一般用開(kāi)源驅(qū)動(dòng)就行但也要確保mesa-utils裝好了。編譯命令和 Windows 類似node Kha/make.js --target linux --arch x64 --graphics opengl --release編譯成功后可執(zhí)行文件在build/linux/Release目錄下名字叫ArmorPaint。直接運(yùn)行就行如果報(bào)錯(cuò)缺少動(dòng)態(tài)庫(kù)用ldd ArmorPaint查看缺哪個(gè)然后裝上對(duì)應(yīng)的庫(kù)。4.3 macOS 平臺(tái)編譯實(shí)錄macOS 上編譯 ArmorPaint 的人相對(duì)少一些但我也試過(guò)。主要問(wèn)題是 Xcode 的版本和命令行工具的配置。首先確保你裝了 Xcode 命令行工具xcode-select --install。然后裝 Homebrew用 Homebrew 裝 SDL2 和 OpenALbrew install sdl2 openal-softHaxe 和 Haxelib 的安裝和 Linux 類似去官網(wǎng)下載 macOS 的二進(jìn)制包解壓后加到 PATH。然后haxelib install kha。編譯命令node Kha/make.js --target macos --arch x64 --graphics opengl --release如果你用的是 Apple Silicon 的 Mac把--arch改成arm64。但要注意Kha 對(duì) arm64 的支持可能不完善我試過(guò)編譯 arm64 版本結(jié)果運(yùn)行時(shí)報(bào)錯(cuò)說(shuō)某個(gè)匯編指令不支持。后來(lái)還是用 x64 版本通過(guò) Rosetta 運(yùn)行性能損失大概 10% 到 15%但至少能用。macOS 上還有一個(gè)坑是代碼簽名。編譯出來(lái)的.app包默認(rèn)沒(méi)有簽名雙擊運(yùn)行會(huì)被 Gatekeeper 攔截。解決辦法是在“系統(tǒng)偏好設(shè)置”-“安全性與隱私”里允許運(yùn)行或者用codesign命令手動(dòng)簽名codesign --force --deep --sign - build/macos/Release/ArmorPaint.app4.4 編譯后的運(yùn)行測(cè)試與性能調(diào)優(yōu)編譯成功只是第一步能不能穩(wěn)定運(yùn)行才是關(guān)鍵。我編譯出來(lái)的第一個(gè)版本啟動(dòng)后界面能顯示但一加載模型就閃退。查了日志發(fā)現(xiàn)是顯卡驅(qū)動(dòng)的問(wèn)題——我的 NVIDIA 驅(qū)動(dòng)版本太老不支持 ArmorPaint 用到的某個(gè) OpenGL 擴(kuò)展。更新驅(qū)動(dòng)后問(wèn)題解決。性能方面Release 版本比 Debug 版本快很多。我實(shí)測(cè)在同一個(gè)模型上繪制紋理Debug 版本幀率只有 20 多Release 版本能到 60 以上。所以最終使用一定要用 Release 版本。另外ArmorPaint 的渲染設(shè)置里可以調(diào)整分辨率縮放和抗鋸齒級(jí)別。如果你的顯卡性能一般可以把分辨率縮放調(diào)到 0.75 或 0.5幀率會(huì)明顯提升。抗鋸齒建議用 FXAA比 MSAA 省資源。還有一個(gè)調(diào)優(yōu)技巧在khafile.js里可以開(kāi)啟或關(guān)閉某些編譯選項(xiàng)比如--no-compress可以加快編譯速度但生成的二進(jìn)制更大--optimize可以開(kāi)啟更激進(jìn)的優(yōu)化但編譯時(shí)間更長(zhǎng)。我一般用默認(rèn)配置除非有特殊需求。5. 常見(jiàn)編譯錯(cuò)誤與排查手冊(cè)5.1 Haxe 編譯階段的典型報(bào)錯(cuò)Haxe 編譯階段的報(bào)錯(cuò)通常和版本不兼容有關(guān)。我遇到最多的就是Type not found或者Field not found這多半是因?yàn)?Kha 的版本和 ArmorPaint 源碼不匹配。解決辦法是查看 ArmorPaint 倉(cāng)庫(kù)的haxelib.json里面會(huì)寫(xiě)明依賴的 Kha 版本。如果沒(méi)有寫(xiě)明就去 GitHub 的 commit 歷史里找看看最近一次成功編譯的 commit 對(duì)應(yīng)的 Kha 版本是多少。另一個(gè)常見(jiàn)報(bào)錯(cuò)是Duplicate class field declaration這通常是因?yàn)樽幽K的版本沖突。比如你手動(dòng)更新了某個(gè)子模塊導(dǎo)致同一個(gè)類被定義了兩次。解決辦法是回退子模塊到主倉(cāng)庫(kù)指定的 commitgit submodule update --init --recursive --force還有一個(gè)報(bào)錯(cuò)是Uncaught exception - load.c(237) : Failed to load library : kha這說(shuō)明 Kha 沒(méi)有正確安裝或者 Haxelib 的路徑不對(duì)。檢查haxelib list里有沒(méi)有 Kha如果沒(méi)有就重新安裝。如果路徑不對(duì)用haxelib setup重新配置。5.2 C 鏈接階段的疑難雜癥C 鏈接階段的報(bào)錯(cuò)通常更棘手因?yàn)樯婕跋到y(tǒng)庫(kù)和第三方庫(kù)。我遇到過(guò)的典型報(bào)錯(cuò)包括undefined reference to SDL_Init缺少 SDL2 庫(kù)。Windows 上檢查 Kha 的 Kinc 子模塊是否拉取完整Linux 上檢查libsdl2-dev是否安裝macOS 上檢查 Homebrew 的 SDL2 是否鏈接正確。cannot find -lGL缺少 OpenGL 庫(kù)。Linux 上裝libgl1-mesa-devWindows 上確保 Windows SDK 里有 OpenGL 的庫(kù)。LNK2019: unresolved external symbolWindows 上常見(jiàn)的鏈接錯(cuò)誤通常是某個(gè)庫(kù)沒(méi)有正確鏈接。檢查 Visual Studio 的項(xiàng)目配置確保所有依賴庫(kù)的路徑都加到了鏈接器里。如果鏈接錯(cuò)誤太多可以嘗試用 Debug 模式編譯因?yàn)?Debug 模式會(huì)輸出更詳細(xì)的錯(cuò)誤信息。另外清理一下構(gòu)建緩存也有幫助rm -rf build然后重新編譯。5.3 運(yùn)行時(shí)崩潰與閃退的排查思路編譯成功但運(yùn)行崩潰這種問(wèn)題最讓人頭疼。我的排查思路是第一看日志。ArmorPaint 運(yùn)行時(shí)會(huì)輸出日志到控制臺(tái)Windows 上可以在命令行里運(yùn)行ArmorPaint.exe查看輸出Linux 和 macOS 上直接在終端里運(yùn)行。日志里通常會(huì)有錯(cuò)誤信息比如Failed to create window或者Shader compilation failed。第二檢查顯卡驅(qū)動(dòng)。很多運(yùn)行時(shí)崩潰都是顯卡驅(qū)動(dòng)引起的。確保你的顯卡驅(qū)動(dòng)是最新的而且支持 ArmorPaint 需要的 OpenGL 版本至少 OpenGL 3.3。第三檢查模型文件。有些模型文件格式不標(biāo)準(zhǔn)加載時(shí)會(huì)崩潰。試試用 Blender 重新導(dǎo)出模型或者換一個(gè)簡(jiǎn)單的模型測(cè)試。第四檢查內(nèi)存。ArmorPaint 在處理高面數(shù)模型時(shí)會(huì)吃很多內(nèi)存如果內(nèi)存不足會(huì)直接崩潰。打開(kāi)任務(wù)管理器看看內(nèi)存占用如果接近 100%那就需要升級(jí)內(nèi)存或者簡(jiǎn)化模型。5.4 常見(jiàn)問(wèn)題速查表問(wèn)題現(xiàn)象可能原因解決方案編譯時(shí)報(bào)Type not foundKha 版本不匹配回退 Kha 到源碼指定的版本鏈接時(shí)報(bào)undefined reference缺少依賴庫(kù)安裝對(duì)應(yīng)的開(kāi)發(fā)庫(kù)運(yùn)行時(shí)報(bào)Failed to create OpenGL context顯卡驅(qū)動(dòng)問(wèn)題更新顯卡驅(qū)動(dòng)加載模型時(shí)閃退模型文件不標(biāo)準(zhǔn)用 Blender 重新導(dǎo)出界面顯示異常圖形 API 不兼容換用其他圖形 API 編譯編譯速度極慢Debug 模式或硬件不足用 Release 模式升級(jí)硬件程序啟動(dòng)后黑屏分辨率或縮放問(wèn)題修改配置文件或命令行參數(shù)6. 編譯版的使用體驗(yàn)與后續(xù)擴(kuò)展6.1 編譯版和官方版的差異對(duì)比自己編譯的 ArmorPaint 和官方付費(fèi)版在功能上基本一致因?yàn)樵创a是同一套。但有幾個(gè)細(xì)微差別第一官方版會(huì)定期更新修復(fù) bug 和添加新功能。你自己編譯的版本取決于你拉取的源碼版本如果你不主動(dòng)更新就會(huì)停留在舊版本。第二官方版可能包含一些閉源的插件或資源比如某些高級(jí)筆刷或材質(zhì)庫(kù)。編譯版只有開(kāi)源的部分這些額外資源需要自己找或者自己制作。第三官方版有代碼簽名Windows 和 macOS 上不會(huì)觸發(fā)安全警告。編譯版沒(méi)有簽名運(yùn)行時(shí)可能會(huì)被系統(tǒng)攔截需要手動(dòng)允許。第四官方版的技術(shù)支持更完善遇到問(wèn)題可以找官方客服。編譯版只能自己排查或者去社區(qū)求助。不過(guò)編譯版也有優(yōu)勢(shì)你可以自己修改源碼定制功能。比如我改過(guò)筆刷的默認(rèn)參數(shù)把某些常用筆刷的硬度調(diào)高了一點(diǎn)用起來(lái)更順手。我還改過(guò)界面布局把常用的工具按鈕放到了更順手的位置。這些定制在官方版里是做不到的。6.2 我個(gè)人的使用感受與優(yōu)化建議用了一段時(shí)間編譯版整體感受是能用但需要折騰。如果你只是想畫(huà)貼圖不想折騰編譯那官方版更省心。但如果你喜歡折騰或者有特殊需求編譯版的可玩性更高。優(yōu)化建議方面我總結(jié)了幾個(gè)點(diǎn)定期更新源碼。ArmorPaint 的開(kāi)發(fā)比較活躍每隔幾個(gè)月就有新功能。定期git pull然后重新編譯可以體驗(yàn)到最新功能。備份你的修改。如果你改了源碼記得用 Git 分支管理否則更新的時(shí)候會(huì)沖突。加入社區(qū)。ArmorPaint 的 Discord 和 GitHub Issues 里有很多有用的信息遇到問(wèn)題可以先搜一下。關(guān)注性能。編譯版默認(rèn)可能沒(méi)有開(kāi)啟所有優(yōu)化你可以在khafile.js里調(diào)整編譯參數(shù)比如開(kāi)啟 LTO鏈接時(shí)優(yōu)化來(lái)提升性能。6.3 后續(xù)可以嘗試的擴(kuò)展方向如果你已經(jīng)成功編譯了 ArmorPaint可以嘗試一些擴(kuò)展方向第一編譯到其他平臺(tái)。比如 Android 或 HTML5雖然功能可能不完整但可以體驗(yàn)一下移動(dòng)端或網(wǎng)頁(yè)端的紋理繪制。第二修改源碼添加自定義功能。比如添加新的筆刷類型或者集成其他開(kāi)源庫(kù)。ArmorPaint 的代碼結(jié)構(gòu)比較清晰Haxe 語(yǔ)言也不難學(xué)有編程基礎(chǔ)的話可以試試。第三制作自己的材質(zhì)庫(kù)。ArmorPaint 支持導(dǎo)入自定義材質(zhì)你可以用其他工具制作 PBR 材質(zhì)然后導(dǎo)入到 ArmorPaint 里使用。第四參與開(kāi)源貢獻(xiàn)。如果你修復(fù)了某個(gè) bug 或者添加了某個(gè)功能可以給官方倉(cāng)庫(kù)提 Pull Request幫助其他用戶。我在實(shí)際操作中的體會(huì)是編譯 ArmorPaint 這件事最難的不是技術(shù)本身而是耐心。因?yàn)橘Y料少很多問(wèn)題要靠自己摸索有時(shí)候一個(gè)報(bào)錯(cuò)要查半天。但一旦編譯成功那種成就感是很足的。而且通過(guò)編譯你對(duì)這個(gè)軟件的理解會(huì)更深入用起來(lái)也更得心應(yīng)手。如果你也在編譯過(guò)程中遇到問(wèn)題歡迎交流我盡量幫你避坑。 ArmorPaint 源碼編譯實(shí)戰(zhàn)：從環(huán)境配置到運(yùn)行調(diào)試的完整避坑指南
1. 為什么我要自己編譯 ArmorPaintArmorPaint 這個(gè)軟件圈內(nèi)人應(yīng)該不陌生。它是一個(gè)開(kāi)源的 3D 模型紋理繪制工具主打 PBR 材質(zhì)繪制支持直接在模型表面畫(huà)貼圖功能上對(duì)標(biāo) Substance Painter 那一類商業(yè)軟件。官方提供的是付費(fèi)下載的預(yù)編譯版本源碼托管在公開(kāi)倉(cāng)庫(kù)里采用比較特殊的授權(quán)模式——源碼開(kāi)放但官方編譯好的二進(jìn)制包需要付費(fèi)購(gòu)買。這就意味著如果你不想花錢(qián)或者想自己改點(diǎn)東西那就得自己從源碼編譯。我最初接觸 ArmorPaint 是因?yàn)榻恿艘粋€(gè)獨(dú)立游戲的外包需要給一批低模角色畫(huà)手繪風(fēng)格的貼圖。Substance Painter 的訂閱費(fèi)對(duì)我來(lái)說(shuō)有點(diǎn)肉疼Blender 自帶的紋理繪制功能又太基礎(chǔ)圖層混合和筆刷系統(tǒng)都不夠用。找了一圈ArmorPaint 是最合適的選擇。但官方編譯版要花錢(qián)而且我后來(lái)發(fā)現(xiàn)官方版本在某些 Linux 發(fā)行版上跑起來(lái)有問(wèn)題顯卡驅(qū)動(dòng)兼容性也不太好。于是我就動(dòng)了自己編譯的念頭。這一編譯就踩了整整三天的坑。從環(huán)境配置到依賴?yán)木幾g報(bào)錯(cuò)到運(yùn)行閃退幾乎每個(gè)環(huán)節(jié)都卡過(guò)我。網(wǎng)上關(guān)于 ArmorPaint 編譯的中文資料少得可憐官方文檔寫(xiě)得也比較簡(jiǎn)略很多細(xì)節(jié)要靠自己摸索。所以我把整個(gè)編譯過(guò)程整理出來(lái)包括我遇到的所有問(wèn)題和解決方案希望能幫到后面想自己編譯的朋友。這篇文章適合幾類人一是想白嫖 ArmorPaint 但不想付費(fèi)的開(kāi)發(fā)者二是需要在特定平臺(tái)上運(yùn)行 ArmorPaint 的用戶比如某些 Linux 發(fā)行版或者老版本的 Windows三是想自己修改源碼、定制功能的進(jìn)階玩家。如果你只是想在 Windows 上隨便用用那直接買官方版可能更省事。但如果你有編譯需求或者想深入了解這個(gè)軟件的架構(gòu)那這篇內(nèi)容應(yīng)該能幫你省下不少時(shí)間。2. 編譯前的環(huán)境準(zhǔn)備與工具選型2.1 硬件與操作系統(tǒng)的選擇ArmorPaint 的編譯對(duì)硬件要求不算特別高但也不是隨便一臺(tái)機(jī)器就能跑。我實(shí)測(cè)下來(lái)編譯過(guò)程主要吃 CPU 和內(nèi)存顯卡反而不是編譯階段的瓶頸。我的主力機(jī)是 AMD Ryzen 7 5800X32GB 內(nèi)存編譯一次大概需要 8 到 12 分鐘。如果你用的是筆記本低壓 U比如 i5-10210U 這種編譯時(shí)間可能會(huì)拉長(zhǎng)到 20 分鐘以上而且內(nèi)存如果只有 8GB大概率會(huì)在鏈接階段爆內(nèi)存。操作系統(tǒng)方面官方主要支持 Windows、Linux 和 macOS。我三個(gè)平臺(tái)都試過(guò)Windows 上編譯最省心因?yàn)楣俜教峁┝祟A(yù)編譯的依賴庫(kù)Linux 上最折騰不同發(fā)行版的包管理器和庫(kù)版本差異很大macOS 上介于兩者之間但 Xcode 的版本兼容性需要注意。如果你只是想快速得到一個(gè)可用的編譯版我建議在 Windows 上操作用 Visual Studio 2022 作為編譯工具鏈。具體來(lái)說(shuō)Windows 10 或 Windows 11 都可以但要注意系統(tǒng)版本不能太老。我試過(guò)在 Windows 8.1 上編譯結(jié)果因?yàn)槿鄙倌承┫到y(tǒng) API 導(dǎo)致編譯失敗。Linux 方面Ubuntu 20.04 和 22.04 是比較穩(wěn)妥的選擇Arch 系雖然包新但滾動(dòng)更新容易導(dǎo)致依賴版本對(duì)不上。macOS 建議用 12 以上的版本Xcode 命令行工具要裝好。2.2 編譯工具鏈的安裝與配置ArmorPaint 是用 Haxe 語(yǔ)言寫(xiě)的然后通過(guò) Kha 框架跨平臺(tái)編譯。所以你需要的不只是 C 編譯器還要裝 Haxe 工具鏈和 Kha 的相關(guān)依賴。這是很多人第一次編譯時(shí)最容易懵的地方——以為是個(gè)普通的 C 項(xiàng)目結(jié)果發(fā)現(xiàn)構(gòu)建系統(tǒng)完全不是那回事。首先說(shuō) Haxe。你需要去 Haxe 官網(wǎng)下載對(duì)應(yīng)平臺(tái)的安裝包版本建議用 4.2.5 或 4.3.0太新的版本有時(shí)候會(huì)和 Kha 的某些庫(kù)不兼容。安裝完之后打開(kāi)終端或命令行輸入haxe -version確認(rèn)安裝成功。然后需要安裝 Haxelib這是 Haxe 的包管理器類似 Node.js 的 npm 或者 Python 的 pip。裝好 Haxelib 之后你需要通過(guò)它安裝 Kha 框架。Kha 的安裝命令是haxelib install kha但這里有個(gè)坑——Kha 的版本更新很快而 ArmorPaint 的源碼可能只兼容特定版本的 Kha。我建議先去看 ArmorPaint 源碼根目錄下的khafile.js或者h(yuǎn)axelib.json里面會(huì)寫(xiě)明依賴的 Kha 版本。如果沒(méi)有寫(xiě)明那就用haxelib install kha裝最新版然后祈禱能編譯通過(guò)。我試過(guò)用 Kha 的最新版編譯 ArmorPaint 0.9 的源碼結(jié)果報(bào)了一堆 API 不兼容的錯(cuò)誤后來(lái)回退到 Kha 22.10 才搞定。除了 Haxe 和 Kha你還需要一個(gè) C 編譯器。Windows 上用 Visual Studio 2022 的 MSVC 工具鏈安裝的時(shí)候記得勾選“使用 C 的桌面開(kāi)發(fā)”工作負(fù)載。Linux 上用 GCC 或 Clang 都行但要注意版本GCC 9 以上比較穩(wěn)妥。macOS 上用 Xcode 自帶的 Clang。另外Git 也是必須的因?yàn)槟阈枰獜膫}(cāng)庫(kù)拉取源碼和子模塊。2.3 依賴庫(kù)的拉取與版本管理ArmorPaint 的依賴庫(kù)不少包括但不限于SDL2、OpenGL 或 Vulkan 的 SDK、各種圖像編解碼庫(kù)如 stb_image、物理引擎如 Bullet 或 ODE用于某些碰撞檢測(cè)功能。這些依賴大部分可以通過(guò) Kha 的構(gòu)建系統(tǒng)自動(dòng)拉取但有些需要你手動(dòng)安裝。在 Windows 上Kha 會(huì)自動(dòng)下載預(yù)編譯的依賴庫(kù)你基本不用操心。但在 Linux 上你需要通過(guò)包管理器安裝一些系統(tǒng)級(jí)的庫(kù)比如libsdl2-dev、libgl1-mesa-dev、libopenal-dev等等。具體缺哪些編譯報(bào)錯(cuò)的時(shí)候會(huì)告訴你。我建議在 Ubuntu 上先把這一串裝上sudo apt-get install libsdl2-dev libgl1-mesa-dev libopenal-dev libx11-dev libxext-dev libxrandr-dev libxi-dev libxcursor-dev libxinerama-dev libasound2-dev libpulse-devmacOS 上相對(duì)簡(jiǎn)單大部分庫(kù)系統(tǒng)自帶但你可能需要裝 SDL2 和 OpenAL。用 Homebrew 裝就行brew install sdl2 openal-soft。這里有個(gè)經(jīng)驗(yàn)依賴庫(kù)的版本不要盲目追新。我試過(guò)在 Ubuntu 22.04 上用系統(tǒng)自帶的 SDL2 2.26結(jié)果編譯出來(lái)的 ArmorPaint 運(yùn)行時(shí)報(bào)錯(cuò)說(shuō)某個(gè)符號(hào)找不到。后來(lái)?yè)Q成 SDL2 2.0.20 的源碼自己編譯安裝問(wèn)題就解決了。所以如果你在 Linux 上遇到奇怪的鏈接錯(cuò)誤先檢查一下依賴庫(kù)的版本。3. 源碼獲取與編譯參數(shù)詳解3.1 從倉(cāng)庫(kù)拉取源碼的正確姿勢(shì)ArmorPaint 的源碼托管在 GitHub 上倉(cāng)庫(kù)地址是https://github.com/armory3d/armorpaint。但你不能直接git clone就完事因?yàn)樗昧俗幽Ksubmodule。如果你直接 clone 主倉(cāng)庫(kù)很多依賴目錄是空的編譯的時(shí)候會(huì)報(bào)找不到文件。正確的做法是git clone --recursive https://github.com/armory3d/armorpaint.git如果你已經(jīng) clone 了但忘了加--recursive可以進(jìn)入目錄后執(zhí)行g(shù)it submodule update --init --recursive這一步會(huì)拉取 Kha、Iron、Armory 等子模塊。網(wǎng)絡(luò)狀況不好的話可能會(huì)卡住或者失敗。我建議在拉取之前先配置一下 Git 的代理或者用國(guó)內(nèi)的一些鏡像源。不過(guò)要注意子模塊的版本必須和主倉(cāng)庫(kù)的 commit 對(duì)應(yīng)不要手動(dòng)去改子模塊的版本否則編譯大概率出問(wèn)題。拉取完成后檢查一下目錄結(jié)構(gòu)。根目錄下應(yīng)該有Sources、Assets、Kha、Libraries等文件夾。如果Kha文件夾是空的說(shuō)明子模塊沒(méi)拉下來(lái)需要重新執(zhí)行上面的命令。3.2 編譯目標(biāo)平臺(tái)與架構(gòu)的選擇ArmorPaint 支持編譯到多個(gè)平臺(tái)Windows、Linux、macOS、Android、HTML5 等。但不同平臺(tái)的編譯流程和依賴差異很大。我主要關(guān)注桌面端所以這里只講 Windows、Linux 和 macOS 的編譯。在編譯之前你需要確定目標(biāo)架構(gòu)。Windows 上一般是 x64Linux 上也是 x64macOS 上現(xiàn)在有 x64 和 arm64Apple Silicon兩種。如果你用的是 M1 或 M2 的 Mac編譯的時(shí)候需要指定 arm64 架構(gòu)否則編譯出來(lái)的程序在 Rosetta 下跑性能會(huì)打折扣。Kha 的構(gòu)建系統(tǒng)通過(guò)khafile.js來(lái)配置編譯目標(biāo)。你可以在根目錄下找到這個(gè)文件里面有一行l(wèi)et target ...默認(rèn)可能是windows或linux。如果你想編譯到其他平臺(tái)需要修改這個(gè)變量。不過(guò)更推薦的方式是通過(guò)命令行參數(shù)來(lái)指定比如node Kha/make.js --target windows --arch x64這樣不會(huì)污染源碼文件也方便切換。3.3 關(guān)鍵編譯參數(shù)的解讀與設(shè)置Kha 的構(gòu)建系統(tǒng)提供了一系列參數(shù)常用的有--target指定目標(biāo)平臺(tái)如windows、linux、macos、android、html5。--arch指定架構(gòu)如x64、arm64、x86。--debug編譯 Debug 版本包含調(diào)試符號(hào)運(yùn)行速度慢但方便排查問(wèn)題。--release編譯 Release 版本開(kāi)啟優(yōu)化運(yùn)行速度快但調(diào)試信息少。--graphics指定圖形 API如opengl、vulkan、direct3d11。這個(gè)參數(shù)很關(guān)鍵選錯(cuò)了可能導(dǎo)致程序無(wú)法啟動(dòng)。我一般先用 Debug 模式編譯一次確認(rèn)能跑起來(lái)再用 Release 模式編譯最終版本。圖形 API 方面Windows 上推薦direct3d11或openglLinux 上推薦opengl或vulkanmacOS 上只能用opengl或metal但 Kha 對(duì) Metal 的支持不太完善建議用 OpenGL。還有一個(gè)參數(shù)是--kha用來(lái)指定 Kha 的路徑。如果你把 Kha 放在非標(biāo)準(zhǔn)位置需要手動(dòng)指定。一般情況下不用管構(gòu)建腳本會(huì)自動(dòng)找到。編譯命令的完整形式大概是這樣的node Kha/make.js --target windows --arch x64 --graphics opengl --release執(zhí)行這個(gè)命令后Kha 會(huì)先調(diào)用 Haxe 編譯器把 Haxe 代碼編譯成 C 代碼然后再調(diào)用 C 編譯器把 C 代碼編譯成可執(zhí)行文件。整個(gè)過(guò)程可能需要幾分鐘到十幾分鐘取決于你的機(jī)器性能。4. 實(shí)操編譯全流程與踩坑記錄4.1 Windows 平臺(tái)編譯實(shí)錄我在 Windows 上編譯過(guò)三次第一次花了整整一個(gè)下午后面兩次就快多了。下面是我總結(jié)的完整流程。第一步安裝 Visual Studio 2022。去官網(wǎng)下載 Community 版安裝的時(shí)候勾選“使用 C 的桌面開(kāi)發(fā)”確保 MSVC 編譯器和 Windows SDK 都裝上。安裝完成后打開(kāi)“Developer Command Prompt for VS 2022”后續(xù)的編譯命令都在這個(gè)命令行里執(zhí)行因?yàn)樗鼤?huì)自動(dòng)配置好環(huán)境變量。第二步安裝 Haxe 和 Haxelib。去 Haxe 官網(wǎng)下載 Windows 安裝包一路下一步就行。裝完后打開(kāi)命令行輸入haxe -version確認(rèn)。然后輸入haxelib setup指定一個(gè)目錄存放 Haxelib 的包默認(rèn)是C:\HaxeToolkit\haxelib或者用戶目錄下的haxelib文件夾。第三步安裝 Kha。在命令行里執(zhí)行haxelib install kha如果網(wǎng)絡(luò)慢可以加上--always參數(shù)跳過(guò)確認(rèn)。裝完后執(zhí)行haxelib list確認(rèn) Kha 已經(jīng)安裝。第四步拉取 ArmorPaint 源碼。找個(gè)合適的目錄執(zhí)行g(shù)it clone --recursive https://github.com/armory3d/armorpaint.git這一步可能會(huì)比較慢因?yàn)樽幽K不少。如果卡在某個(gè)子模塊上可以按 CtrlC 中斷然后進(jìn)入 ArmorPaint 目錄手動(dòng)執(zhí)行g(shù)it submodule update --init --recursive多試幾次。第五步編譯。進(jìn)入 ArmorPaint 目錄執(zhí)行node Kha/make.js --target windows --arch x64 --graphics opengl --release然后就是等待。編譯過(guò)程中會(huì)輸出大量日志如果看到紅色的錯(cuò)誤信息就要停下來(lái)排查。我第一次編譯的時(shí)候報(bào)錯(cuò)說(shuō)找不到SDL2.h原因是 Kha 沒(méi)有自動(dòng)下載 SDL2 的預(yù)編譯庫(kù)。解決辦法是手動(dòng)去 Kha 的Kinc目錄下執(zhí)行g(shù)it submodule update --init --recursive把 Kinc 的子模塊也拉下來(lái)。編譯成功后可執(zhí)行文件會(huì)生成在build\x64\Release目錄下名字叫ArmorPaint.exe。雙擊運(yùn)行如果能看到界面說(shuō)明編譯成功了。4.2 Linux 平臺(tái)編譯實(shí)錄Linux 上的編譯比 Windows 麻煩一些主要是依賴庫(kù)的問(wèn)題。我用的是 Ubuntu 22.04下面是我踩過(guò)的坑。首先Haxe 和 Haxelib 的安裝。Ubuntu 的 apt 源里有 Haxe但版本可能比較老。我建議去 Haxe 官網(wǎng)下載 Linux 的二進(jìn)制包解壓后把haxe和haxelib加到 PATH 里?；蛘哂?snap 安裝sudo snap install haxe。但 snap 版本的 Haxelib 有時(shí)候會(huì)有權(quán)限問(wèn)題我最后還是用了官網(wǎng)的二進(jìn)制包。然后安裝 Khahaxelib install kha。這一步和 Windows 一樣。接下來(lái)是依賴庫(kù)。Ubuntu 上需要裝一堆開(kāi)發(fā)庫(kù)前面已經(jīng)列過(guò)了。但有個(gè)坑Ubuntu 22.04 的libsdl2-dev版本是 2.0.20而 Kha 可能期望的是 2.0.18 或更早的版本。我編譯的時(shí)候報(bào)錯(cuò)說(shuō)SDL_GetWindowDisplayIndex符號(hào)找不到后來(lái)發(fā)現(xiàn)是 SDL2 版本太新某些 API 變了。解決辦法是去 SDL2 官網(wǎng)下載 2.0.18 的源碼自己編譯安裝wget https://www.libsdl.org/release/SDL2-2.0.18.tar.gz tar -xzf SDL2-2.0.18.tar.gz cd SDL2-2.0.18 ./configure --prefix/usr/local make -j$(nproc) sudo make install然后重新編譯 ArmorPaint問(wèn)題解決。還有一個(gè)坑是 OpenGL 的驅(qū)動(dòng)。如果你用的是 NVIDIA 顯卡需要裝好閉源驅(qū)動(dòng)否則編譯出來(lái)的程序運(yùn)行時(shí)會(huì)報(bào)Failed to create OpenGL context。AMD 和 Intel 的核顯一般用開(kāi)源驅(qū)動(dòng)就行但也要確保mesa-utils裝好了。編譯命令和 Windows 類似node Kha/make.js --target linux --arch x64 --graphics opengl --release編譯成功后可執(zhí)行文件在build/linux/Release目錄下名字叫ArmorPaint。直接運(yùn)行就行如果報(bào)錯(cuò)缺少動(dòng)態(tài)庫(kù)用ldd ArmorPaint查看缺哪個(gè)然后裝上對(duì)應(yīng)的庫(kù)。4.3 macOS 平臺(tái)編譯實(shí)錄macOS 上編譯 ArmorPaint 的人相對(duì)少一些但我也試過(guò)。主要問(wèn)題是 Xcode 的版本和命令行工具的配置。首先確保你裝了 Xcode 命令行工具xcode-select --install。然后裝 Homebrew用 Homebrew 裝 SDL2 和 OpenALbrew install sdl2 openal-softHaxe 和 Haxelib 的安裝和 Linux 類似去官網(wǎng)下載 macOS 的二進(jìn)制包解壓后加到 PATH。然后haxelib install kha。編譯命令node Kha/make.js --target macos --arch x64 --graphics opengl --release如果你用的是 Apple Silicon 的 Mac把--arch改成arm64。但要注意Kha 對(duì) arm64 的支持可能不完善我試過(guò)編譯 arm64 版本結(jié)果運(yùn)行時(shí)報(bào)錯(cuò)說(shuō)某個(gè)匯編指令不支持。后來(lái)還是用 x64 版本通過(guò) Rosetta 運(yùn)行性能損失大概 10% 到 15%但至少能用。macOS 上還有一個(gè)坑是代碼簽名。編譯出來(lái)的.app包默認(rèn)沒(méi)有簽名雙擊運(yùn)行會(huì)被 Gatekeeper 攔截。解決辦法是在“系統(tǒng)偏好設(shè)置”-“安全性與隱私”里允許運(yùn)行或者用codesign命令手動(dòng)簽名codesign --force --deep --sign - build/macos/Release/ArmorPaint.app4.4 編譯后的運(yùn)行測(cè)試與性能調(diào)優(yōu)編譯成功只是第一步能不能穩(wěn)定運(yùn)行才是關(guān)鍵。我編譯出來(lái)的第一個(gè)版本啟動(dòng)后界面能顯示但一加載模型就閃退。查了日志發(fā)現(xiàn)是顯卡驅(qū)動(dòng)的問(wèn)題——我的 NVIDIA 驅(qū)動(dòng)版本太老不支持 ArmorPaint 用到的某個(gè) OpenGL 擴(kuò)展。更新驅(qū)動(dòng)后問(wèn)題解決。性能方面Release 版本比 Debug 版本快很多。我實(shí)測(cè)在同一個(gè)模型上繪制紋理Debug 版本幀率只有 20 多Release 版本能到 60 以上。所以最終使用一定要用 Release 版本。另外ArmorPaint 的渲染設(shè)置里可以調(diào)整分辨率縮放和抗鋸齒級(jí)別。如果你的顯卡性能一般可以把分辨率縮放調(diào)到 0.75 或 0.5幀率會(huì)明顯提升。抗鋸齒建議用 FXAA比 MSAA 省資源。還有一個(gè)調(diào)優(yōu)技巧在khafile.js里可以開(kāi)啟或關(guān)閉某些編譯選項(xiàng)比如--no-compress可以加快編譯速度但生成的二進(jìn)制更大--optimize可以開(kāi)啟更激進(jìn)的優(yōu)化但編譯時(shí)間更長(zhǎng)。我一般用默認(rèn)配置除非有特殊需求。5. 常見(jiàn)編譯錯(cuò)誤與排查手冊(cè)5.1 Haxe 編譯階段的典型報(bào)錯(cuò)Haxe 編譯階段的報(bào)錯(cuò)通常和版本不兼容有關(guān)。我遇到最多的就是Type not found或者Field not found這多半是因?yàn)?Kha 的版本和 ArmorPaint 源碼不匹配。解決辦法是查看 ArmorPaint 倉(cāng)庫(kù)的haxelib.json里面會(huì)寫(xiě)明依賴的 Kha 版本。如果沒(méi)有寫(xiě)明就去 GitHub 的 commit 歷史里找看看最近一次成功編譯的 commit 對(duì)應(yīng)的 Kha 版本是多少。另一個(gè)常見(jiàn)報(bào)錯(cuò)是Duplicate class field declaration這通常是因?yàn)樽幽K的版本沖突。比如你手動(dòng)更新了某個(gè)子模塊導(dǎo)致同一個(gè)類被定義了兩次。解決辦法是回退子模塊到主倉(cāng)庫(kù)指定的 commitgit submodule update --init --recursive --force還有一個(gè)報(bào)錯(cuò)是Uncaught exception - load.c(237) : Failed to load library : kha這說(shuō)明 Kha 沒(méi)有正確安裝或者 Haxelib 的路徑不對(duì)。檢查haxelib list里有沒(méi)有 Kha如果沒(méi)有就重新安裝。如果路徑不對(duì)用haxelib setup重新配置。5.2 C 鏈接階段的疑難雜癥C 鏈接階段的報(bào)錯(cuò)通常更棘手因?yàn)樯婕跋到y(tǒng)庫(kù)和第三方庫(kù)。我遇到過(guò)的典型報(bào)錯(cuò)包括undefined reference to SDL_Init缺少 SDL2 庫(kù)。Windows 上檢查 Kha 的 Kinc 子模塊是否拉取完整Linux 上檢查libsdl2-dev是否安裝macOS 上檢查 Homebrew 的 SDL2 是否鏈接正確。cannot find -lGL缺少 OpenGL 庫(kù)。Linux 上裝libgl1-mesa-devWindows 上確保 Windows SDK 里有 OpenGL 的庫(kù)。LNK2019: unresolved external symbolWindows 上常見(jiàn)的鏈接錯(cuò)誤通常是某個(gè)庫(kù)沒(méi)有正確鏈接。檢查 Visual Studio 的項(xiàng)目配置確保所有依賴庫(kù)的路徑都加到了鏈接器里。如果鏈接錯(cuò)誤太多可以嘗試用 Debug 模式編譯因?yàn)?Debug 模式會(huì)輸出更詳細(xì)的錯(cuò)誤信息。另外清理一下構(gòu)建緩存也有幫助rm -rf build然后重新編譯。5.3 運(yùn)行時(shí)崩潰與閃退的排查思路編譯成功但運(yùn)行崩潰這種問(wèn)題最讓人頭疼。我的排查思路是第一看日志。ArmorPaint 運(yùn)行時(shí)會(huì)輸出日志到控制臺(tái)Windows 上可以在命令行里運(yùn)行ArmorPaint.exe查看輸出Linux 和 macOS 上直接在終端里運(yùn)行。日志里通常會(huì)有錯(cuò)誤信息比如Failed to create window或者Shader compilation failed。第二檢查顯卡驅(qū)動(dòng)。很多運(yùn)行時(shí)崩潰都是顯卡驅(qū)動(dòng)引起的。確保你的顯卡驅(qū)動(dòng)是最新的而且支持 ArmorPaint 需要的 OpenGL 版本至少 OpenGL 3.3。第三檢查模型文件。有些模型文件格式不標(biāo)準(zhǔn)加載時(shí)會(huì)崩潰。試試用 Blender 重新導(dǎo)出模型或者換一個(gè)簡(jiǎn)單的模型測(cè)試。第四檢查內(nèi)存。ArmorPaint 在處理高面數(shù)模型時(shí)會(huì)吃很多內(nèi)存如果內(nèi)存不足會(huì)直接崩潰。打開(kāi)任務(wù)管理器看看內(nèi)存占用如果接近 100%那就需要升級(jí)內(nèi)存或者簡(jiǎn)化模型。5.4 常見(jiàn)問(wèn)題速查表問(wèn)題現(xiàn)象可能原因解決方案編譯時(shí)報(bào)Type not foundKha 版本不匹配回退 Kha 到源碼指定的版本鏈接時(shí)報(bào)undefined reference缺少依賴庫(kù)安裝對(duì)應(yīng)的開(kāi)發(fā)庫(kù)運(yùn)行時(shí)報(bào)Failed to create OpenGL context顯卡驅(qū)動(dòng)問(wèn)題更新顯卡驅(qū)動(dòng)加載模型時(shí)閃退模型文件不標(biāo)準(zhǔn)用 Blender 重新導(dǎo)出界面顯示異常圖形 API 不兼容換用其他圖形 API 編譯編譯速度極慢Debug 模式或硬件不足用 Release 模式升級(jí)硬件程序啟動(dòng)后黑屏分辨率或縮放問(wèn)題修改配置文件或命令行參數(shù)6. 編譯版的使用體驗(yàn)與后續(xù)擴(kuò)展6.1 編譯版和官方版的差異對(duì)比自己編譯的 ArmorPaint 和官方付費(fèi)版在功能上基本一致因?yàn)樵创a是同一套。但有幾個(gè)細(xì)微差別第一官方版會(huì)定期更新修復(fù) bug 和添加新功能。你自己編譯的版本取決于你拉取的源碼版本如果你不主動(dòng)更新就會(huì)停留在舊版本。第二官方版可能包含一些閉源的插件或資源比如某些高級(jí)筆刷或材質(zhì)庫(kù)。編譯版只有開(kāi)源的部分這些額外資源需要自己找或者自己制作。第三官方版有代碼簽名Windows 和 macOS 上不會(huì)觸發(fā)安全警告。編譯版沒(méi)有簽名運(yùn)行時(shí)可能會(huì)被系統(tǒng)攔截需要手動(dòng)允許。第四官方版的技術(shù)支持更完善遇到問(wèn)題可以找官方客服。編譯版只能自己排查或者去社區(qū)求助。不過(guò)編譯版也有優(yōu)勢(shì)你可以自己修改源碼定制功能。比如我改過(guò)筆刷的默認(rèn)參數(shù)把某些常用筆刷的硬度調(diào)高了一點(diǎn)用起來(lái)更順手。我還改過(guò)界面布局把常用的工具按鈕放到了更順手的位置。這些定制在官方版里是做不到的。6.2 我個(gè)人的使用感受與優(yōu)化建議用了一段時(shí)間編譯版整體感受是能用但需要折騰。如果你只是想畫(huà)貼圖不想折騰編譯那官方版更省心。但如果你喜歡折騰或者有特殊需求編譯版的可玩性更高。優(yōu)化建議方面我總結(jié)了幾個(gè)點(diǎn)定期更新源碼。ArmorPaint 的開(kāi)發(fā)比較活躍每隔幾個(gè)月就有新功能。定期git pull然后重新編譯可以體驗(yàn)到最新功能。備份你的修改。如果你改了源碼記得用 Git 分支管理否則更新的時(shí)候會(huì)沖突。加入社區(qū)。ArmorPaint 的 Discord 和 GitHub Issues 里有很多有用的信息遇到問(wèn)題可以先搜一下。關(guān)注性能。編譯版默認(rèn)可能沒(méi)有開(kāi)啟所有優(yōu)化你可以在khafile.js里調(diào)整編譯參數(shù)比如開(kāi)啟 LTO鏈接時(shí)優(yōu)化來(lái)提升性能。6.3 后續(xù)可以嘗試的擴(kuò)展方向如果你已經(jīng)成功編譯了 ArmorPaint可以嘗試一些擴(kuò)展方向第一編譯到其他平臺(tái)。比如 Android 或 HTML5雖然功能可能不完整但可以體驗(yàn)一下移動(dòng)端或網(wǎng)頁(yè)端的紋理繪制。第二修改源碼添加自定義功能。比如添加新的筆刷類型或者集成其他開(kāi)源庫(kù)。ArmorPaint 的代碼結(jié)構(gòu)比較清晰Haxe 語(yǔ)言也不難學(xué)有編程基礎(chǔ)的話可以試試。第三制作自己的材質(zhì)庫(kù)。ArmorPaint 支持導(dǎo)入自定義材質(zhì)你可以用其他工具制作 PBR 材質(zhì)然后導(dǎo)入到 ArmorPaint 里使用。第四參與開(kāi)源貢獻(xiàn)。如果你修復(fù)了某個(gè) bug 或者添加了某個(gè)功能可以給官方倉(cāng)庫(kù)提 Pull Request幫助其他用戶。我在實(shí)際操作中的體會(huì)是編譯 ArmorPaint 這件事最難的不是技術(shù)本身而是耐心。因?yàn)橘Y料少很多問(wèn)題要靠自己摸索有時(shí)候一個(gè)報(bào)錯(cuò)要查半天。但一旦編譯成功那種成就感是很足的。而且通過(guò)編譯你對(duì)這個(gè)軟件的理解會(huì)更深入用起來(lái)也更得心應(yīng)手。如果你也在編譯過(guò)程中遇到問(wèn)題歡迎交流我盡量幫你避坑。