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.

建立應用程式

Godot 擁有強大的內建 UI(使用者介面)系統,而且它的體積非常小巧,這讓它成為 Electron 或 Qt 等框架的理想替代品。

本頁面提供了使用 Godot 建立非遊戲應用的指南,以及執行常見任務以提升桌面集成度的說明。

備註

Godot 首先是一個遊戲引擎。這意味著使用 Godot 建立應用程式是其功能集帶來的附帶產物,而非開發的主要目標。

也參考

可以參考使用 Godot 開發的開源應用程式範例:Material Maker 和 Pixelorama。

執行常見任務

建立多視窗

此功能僅在 Windows、 macOS 和 Linux 系統上受支援(僅限 X11/XWayland,不支援原生 Wayland 模式)。

可使用 Window 節點建立額外視窗。這些視窗可獨立於主應用程式視窗進行移動、調整大小、最小化和關閉。

但是,如果關閉主視窗,所有其他視窗也會隨之關閉,因為關閉主視窗會終止整個處理程序。為避免此問題,可將主視窗最小化,並將其 unfocusable 屬性設為 true (使其從任務欄和任務切換器中隱藏),然後在啟動時立即建立額外的 Window 節點。在這種情況下,請務必提供替代的退出方式,例如 托盤圖示。

限制視窗大小

大多數應用程式只有在視窗尺寸達到某個最小值時才能正確渲染。對於更特定的使用場景,可能還需要強制設定最大視窗尺寸。

可通過 Window 節點上的 min_size 和 max_size 屬性來強制設定尺寸限制。請記得根據應用程式的縮放因子對這些尺寸限制進行換算(詳見 針對高 DPI 顯示屏進行縮放)。

小訣竅

提醒一下,你可以在任意 Node 上呼叫 get_window() 來取得根 Window 節點並設定其屬性。

使用原生檔案對話框

此功能僅支援 Windows、 macOS 、Linux 和 Android 系統。

預設情況下,Godot 使用其自帶的 FileDialog 實作作為檔案對話框。不過,你也可以改用作業系統的原生檔案對話框。使用者通常更傾向於使用原生對話框,因為它們能更好地與桌面環境集成,並提供更熟悉的使用體驗。

你可以通過在 FileDialog 節點上啟用 use_native_dialog 屬性來使用原生檔案對話框。由於沒有專案設定可以全域控制此行為,因此必須在專案中使用的每個 FileDialog 節點上分別進行設定。

macOS 上標準 FileDialog(左)與原生檔案對話框(右)的對比

macOS 上標準 FileDialog(左)與原生檔案對話框(右)的對比

備註

有關各平台支援情況的詳細資訊,請參閱 屬性說明。

另外,在 macOS 上,如果編輯器中啟用了遊戲內嵌(game embedding)功能,將不支援呼叫系統原生的檔案對話框。如果你想在執行專案時測試這個功能,請務必先關閉遊戲內嵌。具體操作是:切換到頂部的 Game 面板,點擊頂部工具列最右側的圖示,然後取消勾選 Embed Game on Next Play。

在系統托盤中建立圖示

此功能僅支援 Windows 和 macOS 系統。

你可以使用 StatusIndicator 節點在系統托盤(也稱通知區域)中建立一個或多個圖示。除了工具提示外,該節點還可以關聯一個 PopupMenu 節點,以便在點擊圖示時顯示下拉選單。

StatusIndicator 還提供了一個 pressed 訊號,會在點擊圖示時觸發。你可以利用該訊號在不顯示下拉選單的情況下執行操作,或根據按下的滑鼠按鍵執行不同的操作。

建立托盤圖示後,你可能還需要實作“關閉時最小化”行為。這意味著當使用者通過視窗管理器的 X 按鈕嘗試關閉應用程式時,程式會最小化到系統托盤而非退出。為此,請將以下腳本附加到一個以 StatusIndicator 為根節點的 自動載入 場景 上:

extends StatusIndicator

# Disable this behavior when running from the editor with game embedding,
# as it doesn't cooperate well.
var tray_icon_supported = (
        DisplayServer.has_feature(DisplayServer.FEATURE_STATUS_INDICATOR)
        and not Engine.is_embedded_in_editor()
    )


