ゲームセッションを統合する

Last updated on July 14, 2026

注釈：本資料はAI技術を用いて翻訳されています。

概要​

AGS Game SDK または Extend SDK を通じて、AccelByte Gaming Services (AGS) Session でゲームセッションを管理できます。この記事では、ゲームセッションの統合方法を説明し、以下に関するコードスニペットを提供します。

  • ゲームセッションの作成
  • ゲームセッションリストのクエリ
  • 現在のユーザーのゲームセッションの取得
  • ゲームセッション詳細の取得
  • ゲームセッションの更新
  • ゲームセッションの削除
  • プレイヤーをゲームセッションに招待
  • ゲームセッションへの参加
  • ゲームセッション招待のキャンセル
  • ゲームセッション招待の拒否
  • ゲームセッションからの退出
  • ゲームセッションリーダーの昇格
  • ゲームセッションからプレイヤーをキック
  • ゲームセッション通知の受信
  • ゲームセッションのリフレッシュ
  • 切断・再接続後のプレイヤーセッションの処理

ゲームセッションを作成する​

作成リクエストに基づいて新しいゲームセッションを作成します。

FApiClientPtr ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient();

FAccelByteModelsV2GameSessionCreateRequest Request;
Request.ConfigurationName = ConfigurationName; // MANDATORY
Request.Joinability = EAccelByteV2SessionJoinability::INVITE_ONLY; // Optional
Request.Type = EAccelByteV2SessionConfigurationServerType::DS; // Optional
Request.ClientVersion = GameServerVersion; // Optional
Request.ServerName = LocalServerName; // Optional
Request.Deployment = Deployment; // Optional
Request.RequestedRegions = {"us-west-1", "us-west2"}; // Optional

// Optional
TArray<FString> TeamA = {TeamAUserId1, TeamAUserId2};
TArray<FString> TeamB = {TeamBUserId1, TeamBUserId2};
TArray<FAccelByteModelsV2GameSessionTeam> Teams;
Teams.Add({TeamA});
Request.Teams = Teams;

// Optional
Request.Attributes.JsonObject = MakeShared<FJsonObject>();
Request.Attributes.JsonObject->SetStringField("PartyAttribute", "Attribute1");

Request.MaxPlayers = 10; // Optional
Request.MinPlayers = 1; // Optional
Request.InactiveTimeout = 30; // Optional
Request.InviteTimeout = 86400; // Optional


ApiClient->Session.CreateGameSession(Request,
     THandler<FAccelByteModelsV2GameSession>::CreateLambda(
        [&](const FAccelByteModelsV2GameSession& Result)
         {
             // Do something when operation is successful
         }),
     FErrorHandler::CreateLambda(
        [&](int32 ErrorCode, const FString& ErrorMessage)
         {
             // Do something when operation fails or has an error
         }));

ゲームセッションリストをクエリする​

リクエストと同じ属性を持つすべてのゲームセッションをクエリします。 サポートされている操作:

  1. EAccelByteV2SessionQueryComparisonOp::EQUAL（equals と同様の特定値によるクエリ比較演算子）
  2. EAccelByteV2SessionQueryComparisonOp::NOT_EQUAL（特定値 notEquals によるクエリ）
  3. EAccelByteV2SessionQueryComparisonOp::CONTAINS（in と同様のクエリ）
  4. EAccelByteV2SessionQueryComparisonOp::NOT_CONTAINS（notIn と同様のクエリ）
  5. EAccelByteV2SessionQueryComparisonOp::GREATER_THAN（greaterThan と同様のクエリ）
  6. EAccelByteV2SessionQueryComparisonOp::GREATER_THAN_EQUAL（greaterThanEquals と同様のクエリ）
  7. EAccelByteV2SessionQueryComparisonOp::LESS_THAN（lessThan と同様のクエリ）
  8. EAccelByteV2SessionQueryComparisonOp::LESS_THAN_EQUAL（lessThanEquals と同様のクエリ）

⚠️ 警告: パフォーマンスに関する考慮事項

