This document is about: QUANTUM 2

SWITCH TO

QUANTUM 1 QUANTUM 2 QUANTUM 3

Hierarchical Finite State Machine

建立一個新的HFSM

在編輯器的頂端列上，按一下(+)按鈕，然後選擇狀態機選項。

之後將提示您儲存HFSM檔案。在您希望的地方儲存它。這將建立一個資料資產，用於保留您 在視覺編輯器上 已完成的工作。

注意事項：您現在選擇的名稱，將是您編譯您在視覺編輯器上已完成的工作時，進一步生成的另一個資料資產的名稱。那將是實際上用於驅動您的機器人的資料資產，所以您已經可以選擇一個暗示性的名稱。

當您儲存檔案時，主要的機器人SDK視窗將被一個單一的 新狀態 填入，供您開始使用。

現在，讓我們進一步看看這個初始狀態：

指出這是HFSM的初始狀態；
狀態的名稱；
從這個狀態而生的轉換清單。

建立一個新的狀態

為了建立一個新的狀態，以右鍵按一下在編輯器視窗上的任何空的空間，並且選擇 建立新狀態

編輯一個狀態

為了編輯一個狀態，以右鍵按一下目標狀態，並且選擇 編輯這個狀態。

在這裡，您可以定義狀態的名稱及刪除／重新排序轉換。

附註：重新排序轉換將不會改變它們的優先順序。 它只用於視覺調整。在這個教學中將進一步說明優先順序主題。它只用於視覺調整。

按下Enter 以適用更改或 按下Esc 以放棄那些更改。

最小化狀態檢視

常見的情況是，HFSM在狀態及轉換的數量方面大幅增加，這可能導致難以實際了解某些HFSM的流程。在任何狀態節點上，您可以按一下 最小化 按鈕，以隱藏轉換槽及更改從它開始畫／畫向它的線的方式，從而啟用一個簡化的檢視。

讓我們分析 使用前 及 使用後。

在兩個狀態間建立一個轉換

為了開始在兩個狀態間建立一個轉換，首先按一下任何狀態的左／右邊緣的小圓圈的任一個。然後，如果您按一下另一個狀態，將建立一個連接這兩個狀態的新的轉換。

如果您不是按一下另一個狀態，而是按一下任何空白的空的空間，如果您希望立即建立目標狀態，編輯器將彈出建立面板。

無論您何時建立一個新的轉換，它將是暗色，指出該轉換 還沒被定義。

有幾種與轉換互動的方式：

當您的滑鼠滑過一個轉換，它將被醒目提示；
當您以左鍵按一下一個轉換，小圓圈將走過它，以指出轉換的方向；
當您按兩下一個轉換，您將進入它的子圖表；
從右鍵選單中，您可以：進入轉換子圖表，停用轉換或刪除它。

讓我們來分析已經在決策子圖表上建立的節點：

這是用於實際地定義轉換的節點。這裡有四個重要的概念：

這個節點的名稱指出原始狀態及目標狀態。它可以被更改，這是使用右鍵選單完成，所以您可以選擇有意義的名稱，並且它將顯示在上層，這讓情況更容易理解；
第一個槽用於定義一個在評估這個轉換時需要被考量的事件；
第二個槽用於定義撰寫轉換的決策；
第三個槽用於定義來自 相同的節點 的所有轉換之間的執行的順序。

讓我們開始針對這個轉換來定義一個簡單的決策。為了做到這點，以右鍵按一下任何空白空間，此時一個面板將會顯示您可以建立的決策。

為了簡單說明，讓我們選擇 真決策。當然，這個決策的結果總是為真。

有一個輸出槽，其定義這個決策的結果將被驅動到的地方。

所以，以左鍵按一下結果槽一側上的圓圈，並且連接它到決策槽：

這樣就完成了。您已經定義了最簡單的轉換。有了這個，只要您的機器人處於 新狀態 並且已更新HFSM，機器人將轉換到 新狀態1。