func _ready():
    visible = false

    if tray_icon_supported:
        get_tree().auto_accept_quit = false
        get_window().focus_entered.connect(
                func():
                    # Hide the tray icon when the window gains focus,
                    # which means it was restored from its minimized state.
                    visible = false
            )
        pressed.connect(
                func(_mouse_button, _position):
                    # Restore the application when the tray icon is clicked.
                    get_window().mode = Window.MODE_WINDOWED
            )


func _notification(what):
    if not tray_icon_supported:
        return

    match what:
        NOTIFICATION_WM_CLOSE_REQUEST:
            get_window().mode = Window.MODE_MINIMIZED
            # Show the tray icon.
            visible = true

有關如何重寫使用者嘗試關閉應用程式時的行為,請參閱 處理結束(退出)請求。當使用者存在未儲存的更改時,正確處理此行為至關重要,以避免資料丟失。

備註

當存在多個 StatusIndicator 節點時,它們在系統托盤中的排列順序取決於其被新增到場景樹中的先後順序。

使用用戶端裝飾

此功能僅支援 macOS 。

在 macOS 上,應用程式可以使用系統的全域選單欄,而無需在應用視窗內顯示選單欄。這在 Godot 中也被稱為 原生選單 。

macOS 上標準 MenuBar(左)、帶原生彈出選單的 MenuBar(中)與原生選單(右)的對比

macOS 上標準 MenuBar(左)、帶原生彈出選單的 MenuBar(中)與原生選單(右)的對比

Godot 支援通過 MenuBar 節點建立選單,該節點會將其 PopupMenu 子節點顯示為選單。你可以在屬性檢視器中啟用 MenuBar 節點的 prefer_global_menu 屬性,以開啟全域選單支援。在 macOS 上,啟用後 MenuBar 節點將隱藏且不佔用空間,其選單會轉而顯示在系統的全域選單欄中。若停用此屬性,MenuBar 節點將照常在應用視窗內顯示選單,但在作業系統支援的情況下仍會使用原生彈出選單。

備註

在 macOS 上,應用選單(專案名稱以粗體顯示)以及 Window 和 Help 選單始終存在。請勿手動將這些選單新增到全域選單中。

在 Godot 4.6 及更高版本中,你可以通過修改 PopupMenu 節點的 system_menu_id 屬性,在這些選單中新增新項。可選目標包括: Application Menu (首個選單,應用名稱以粗體顯示)、 Window Menu 、 Help Menu 和 Dock (右鍵點擊程式塢圖示時顯示)。這些選單中已有的標準選單項將被保留:

在 macOS 系統視窗選單中新增的自訂選項

在 macOS 系統視窗選單中新增的自訂選項

一個專案可以包含多個 MenuBar 節點。如果多個 MenuBar 節點均啟用了 Prefer Global Menu 屬性,則在 MenuBar 節點被新增到場景樹時,其選單選項將按照 Start Index 屬性指定的索引位置插入。這樣可以將與情境相關的選單置於選單欄末尾,從而確保在新增或移除額外的選單欄時,原有的選單選項位置保持不變。

對於更進階的用法,你也可以直接使用 NativeMenu 單例,而無需借助 MenuBar 節點。

備註

當編輯器中啟用了遊戲內嵌(game embedding)功能時,將不支援全域選單的整合。如果你想在執行專案時測試這個功能,請務必先關閉遊戲內嵌。具體操作是:切換到頂部的 Game 面板,點擊頂部工具列最右側的圖示,然後取消勾選 Embed Game on Next Play 。

使用用戶端視窗裝飾

此功能僅支援 macOS 。

許多現代應用程式採用 用戶端裝飾 (CSD),而非相依性作業系統的視窗管理器來繪製標題欄和視窗邊框(伺服端裝飾)。這種方式可實現更靈活的外觀定制,並與應用程式的 UI 更好地融合。

Godot 目前僅在 macOS 上支援用戶端裝飾。可通過啟用 display/window/size/extend_to_title 專案設定來使用該功能。

macOS 上標準視窗裝飾(上方)與用戶端裝飾(下方)的對比

