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...

多重解析度

多重解析度的問題

開發者常常對於如何在遊戲中最佳化支援多種解析度感到困擾。對於桌面和主機遊戲來說，這較為單純，因為大多數螢幕的長寬比為 16:9，且解析度多為標準規格（720p、1080p、1440p、4K……）。

行動遊戲一開始也很單純。多年來 iPhone 和 iPad 都使用相同的解析度。引入 Retina 後，他們只提高了像素密度，大多數開發者只需要提供預設和雙倍解析度的美術素材。

現在情況已經不同，市面上有許多不同的螢幕尺寸、密度與長寬比。非傳統尺寸（如超寬螢幕）也越來越普及。

對於 3D 繪製，通常不太需要支援多重解析度。由於其向量式的特性，3D 幾何會依據檢視區大小自動填滿畫面。至於 2D 與遊戲 UI 就不同了，因為美術資產通常會在 Photoshop、GIMP、Krita 等軟體中以特定像素尺寸製作。

由於版面配置、長寬比、解析度和像素密度變動幅度大，已經不可能為每一種螢幕設計專屬的 UI，因此必須採用其他方法。

統一尺寸適配

最常見的做法是先設定一個 基準 解析度，之後再讓其他解析度自動適配。這個基準解析度通常是多數玩家在其硬體上遊玩遊戲時的常見設定。針對行動裝置，Google 提供了 統計資料，而桌面平台則可參考 Steam 的 硬體調查。

舉例來說，Steam 顯示最常見的 主要顯示解析度 為 1920×1080，因此明智的做法是以這個解析度開發遊戲，然後再針對不同尺寸與長寬比進行縮放處理。

Godot 提供多種實用工具來簡化這項工作。

也參考

你可以參考 Multiple Resolutions and Aspect Ratios 範例專案，實際體驗 Godot 多解析度支援的運作方式。

基礎尺寸

你可以在專案設定的 Display → Window 項目下指定視窗的基礎尺寸。

但這項設定的作用並非將螢幕解析度切換為此數值。你可以把這個數值視為「設計尺寸」，也就是你在編輯器中工作的區域大小。這個設定對應 2D 編輯器中藍色矩形的尺寸。

你經常需要支援螢幕或視窗尺寸與基礎尺寸不同的裝置。Godot 提供多種方法，讓你可以控制視口（viewport）如何縮放或拉伸以適應不同的螢幕尺寸。

備註

在本頁中，window 指的是系統分配給遊戲的螢幕區域，而 viewport 指的是遊戲控制以填滿螢幕區域的根物件（可透過 get_tree().root 存取）。這個 viewport 實際上是一個 Window 實例。請回憶 介紹 章節中提到，所有 Window 物件本質上都是 viewports。

若要在執行期間以腳本設定拉伸基礎尺寸，請使用 get_tree().root.content_scale_size 屬性（參見 Window.content_scale_size）。更改此值會間接改變 2D 元素的大小。不過，若要提供給使用者自訂縮放選項，建議使用 縮放比例，這樣更容易調整。

備註

Godot 採用現代化的多重解析度處理方式。引擎本身**不會**主動變更螢幕解析度。雖然直接更動螢幕解析度效率最高，但這卻是最不可靠的做法，因為如果遊戲閃退，顯示器可能會卡在低解析度。這種情況在 macOS 或 Linux 上尤其常見，因為它們對於動態解析度切換的處理不如 Windows。

更改螢幕解析度也會讓開發者喪失對濾鏡和長寬比拉伸的掌控，這對像素美術遊戲來說尤其重要，否則畫面容易失真。

此外，切換螢幕解析度會讓 Alt-Tab 切換遊戲的速度變得很慢，因為每次切換都會重設解析度。

縮放處理

市面上的裝置類型繁多，螢幕種類、像素密度和解析度都不一樣。要全部兼容非常費工，因此 Godot 提供許多工具協助開發者。Viewport 節點具備各種縮放處理功能，場景樹的根節點永遠是一個 viewport（載入的場景會被實例化為其子節點，可透過 get_tree().root 或 get_node("/root") 取得）。

雖然直接修改根 Viewport 參數是最彈性的解法，但這會帶來更多工作量、程式碼與推測，因此 Godot 在專案設定中提供了一套參數，讓你輕鬆處理多重解析度。

小訣竅

