Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

為 Windows 進行編譯

也參考

這個頁面描述的是如何從源碼編譯 Windows 編輯器和匯出範本二進位檔案。如果你要找的是匯出專案到 Windows，請閱讀 為 Windows 匯出。

系統需求

若要在 Windows 下進行編譯，需要滿足下列條件：

  • A C++ compiler. Use one of the following:

    • Visual Studio Community, version 2019 or later. Visual Studio 2022 is recommended. Make sure to enable C++ in the list of workflows to install. If you've already installed Visual Studio without C++ support, run the installer again; it should present you a Modify button. Supports x86_64, x86_32, and arm64.

    • MinGW-w64 with GCC can be used as an alternative to Visual Studio. Be sure to install/configure it to use the posix thread model. Important: When using MinGW to compile the master branch, you need GCC 9 or later. Supports x86_64 and x86_32 only.

    • MinGW-LLVM with clang can be used as an alternative to Visual Studio and MinGW-w64. Supports x86_64, x86_32, and arm64.

  • Python 3.8+. Make sure to enable the option to add Python to the PATH in the installer.

  • SCons 4.0+ build system. Using the latest release is recommended, especially for proper support of recent Visual Studio releases.

備註

若有安裝 ``Scoop <https://scoop.sh/>`_ ，則可以通過下列指令來輕鬆安裝 MinGW 以及其他相依性套件：

scoop install gcc python scons make mingw

備註

若有安裝 MSYS2 ，則可以通過下列指令輕鬆安裝 MinGW 以及其他相依性套件：

pacman -S mingw-w64-x86_64-python3-pip mingw-w64-x86_64-gcc  \
    mingw-w64-i686-python3-pip mingw-w64-i686-gcc make

必須於各個 MSYS2 MinGW 子系統的 Shell 中執行 pip install scons 。

也參考

要獲取編譯所需的 Godot 源碼，請參閱 取得原始碼。

有關配合 Godot 使用 SCons 的一般說明，請參考 建置系統簡介 。

設定 SCons

若要安裝 SCons，請開啟命令提示字元並輸入下列指令。

python -m pip install scons

如果你看到提示資訊 Defaulting to user installation because normal site-packages is not writeable，那麼你就需要提升許可權後再重新執行該命令。使用管理員身份打開一個新的命令提示符，然後再執行該命令，確保 SCons 可以通過 PATH 存取。

若要檢查是否有正確安裝 Python 與 SCons，可以在命令提示字元 (cmd.exe) 中輸入 python --version 與 scons --version 。

若上述指令執行失敗，請確定有在安裝 Python 後將 Python 加至 PATH 環境變數中，然後再試一次。要將 Python 加入 PATH 環境變數，可以再次執行 Python 安裝程式，並開啟將 Python 加至 PATH 的選項。

如果 SCons 無法偵測到你的 Visual Studio 安裝，可能是因為你的 SCons 版本太老了。請使用 python -m pip install --upgrade scons 將其更新為最新版本。

下載 Godot 原始碼

更多資訊請參考 匯出專案 。

本教學假設原始碼放置於 C:\godot 中。

警告

為了防止編譯過程中由於連續病毒掃描而導致的速度減慢，請將 Godot 原始檔案夾新增到殺毒軟體中的例外列表中。

For Windows Defender, hit the Windows key, type "Windows Security" then hit Enter. Click on Virus & threat protection on the left panel. Under Virus & threat protection settings click on Manage Settings and scroll down to Exclusions. Click Add or remove exclusions then add the Godot source folder.

編譯

選擇編譯器

SCons will automatically find and use an existing Visual Studio installation. If you do not have Visual Studio installed, it will attempt to use MinGW instead. If you already have Visual Studio installed and want to use MinGW-w64, pass use_mingw=yes to the SCons command line. Note that MSVC builds cannot be performed from the MSYS2 or MinGW shells. Use either cmd.exe or PowerShell instead. If you are using MinGW-LLVM, pass both use_mingw=yes and use_llvm=yes to the SCons command line.

小訣竅

