Sample Menu Customization

簡介

樣例菜單與 SDK 一同捆綁提供，可用作創建自定義菜單的起點。進行升級時，樣例菜單會被替換，因此需要採取一些預防措施，確保修改不會被覆蓋。

樣例菜單是一個場景，在樣例文件夾中有一個菜單預製體。在該菜單預製體中，每個屏幕都有一個對應的預製體。

添加新場景

為了使場景選擇屏幕正常工作，菜單需要知道可用場景的相關信息。
創建或選擇 QuantumMenuConfig 資產，並將其分配給 QuantumMenuUIController 腳本（該腳本位於樣例菜單場景和 QuantumMenu 預製體中）。

QuantumMenuConfig - Controller — QuantumMenuConfig - 控制器

要添加一個可被菜單選擇的場景，第一步是要有一個包含 Quantum 地圖的 Unity 場景，就像初始的 QuantumGameScene 一樣。

使用該場景在 QuantumMenuConfig 資產的 AvailableScenes 列表中配置一個新條目。

確保將該場景也放入 Unity 的 BuildSettings 中。

| 名稱 | 描述 |
| ----------- | ----------- |
| Name| 顯示的場景名稱。 |
| ScenePath | 在這裡拖放場景文件。 |
| Preview | 拖放紋理以顯示為場景預覽，例如使用 QuantumMenuSpriteEmpty。 |
| Map | 拖放場景中使用的 Quantum 地圖資產。 |
| SystemsConfig | 拖放要在啟動遊戲時添加到 RuntimeConfig 的 Quantum SystemsConfig 資產。 |

QuantumMenuConfig - Available Scenes — QuantumMenuConfig - 可用場景

有兩個按鈕可以自動執行部分流程：

AddCurrentSceneToAvailableScenes: 嘗試將當前加載的場景添加為可用場景。
InitializeAllBuildSettingsScenes : 嘗試將 Unity BuildSettings 中所有的場景添加為可用場景。

佈局概述

樣例菜單包含一個場景和一個位於樣例文件夾中的預製體。該預製體包含所有屏幕預製體，並且以一個菜單基類為結構，該基類引用每個單獨的屏幕。這些屏幕繼承自QuantumMenuUIScreen，提供了多種功能，例如允許用戶在隱藏和顯示屏幕時加入動畫。

菜單自定義

本節包含一些有關如何修改菜單的建議。每種方法都有其自身的優點和缺點。

原型設計

最簡單的方法是直接修改 QuantumMenu 預製體。但是，在 Quantum SDK 升級時，所有更改都可能丟失。建議此選項僅用於實驗和原型設計。

預製體變體

為了在自定義和升級能力之間取得良好的平衡，建議從 QuantumMenu 創建一個預製體變體。如果需要向類（例如 QuantumMenuUIMain）添加新成員，創建部分類也是一個實用的選擇。

預製體創建

要創建預製體變體，在 Assets/Photon/Quantum/Samples 目錄中找到目標預製體。然後，右鍵單擊它並選擇 Create > Prefab Variant。

由於這是一個嵌套預製體，還需要為QuantumMenu Variant中的每個屏幕創建一個變體。之後，在QuantumMenuUiController上更改屏幕引用。

現在，在 QuantumMenuScene 或任何用作菜單的其他場景中，將原始的 QuantumMenu 預製體替換為其變體。重要的是要將其放置在 Canvas 中才能正常工作。

預製體複製

要自定義菜單且在升級 Quantum 時不丟失更改，複製 QuantumMenu 預製體是最簡單的方法。但是，您的自定義菜單與樣例之間將沒有聯繫，因此未來的更新將不會被納入。

構建屏幕

當您繼承自QuantumMenuUIScreen時，您的自定義屏幕將獲得多個有價值的訪問器。其中包括IQuantumMenuConfig, IQuantumMenuConnection, IQuantumMenuConnectArgs, 和IQuantumMenuUIController，它們可能包含對您的自定義需求有用的信息。此外，它還將繼承默認的Show和Hide方法。有關使用樣例菜單框架構建屏幕的更多信息，請參閱樣例菜單API文檔。

屏幕插件

這是一種向屏幕添加小部件的方式，類似於插件，因此同一個小部件可以被其他屏幕使用，而無需向基礎屏幕添加代碼。通過繼承QuantumMenuScreenPlugin，插件將收到對Show()和Hide()的調用，如下方的代碼片段所示。QuantumMenuScreenPluginPing在PhotonMenuViewGameplay屏幕中實現，可用作示例。

public class QuantumMenuScreenPluginFoo : QuantumMenuScreenPlugin {

    public override void Show(QuantumMenuUIScreen screen) {
      base.Show(screen);
    }

    public override void Hide(QuantumMenuUIScreen screen) {
      base.Hide(screen);
    }
}

簡單連接

如果您希望完全自定義構建菜單，QuantumSampleConnection是一個簡化的場景，可用作參考，以了解啟動會話所需的關鍵步驟。在QuantumSimpleConnectionGUI中，您可以看到建立連接、選擇地圖和啟動會話所需的基本操作。

擴展 RuntimePlayer 數據

默認情況下，RuntimePlayer類帶有幾個有用的 / 常見的字段，旨在加快原型設計過程：PlayerNickname用於存儲玩家在菜單上設置的名稱，PlayerAvatar是對實體原型的引用，該原型表示具有特定玩家的角色，可用於在模擬開始時在某些系統代碼中創建實體。

儘管暱稱是在運行時通過菜單 UI 設置的，但玩家頭像不是，它可以通過代碼設置，或者直接在QuantumMenu遊戲對象的QuantumMenuUIController組件的ConnectArgs/RuntimePlayers數組上設置。

為了添加更多特定於玩家的數據，並讓自定義菜單邏輯相應地填充這些數據，請按照以下步驟操作：

找到文件RuntimePlayer.User.cs並添加相關數據，並按照示範進行序列化：

namespace Quantum
{
  using Photon.Deterministic;

  public partial class RuntimePlayer
  {
    public int TeamId;

    partial void SerializeUserData(BitStream stream)
    {
      stream.Serialize(ref TeamId);
    }
  }
}

創建一個新類，該類繼承自QuantumMenuConnectionBehaviourSDK，重寫ConnectAsyncInternal()方法，並按照示範添加相關數據：

namespace Quantum
{
  using Quantum.Menu;
  using System.Threading.Tasks;

  public class CustomQuantumConnectionBehaviour : QuantumMenuConnectionBehaviourSDK
  {
    protected override Task<ConnectResult> ConnectAsyncInternal(QuantumMenuConnectArgs connectArgs)
    {
      connectArgs.RuntimePlayers[0].TeamId = 1; // Add any game-specific logic for getting the desired team id here
      return base.ConnectAsyncInternal(connectArgs);
    }
  }
}

在菜單場景中，找到QuantumMenu對象，並將QuantumMenuConnectionBehaviourSDK替換為CustomQuantumConnectionBehaviour。不要忘記添加上一個腳本具有的完全相同的OnProgress回調；
在同一對象上的QuantumMenuUIController中，在Connection字段上引用新添加的組件。

簡介
添加新場景
佈局概述
菜單自定義

原型設計
預製體變體
預製體複製
構建屏幕

屏幕插件
簡單連接
擴展 RuntimePlayer 數據