若要以低於 2D 元素的解析度來繪製 3D（且不需要使用額外的 Viewport），可以使用 Godot 的 resolution scaling 支援。這是在 GPU 成為瓶頸時可顯著提升效能的好方法。該功能適用於任何拉伸模式與拉伸長寬比的組合。

拉伸設定

備註

When testing different stretch modes and stretch aspect settings, make sure game embedding is configured to use the Stretch to Fit scaling option:

This ensures the viewport size always matches the window size, like when game embedding is disabled.

拉伸設定可在專案設定中找到，包含以下選項：

拉伸模式

Stretch Mode （拉伸模式）決定基礎尺寸如何被拉伸來適應螢幕或視窗解析度。以下動畫以 16×9 像素的「基礎尺寸」示範不同拉伸模式的效果。單一精靈（同樣 16×9 像素）覆蓋整個視口，並在上方加上一條對角線 Line2D ：

• Stretch Mode = Disabled （預設）：不進行拉伸。場景中的一單位對應螢幕上一像素。在這種模式下， Stretch Aspect （拉伸比例）設定無效。

  

• Stretch Mode = Canvas Items：在此模式下，專案設定中所指定的寬度與高度（基礎尺寸）會被拉伸以覆蓋整個螢幕（會考慮 Stretch Aspect 設定）。這代表所有物件都直接以目標解析度進行算繪。3D 畫面不受影響；而 2D 則不再有精靈像素與螢幕像素的 1:1 對應，可能導致縮放失真。

  

• Stretch Mode = Viewport：視口拉伸代表根 Viewport 的尺寸會被精確設為專案設定 Display 區段中指定的基礎尺寸，場景會先算繪到這個 viewport，再將這個 viewport 拉伸至螢幕大小（會考慮 Stretch Aspect 設定）。

  

若要於執行期間以腳本設定拉伸模式，請使用 get_tree().root.content_scale_mode 屬性（參考 Window.content_scale_mode 和 ContentScaleMode 列舉）。

拉伸比例

第二個設定是拉伸比例（Stretch Aspect）。僅在 Stretch Mode 設為 Disabled 以外時才有效。

在下方動畫中，你會看到灰色與黑色區域。黑色區域由引擎自動產生，無法繪製內容；灰色區域則屬於你的場景，可以繪製。這些灰色區域對應 2D 編輯器中藍色框線外的部分。

• Stretch Aspect = Ignore：拉伸時忽略長寬比。這表示畫面會被強制拉伸以完全填滿螢幕，不論螢幕比例是否比設計時寬或窄。這可能導致畫面變形，例如物件看起來比原設計更寬或更高。

  

• Stretch Aspect = Keep：拉伸時保持長寬比。這表示無論螢幕解析度為何，視口都維持原本尺寸，必要時會在上下（黑邊：Letterbox）或左右（黑邊：Pillarbox）加上黑條。

  如果你已知目標裝置的長寬比，或不打算處理多種長寬比，這是一個好選擇。

  

• Stretch Aspect = Keep Width：拉伸時保持長寬比。如果螢幕比基礎尺寸寬，則左右會加上黑條（Pillarbox）；如果螢幕比基礎尺寸高，視口會往垂直方向擴增（底部會顯示更多內容）。你也可以把這看成「垂直擴充」。

  這通常是設計可縮放 GUI 或 HUD 最佳選擇，你可以將某些控制元件錨定在底部（參考 尺寸與錨點）。

  

• Stretch Aspect = Keep Height：拉伸時保持長寬比。如果螢幕比基礎尺寸高，則上下會加上黑條（Letterbox）；若螢幕比基礎尺寸寬，則視口會往水平方向擴增（右邊會顯示更多內容）。你也可以把這看成「水平擴充」。

  這通常適合水平捲動的 2D 遊戲（如跑酷或橫向卷軸平台遊戲）。

  

• Stretch Aspect = Expand：拉伸時保持長寬比，但不固定基礎寬度或高度。視口會依據螢幕長寬比，往水平方向（若螢幕比基礎尺寸寬）或垂直方向（若螢幕比基礎尺寸高）擴增。

  

小訣竅

若要以自動縮放因子同時支援橫向與直向顯示，請將專案的基礎解析度設為 正方形 （1:1 長寬比）而非矩形。例如你原本想用 1280×720 作為基礎解析度，但想同時支援直向與橫向，則可將專案的基礎視窗尺寸設成 720×720。