macOS 上標準視窗裝飾(上方)與用戶端裝飾(下方)的對比

啟用用戶端裝飾後,視窗邊框將不再顯示,最小化/最大化/關閉按鈕會以疊加層形式呈現在應用程式介面上。你需要確保應用程式在頂部預留足夠的邊距,以便按鈕能夠舒適地顯示,同時還需使用 Label 節點或類似控制項來展示視窗標題。

若要根據是否啟用了用戶端裝飾來動態調整你的 UI,請使用 DisplayServer.has_feature 方法,並同時檢查 Window.extend_to_title 的目前值(這也是專案設定所修改的內容):

func _ready():
    if DisplayServer.has_feature(FEATURE_EXTEND_TO_TITLE) and get_window().extend_to_title:
        # Adjust UI for client-side decorations (a MarginContainer node
        # can be useful here). Also set the window title to be displayed
        # according to the native window title.
        $WindowTitle.visible = true
        $WindowTitle.text = get_window().title
        if OS.is_debug_build():
            $WindowTitle.text += " (DEBUG)"

為了正確定位視窗標題,建議考慮使用 DisplayServer.window_get_safe_title_margins() ,它會回傳一個 Vector3,其中 x 代表左邊距, y 代表右邊距(當系統使用從右向左的排版時會增加),而 z 代表高度。此外,你可以呼叫 DisplayServer.window_set_window_buttons_offset() 來調整關閉/最小化/最大化按鈕的位置(通常是為了讓它們垂直居中)。

macOS 上使用用戶端裝飾時的安全標題邊距

macOS 上使用用戶端裝飾時的安全標題邊距

備註

在 macOS 上,如果編輯器中啟用了遊戲內嵌(game embedding)功能,將不支援用戶端裝飾(client-side decorations)。如果你想在執行專案時測試這個功能,請務必先關閉遊戲內嵌。具體操作是:切換到頂部的 Game 面板,點擊頂部工具列最右側的圖示,然後取消勾選 Embed Game on Next Play 。

在任務欄或 Dock 欄上顯示進度狀態

此功能僅支援 Windows 和 macOS 系統。

應用程式可以向作業系統彙報進度狀態,這個狀態會直接顯示在任務欄或 Dock 欄的圖示上。這個狀態主要由兩部分組成:目前的狀態(比如進行中、已暫停、出錯)以及完成的百分比。這樣,即使使用者目前沒有聚焦在這個應用上(比如正在看別的視窗),也能直觀地看到任務的進展。

在 macOS 的 Dock 欄上顯示進度

在 macOS 的 Dock 欄上顯示進度

這通常是通過將 ProgressBar 節點的進度,與彙報給作業系統的進度保持同步來實現的。

func set_progress(value, indeterminate = false):
    $ProgressBar.value = value
    $ProgressBar.indeterminate = indeterminate

    if $ProgressBar.indeterminate:
        get_window().set_taskbar_progress_state(DisplayServer.PROGRESS_STATE_INDETERMINATE)
    else:
        get_window().set_taskbar_progress_state(DisplayServer.PROGRESS_STATE_NORMAL)

    # The taskbar progress value must be between `0.0` and `1.0`
    # (values outside this range are clamped).
    # ProgressBar provides a `ratio` property that represents its current progress
    # as a value between `0.0` and `1.0`.
    get_window().set_taskbar_progress_value($ProgressBar.ratio)

有幾種進度狀態可供選擇:無進度(會直接隱藏進度條)、不確定、正常、已暫停、出錯。具體細節可查看類參考文件。

你還可以使用 Window.request_attention() 來讓視窗在任務欄上閃爍(或者在 macOS 的 Dock 欄上跳動)。舉個例子,當某個耗時較長的操作完成後,就可以用這個功能來吸參照戶的注意。

備註

當編輯器中啟用了遊戲內嵌(game embedding)功能時,將不支援進度報告。如果你想在執行專案時測試這個功能,請務必先關閉遊戲內嵌。具體操作是:切換到頂部的 Game 面板,點擊頂部工具列最右側的圖示,然後取消勾選 Embed Game on Next Play 。

