> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ユーザーと入力デバイス

> ユーザーと入力デバイス

ゲームは、指定したユーザーに関連付けられている入力デバイスがどれかを知る必要があります。これは、次の質問に答えるための鍵となります。

* ゲーム内で誰がアクションを行ったのか?

* 誰が実績を獲得するのか?

* 誰が購入を行っているのか?

このトピックでは、これらの関連付けを扱い、この種の質問に答えるのに役立ついくつかの主要な概念を扱います。

## XBOX One ERA と Microsoft Game Development Kit (GDK) のユーザー モデルの違い

新しい Microsoft Game Development Kit (GDK) タイトルを開発する場合でも、以前のタイトルを XBOX One ERA から移植する場合でも、XBOX One ERA のユーザー モデルに慣れていると、ユーザーと入力デバイスの管理の実装は混乱することがあります。

* ゲームのセーブや実績が必要な場合など、ユーザーが必要なタイトルは、プライマリ ユーザーを確立する必要があります。このプライマリ ユーザーはタイトル専用の構成要素で、システムから提供されるものではありません。

* タイトルは [XUserAddAsync](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuseraddasync.md) の呼び出しを介して追加されたユーザーについてのみ知っています。タイトルは、追加していないユーザーに対してシステムが行ったアクションについて通知されません。

* 以前にタイトル ユーザーに関連付けられていたデバイスが、タイトルが認識していないユーザーに関連付けられた場合、タイトルには新しいユーザーなしにデバイス関連付けイベントのみが通知されます。

* タイトル ユーザーに関連付けられていなかったデバイスが、[XUserAddAsync](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuseraddasync.md) で追加されていない別のユーザーに関連付けられた場合、タイトルには関連付けイベントは通知されません。

* アカウント ピッカーは、どのように呼び出されたか (System Guide vs [XUserAddAsync](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuseraddasync.md)) に基づいて異なる動作をします。

> [!NOTE]
>
> UserManagement サンプルは、さまざまなゲーム状況におけるユーザー管理と入力デバイスのペアリング動作を扱います。また、ユーザーと入力デバイスに関する XR 要件も扱います。サンプルの詳細については、[Microsoft Game Development Kit サンプル](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/development-downloads/gdk-samples-home) を参照してください。

## 指定したユーザーを識別する方法