若要讓玩家能於執行時自由選擇螢幕方向，記得將 Display > Window > Handheld > Orientation 設為 sensor。

若要於執行期間以腳本設定拉伸比例，請使用 get_tree().root.content_scale_aspect 屬性（參考 Window.content_scale_aspect 和 ContentScaleAspect 列舉）。

縮放比例

Scale**（縮放比例）設定可讓你在上述 **Stretch 選項的基礎上再額外加上一個縮放因子。預設值 1.0 代表不額外縮放。

例如，若設定 Scale 為 2.0 且 Stretch Mode 維持 Disabled，則場景中每個單位會對應螢幕上的 2×2 像素。這在非遊戲應用中是提供縮放選項的好方式。

若 Stretch Mode 設為 canvas_items，2D 元素會依基礎視窗大小縮放，然後再乘上 Scale 設定。這個參數也可以讓玩家自由調整，以符合不同需求。

若 Stretch Mode 設為 viewport，則視口解析度會除以 Scale。這會讓像素看起來更大，並降低算繪解析度（在相同視窗大小下），可提升效能。

若要於執行期間以腳本設定縮放比例，請使用 get_tree().root.content_scale_factor 屬性（參考 Window.content_scale_factor）。

你也可以透過 GUI > Theme > Default Theme Scale 專案設定來調整預設專案主題的產生縮放。這能讓你在基礎解析度遠高於或低於預設值時，仍可得到邏輯尺寸更合理的 UI。不過，這個專案設定無法在執行時變更，其值只會在專案啟動時讀取一次。

縮放模式

從 Godot 4.2 開始，Stretch Scale Mode**（縮放模式）可以把自動判斷的縮放因子（以及手動指定的 **Stretch Scale 設定）限制為整數。預設值為 fractional，代表可以套用任何縮放倍數（包含像 2.5 這種小數）。若設為 integer，則會自動向下取整數。例如原本縮放因子是 2.5，會被取為 2.0。這對顯示像素美術時避免失真非常有幫助。

請比較下列以 viewport 拉伸模式搭配 fractional 縮放模式顯示的像素美術：

棋盤格顯示不均勻，Logo 與文字線條寬度變化很大。

同一張像素美術改用 viewport 拉伸模式且縮放模式設為 integer 時：

棋盤格顯示均勻，線條寬度一致。

舉例來說，若你的視口基礎尺寸為 640×360，視窗尺寸為 1366×768：

• 使用 fractional 時，視口會以 1366×768 解析度顯示（縮放約為 2.133×），整個視窗空間都會被利用。每個視口像素對應約 2.133×2.133 螢幕像素。但由於螢幕僅能顯示「整數」像素，這會導致縮放不均勻，進而讓像素美術顯示失真。

• 使用 integer 時，視口以 1280×720 解析度顯示（縮放為 2×），剩餘區域會自動以黑邊填滿。此時每個視口像素都對應 2×2 螢幕像素。

此設定適用於任何拉伸模式。不過，若拉伸模式為 disabled，它只會對 Stretch Scale 設定進行向下取整數。這對 3D 遊戲但 UI 採像素美術時很有用，能避免 3D 視口可見區域因縮放而縮小（這問題常發生於 canvas_items 或 viewport 拉伸模式配合 integer 縮放模式時）。

小訣竅

遊戲建議使用 Exclusive Fullscreen**（獨佔全螢幕）視窗模式，而非 **Fullscreen，因為後者設計目的是避免 Windows 將視窗誤判為獨佔全螢幕。

Fullscreen 主要用於需要每像素透明度且不希望被作業系統關閉這功能的 GUI 應用程式。它會在螢幕底部保留 1 像素的線條。而 Exclusive Fullscreen 則會真正以螢幕實際尺寸運作，讓 Windows 能降低全螢幕遊戲的抖動與輸入延遲。

對於整數縮放來說，這尤其重要，因為 Fullscreen 模式會讓畫面高度少 1 像素，導致整數縮放時縮放倍率較預期還小。

常見應用場景

建議使用下列設定以妥善支援多重解析度與長寬比。

桌面遊戲

非像素美術：

• 建議將基礎視窗寬度設為 1920、高度設為 1080。如果你的顯示器比 1920×1080 小，可以將 Window Width Override 和 Window Height Override 設為較小的數值，讓專案啟動時視窗自動縮小。