クエリパフォーマンスへの影響:

  • 複数の属性を同時にクエリすると、クエリパフォーマンスと応答時間に大きな影響を与えます
  • クエリ条件を追加するたびに、計算の複雑さとデータベースの負荷が増加します
  • 複数の NOT_EQUAL、NOT_CONTAINS、または範囲操作を含む複雑なクエリは、特にリソースを多く消費します

ベストプラクティス:

  • NOT_EQUAL 操作を避ける - これらはテーブルの全件スキャンを必要とし、大規模なデータセットには最適化されていません
  • EQUAL 操作を優先する - これらは Equality, Sort and Range (ESR) インデックスの原則を活用し、最適なパフォーマンスを実現します
  • クエリの複雑さを制限する - フィルタリングに必要な最小限の属性数を使用してください

複雑なクエリ要件やパフォーマンス最適化戦略については、AccelByte サポートに相談し、ゲームフローと規模の要件に合わせたベストプラクティスの推奨事項を入手してください。

FApiClientPtr ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient();

// query with specific value `equals`
FAccelByteModelsV2GameSessionQuery Query;
Query.AddParam("map", EAccelByteV2SessionQueryComparisonOp::EQUAL, "SampleMap");

// query with `in`
TArray<FString> PossibleValues;
PossibleValues.Add(TEXT("solo"));
PossibleValues.Add(TEXT("adventure"));
Query.AddParam("custom_game_mode", EAccelByteV2SessionQueryComparisonOp::CONTAINS, PossibleValues);

// query with range value `greaterThanEquals`
constexpr int32 QueriedGreater = 2;
FAccelByteModelsV2GameSessionQuery Query;
Query.AddParam("level", EAccelByteV2SessionQueryComparisonOp::LESS_THAN_EQUAL, QueriedGreater);

int64 Offset = 0;
int64 Limit = 20;
ApiClient->Session.QueryGameSessions(
    Query,
    THandler<FAccelByteModelsV2PaginatedGameSessionQueryResult>::CreateLambda(
        [&](const FAccelByteModelsV2PaginatedGameSessionQueryResult& Result)
        {
            // Do something when the operation succeeds
        }),
    FErrorHandler::CreateLambda(
        [&](int32 ErrorCode, const FString& ErrorMessage)
        {
            // Do something when the operation fails or has an error
        }),
    Offset,
    Limit);

現在のユーザーのゲームセッションを取得する​

ユーザーのゲームセッションのリストとその情報を取得します。

FApiClientPtr ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient();

ApiClient->Session.GetMyGameSessions(
	THandler<FAccelByteModelsV2PaginatedGameSessionQueryResult>::CreateLambda(
		[&](const FAccelByteModelsV2PaginatedGameSessionQueryResult& Result)
		{
			// Do something when the operation succeeds
		}),
	FErrorHandler::CreateLambda(
		[&](int32 ErrorCode, const FString& ErrorMessage)
		{
			// Do something when the operation fails or has an error
		}));

ゲームセッションの詳細を取得する​

ゲームセッションの識別情報を指定して、特定のゲームセッションの詳細を取得します。

FApiClientPtr ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient();

ApiClient->Session.GetGameSessionDetails( SessionId,
	THandler<FAccelByteModelsV2GameSession>::CreateLambda(
		 [&](const FAccelByteModelsV2GameSession& Result)
		 {
			 // Do something when the operation succeeds
		 }),
	FErrorHandler::CreateLambda(
		 [&](int32 ErrorCode, const FString& ErrorMessage)
		 {
			 // Do something when the operation fails or has an error
		 }));

ゲームセッションを更新する​

特定のゲームセッションのデータを更新します。

FApiClientPtr ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient();

FAccelByteModelsV2GameSessionUpdateRequest Request;
Request.Version = PartyDataVersion; // Mandatory, must be the same version as current data in the backend
Request.Joinability = EAccelByteV2SessionJoinability::INVITE_ONLY; // Optional
Request.Attributes.JsonObject = MakeShared<FJsonObject>(); // Optional
Request.Attributes.JsonObject->SetStringField("AttributeName", "Attribute1"); // Optional
Request.MaxPlayers = 10; // Optional
Request.MinPlayers = 1; // Optional
Request.InactiveTimeout = 30; // Optional
Request.InviteTimeout = 86400; // Optional

