Reactive Entity Setsガイド

実験的機能 - Reactive Entity Setsはv2.1.0で利用可能です。APIは将来のバージョンで変更される可能性があります。本番環境での使用は自己責任で行ってください。

重要な注意 — ランタイムデータの永続性 ScriptableObjectはシーンをまたいでデータを保持できますが、シーン遷移中にどのオブジェクトからも参照されなくなると、Unityによってメモリからアンロードされランタイムデータが消失します。これを防ぐには、Manager SceneパターンとReactiveEntitySetHolderを使用してください。詳細は永続化を参照してください。

目的

このガイドでは、集中化されたエンティティ状態管理のためのReactive Entity Setsの使い方を説明します。Runtime Setsとの違い、エンティティデータの定義方法、エンティティごとの状態変更のサブスクライブ方法を学びます。

Reactive Entity Setsとは？

Reactive Entity Setsは、自動変更通知付きでエンティティごとのデータを格納するScriptableObjectベースの状態コンテナです。オブジェクト参照のみを追跡するRuntime Setsとは異なり、Reactive Entity Setsは各エンティティの実際の状態（体力、スコア、ステータスエフェクト）を格納します。

// エンティティIDで状態を格納
entitySet.Register(this, new EnemyState { Health = 100 });

// どこからでも状態を読み取り
var state = entitySet.GetData(entityId);

// 自動イベント付きで状態を更新
entitySet.UpdateData(this, state => {
    state.Health -= 10;
    return state;
});

このアーキテクチャは以下を可能にします。

  • エンティティ状態がシーンロードをまたいで保持される
  • IDで任意のエンティティの状態にアクセスできる
  • Sparse Setによる定数時間操作（O(1)）
  • 特定のエンティティの変更をサブスクライブできる

いつReactive Entity Setsを使うか

Reactive Entity Setsを使う場合

  • エンティティごとの状態が必要（体力、マナ、ステータスエフェクト）
  • オブジェクトを取得せずにIDでルックアップしたい
  • 状態をシーン間で永続化する
  • 外部システムからエンティティデータを読み取る（UI、AI、ネットワーク）

Runtime Setsを使う場合

  • アクティブなオブジェクトの追跡のみが必要（エンティティごとの状態なし）
  • 個別データを必要とせず全オブジェクトを反復する
  • IDベースのルックアップが不要

比較

機能 Runtime Sets Reactive Entity Sets
格納 オブジェクト参照 エンティティごとのデータ構造体
ルックアップ 反復のみ IDでO(1)
イベント コレクション変更 エンティティごと + コレクション
永続化 シーンライフサイクル ScriptableObject
ユースケース オブジェクト追跡 状態管理

クイック判断ガイド

シナリオ 使用
レベル内のすべての敵を追跡 Runtime Set
各敵の体力とステータスを格納 Reactive Entity Set
ミニマップアイコンを表示 Runtime Set
個別のヘルスバーを表示 Reactive Entity Set

アーキテクチャ概要 

flowchart TB
    subgraph EntitySet["ReactiveEntitySetSO<EnemyState>"]
        SS[Sparse Set]
        subgraph Data["エンティティごとの状態"]
            D1["ID: 101 → Health: 80"]
            D2["ID: 102 → Health: 100"]
            D3["ID: 103 → Health: 45"]
        end
        Traits["Traitsマスク (ulong)"]
        subgraph Events["イベントチャンネル"]
            E1[OnItemAdded]
            E2[OnItemRemoved]
            E3[OnDataChanged]
            E4[OnTraitAdded]
        end
    end

    View[ReactiveView]

    Enemy1[Enemy 101] -->|Register/Update| SS
    Enemy2[Enemy 102] -->|Register/Update| SS
    SS --> Data
    SS --> Traits

    Data -->|状態変更| E3
    Traits -->|Traits変更| E4
    E3 -->|通知| UI[ヘルスバーUI]
    E3 -->|通知| AI[AIシステム]
    E4 -->|フィルタードメンバーシップ| View

Sparse Set — O(1)の登録・検索・削除を実現するデータ構造です。エンティティIDから状態データへの高速なマッピングを提供します。

データは3つのステージでシステムを流れます。

  1. エンティティスポーン → ReactiveEntity.OnEnable() → EntitySetに登録
  2. 状態更新 → UpdateData() → エンティティごとのコールバックが発火
  3. エンティティ破棄 → ReactiveEntity.OnDisable() → EntitySetから登録解除

ガイドセクション

ページ 説明
基本的な使い方 state構造体の定義、アセット作成、エンティティ登録
イベント エンティティごとのサブスクリプション、セットレベルの通知
Traits エンティティの分類とフィルタリングのためのビットマスクフラグ
Views メンバーシップを自動追跡するリアクティブなフィルタードサブセット
パターン ボスヘルスバー、ステータスエフェクト、セーブ/ロード
ベストプラクティス パフォーマンスのヒント、トラブルシューティング
永続化 シーン遷移時のデータ消失を防ぐ
Job System Orchestratorを使った高性能並列処理
可観測性 集合論的可観測性とスナップショットパターン

関連ドキュメント

設計思想と理論的基礎はRES設計を参照してください。

Table of contents

This site uses Just the Docs, a documentation theme for Jekyll.