按一下決策欄位，可以編輯一個決策欄位值。

按下 Enter 以適用更改或 按下 Esc 以放棄更改。

現在我們定義了一個非常簡單的轉換，讓我們回到頂層檢視，並且看看它看起來如何。您可以按一下頂層列的階層連結列的根按鈕，來導航回狀態檢視：

或者，您可以使用左側面板，來導航狀態：

現在您可以看到轉換不再是紅色。這指出這是一個有效的轉換。

定義轉換優先順序

對於具有多個轉換的狀態，可以定義首先要評估哪個轉換。為了定義這個順序，使用 優先順序 槽。按一下它以設定其值。

可以在狀態節點上看見轉換的優先順序。

轉換將被評估的順序是：從高優先順序到低優先順序。有了這個，您已經可以定義首先需要檢查哪個轉換。

注意事項： 針對狀態的轉換所定義的優先順序，對另一個狀態的轉換而言沒有影響。

建立新的轉換

我們目前只有在我們的兩個狀態之間的一個轉換。有了這個，優先順序欄位是無用的，因為沒有狀態有多個轉換。

為了建立一個新的轉換，將滑鼠放在您的狀態的底部部分，並且按一下顯示的 (+) 按鈕。

之後您可以定義該新的轉換，就像您對第一個轉換所做的一樣。

特殊轉換類型

轉換集

這些節點類型可用於群組許多的轉換。重新使用一個轉換集特別有用，因為許多狀態可以指向一個單一的轉換集。

為了建立一個新的轉換集，以右鍵按一下任何空的空間，並且選擇 建立新的轉換集。這將建立一個節點，其非常相似於狀態節點：它開始於一個單一的未定義的轉換，並且您可以透過將滑鼠暫留在其底部部分，來建立許多新的轉換：

之後，只需建立連結。這裡是一個示例：

也可以使用轉換集的右上角按鈕，來最小化轉換集：

任何轉換

當您希望定義一些應該 從位於該同一階層層級上的任何狀態 選取的轉換時，這些轉換非常有用。 附註： 將在本文檔中進一步說明階層。

從右鍵選單來建立新的「任何」轉換。

現在，定義「任何」轉換的目標狀態。

在上述的範例圖，該階層層級上的每個狀態都將考量來自「任何」節點的轉換。

但是可以定義一個忽略「任何」轉換的狀態的清單。從 已排除清單 選單中選擇這些。

入口轉換

這個轉換類型意味著強迫HFSM從一個狀態轉到 您的階層的任何層級 中的任何其他狀態。從右鍵選單建立新的入口轉換。

現在您必須定義這個入口將把HFSM帶往哪個狀態。按一下下拉式選單以選擇它。請注意，目標狀態的名稱將基於您擁有的階層：

在您定義入口的目標之後，您只需定義哪些狀態將考量該入口。

已撰寫的決策

除了使用單一決策來定義轉換，也可以建立一些已撰寫的決策。機器人SDK已經帶有3個邏輯決策可以立即使用。

這裡是一些已撰寫的決策的範例，它們基於和、或及非決策：

事件

如果您希望評估一個轉換，且不在您的 quantum_code 專案上建立一個新的決策、編譯或設定決策等等，您可以使用事件。

事件的工作方式非常簡單：每當事件被觸發時，目前狀態的轉換將檢查該事件是否正在被接聽。如果任何轉換接聽該事件，它將被選取。就程式碼而言，這是觸發事件所需的：

在任何 quantum_code 指令碼中，請執行：

HFSMManager.TriggerEvent(f, &guy->Fields.HFSMAgent.Data, (Entity*)guy, "SomeEventName");

這個方法調用可以被新增到您的動作／決策，或到您有的任何其他邏輯，比如在您的系統中。

為了建立一個新的事件，按一下事件的工作階段的左側面板上的 (+) 按鈕：

當您這樣做，您將被提示來建立您的新的事件。您也可以在事件上按兩下，來開啟選單以 編輯或刪除事件。

