This document is about: QUANTUM 2

SWITCH TO

QUANTUM 1 QUANTUM 2 QUANTUM 3

This page is a work in progress and could be pending updates.

Assets in Simulation

資料資產類別

Quantum資產是正常C#類別，其在運行階段將作為不可變的資料容器。一些規則定義了這些資產在Quantum中必須被設計、執行及使用的方式。

這是一個附有一些簡單的確定性屬性的資產類別（針對一個角色規格）的一個最小的定義：

namespace Quantum {
  partial class CharacterSpec {
    public FP Speed;
    public FP MaxHealth;
  }
}

請注意，資產類別定義必須是部分，並且被內含在Quantum命名空間之中。

本章節後面將討論建立及載入資產類別的執行個體到資料庫（從Unity編輯）。

使用及連接資產

為了告訴Quantum這是一個資產類別（透過使內部中繼資料繼承基本 資產物件 類別，並且準備資料庫來內含內部中繼資料的執行個體，來新增內部中繼資料）：

// this goes into a DSL file
asset CharacterSpec;

資產執行個體是不可變的物件，其必須以參照來被執行。因為正常C#物件參照不允許被包含在我們的記憶體對齊的ECS架構中，因此必須在DSL中使用 asset_ref 特殊類型，以在遊戲狀態中宣告屬性（從實體、元件或任何其他暫時性資料架構）：

component CharacterData {
    // reference to an immutable instance of CharacterSpec (from the Quantum asset database)
    asset_ref<CharacterSpec> Spec;
    // other component data
}

為了在建立一個角色實體時，指派一個資產參照，一個選項是從幀資產資料庫直接地取得執行個體，並且將其設定到屬性：

// assuming cd is a pointer to the CharacterData component
// using the SLOW string path option (fast data driven asset refs will be explained next)
cd->Spec = frame.FindAsset<CharacterSpec>("path-to-spec");

資產的基本使用是在運行階段讀取資料，並且將其應用到系統之中的任何計算。以下實例從被指派的 角色規格 使用速度值，以計算相應的角色速度（物理引擎）：

// consider cd a CharacterData*, and body a PhysicsBody2D* (from a component filter, for example)
var spec = frame.FindAsset<CharacterSpec>(cd->Spec.Id);
body->Velocity = FPVector2.Right * spec.Speed;

關於確定性的注意事項

請注意，上述程式碼只讀取速度屬性，以在運行階段針對角色計算所需的速度，但是它的值（速度）將永不改變。

在運行階段從一個更新中轉換一個遊戲狀態資產參照，是完全安全且有效的（因為asset_ref是一個可復原的類型，因此其可以是遊戲狀態的一部分）。

然而，更改一個資料資產的屬性的值並不是確定性的（因為在資產上的內部資料不被認為是遊戲狀態的一部分，因此它永不被復原）。

以下的程式碼片段展示了在運行階段哪些是安全（轉換參照）及不安全（更改內部資料）的實例：

// cd is a CharacterData*

// this is VALID and SAFE, as the CharacterSpec asset ref is part of the game state
cd->Spec = frame.FindAsset<CharacterSpec>("anotherCharacterSpec-path");

// this is NOR valid NEITHER deterministic, as the internal data from an asset is NOT part of the transient game state:
var spec = frame.FindAsset<CharacterSpec>("anotherCharacterSpec-path");
// (DO NOT do this) changing a value directly in the asset object instance
spec.Speed = 10;

資產物件組態屬性

您可以透過AssetObjectConfig屬性來微調資產連結指令碼生成。

[AssetObjectConfig(GenerateLinkingScripts = false)]
partial class CharacterSpec {
    // ...
}

生成連結指令碼 （預設=真）——防止生成任何讓資產在Unity中成為可編輯的指令碼。
生成資產建立選單 （預設=真）——針對此資產，防止Unity CreateAssetMenu屬性的生成。
生成資產重新設定方法 （預設=真）——防止Unity可指令碼物件Reset()方法的生成（其中當建立資產時，一個Guid被自動地生成）。
自訂建立資產選單名稱 （預設=空）——覆寫CreateAssetMenu名稱。如果設定為null，將使用繼承圖表來自動地生成一個選單路徑。
自訂建立資產選單順序 （預設=-1）——覆寫CreateAssetMenu順序，如果設定為-1，將使用字母的順序。

覆寫資產指令碼位置及停用AOT檔案生成

建立檔案 tools\codegen_unity\quantum.codegen.unity.dll.config。警示：升級時需小心，因為檔案在該過程中可能遺失。

XML

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <add key="RelativeLinkDrawerFilePath" value="Quantum/Editor/PropertyDrawers/Generated/AssetLinkDrawers.cs"/>
    <add key="RelativeAssetScriptFolderPath" value="Quantum/AssetTypes/Generated"/>
    <add key="RelativeGeneratedFolderPath" value="Quantum/Generated"/>
    <add key="GenerateAOTFile" value="true"/>
    <add key="EndOfLineCharacters" value="&#13;&#10;"/>
  </appSettings>
</configuration>

資產繼承

在資料資產中可以使用繼承，其提供開發者非常多的彈性（特別是當與多型方法一起使用的時候）。

繼承的基本步驟是建立一個抽象基礎資產類別（我們將繼續使用我們的 角色規格 實例）：

namespace Quantum {
  partial abstract class CharacterSpec {
    public FP Speed;
    public FP MaxHealth;
  }
}

角色規格 的實體子類別可能會新增它們自己的自訂資料屬性，並且必須被標記為 可序列化的 類型：

namespace Quantum {
  [Serializable]
  public partial class MageSpec : CharacterSpec {
    public FP HealthRegenerationFactor;
  }

  [Serializable]
  public partial class WarriorSpec : CharacterSpec {
    public FP Armour;
  }
}