發送桌面通知

Godot 目前不支援發送桌面通知的原生功能。

不過,在 macOS 和 Linux 上,你可以分別使用 osascript 和 notify-send 命令行工具來發送桌面通知:

func send_notification(title, message):
    var app_name = ProjectSettings.get_setting("application/config/name")
    if app_name.is_empty():
        app_name = "Unnamed Project"

    if OS.has_feature("macos") and not OS.is_sandboxed():
        # Note that this will not work if the project is exported in sandbox mode
        # (e.g. for the Mac App Store).
        OS.execute("osascript", [
                "-e",
                'display notification \\"%s\\" with title \\"%s\\" subtitle \\"%s\\"' % [
                    message,
                    app_name,
                    title,
                ]
            ])
    elif OS.has_feature("linuxbsd"):
        OS.execute("notify-send", ["--app-name", app_name, title, message])

func _ready():
    send_notification("Success", "Operation completed successfully.")

遺憾的是,Windows 上沒有開箱即用的等效工具。

跨會話記住視窗位置和大小

Godot 沒有內建的跨會話記憶視窗位置和大小功能,但可以通過腳本手動實作。一個支援多顯示器設定的基礎範例是使用包含此腳本的 Autoload :

extends Node

# Use a dedicated configuration file for the window state.
# This way, the application's other configuration files are left
# untouched and can be put in version control without unnecessary diffs
# being produced.
const CONFIG_WINDOW_PATH = "user://window.ini"

var config_file = ConfigFile.new()


func _enter_tree():
    config_file.load(CONFIG_WINDOW_PATH)

    # Do not restore previous window state if running from the editor
    # with game embedding enabled.
    if not Engine.is_embedded_in_editor():
        var window_screen = config_file.get_value("main", "screen", -1)
        if window_screen is int:
            get_window().current_screen = window_screen

        var window_mode = config_file.get_value("main", "mode", -1)
        if window_mode is Window.Mode:
            get_window().mode = window_mode

        var window_position = config_file.get_value("main", "position", -1)
        if window_position is Vector2i:
            get_window().position = window_position

        var window_size = config_file.get_value("main", "size", -1)
        if window_size is Vector2i:
            get_window().size = window_size


func _exit_tree():
    # Save the current window state when the application is quit normally.
    # In a real world scenario, it's recommended to also save this information
    # regularly (e.g. with a Timer node), so that the window state can be
    # restored after a crash or when terminated externally.
    config_file.set_value("main", "screen", get_window().current_screen)
    config_file.set_value("main", "mode", get_window().mode)
    config_file.set_value("main", "position", get_window().position)
    config_file.set_value("main", "size", get_window().size)
    config_file.save(CONFIG_WINDOW_PATH)

備註

上面的範例僅追蹤主視窗的位置。在生成多個視窗的應用程式中,你需要分別儲存和載入每個視窗的位置和大小。

在啟動畫面(Splash Screen)期間隱藏視窗

對於某些應用程式,可能更傾向於隱藏預設啟動畫面,轉而繪製一個帶有進度條的自訂啟動畫面(或者,如果應用程式啟動很快,甚至完全可以不要啟動畫面)。

Godot 缺乏在啟動畫面期間隱藏視窗的原生支援,但你可以通過在專案設定中使用一個非常小的透明視窗來實現這一點,然後在主場景載入完成後調整視窗大小並停用透明度。

為此,專案設定應按照如下方式進行設定:

這個腳本可以作為一個 Autoload (自動載入單例)來使用,以便在啟動畫面顯示完畢後,恢復原始的(項目)設定:

extends Node


func _enter_tree():
    # Wait a frame to be rendered before restoring the window properties.
    # Otherwise, properties will be restored too early and the window border
    # will show up around a transparent window.
    await get_tree().process_frame

    get_viewport().transparent_bg = false
    get_window().transparent = false
    get_window().borderless = false
    get_window().size = Vector2i(1152, 648)

將應用程式顯示為覆蓋層

可以將應用程式視窗顯示為懸浮在其他視窗之上的覆蓋層。這對於小部件或系統監視器之類的應用非常有用。