為了在轉換子圖表上放置一個事件，您必須拖放它。然後，類似於您對決策所做的，您可以連接事件的輸出槽到轉換的事件輸入槽：

注意事項： 與決策有所不同，這裡沒有複合事件定義，並且一個轉換不接受超過一個事件的連接。

帶有由 僅一個事件 定義的決策的轉換，被視為 有效轉換。

也可以透過設定 一個事件及一個決策，來定義一個轉換。在這種情況下，只有在同一個幀上觸發事件並且決策條件為真時，才發生轉換。

定義動作

現在我們討論了如何建立狀態機的流程（帶有狀態及轉換），讓我們看一下如何針對一個狀態來定義動作。

更多關於這個主題的資訊，請參見：定義動作

停用

當測試您的AI時，為了暫時地停用一些邏輯而停用一些節點，可能有用。更多關於如何停用節點的資訊，請參見：停用

階層

在任何狀態的子圖表上，您可以建立新的狀態及轉換的集。假設您在 新的狀態 子圖標上，而且您建立一個新的狀態稱為 另一個狀態。當您這樣做的時候，將在這兩個動作之間建立一個關係： 新的狀態是上層而另一個狀態是下層。

上層及下層狀態的動作集轉換都將被執行。這樣的話，可以封裝一個狀態機到另一個狀態機之內。

假設如果您有 3個層次的行為的魔王，這可能非常方便：它一開始是簡易模式，然後當它的血量剩下一半時變得稍微難一點，最後在它總健康值只剩10%時變得更難。您可以在頂層圖表建立3個主要狀態，並且各個狀態將有其自己的狀態機以定義魔王的難度。

改善HFSM的組織方式是非常有用的。

為了建立一個下層狀態，只需前往任何狀態的子圖表，以右鍵按一下空的空間，並且選擇 建立新的狀態 選項。有了這個，您可以有一個複雜的階層層級，您可以在左側選單中看見它：

注意事項： 您可以按一下這些按鈕來導航於階層上。也可以以右鍵按一下任何這些狀態，以在您的目前的圖表檢視上來對它建立一個新的入口。

重要事項： 也可以為HFSM上的每個階層層級來定義預設狀態。這定義了在上層狀態之間轉換時輸入的下層狀態。為了定義哪個是預設狀態，以右鍵按一下任何狀態節點並且選擇「設為預設狀態」。

編譯您的HFSM

為了實際上使用您建立的HFSM，您必須編譯您所完成的事情。

為了編譯，您有兩個選項：

左按鈕只用於編譯目前開啟的文件；
右按鈕用於編譯在您的專案上您有的每個AI文件。

您的HFSM檔案將位於："Assets/Resources/DB/CircuitExport/HFSM_Assets"。

設定將被您的機器人使用的AI

為了最終使用建立的AI，您只需參照已編譯的資產。為了完成它，您可以基於GUID來載入資產，或您可以只是建立一個 資產連結 以指向所需的AI資產：

HFSM編碼

現在，就DSL而言，在建立新的HFSM代理方面有兩個主要選項：

您可以將HFSM代理元件新增到您的實體中；
您可以在您的架構或全域空間上宣告它，而無需擁有實體。

這一點很重要，因為可能讓HFSM執行超出實體的範圍的動作，比如建立遊戲流程、定義遊戲開始時執行哪些動作、定義何時遊戲將改變其目前狀態等等。

初始化代理

現在首先，舉例而言，這是您建立一個新的HFSM代理，並且新增它到您的實體的方式，前提是您沒有正在使用一個實體原型：

var hfsmAgent = new HFSMAgent();
f.Set(myEntity, hfsmAgent);

然後，在任何更適合您的應用程式之處，您必須基於您從視覺編輯器編譯的HFSMRoot資產，針對該實體來調用HFSMManager.Init方法，。

無論 您是否正在使用實體原型，下述的初始化步驟都需要完成：