• 另外，若主要目標是高階裝置，請將基礎視窗寬度設為 3840、高度設為 2160。如此可提供更高解析度的 2D 素材，畫面更銳利，但代價是更高的記憶體使用量與檔案大小。你也應將 GUI > Theme > Default Theme Scale 提高到 2.0 到 3.0 之間，確保 UI 元素維持可讀性。

  • 請注意，這會讓未使用 mipmap 的貼圖在低解析度裝置上出現顆粒感，因此務必遵循 降低縮小取樣時的鋸齒 中的指引。

• 將拉伸模式（Stretch Mode）設定為 canvas_items （2D 元素）。

• 將拉伸比例設為 expand （擴充），可同時支援多種長寬比，也能善用高比例的手機螢幕（如 18:9、19:9）。

• 使用 佈局 選單將 Control 節點的錨點設定到正確的角落。

• 對於 3D 遊戲，建議在遊戲選項選單中提供 解析度縮放，讓玩家可以將 3D 繪製的解析度與 UI 元素分開調整。這對效能調校很有幫助，特別是在低階硬體上。

像素美術：

• 把基礎視窗大小設為你預期要用的視口尺寸。大多數像素美術遊戲會使用 256×224 到 640×480 之間的視口尺寸。640×360 是不錯的基準，因為用整數縮放時能剛好對應 1280×720、1920×1080、2560×1440、3840×2160，而不會出現黑邊。視口尺寸越大，所需美術解析度越高，除非你想同時顯示更多遊戲世界內容。

• 將拉伸模式設定為 viewport （視口）。

• 將拉伸比例設定為 keep （保持）以強制採用單一長寬比（會有黑邊）；若想同時支援多種長寬比，也可設為 expand （擴充）。

• 若選用 expand 拉伸比例，請用 佈局 選單將 Control 節點的錨點對齊到正確的角落。

• 將縮放模式（Stretch Scale Mode）設為 integer （整數縮放）。這可避免像素美術出現縮放不均勻導致的顯示問題。

備註

viewport 拉伸模式會先以低解析度算繪，最後再拉伸到目標視窗尺寸。如果你可以接受精靈移動或旋轉到「次像素」位置，或想要高解析度的 3D 視口，也可以改用 canvas_items 拉伸模式。

橫向手機遊戲

Godot 預設為橫向顯示，因此通常不需調整顯示方向設定。

• 建議基礎視窗寬度設為 1280，高度設為 720。

• 另外，若主要目標是高階裝置，可將基礎視窗寬度設為 1920、高度設為 1080。這樣能提供更高解析度的 2D 素材、帶來更清晰的視覺效果，但記憶體使用量與檔案大小也會增加。許多裝置的螢幕解析度甚至更高（如 1440p），但在智慧型手機螢幕尺寸較小的情況下，與 1080p 的差異其實不太明顯。你也應將 GUI > Theme > Default Theme Scale 提高到 1.5 到 2.0 之間，確保 UI 元素維持可讀性。

  • 請注意，這會讓未使用 mipmap 的貼圖在低解析度裝置上出現顆粒感，因此務必遵循 降低縮小取樣時的鋸齒 中的指引。

• 將拉伸模式（Stretch Mode）設定為 canvas_items （2D 元素）。

• 將拉伸比例設為 expand （擴充），可同時支援多種長寬比，也能善用高比例的手機螢幕（如 18:9、19:9）。

• 使用 佈局 選單將 Control 節點的錨點設定到正確的角落。

小訣竅

若要更好支援平板電腦與摺疊機（這類裝置常見 4:3 長寬比），可考慮使用 4:3 為基礎解析度，並參照本章剩餘建議。例如，可將基礎視窗寬度設為 1280，高度設為 960。

直向手機遊戲

• 建議基礎視窗寬度設為 720，高度設為 1280。

• 另外，若主要目標是高階裝置，可將基礎視窗寬度設為 1080、高度設為 1920。這樣能提供更高解析度的 2D 素材、帶來更清晰的視覺效果，但記憶體使用量與檔案大小也會增加。許多裝置的螢幕解析度甚至更高（如 1440p），但在智慧型手機螢幕尺寸較小的情況下，與 1080p 的差異其實不太明顯。你也應將 GUI > Theme > Default Theme Scale 提高到 1.5 到 2.0 之間，確保 UI 元素維持可讀性。

  • 請注意，這會讓未使用 mipmap 的貼圖在低解析度裝置上出現顆粒感，因此務必遵循 降低縮小取樣時的鋸齒 中的指引。