要做到這一點,請啟用以下 所有 專案設定:

記得使用腳本來設定視窗的位置和大小,因為無邊框視窗通常無法由使用者直接拖動。

若要允許滑鼠輸入穿透到背景應用程式,請在作為覆蓋層繪製的 Window 上將 mouse_passthrough (滑鼠穿透)屬性設定為 true 。你也可以在 mouse_passthrough_polygon (滑鼠穿透多邊形)中定義一個多邊形,以便覆蓋層上的某些區域仍然可以攔截滑鼠輸入。

此外,你可能還想將 exclude_from_capture (從捕獲中排除)屬性設定為 true ,以防止疊加層出現在截圖或錄屏中。此提示僅在 Windows 和 macOS 上實作,且屬於“盡力而為”(best-effort)的機制,因此不應將其用作絕對的安全措施或數字版權管理(DRM)手段。

備註

當編輯器中啟用了遊戲內嵌(game embedding)功能時,將不支援以覆蓋層(overlay)的形式顯示。如果你想在執行專案時測試這個功能,請務必先關閉遊戲內嵌。具體操作是:切換到頂部的 Game 面板,點擊頂部工具列最右側的圖示,然後取消勾選 Embed Game on Next Play 。

此外,請記住,如果目標應用程式使用了獨佔全螢幕模式,疊加層將無法顯示在其上方。必須改用無邊框全螢幕模式,疊加層才能可見。

此外,在 Windows 上使用混合 GPU 設定(例如 NVIDIA Optimus)時,透明視窗顯示也存在一些 known issues 。切換渲染器可能有助於解決此問題。

在 Linux (X11) 系統上,如果使用者在視窗管理器設定中停用了合成器,那麼透明效果將無法顯示。

針對高 DPI 顯示屏進行縮放

現代顯示屏的像素密度差異很大,這通常意味著需要採用不同的縮放比例,以確保使用者介面元素清晰可讀。此外,也可以將此縮放比例作為手動調節選項提供給使用者,以便他們能根據個人習慣調整,從而保持舒適的使用體驗。

Godot 的多解析度支援功能在設定得當的情況下,非常適合用於應用程式的縮放適配。請按照 non-game application section of the Multiple resolutions documentation 中的說明進行操作。

備註

Godot 目前僅在 macOS、Android 和 Linux(僅限 Wayland 協議)系統上支援從作業系統設定中讀取螢幕縮放比例。在 Linux(X11 協議)和 Windows 系統上,你需要提供一個手動縮放選項,以便使用者根據需要調整使用者介面的縮放比例。

螢幕閱讀器集成

螢幕閱讀器通過朗讀使用者介面元素並提供導航控制,使視障人士能夠使用應用程式。盲文顯示器則是另一種方法,它們同樣相依性輔助功能資訊來正常工作。

Godot 會自動檢測是否有螢幕閱讀器在執行,如果檢測到,就會自動啟用輔助功能支援。你可以在 專案設定 中通過 accessibility/general/accessibility_support 來設定此項:如果不需要,可以將其停用。你也可以強制啟用它,這在使用的輔助功能除錯工具未被 Godot 識別為螢幕閱讀器時非常有用。

Godot 使用 AccessKit 庫來實現與螢幕閱讀器的集成。

小訣竅

由於螢幕閱讀器支援是直接使用螢幕閱讀器應用程式本身來播放音訊(而不是通過 Godot 專案),因此即使如在下文中所述將音訊驅動程式設定為 Dummy ,它也能正常工作。

強烈建議在你的目標平台上,使用主流的螢幕閱讀器來測試你的應用程式,以確保視障使用者也能獲得良好的使用體驗。常見的例子包括 Windows 上的 NVDA、macOS 上的 VoiceOver 以及 Linux 上的 Orca。

要讓螢幕閱讀器的支援達到良好的可用性水平,需要做大量的工作。你需要使用 Control.accessibility_name 和 Control.accessibility_description 屬性來定義無障礙標籤,並確保使用者介面在被螢幕閱讀器讀取時,其流程符合邏輯順序。

也參考

另請參閱 文字轉語音 ,瞭解獨立於螢幕閱讀器之外的文字轉語音功能。