var hfsmRootAsset = f.FindAsset<HFSMRoot>(referenceToRoot.Id);
HFSMManager.Init(frame, myEntity, hfsmRootAsset);

// Only do this if you are not using Entity Prototypes
f.Set(myEntity, hfsmAgent);

如果HFSM初始化過程中所需的任何資訊都包含在HFSM代理本身之中，您可以從實體來取得元件，以取得必要的資料：

Unknown

var hfsmAgent = f.Get<HFSMAgent>(myEntity);

使用"OnComponentAdded"回調來初始化

也可以直接在實體原型上設定參照到HFSMRoot資產，並且使用OnComponentAdded信號以透過該資訊來初始化代理：

// At any system...
  public unsafe class AISystem : SystemMainThread, ISignalOnComponentAdded<HFSMAgent>
  {
    public void OnAdded(Frame f, EntityRef entity, HFSMAgent* component)
    {
      // This is how you get the HFSMRoot from the component set on the Entity Prototype
      HFSMRoot hfsmRoot = f.FindAsset<HFSMRoot>(component->Data.Root.Id);

      // Then we just do the initialization step
      HFSMManager.Init(f, entity, hfsmRoot);
    }

  // ...
  }

更新代理

現在，已經初始化實體的HFSM代理，您只需要在您需要的時候調用更新方法：

HFSMManager.Update(f, f.DeltaTime, myEntity);

這將使HFSM執行其初始狀態的資料並且執行動作及轉換到其他狀態。有了這個，AI應該已經執行您在視覺編輯器上建立的流程。

一個範例系統，其初始化及更新代理

namespace Quantum
{
  public unsafe class AISystem : SystemMainThread, ISignalOnComponentAdded<HFSMAgent>
  {
    public void OnAdded(Frame f, EntityRef entity, HFSMAgent* component)
    {
      HFSMRoot hfsmRoot = f.FindAsset<HFSMRoot>(component->Data.Root.Id);
      HFSMManager.Init(f, entity, hfsmRoot);
    }

    public override void Update(Frame f)
    {
      var allAgents = f.Filter<HFSMAgent>();
      while(allAgents.NextUnsafe(out var entity, out var agent))
      {
        HFSMManager.Update(f, f.DeltaTime, entity);
      }
    }
  }
}

編碼動作及決策

為了建立您自己的動作，遵循這些指引：編碼動作

建立您自己的決策，是非常相似的。但是，不是建立一個其繼承於AIAction的新的層級，而是讓其繼承於HFSMDecision抽象層級。

同時，不是必須執行Update方法，而是必須執行Decide方法。使用它來傳回true/false，這取決於您自己的需要。

重要事項：您需要標記您的新的層級為[Serializable]及partial。

namespace Quantum
{
  [Serializable]
  public partial class TrueDecision : HFSMDecision
  {
    public override unsafe bool Decide(Frame frame, EntityRef entity)
    {
      return true;
    }
  }
}

定義欄位值

關於設定值到動作／決策欄位時，您可使用的替代方案的更多資訊，請參見這裡：定義欄位值.

AI參數

如果您希望有更彈性的欄位，並且透過不同的方式來定義這些欄位的話，這些關於使用AI參數的資訊很有用：手動設定或從黑板／常數／設定節點來設定：AI參數.

AI內容

如需取得更多關於如何將代理內容的資訊作為參數傳送的資訊，請參見這裡：AI內容.

機器人SDK系統

這是一個層級，其用於自動執行一些流程，比如解除配置黑板的記憶體。如需取得更多關於它的資訊，請參見這裡：機器人SDK系統.

偵錯工具

機器人SDK帶有其自己的偵錯工具。它使開發人員可以在運行階段選擇任何HFSM代理，並且看見在視覺編輯器上醒目提示的最新的代理的流程。這裡是一個用於機器人SDK範例專案的偵錯工具的範例：

如同上述GIF所顯示，可以看到代理的當前狀態，以及導致該狀態的最近三次轉換。藍色轉換是最近的一次轉換。比起先前的黑色轉換，它也有更多圓圈穿過線條。