ゲームは入力デバイスと対話するために *ローカル ID* を使用します。ローカル ID は、ゲーム セッション内のユーザーの生存期間中、そのユーザーと共に留まる識別子です。ローカル ID は、ゲームが生成する任意のプロセス、またはゲームが [XLaunchNewGame](https://docs.xbox.com/ja-jp/reference/system/xgame/functions/xlaunchnewgame.md) を呼び出す場合に使用できます。ゲーム セッションをまたいでユーザーを識別するためにローカル ID を使用しないでください。

ユーザーのローカル ID を取得するには、[XUserGetLocalId](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xusergetlocalid.md) 関数を使用します。

## 特定の入力デバイスを識別する方法

ゲームパッド、アーケード スティック、ホイールなどのゲーミング デバイスはすべて、[APP\_LOCAL\_DEVICE\_ID](https://docs.xbox.com/ja-jp/reference/system/xuser/structs/app_local_device_id.md) 構造体によって表される一意の *デバイス ID* を持ちます。このデバイス ID は、ゲームの複数回の起動やシステムの再起動をまたいで持続します。デバイス ID は、同じシステム上で実行される 2 つの異なるゲームの間で異なります。

コンソールで `XInput` を使用している場合、[XInputGetDeviceId](https://docs.xbox.com/ja-jp/reference/input/xinputongameinput/functions/xinputgetdeviceid.md) を使用してデバイス ID を取得できます。

[GameInput](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-overview.md) を使用している場合、[IGameInputDevice::GetDeviceInfo](https://docs.xbox.com/ja-jp/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getdeviceinfo.md) の呼び出しから返される [GameInputDeviceInfo](https://docs.xbox.com/ja-jp/reference/input/gameinput/structs/gameinputdeviceinfo.md) オブジェクトの `deviceId` メンバーからデバイス ID を取得できます。

## ユーザー モデル

タイトルにユーザーが必要な場合 (たとえばゲームのセーブや実績が必要な場合)、タイトルはプライマリ ユーザーの確立に完全に責任があります。このプライマリ ユーザーは、複数のユーザーがサインインできる場合でも維持される必要があります。また、タイトルは必要に応じてプライマリ ユーザーを変更できるようにする必要があります。そうする方法は、[XUserAddAsync](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuseraddasync.md) でアカウント ピッカーを呼び出す *ユーザー切り替え* プロンプトを持つことです。

アカウント ピッカーは、以前にコンソールにサインインしたすべてのユーザーをリストし、新しいアカウントにサインインするための **Add new** ボタンを持ち、一時的なゲスト ユーザーのサインインを可能にします。これらのユーザー アカウントは、ユーザーの真の身元に関係なく選択できます。システムは、この方法で他人としてプレイすることを選ぶユーザーをサポートします。

Microsoft Game Development Kit (GDK) タイトルは、システム上のユーザーについての完全な知識を持ちません。代わりに、ユーザーは [XUserAddAsync](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuseraddasync.md) の呼び出しを介してのみタイトルに追加できます。この方法で追加されたユーザーが、タイトルが対話できる唯一のユーザーです。システムは、タイトルが追加していないユーザーに対して行われたアクションについてタイトルに通知しません。その結果、タイトルは独自のユーザー リストを保持する必要があります。

アカウント ピッカーは、System Guide からと [XUserAddAsync](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuseraddasync.md) 経由の 2 つの方法で表示できます。このピッカーはこの 2 つの状況で異なる動作をします。

| ケース | [XUserAddAsync](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuseraddasync.md) アカウント ピッカー | Guide アカウント ピッカー |
| - | - | - |
| タイトルにサインインしていないユーザーを選択 | ユーザーはシステムとタイトルの両方にサインインされます。 | ユーザーはシステムにのみサインインされます。タイトルにはサインインが通知されません。 |
| タイトルに既にサインインしているユーザーを選択 | ユーザーは既にタイトルにサインインしているため、それ以上のユーザー状態変更は発生しません。 | ユーザーは既にタイトルにサインインしているため、それ以上のユーザー状態変更は発生しません。 |

> [!NOTE]
>
> タイトルにサインインしているユーザーの集合は、常にシステムにサインインしているユーザーのサブセットです。タイトルには、システムがサインインしていないユーザーはサインインできません。ただし、システムには、タイトルが知らないユーザーが存在する可能性があります。

ユーザー イベントは、[XUserRegisterForChangeEvent](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuserregisterforchangeevent.md) で登録された [XUserChangeEventCallback](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuserchangeeventcallback.md) を介して処理できます。イベントは、[XUserAddAsync](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuseraddasync.md) でサインインされたユーザーに対してのみ呼び出されます。ユーザーがシステムからサインアウトした場合、タイトルは適切に対応して、タイトルからユーザーを削除するか、プレイヤーが再度ユーザーのサインインを試みることができるようにする必要があります。

## 入力デバイスの関連付け

Microsoft Game Development Kit (GDK) では、ユーザーに任意の数の入力デバイスを関連付けることができます。ユーザーとデバイスの間の 1 対 1 のマッピングを想定した古いタイトルを移植する場合、これは困難なことがあります。

デバイスの関連付けは通常、アカウント ピッカーを介して行われます。UI からユーザーを選択した入力デバイスが、そのユーザーに関連付けられるようになります。関連付けは他のケースからも変わることがあります。たとえば、ユーザーがサインアウトされたときや、[AddDefaultUserSilently](https://docs.xbox.com/ja-jp/reference/system/xuser/enums/xuseraddoptions.md) および [AddDefaultUserAllowingUI](https://docs.xbox.com/ja-jp/reference/system/xuser/enums/xuseraddoptions.md) オプションを使用して UI なしで [XUserAddAsync](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuseraddasync.md) が使用されるときなどです。

アカウント ピッカーも、ピッカーがどのように表示されたかに基づいて関連付けに関して異なる動作をします。

| ケース | [XUserAddAsync](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuseraddasync.md) アカウント ピッカー | Guide アカウント ピッカー |
| - | - | - |
| タイトルにサインインしていないユーザーを選択 | ユーザーがタイトルにサインインした後、プロンプトを完了したデバイスがユーザーに関連付けられます。 | ユーザーはシステムにサインインされ (まだサインインしていない場合)、プロンプトを完了したデバイスがそのユーザーに関連付けられます。タイトルはこのユーザーを認識していないため、デバイスが関連付けられていないことが通知されます。 |
| タイトルに既にサインインしているユーザーを選択 | プロンプトを完了したデバイスは、システムとタイトル ユーザーに関連付けられるようになります。 | プロンプトを完了したデバイスは、システムとタイトル ユーザーに関連付けられるようになります。 |

アカウント ピッカーなしに、[AddDefaultUserSilently](https://docs.xbox.com/ja-jp/reference/system/xuser/enums/xuseraddoptions.md) または [AddDefaultUserAllowingUI](https://docs.xbox.com/ja-jp/reference/system/xuser/enums/xuseraddoptions.md) オプションのいずれかを利用する [XUserAddAsync](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuseraddasync.md) の呼び出しによって、タイトルにユーザーが自動的にサインインされた場合、システムが持っていた入力デバイスのペアリングがタイトルに伝達されます。

ユーザー デバイスの関連付け変更の通知を受け取るには、[XUserRegisterForDeviceAssociationChanged](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuserregisterfordeviceassociationchanged.md) メソッドを使用して [XUserDeviceAssociationChangedCallback](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuserdeviceassociationchangedcallback.md) コールバックを登録できます。特定のデバイスの関連付けを検索するために [XUserFindForDevice](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuserfindfordevice.md) を呼び出すこともできます。

> [!NOTE]
>
> タイトルは [XUserAddAsync](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuseraddasync.md) で追加されたユーザーについてのみ知ることができるため、ユーザー デバイスの関連付けのコールバックとメソッドは、タイトルが以前に追加したユーザーのみを返せます。

## 既定のオーディオ エンドポイントとユーザーのマッチング

ヘッドセットやマイクは、ゲームと共に頻繁に提供されます。次のような重要な質問があります。

* ユーザーはヘッドセットを持っていますか? 持っている場合、どのヘッドセットを使用している可能性が高いですか?
  既定の通信レンダリング オーディオ エンドポイントは何ですか?

* ユーザーには関連付けられたマイクがありますか? 既定の通信キャプチャ エンドポイントは何ですか?

特定のユーザーについてこれらの質問に答えるには、ゲームは [XUserGetDefaultAudioEndpointUtf16](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xusergetdefaultaudioendpointutf16.md) を呼び出せます。ユーザーとデバイスの関連付けが変わる可能性があるのと同様に、特定のユーザーに関連付けられた既定のオーディオ エンドポイントも変わる可能性があります。これらの関連付け変更を検出するには、ゲームは [XUserRegisterForDefaultAudioEndpointUtf16Changed](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuserregisterfordefaultaudioendpointutf16changed.md) を呼び出し、結果として得られるコールバックに注意を払う必要があります。


## Related topics

- [XUserFindForDevice](https://docs.xbox.com/ja-jp/reference/system/xuser/functions/xuserfindfordevice.md)
- [ユーザー](https://docs.xbox.com/ja-jp/build/core-features/common/user/user-toc.md)
- [XUserDeviceAssociationChange](https://docs.xbox.com/ja-jp/reference/system/xuser/structs/xuserdeviceassociationchange.md)
- [GDK のユーザー ID と XUser API](https://docs.xbox.com/ja-jp/build/core-features/common/user/index.md)
- [ゲスト ユーザーの概要](https://docs.xbox.com/ja-jp/build/core-features/common/user/users-guest-overview.md)