在DSL中

當您已經在DSL中宣告一個資產，您可以在DSL中使用asset_ref<T>類型，以參照到基礎類別和其任何子類別。

component CharacterData {
  // Accepts asset references to CharacterSpec base class and its sub-classes(MageSpec and WarriorSpec).
  asset_ref<CharacterSpec> ClassDefinition;
  FP CooldownTimer;
}

如果您希望保留一個特定到一個子類別的參照，首先需要在DSL中使用asset import來宣告被衍生的資產：

asset CharacterSpec;
asset import MageSpec;

如果在DSL中已經宣告被衍生的資產，只需使用asset_ref<T>作為基礎類別。舉例而言，為了使用直接地在DSL中MageSpec而非CharacterSpec，我們需要寫下列程式碼：

component MageData {
  // Only accepts asset references to MageSpec class.
  asset_ref<MageSpec> ClassDefinition;
  FP CooldownTimer;
}

由資料驅動的多型

讓遊戲遊玩邏輯直接地評估（在假如或轉換陳述式中）實體 角色規格 類別，將是一個非常糟糕的設計，所以當和多型方法搭配時，資產繼承更有道理。

請注意，新增邏輯到資料資產，意味著在quantum.state專案中執行邏輯，而這個邏輯仍然必須考慮以下限制：

在暫時性遊戲狀態資料上操作：這意味著在資料資產中的邏輯方法必須收到暫時性資料作為參數（實體指標或是幀物件本身）；
只讀取，永不修改資產上的資料：資產必須仍然被對待為 不可變的 唯讀執行個體；

以下實例新增一個虛擬方法到基礎類別，並且新增一個自訂執行方式到子類別中的一個（請注意，我們在此文檔頂部使用了更多的針對角色實體所定義的健康欄位）：

namespace Quantum {
  partial unsafe abstract class CharacterSpec {
    public FP Speed;
    public FP MaxHealth;
    public virtual void Update(Frame f, EntityRef e, CharacterData* cd) {
      if (cd->Health < 0)
        f.Destroy(e);
    }
  }

  [Serializable]
  public partial unsafe class MageSpec : CharacterSpec {
    public FP HealthRegenerationFactor;
    // reads data from own instance and uses it to update transient health of Character pointer passed as param
    public override void Update(Frame f, EntityRef e, CharacterData* cd) {
      cd->Health += HealthRegenerationFactor * f.DeltaTime;
      base.Update(f, e, cd);
    }
  }
}

為了獨立地使用這個指派到各個 角色資料 的實體資產的有彈性的方法執行方式，這可以從任何系統被執行：

// Assuming cd is the pointer to a specific entity's CharacterData component, and entity is the corresponding EntityRef:

var spec = frame.FindAsset<CharacterSpec>(cd->Spec.Id);
// Updating Health using data-driven polymorphism (behavior depends on the data asset type and instance assigned to character
spec.Update(frame, entity, cd);

在資產中使用DSL生成的架構

在DSL中定義的Structs也可以在資產上被使用。DSL架構必須以[Serializable]屬性來標註，不然資料在Unity中無法被檢查。

[Serializable]
struct Foo {
  int Bar;
}

asset FooUser;

在一個Quantum資產中使用DSL struct。

namespace Quantum {
  public partial class FooUser {
    public Foo F;
  }
}

如果一個架構不是[Serializable]——友善地（比如，因為它是一個聯集或含有一個Quantum集合），可取而代之地使用原型：

using Quantum.Prototypes;
namespace Quantum {
  public partial class FooUser {
    public Foo_Prototype F;
  }
}

在需要時，原型可以被具體化到模擬架構：

Foo f = new Foo();
fooUser.F.Materialize(frame, ref f, default);

動態資產

在運行階段可以透過模擬來建立資產。這個功能稱為 動態資產DB。

var assetGuid = frame.AddAsset(new MageSpec() {
  Speed = 1,
  MaxHealth = 100,
  HealthRegenerationFactor = 1
});

該資產可以如同任何其他資產一樣被載入和處置：

MageSpec asset = frame.FindAsset<MageSpec>(assetGuid);
frame.DisposeAsset(assetGuid);

動態資產不在同儕節點間同步。取而代之地，建立新資產的程式碼需要是確定性，並且確保各個同儕節點將使用相同的值來處理一個資產。

針對上述規則的唯一的例外是當有一個延遲加入的時候——新的客戶端將收到一個 動態資產DB 的快照以及最新的幀資料。不同於幀的序列化，動態資產的序列化及取消序列化是在模擬之外被委派到IAssetSerializer介面。當在Unity中運行時，預設使用QuantumUnityJsonSerializer：可以序列化／取消序列化任何可Unity序列化的類型。

初始化動態資產DB

可透過預先存在的動態資產來初始化模擬。類似於在模擬時新增資產，在客戶端間，這些需要是確定性。

首先，需要建立及以資產填入DynamicAssetDB的一個執行個體：

var initialAssets = new DynamicAssetDB();
initialAssets.AddAsset(new MageSpec() {
    HealthRegenerationFactor = 10
});
initialAssets.AddAsset(new WarriorSpec() {
    Armour = 100
});
...

第二，需要使用QuantumGame.StartParameters.InitialDynamicAssets來傳遞執行個體到一個新的模擬。在Unity中，因為管理一個QuantumGame的是QuantumRunner行為，因此取而代之地使用QuantumRunner.StartParamters.InitialDynamicAssets。

資料資產類別
使用及連接資產

關於確定性的注意事項
資產物件組態屬性
覆寫資產指令碼位置及停用AOT檔案生成

資產繼承

在DSL中
由資料驅動的多型
在資產中使用DSL生成的架構

動態資產

初始化動態資產DB