ApiClient->Session.UpdateGameSession(GameSessionID, Request, THandler<FAccelByteModelsV2GameSession>::CreateLambda(
	[&](const FAccelByteModelsV2GameSession& Result)
	{
		// Do something when the operation succeeds
	}),
	FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& Message)
	{
		// Do something when operation fails or has an error
	}));

ゲームセッションを削除する​

既存のゲームセッションを削除します。

FApiClientPtr ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient();
ApiClient->Session.DeleteGameSession(SessionId, FVoidHandler::CreateLambda([]
{
   // Successfully deleted game session
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& Message)
{
   // Error deleting game session
}));

プレイヤーをゲームセッションに招待する​

ユーザーの識別情報を指定して、他のプレイヤーをゲームセッションに招待します。

FApiClientPtr ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient();

ApiClient->Session.SendGameSessionInvite(SessionId, UserIdToInvite, FVoidHandler::CreateLambda(
	[&]
	{
		// Do something when the operation succeeds
	}),
	FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& Message)
	{
		// Do something when the operation fails or has an error
	}));

送信済みのゲームセッション招待をキャンセルする​

プレイヤーは送信済みの招待をキャンセルできます。招待された側と招待した側の両方に、招待がキャンセルされたことを知らせる通知が届きます。招待された側は、キャンセルされた後は以前の招待を承諾できません。

// Invitee and inviter listen for session invite canceled notification.
auto OnSessionInviteCanceledDelegate = SessionInterface->AddOnSessionInviteCanceledDelegate_Handle(
	FOnSessionInviteCanceledDelegate::CreateLambda([](const FString& SessionID) // ID of canceled game session.
	{
		// Received invitation canceled.
	}));

// Game session leader (inviter) cancel invitation.
FName GameSessionName = NAME_GameSession;
auto OnCancelSessionInviteCompleteDelegate = SessionInterface->AddOnCancelSessionInviteCompleteDelegate_Handle(FOnCancelSessionInviteCompleteDelegate::CreateLambda(
	[&](const FUniqueNetId& LocalUserId, FName SessionName, const FUniqueNetId& Invitee, const FOnlineError& ErrorInfo)
	{
		bool bInvitationCanceled = ErrorInfo.bSucceeded;
		// Cancel session invitation complete.
	}));

SessionInterface->CancelSessionInvite(PlayerIndex, GameSessionName, *InviteeUniqueNetId);

ゲームセッションに参加する​

セッションの識別情報を指定して、既存のゲームセッションに参加します。

FApiClientPtr ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient();

ApiClient->Session.JoinGameSession(SessionId, THandler<FAccelByteModelsV2GameSession>::CreateLambda(
	[&](const FAccelByteModelsV2GameSession& Result)
	{
		// Do something when the operation succeeds
	}),
	FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& Message)
	{
		// Do something when operation fails or has an error
	}));

コードによるセッションへの参加​

セッションでコードが有効になっている場合、プレイヤーはセッションコードを使ってセッションに参加できます。これはパーティーセッションとゲームセッションの両方に適用されます。ユーザーがコードでセッションに参加する場合、AGS は次のセッションタイプについて招待チェックとセッション参加可否のチェックをバイパスします。

  • OPEN
  • INVITE ONLY
  • Friends Only（メンバーのフレンド、リーダーのフレンド、フレンドのフレンド）

コードで参加するユーザーは、すでに招待されているかどうかにかかわらず、上記の参加可否設定に基づいてセッションに入ることができます。

FString SessionCode = TEXT("yourGameSessionCode");

const FApiClientPtr ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient();
ApiClient->Session.JoinGameSessionByCode(
	SessionCode,
	THandler<FAccelByteModelsV2GameSession>::CreateLambda([&](const FAccelByteModelsV2GameSession& Response)
    	{
        	// Do something if JoinGameSessionByCode succeeded
    	})
	, FErrorHandler::CreateLambda([&bIsDone](const int32 ErrorCode, const FString& ErrorMessage)
    	{
        	// Do something if JoinGameSessionByCode failed

    	}));

ハンギングセッションを回避する​