新增單元測試

在一個應用程式中,擁有 單元測試 通常比在遊戲中更具價值。這可用於以自動化方式捕獲回歸錯誤,在邏輯能夠清晰分離的應用程式場景中,這往往更容易實現。

GDScript 本身並沒有內建單元測試框架,但社區維護了一些用於單元測試的外掛:

對於 C# 和 GDExtension(C++、Rust 等),你可以使用標準測試框架,例如 NUnit 或 doctest。

最佳化發佈包的體積

由於非遊戲應用程式通常不需要引擎的大部分功能,例如音訊、2D 或 3D,因此可以編譯經過最佳化的匯出範本來縮小檔案大小。這也能改善啟動速度,尤其在網頁平台上,二進位檔的大小會直接影響初始化速度。

檔案大小的減小通常很顯著(相對於專案的大小而言),因為與遊戲相比,應用套件含的大型素材更少。請參閱 最佳化建置檔案大小 以瞭解執行此操作的更多資訊。

打包成一個單獨的可執行檔

預設情況下,Godot 會生成一個包含專案資料的 PCK 檔案,並把它放在可執行程式(.exe)的旁邊。這就意味著,如果你只移動了可執行程式,而沒有同時把 PCK 檔案一起移走,程式就沒法執行了。這對於那些越來越傾向於‘單檔案分發’的應用程式來說,顯然不太理想。

如果你想讓應用完全獨立,變成一個單檔案的可執行程式,可以在匯出預設選項中開啟 Embed PCK (嵌入 PCK)。這樣會把 PCK 資來源資料直接打包塞進可執行程式(.exe)內部,以後你就可以隨意移動這個程式,而不用擔心它因為找不到檔案而損壞。另外,這也讓你可以直接在 ZIP 壓縮檔里執行程式,完全不需要先把它解壓出來。

備註

PCK 嵌入功能會根據平台的不同,存在一定的體積限制。對於非常龐大的應用(比如好幾個 GB 的大型遊戲),可能無法在所有平台上使用這個功能。具體的細節,建議去查看對應目標平台的匯出文件哦。

建立便攜式應用

當一個應用程式無需安裝就能直接執行,並且它的所有設定資訊都完全獨立、只儲存在它被解壓的那個資料夾里時,這個應用就被稱為 便攜版(Portable) 。這樣一來,你就可以把應用程式的檔案直接放在 U 盤或類似的行動裝置里,帶到不同的電腦上隨時使用,完全不需要經歷繁瑣的安裝過程。

Godot 編輯器自帶的 self-contained mode 目前還無法直接在專案內部使用。不過,你依然可以通過以下方法,選擇將你自己的設定檔案儲存到包含可執行程式的那個資料夾里:

var config_path = OS.get_executable_path().get_base_dir().path_join("config.ini")
# Then use `config_path` to save/load configuration files using ConfigFile or similar.

你可能希望把便攜模式做成可選的,因為並不是所有玩家都希望這樣。通常的做法是,檢測可執行程式所在的資料夾里是否存在某個特定的檔案(比如一個命名為 portable.txt 的檔案),只有當這個檔案存在時,才把設定檔案儲存到可執行程式所在的資料夾里。

警告

請記住,這個功能(便攜模式)只有在應用程式被解壓到一個‘可寫入’的位置時才會生效。如果可執行程式是在一個‘只讀’的位置執行的,比如在 Windows 上的 C:\Program Files 目錄里,就會導致權限報錯。

製作安裝包

雖然遊戲通常通過 Steam 等啟動器安裝或以 ZIP 格式下載,但應用程式通常以安裝程式的形式分發,以便更好地與桌面集成。安裝程式可以執行諸如向開始選單或桌面新增快捷方式、設定檔案關聯等操作。安裝程式也可以通過命令行自動執行,這使其更適合企業環境。

Godot 沒有對為匯出專案建立安裝程式的內建支援。不過,你仍然可以使用第三方工具建立自己的安裝程式。

以下是一些可以用來製作安裝程式的工具(不完全清單):

資源

這些頁面涵蓋了一些常在非遊戲應用之中執行的任務: