UEFNでプレイヤーが退出した際、Verseのweak_mapは自動クリーンアップされるのか？
要点まとめ
UEFNのVerseにおいて、プレイヤーが退出した際に`weak_map`からプレイヤーのエントリが自動的に削除されない問題とその対策を解説しています。手動でクリーンアップを行わない場合、古いオブジェクト参照によるruntime crashやメモリリーク、Epicのクラウドセーブ制限超過といった深刻な問題が発生します。本記事では、一時的なセッションデータと永続データを分離し、カスタムマップの再構築によって安全にセッション状態を管理する手順やベストプラクティスを提示しています。
AIコーディングアシスタントの「プレイヤーがフォートナイト島から切断した瞬間に、Verseは自動的にweak_mapからプレイヤーデータをパージする」という言葉を鵜呑みにしていると、深刻なruntime crashを引き起こす原因になります。プレイヤーオブジェクトがGarbage Collectionされた時点で、weak referenceであるためエンジンがキーをクリーンアップするはずだ、という主張は論理的に聞こえるかもしれません。しかし、Unreal Editor for Fortnite（UEFN）における現実ははるかに複雑であり、Verseのメモリマネージャーがプレイヤーのライフサイクルを処理する方法を誤解すると、予期せぬ状態のリークや致命的な例外（exception）を引き起こします。
プレイヤーが退出した後に、マップ内の古いオブジェクトを参照しようとすると、恐ろしいErrRuntime_WeakMapInvalidKeyエラーが発生したり、島全体のクラッシュを引き起こしたりする可能性があります。サーバーの安定性を維持するためには、厳格なUEFN server crash fix protocolを実装する必要があります。これを回避するために、デベロッパーはVerseが内部でどのようにメモリを処理しているかを理解し、明示的なクリーンアップルーチンを実装する方法を学ぶ必要があります。
誤解：AIによるアドバイス vs Verseの現実
多くのデベロッパーが、プレイヤーがマッチを退出した際にそのプレイヤーのマップデータをどのように処理すべきか、AIアシスタントに質問しています。よくあるAIのアドバイスは、「エンジンはプレイヤーキーを『weak reference』として扱うため、退出時にマップからプレイヤーのエントリを自動的に削除する」というものですが、これは根本的に誤りです。
Verseのweak_map(player, t)は、Garbage Collectionを妨げるハード参照サイクルを防ぐために内部的にweak referenceをキーとして使用していますが、マップエントリ自体の自動的かつ即座のクリーンアップは行いません。キーのスロットとそれに関連付けられたデータの両方を含むエントリは、マップコンテナ内に割り当てられたまま残ります。
プレイヤーが退出した後にコードがそのキーにアクセス、評価、または変更を試みると、Verseのruntimeはnullまたは無効なplayerオブジェクトをデリファレンスしようとします。正常に処理を失敗させる代わりに、runtimeはクラッシュを引き起こすか、キャッチ不可能な例外を発生させます。システムは、自動的なクリーンアップに依存するのではなく、デベロッパーが明示的にライフサイクルの移行を処理することを想定しています。
weak_mapがプレイヤーエントリを自動クリーンアップしない理由
これが起こる理由を理解するには、UEFNにおけるweak_mapの目的を見る必要があります。弱いマップが一時的なメモリキャッシュとして機能する一般的なプログラミング環境とは異なり、Verseは主に**persistent player data（永続的なプレイヤーデータ）**の管理者としてweak_map(player, t)を使用します。
プレイセッションをまたぐ永続化
モジュールスコープで宣言されたweak_map(player, t)を使用すると、エンジンはその値をEpicの永続的なクラウドデータベースにフックします。プレイヤーがマッチを退出して3日後に戻ってきた場合、エンジンはプレイヤーIDを永続的なマップキーと照合して、その進行状況を復元します。
もしプレイヤーがゲームを退出した瞬間にエンジンがマップからそのエントリを自動的に消去していたら、マップはすべての永続データを失うことになります。プレイヤーが切断されたり、ネットワークタイムアウトが発生したりするたびに、レベル、カスタム通貨、アンロックされたアイテムがゼロにリセットされてしまいます。したがって、データベースは、切断をまたいでデータを維持することを目的に、これらのエントリをそのまま保持するように設計されています。
プレイヤーオブジェクトのスコープされたライフタイム
プレイヤーがマッチを退出すると、playspace内のアクティブなセッションオブジェクトは破棄されます。Verseコードによって保持されている物理的なplayer参照は、無効なハンドル（デッドハンドル）になります。
マップ内のキーが無効かつ非アクティブなオブジェクトを指すようになるため、そのデッドな参照を使用してマップに問い合わせを行うと失敗します。エンジンは、リアルタイムでマップからデッドなキーをスキャンしてスクラブするような動作は行いません。代わりにそれらを不活性な状態のまま残すため、古い参照（stale reference）の蓄積を防ぐには手動での管理が不可欠となります。
その結果生じる影響：メモリリーク、古いデータ、そしてサーバークラッシュ
プレイヤーエントリのクリーンアップを怠ると、長いマッチにおいてゲームのパフォーマンスとサーバーの安定性を低下させる3つの明確な問題が発生します。
- 古いデータのリーク（Stale Data Leakage）： プレイヤーが退出し、別のプレイヤーが参加した際、エンジンが内部のプレイヤースロットを再利用すると、新しいプレイヤーが古いプレイヤーのセッションデータを引き継いでしまう可能性があります。これにより、新しいプレイヤーがインベントリいっぱいの状態でスポーンしたり、誤ったマッチ統計が表示されたりする状態バグが発生します。
- メモリの蓄積（Memory Accumulation）： 単一のbooleanやintegerが占めるスペースは無視できるほど小さいですが、高容量のロビーで最大50人のプレイヤーに対して複雑な構造体を格納すると、メモリ使用量が増加する可能性があります。4時間のサーバーセッションにわたり、この蓄積はサーバーのティックレートを低下させる原因になります。
- ルックアップの失敗（Look-up Failures）： 非アクティブなプレイヤーのステータスをクエリしようとしたり、デッドなプレイヤー参照に対して関数を呼び出したりすると、即座にruntime crashが引き起こされます。
Epicクラウドセーブ制限への到達
UEFNは永続データに対して厳格な制限を課しています。島ごとに最大4つの永続的なweak_mapに制限されており、各プレイヤーの個別レコードサイズは256 KBを超えることはできません。
一時的なセッション状態を保存するために永続的なweak_mapを使用すると、この貴重なデータベーススペースを無駄にすることになります。更新のたびにEpicのデータベースへの書き込みが発生し、書き込みスロットリングのペナルティを受けたり、256 KBの制限を超えたりするリスクがあり、さらにデータを書き込もうとしたときにランタイムエラーが発生します。
ステップバイステップ・チュートリアル：プレイヤーのセッション状態を安全に管理する
メモリリークやデータベースの肥大化を招くことなくプレイヤーの状態を管理するには、一時的なセッションデータと永続的なクラウドデータを分離する必要があります。一時的なデータは標準の非永続的なマップに保存し、プレイヤーの切断時に手動でクリーンアップする必要があります。
ステップ1：セッション状態の構造体（Struct）を定義する
まず、シングルラウンドまたはマッチ中にプレイヤーが必要とするすべての変数を含む、永続化しない構造体（struct）を定義します。このクラスまたは構造体に<persistable>の指定をしないでください。
# Define the transient data structure for active gameplay tracking
player_session_state := struct:
IsMoneyBagFull : logic = false
CurrentGold : int = 0
SpawnTime : float = 0.0
ステップ2：マネージャーデバイスを構築する
コーディネーターとして機能するcreative deviceを作成します。これは、アクティブなプレイヤーの変更可能な非永続的マップを保持します。Verseの標準マップは不変（immutable）であるため、プレイヤーが参加または退出したときに上書きできるように、マップ変数をvarとして宣言します。
using { /Fortnite.com/Devices }
using { /Fortnite.com/Playspaces }
using { /Verse.org/Simulation }
# Device handling player lifecycle events and session state mapping
state_manager_device := class(creative_device):
# Non-persistent map for tracking active player sessions
var SessionStates : [player]player_session_state = map{}
ステップ3：Playspaceイベントの購読（Subscribe）
OnBegin関数内で、playspaceの接続イベントを購読（subscribe）します。これにより、プレイヤーが参加したときに初期化コードを実行し、退出したときにクリーンアップコードを実行できるようになります。
OnBegin<override>()<suspends>:void=
GetPlayspace().PlayerAddedEvent().Subscribe(OnPlayerAdded)
GetPlayspace().PlayerRemovedEvent().Subscribe(OnPlayerRemoved)
# Initialize any players already in the session (useful for UEFN hot-reloading)
for (Player : GetPlayspace().GetPlayers()):
OnPlayerAdded(Player)
ステップ4：登録およびクリーンアップロジックの実装
プレイヤーが参加したときは、デフォルトのセッション状態をマップに追加します。プレイヤーが退出したときは、マップからそのエントリをパージする必要があります。Verseには組み込みのMap.Remove()関数が存在しないため、退出するプレイヤーをフィルタリングしてマップを再構築する必要があります。これにより、古い参照がメモリに残り続けるのを防ぎます。
# Triggered when a player connects to the server
OnPlayerAdded(Player: player):void=
if (not SessionStates[Player]):
InitialState := player_session_state{IsMoneyBagFull := false, CurrentGold := 0, SpawnTime := GetEngineTime()}
if (set SessionStates[Player] = InitialState):
Print("Initialized gameplay state for joining player.")
# Triggered when a player disconnects or leaves the game
OnPlayerRemoved(Player: player):void=
Print("Player disconnected. Initiating map cleanup.")
RemovePlayerSession(Player)
# Purges the player's entry by reconstructing the map
RemovePlayerSession(PlayerToRemove: player):void=
var CleanedStates : [player]player_session_state = map{}
for (ActivePlayer -> State : SessionStates):
# Copy all players except the one who left
if (ActivePlayer <> PlayerToRemove):
if (set CleanedStates[ActivePlayer] = State):
# Entry successfully migrated to the cleaned map
set SessionStates = CleanedStates
Print("Successfully removed player session entry from memory.")
プレイヤーの削除時にマップを再構築することで、参照キーを完全に削除します。これにより、Garbage Collectorはゲームループ内に古いエントリを残すことなく、プレイヤーのリソースを回収できます。
これらのライフサイクルの移行時にカスタムtelemetryを追跡したい場合は、セッション時間や通貨の統計情報を外部のBackendにレポートする際、32-character analytics event name limit in Verseのような制限にも留意する必要があります。
Verseの状態管理におけるベストプラクティス
UEFNサーバーの安定性とパフォーマンスを維持するために、プレイヤーデータの管理について以下のガイドラインに従ってください。
- セッションデータと永続データの区別： 短寿命の変数（現在のマッチ時の体力、ラウンドスコア、一時的な位置など）を永続的な
weak_mapに保存しないでください。一時的な状態は、マネージャークラスにラップされた標準の変更可能（mutable）なマップに保持します。 IsActiveによるプレイヤーのアクティビティ確認： 任意のマップでプレイヤーのデータを取得または変更する前に、IsActive[]クエリを使用してそのプレイヤーがまだplayspaceに存在するかどうかを確認してください。IsActive[]がfalseを返した場合は、ルックアップを中止し、クリーンアップイベントをトリガーします。FitsInPlayerMapによるデータサイズ監視： 永続的なweak_mapに書き込む際は、FitsInPlayerMap()を呼び出して更新データが256 KBの制限を超えないことを確認し、ランタイム例外を防ぎます。- マップの集約： 変数ごとに個別のマップを作成しないでください。すべてのプレイヤー変数を含む単一のクラスを定義し、プレイヤーをそのクラスにマッピングします。これにより、マップの数を最小限に抑え、島あたり最大4つの永続的なweak_mapという制限を遵守できます。
信頼性の高いクラウドBackendへの複雑さのオフロード
Verseでのプレイヤーセッションのライフサイクル、データベースの制限、および手動クリーンアップロジックの管理は、すぐに複雑化する可能性があります。セッションをまたぐ進行状況の保存、グローバルに同期されたインベントリ、あるいは地域ごとのMatchmakingなどを構築する必要がある場合、これらの状態を手動で管理するには、Webhookの設定、外部データベースのスケーリング、サーバー間同期の処理が必要になります。
horizOnを使用すれば、これらのBackendの課題は自動的に処理されます。horizOn SDKをゲームサーバーに統合することで、プレイヤーセッション管理を専用のクラウドデータベースにオフロードできます。プレイヤーが切断すると、horizOnは自動セッションクリーンアップをトリガーし、グローバルデータベースを更新して、Verseの256 KBメモリ制限やruntime crashのリスクを回避しながら、サーバーインスタンス間でインベントリレコードを同期します。
UEFNのBackendをスケールアップする準備はできましたか？無料でhorizOnをお試しいただくか、API docsをご覧ください。