ハンギングセッションは、ゲームクライアントがプレイヤーがセッションから退出したと想定しているにもかかわらず、実際にはそのプレイヤーがゲームセッションのアクティブなメンバーのままである場合に発生します。この状況は、ゲームがクラッシュしたり強制終了したりした際に、セッションから正常に退出できなかった場合に発生することがあります。

これはバックエンド側とゲームクライアント側の両方のデータの正確性に影響を与える可能性があります。バックエンド側にハンギングセッションのデータが多すぎると、予期しない動作が発生することがあります。例えば、

  • ゲーム管理者が、プレイヤーの最大アクティブセッション数を一度に1セッションのみに設定している場合。
  • バックエンドにハンギングセッションのデータが存在する場合、プレイヤーが古いセッションに登録されたままになっているため、新しいセッションに参加する際にゲームでエラーが発生します。

AccelByte は、ゲームが新しいセッションに参加する前に、プレイヤーのアクティブなセッションを取得し、まずそれらから退出することを推奨しています。これはセッションブラウザーのフローで役立ちます。

実装例については、Byte Wars の サブシステムの実装 - セッションの概要 の記事を参照してください。

プレイヤーのアクティビティを一度に1つのゲームセッションに限定するには、セッションで Auto-leave Game Session オプションを有効にします。これを有効にすると、新しいセッションに参加した際にセッションが自動的にプレイヤーをアクティブなゲームセッションからキックします。これにより、ゲームセッションはパーティーセッションのように動作し、プレイヤーが常に1つのアクティブなゲームセッションにのみ参加できるようになります。詳細については、セッションテンプレートの設定の記事を参照してください。

ゲームセッション招待を拒否する​

他のプレイヤーからのゲームセッション参加への招待を拒否します。

FApiClientPtr ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient();

ApiClient->Session.RejectGameSessionInvite(GameSessionID, FVoidHandler::CreateLambda(
	[&]
	{
		// Do something when the operation succeeds
	}),
	FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& Message)
	{
		// Do something when operation fails or has an error
	}));

ゲームセッションから退出する​

ゲームセッションの識別情報を指定して、現在参加しているゲームセッションから退出します。

FApiClientPtr ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient();

ApiClient->Session.LeaveGameSession(SessionId, FVoidHandler::CreateLambda(
	[&]
	{
		// Do something when the operation succeeds
	}),
	FErrorHandler::CreateLambda([&](int32 ErrorCode, const FString& Message)
	{
		// Do something when operation fails or has an error
	}));

ゲームセッションリーダーを昇格させる​

ゲームセッションリーダーは、他のメンバーをゲームセッションリーダーに昇格させることができます。ゲームセッションリーダーは1人のみのため、以前のリーダーは通常のメンバーになります。

注記

Unreal 用のコードスニペットは近日追加予定です。

ゲームセッションからプレイヤーをキックする​

ゲームセッションリーダーまたはデディケイテッドサーバーは、ゲームセッションからメンバーをキックできます。

const FString GameSessionID = TEXT("game-session-id");
const FString PlayerID = TEXT("player-id");

// Game session leader kick a player from a game session
FApiClientPtr ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient();

ApiClient->Session.KickUserFromGameSession(GameSessionID, PlayerID
	, FVoidHandler::CreateLambda([]()
	{
		// Do something when the operation succeeds
	}),	FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& Message)
	{
		// Do something when operation fails or has an error
	}));

// Dedicated server kicks a player from a game session
FServerApiClientPtr ServerApiClient = AccelByteOnlineSubsystemPtr->GetServerApiClient();
ServerApiClient->ServerSession.KickUserFromGameSession(GameSessionID, PlayerID
	, FVoidHandler::CreateLambda([]()
	{
		// Do something when the operation succeeds
	}),	FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& Message)
	{
		// Do something when operation fails or has an error
	}));

ゲームセッション通知を受信する​

ゲームセッションからのさまざまな更新情報を受け取るために、監視できるゲームセッション通知がいくつかあります。これは WebSocket 接続を使用しており、通知をリアルタイムで受信できるようにしています。

FApiClientPtr ApiClient = AccelByteOnlineSubsystemPtr->GetApiClient();