此外，也可以檢查階層檢視上的目前狀態。帶有箭頭的狀態代表HFSM目前處於該狀態。這很有幫助，因為您不需要深入查看視覺圖表來了解代理目前在階層的深度。

使用偵錯工具

這是在您的專案上使用偵錯工具的步驟：

在您的SystemSetup.cs檔案上啟用BotSDKDebuggerSystem。使用這個特定的系統是選擇性的，因為如果您希望在其他地方使用偵錯邏輯，您只需 在已驗證幀時 在您自己的自訂系統中調用BotSDKDebuggerSystem.OnVerifiedFrame?.Invoke(f);；
在視覺編輯器上，在頂層面板上按一下臭蟲圖示。當圖示為綠色時，偵錯為啟用；

現在有兩個方式來選擇將偵錯哪個實體。它可以被關聯到一個選取的遊戲物件，或它可以在一個檢查器上被選取。您可以選擇上述的其中之一。或者兩個都選：

從一個遊戲物件來偵錯：

選取您的代表一個有HFSMAgent作為一個元件的Quantum實體的預製件／實體原型；
新增BotSDKDebugger到它；
在運行階段，開啟機器人SDK視窗時，選取已新增BotSDKDebugger的遊戲物件。這樣就行了！偵錯應該已經開始；

從一個偵錯工具檢查器視窗來偵錯：

在模擬側，您需要註冊代理實體到偵錯工具視窗。為了完成它，可以調用：

BotSDKDebuggerSystem.AddToDebugger(entitiRef, (optional) customLabel)

針對被偵錯的實體，預設的顯示名稱遵循這個規則：Entity XX | AIAssetName。但如果您希望針對偵錯輸入而言有一個自訂名稱，您可以使用customLabel參數。您可以自由決定它。

也可以建立階層。只需在自訂標籤上使用分隔符號/，它將在偵錯工具視窗上建立階層，其可以被摺疊、擴展等等；
在Unity上，按一下在偵錯工具啟用按鈕右側的按鈕。它開啟一個新的視窗，其顯示所有已註冊實體。選取您希望進行偵錯的實體，這樣就完成了。

舉例而言，上述範例GIF中使用一些自訂標籤：Monster 1, Monster 2, Blue Team/Commander, Blue Team/Warriors/Foo, Blue Team/Warriors/Fuz and Blue Team/Wizards/Bar

重要事項： 當啟用偵錯工具，它將配置記憶體來儲存偵錯所需的資料，如果您正在 從編輯器遊玩，其 可能減慢 遊戲。所以，如果您正在從Unity之內來分析應用程式，部分分析可能被關聯到偵測工具，所以請考慮在分析時停用它。

附註：偵錯工具視窗也將顯示 沒有實體檢視 的實體，所以這就是您如何找到它來偵錯它們的HFSM的方式；

附註2：目前，不可以偵錯沒有連接到一個實體的代理，比如仰賴DSL全域的代理。這將只在以後的版本中新增。

視覺編輯器註解

如需取得更多如何在視覺編輯器上建立註解的資訊，請參見這裡：視覺編輯器註解.

更改編譯匯出資料夾

預設下，機器人SDK編譯生成的資產將放在Assets/Resources/DB/CircuitExport資料夾。您更改匯出資料夾的方式，請參見這裡：更改編譯匯出資料夾.

選擇被儲存的歷史大小

可以更改儲存在機器人SDK檔案的歷史輸入的數量。如需取得更多資訊，請參見這裡：更改歷史儲存計數.

在幀中發生的事

在機器人SDK上，主要輸入點為：

HFSMManager.Update，其被持續地調用，以更新您的代理；
HFSMManager.Init，其用於初始化代理；
HFSMManager.TriggerEvent，其考量一個已觸發事件以強制進行轉換檢查。

為了協助更好地視覺化當調用這些方法時，在一個幀發生的事情，這裡是一個流程圖表：