During development, using the Visual Studio compiler is usually a better idea, as it links the Godot binary much faster than MinGW. However, MinGW can produce more optimized binaries using link-time optimization (see below), making it a better choice for production use. This is particularly the case for the GDScript VM which performs much better with MinGW compared to MSVC. Therefore, it's recommended to use MinGW to produce builds that you distribute to players.

All official Godot binaries are built in custom containers using MinGW.

執行 SCons

After opening a command prompt, change to the root directory of the engine source code (using cd) and type:

C:\godot> scons platform=windows

備註

當使用多個 CPU 執行緒進行編譯，SCons 可能會提示缺少 pywin32。可以安心地忽略這個警告。

小訣竅

If you are compiling Godot to make changes or contribute to the engine, you may want to use the SCons options dev_build=yes or dev_mode=yes. See 開發 for more info.

If all goes well, the resulting binary executable will be placed in C:\godot\bin\ with the name godot.windows.editor.x86_32.exe or godot.windows.editor.x86_64.exe. By default, SCons will build a binary matching your CPU architecture, but this can be overridden using arch=x86_64, arch=x86_32, or arch=arm64.

該執行檔包含了完整的 Godot 遊戲引擎，並且不需任何相依性套件即可執行。執行這個檔案會開啟專案管理員。

小訣竅

If you are compiling Godot for production use, you can make the final executable smaller and faster by adding the SCons option production=yes. This enables additional compiler optimizations and link-time optimization.

LTO takes some time to run and requires up to 30 GB of available RAM while compiling (depending on toolchain). If you're running out of memory with the above option, use production=yes lto=none or production=yes lto=thin (LLVM only) for a lightweight but less effective form of LTO.

備註

若想在客製化建置上使用與 Godot 官方釋出版本不同的編輯器設定，可以通過在 bin/ 資料夾中建立檔名為 ._sc_ 或 _sc_ 的檔案來開啟 自包含模式 。

Compiling with support for Direct3D 12

By default, builds of Godot do not contain support for the Direct3D 12 graphics API.

You can install the required dependencies by running python misc/scripts/install_d3d12_sdk_windows.py in the Godot source repository. After running this script, add the d3d12=yes SCons option to enable Direct3D 12 support. This will use the default paths for the various dependencies, which match the ones used in the script.

You can find the detailed steps below if you wish to set up dependencies manually, but the above script handles everything for you (including the optional PIX and Agility SDK components).

  • godot-nir-static library. We compile the Mesa libraries you will need into a static library. Download it anywhere, unzip it and remember the path to the unzipped folder, you will need it below.

備註

You can optionally build the godot-nir-static libraries yourself with the following steps:

  1. Install the Python package mako which is needed to generate some files.

  2. Clone the godot-nir-static directory and navigate to it.

  3. Run the following:

    git submodule update --init
./update_mesa.sh
scons

    If you are building with MinGW-w64, add use_mingw=yes to the scons command, you can also specify build architecture using arch={architecture}. If you are building with MinGW-LLVM, add both use_mingw=yes and use_llvm=yes to the scons command.

    If you are building with MinGW and the binaries are not located in the PATH, add mingw_prefix="/path/to/mingw" to the scons command.

    Mesa static library should be built using the same compiler and the same CRT (if you are building with MinGW) you are using for building Godot.

Optionally, you can compile with the following for additional features:

  • PIX is a performance tuning and debugging application for Direct3D12 applications. If you compile-in support for it, you can get much more detailed information through PIX that will help you optimize your game and troubleshoot graphics bugs. To use it, download the WinPixEventRuntime package. You will be taken to a NuGet package page where you can click "Download package" to get it. Once downloaded, change the file extension to .zip and unzip the file to some path.

  • Agility SDK can be used to provide access to the latest Direct3D 12 features without relying on driver updates. To use it, download the latest Agility SDK package. You will be taken to a NuGet package page where you can click "Download package" to get it. Once downloaded, change the file extension to .zip and unzip the file to some path.

備註

If you use a preview version of the Agility SDK, remember to enable developer mode in Windows; otherwise it won't be used.

備註

If you want to use a PIX with MinGW build, navigate to PIX runtime directory and use the following commands to generate import library:

# For x86-64:
gendef ./bin/x64/WinPixEventRuntime.dll
dlltool --machine i386:x86-64 --no-leading-underscore -d WinPixEventRuntime.def -D WinPixEventRuntime.dll -l ./bin/x64/libWinPixEventRuntime.a

# For ARM64:
gendef ./bin/ARM64/WinPixEventRuntime.dll
dlltool --machine arm64 --no-leading-underscore -d WinPixEventRuntime.def -D WinPixEventRuntime.dll -l ./bin/ARM64/libWinPixEventRuntime.a

When building Godot, you will need to tell SCons to use Direct3D 12 and where to look for the additional libraries:

C:\godot> scons platform=windows d3d12=yes mesa_libs=<...>

Or, with all options enabled:

C:\godot> scons platform=windows d3d12=yes mesa_libs=<...> agility_sdk_path=<...> pix_path=<...>

備註

For the Agility SDK's DLLs you have to explicitly choose the kind of workflow. Single-arch is the default (DLLs copied to bin/). If you pass agility_sdk_multi_arch=yes to SCons, you'll opt-in for multi-arch. DLLs will be copied to the appropriate bin/<arch>/ subdirectories and at runtime the right one will be loaded.

Compiling with ANGLE support

ANGLE provides a translation layer from OpenGL ES 3.x to Direct3D 11 and can be used to improve support for the Compatibility renderer on some older GPUs with outdated OpenGL drivers and on Windows for ARM.

By default, Godot is built with dynamically linked ANGLE, you can use it by placing libEGL.dll and libGLESv2.dll alongside the executable.

備註

You can use dynamically linked ANGLE with export templates as well, rename aforementioned DLLs to libEGL.{architecture}.dll and libGLESv2.{architecture}.dll and place them alongside export template executables, and libraries will be automatically copied during the export process.

To compile Godot with statically linked ANGLE:

  • Download pre-built static libraries from godot-angle-static library, and unzip them.

  • When building Godot, add angle_libs={path} to tell SCons where to look for the ANGLE libraries:

    scons platform=windows angle_libs=<...>

備註

You can optionally build the godot-angle-static libraries yourself with the following steps:

  1. Clone the godot-angle-static directory and navigate to it.

  2. Run the following command:

    git submodule update --init
./update_angle.sh
scons

    If you are buildng with MinGW, add use_mingw=yes to the command, you can also specify build architecture using arch={architecture}. If you are building with MinGW-LLVM, add both use_mingw=yes and use_llvm=yes to the scons command.

    If you are building with MinGW and the binaries are not located in the PATH, add mingw_prefix="/path/to/mingw" to the scons command.

    ANGLE static library should be built using the same compiler and the same CRT (if you are building with MinGW) you are using for building Godot.

使用 Visual Studio 或其他 IDE 來進行開發

編譯 Godot 不需要使用 IDE，SCons 會處理所有事情。但是如果你想要做引擎開發，或者除錯引擎的 C++ 程式碼，你可能會對配置程式碼編輯器或者 IDE 感興趣。

基於資料夾的編輯器不需要任何特殊的設定就可以開始使用 Godot 的程式碼庫。要使用 Visual Studio 來編輯專案，需要先設定解決方案。

可以通過 SCons 來建立 Visual Studio 解決方案。要建立解決方案，請使用 vsproj=yes 參數來執行 SCons，如：

scons platform=windows vsproj=yes

現在可以在 Visual Studio 解決方案中開啟 Godot 原始碼了，然後可以通過 Visual Studio 的 建置 按鈕來建置 Godot。

也參考

SCons 3.0+ (詳情請參考 為 Windows 進行編譯)。

從其他作業系統上為 Windows 進行交叉編譯

If you are a Linux or macOS user, you need to install MinGW-w64, which typically comes in 32-bit and 64-bit variants, or MinGW-LLVM, which comes as a single archive for all target architectures. The package names may differ based on your distribution, here are some known ones:

Arch Linux

 
pacman -Sy mingw-w64

Debian / Ubuntu

 
apt install mingw-w64