ApiClient->Lobby.SetV2GameSessionInvitedNotifDelegate(Api::Lobby::FV2GameSessionInvitedNotif::CreateLambda(
	[&](const FAccelByteModelsV2GameSessionUserInvitedEvent& Notif)
	{
		// Do something when a notification is received
	}));

ApiClient->Lobby.SetV2GameSessionMembersChangedNotifDelegate(Api::Lobby::FV2GameSessionMembersChangedNotif::CreateLambda(
	[&](const FAccelByteModelsV2GameSessionMembersChangedEvent& Notif)
	{
		// Do something when a notification is received
	}));

ApiClient->Lobby.SetV2GameSessionJoinedNotifDelegate(Api::Lobby::FV2GameSessionJoinedNotif::CreateLambda(
	[&](const FAccelByteModelsV2GameSessionUserJoinedEvent& Notif)
	{
		// Do something when a notification is received
	}));

ApiClient->Lobby.SetV2GameSessionRejectedNotifDelegate(Api::Lobby::FV2GameSessionRejectedNotif::CreateLambda(
	[&](const FAccelByteModelsV2GameSessionUserRejectedEvent& Notif)
	{
		// Do something when a notification is received
	}));

ApiClient->Lobby.SetV2GameSessionKickedNotifDelegate(Api::Lobby::FV2GameSessionKickedNotif::CreateLambda(
	[&](const FAccelByteModelsV2GameSessionUserKickedEvent& Notif)
	{
		// Do something when a notification is received
	}));

ApiClient->Lobby.SetV2GameSessionUpdatedNotifDelegate(Api::Lobby::FV2GameSessionUpdatedNotif::CreateLambda(
	[&](const FAccelByteModelsV2GameSession& Notif)
	{
		// Do something when a notification is received
	}));

ApiClient->Lobby.SetV2DSStatusChangedNotifDelegate(Api::Lobby::FV2DSStatusChangedNotif::CreateLambda(
	[&](const FAccelByteModelsV2DSStatusChangedNotif& Notif)
	{
		// Do something when a notification is received
	}));

ゲームセッションをリフレッシュする​

Refresh Session メソッドを利用することで、ゲームセッションをリフレッシュしてバックエンドと同期できます。指定する SessionName パラメーターは NAME_GameSession に対応させることができます。

SessionInterface->RefreshSession(SessionName, FOnRefreshSessionComplete::CreateLambda([]()
{
    // On refresh session complete
}));

アクティブなセッションをリフレッシュする​

問題を防止し、バックエンドとの適切な同期を確保するために、以下の関数を使用してクライアントにローカルでキャッシュされているすべてのアクティブなセッションをリフレッシュしてください。

SessionInterface->RefreshActiveSessions(FOnRefreshActiveSessionsComplete::CreateLambda(
    [&](bool bWasSuccessful)
{
    // On refresh active sessions complete
}));

切断・再接続後のプレイヤーセッションを処理する​

プレイヤーの接続が中断され、それによってセッションからプレイヤーが削除されるトリガーが発生するシナリオがあります。セッションからの削除は、ゲームセッションを作成する際のセッションテンプレートで、InactiveTimeout の期間に基づいて決定されます。

そのため、接続が復旧した後は、該当のプレイヤーに対応し、セッションの最新状態を処理する必要があります。

AGS Unreal Engine Online Subsystem (AB OSS) は、接続が確立された後にセッションの状態を自動的にリフレッシュします。 開発者はこのデリゲートを監視することで、どのセッションが削除されたかを知ることができます。

const IOnlineSubsystem* Subsystem = Online::GetSubsystem(GetWorld());
if (!ensure(Subsystem != nullptr))
{
    return;
}

const FOnlineSessionAccelBytePtr SessionInterface = StaticCastSharedPtr<FOnlineSessionV2AccelByte>(Subsystem->GetSessionInterface());
if (!ensure(SessionInterface.IsValid()))
{
    return;
}

SessionInterface->AddAccelByteOnReconnectedRefreshSessionDelegate_Handle(
    LocalUserNum,
    FAccelByteOnReconnectedRefreshSessionDelegate::CreateLambda(
        [&](int32 LocalUserNum, bool bWasSuccess, const TArray<FName>& RemovedSessionNames) {
            // do something when local session data updated after reconnected
            ...
        }));
に最終更新
On this page