• 將 Display > Window > Handheld > Orientation 設定為 portrait （直向）。

• 將拉伸模式（Stretch Mode）設定為 canvas_items （2D 元素）。

• 將拉伸比例設為 expand （擴充），可同時支援多種長寬比，也能善用高比例的手機螢幕（如 18:9、19:9）。

• 使用 佈局 選單將 Control 節點的錨點設定到正確的角落。

小訣竅

若要更好支援平板電腦與摺疊機（這類裝置常見 4:3 長寬比），可考慮使用 3:4 為基礎解析度，並參照本章剩餘建議。例如，可將基礎視窗寬度設為 960，高度設為 1280。

非遊戲應用

• 將基礎視窗寬高設為你想支援的最小視窗尺寸。這不是強制規定，但可確保你設計 UI 時會考慮小型視窗。

• 保持拉伸模式為預設值 disabled （停用）。

• Keep the stretch aspect to its default value, keep (its value won't be used since the stretch mode is disabled).

• You can define a minimum window size by setting get_window().min_size in a script's _ready() function. This prevents the user from resizing the application below a certain size, which could break the UI layout.

• 在應用程式設定中加入一個選項，用來調整根 Viewport 的 stretch scale，以便在 hiDPI 顯示器上放大 UI。可一併參考下方的 hiDPI 支援章節。

hiDPI 支援

預設情況下，Godot 專案會被作業系統視為具備 DPI 感知。這由 Display > Window > DPI > Allow hiDPI 專案設定控制，通常應保持啟用。停用 DPI 感知可能會導致 Windows 上的全螢幕行為異常。

由於 Godot 專案具備 DPI 感知能力，在 hiDPI 顯示器上啟動時，視窗可能會非常小（比例取決於螢幕解析度）。對於遊戲來說，最常見的解法是預設全螢幕。你也可以在 autoload 的 _ready() 函式中根據螢幕尺寸調整視窗大小。

若要避免 hiDPI 顯示器上 2D 元素太小：

• 對於遊戲，請使用 canvas_items 或 viewport 拉伸模式，讓 2D 元素自動根據目前視窗大小縮放。

• 對於非遊戲型應用，請使用 disabled 拉伸模式，並在 autoload 的 _ready() 中，依據顯示縮放係數設定拉伸縮放。顯示縮放係數可在作業系統的設定中調整，也可透過 screen_get_scale 取得。目前該方法已在 Android、iOS、Linux（僅 Wayland）、macOS 與 Web 上實作。其他平台則需要你自行依螢幕解析度推測縮放係數（同時提供設定讓使用者必要時覆寫）。Godot 編輯器目前即採用此作法。

Allow hiDPI 設定僅在 Windows 與 macOS 有效，其他平台會忽略此設定。

備註

Godot 編輯器本身一律被標記為具 DPI 感知能力。從編輯器執行專案時，只有在專案設定中啟用 Allow hiDPI 才會具備 DPI 感知。

降低縮小取樣時的鋸齒

若遊戲採用非常高的基礎解析度（如 3840×2160），將畫面縮小到較低解析度（如 1280×720）時，可能會產生鋸齒。

解決方法是：你可以為所有 2D 紋理 啟用 mipmaps。不過，啟用 mipmaps 會增加記憶體用量，在低階行動裝置上可能成為問題。

處理長寬比

調整好各種解析度的縮放後，也要確保你的 使用者介面 能針對不同長寬比做自動縮放。這可以藉由 anchors 及／或 containers 實現。

視野縮放

3D 相機節點的 Keep Aspect （保持長寬比）屬性預設為 Keep Height （保持高度）縮放模式（又稱 Hor+ ）。這通常適用於桌面遊戲或橫向手機遊戲，因為寬螢幕會自動採用更寬的視野。

但若你的 3D 遊戲打算以直向模式進行，建議改用 Keep Width （保持寬度）（又稱 Vert- ）。這樣長寬比高於 16:9（如 19:9）的手機就會自動採用 更高 的視野，這樣才更合理。

為 2D 與 3D 元素採用不同的縮放方式

若要以不同於 2D 元素（如 UI）的解析度來繪製 3D，請使用 Godot 的 resolution scaling 功能。這讓你無需使用額外的 Viewport 節點，就能控制 3D 使用的解析度縮放係數。你可以藉由降低 3D 解析度來提升效能，或透過超取樣來提升品質。