Fedora

 
dnf install mingw64-gcc-c++ mingw64-winpthreads-static \
            mingw32-gcc-c++ mingw32-winpthreads-static

macOS

 
brew install mingw-w64

Mageia

 
urpmi mingw64-gcc-c++ mingw64-winpthreads-static \
      mingw32-gcc-c++ mingw32-winpthreads-static

在嘗試編譯前，SCons 會在 PATH 環境變數中檢查下列二進位檔：

# for MinGW-w64
i686-w64-mingw32-gcc
x86_64-w64-mingw32-gcc

# for MinGW-LLVM
aarch64-w64-mingw32-clang
i686-w64-mingw32-clang
x86_64-w64-mingw32-clang

If the binaries are not located in the PATH (e.g. /usr/bin), you can define the following environment variable to give a hint to the build system:

export MINGW_PREFIX="/path/to/mingw"

Where /path/to/mingw is the path containing the bin directory where i686-w64-mingw32-gcc and x86_64-w64-mingw32-gcc are located (e.g. /opt/mingw-w64 if the binaries are located in /opt/mingw-w64/bin).

若要確定是否有正確設定，可以通過在 Shell 中執行下列指令來確認是否有可使用的編譯器 (輸出的版本可能會依據不同系統而有所不同)：

${MINGW_PREFIX}/bin/x86_64-w64-mingw32-gcc --version
# x86_64-w64-mingw32-gcc (GCC) 13.2.0

備註

If you are building with MinGW-LLVM, add use_llvm=yes to the scons command.

備註

When cross-compiling for Windows using MinGW-w64, keep in mind only x86_64 and x86_32 architectures are supported. MinGW-LLVM supports arm64 as well. Be sure to specify the right arch= option when invoking SCons if building from a different architecture.

疑難排解

在某些 Ubuntu 版本中進行交叉編譯可能會出現 這個 Bug ，這是因為預設的設定未包含 POSIX 執行緒支援。

可以通過如下說明來更改此一設定。64 位元：

sudo update-alternatives --config x86_64-w64-mingw32-gcc
<choose x86_64-w64-mingw32-gcc-posix from the list>
sudo update-alternatives --config x86_64-w64-mingw32-g++
<choose x86_64-w64-mingw32-g++-posix from the list>

32 位元：

sudo update-alternatives --config i686-w64-mingw32-gcc
<choose i686-w64-mingw32-gcc-posix from the list>
sudo update-alternatives --config i686-w64-mingw32-g++
<choose i686-w64-mingw32-g++-posix from the list>

建立 Windows 匯出樣板

Windows export templates are created by compiling Godot without the editor, with the following flags:

C:\godot> scons platform=windows target=template_debug arch=x86_32
C:\godot> scons platform=windows target=template_release arch=x86_32
C:\godot> scons platform=windows target=template_debug arch=x86_64
C:\godot> scons platform=windows target=template_release arch=x86_64
C:\godot> scons platform=windows target=template_debug arch=arm64
C:\godot> scons platform=windows target=template_release arch=arm64

If you plan on replacing the standard export templates, copy these to the following location, replacing <version> with the version identifier (such as 4.2.1.stable or 4.3.dev):

%APPDATA%\Godot\export_templates\<version>\

並改為下列名稱：

windows_debug_x86_32_console.exe
windows_debug_x86_32.exe
windows_debug_x86_64_console.exe
windows_debug_x86_64.exe
windows_debug_arm64_console.exe
windows_debug_arm64.exe
windows_release_x86_32_console.exe
windows_release_x86_32.exe
windows_release_x86_64_console.exe
windows_release_x86_64.exe
windows_release_arm64_console.exe
windows_release_arm64.exe

但是，如果使用自定模組或自定引擎原始碼，則可能會需要在此將自定二進位檔設為自定匯出樣板：

../../../_images/wintemplates.webp

Select matching architecture in the export config.

這種情況下則不需要複製檔案，只需要將產生的檔案參照進 Godot 原始碼資料夾的 bin\ 目錄中即可。這樣一來，下次進行建置時，便會自動參照自定樣板。