Tareas multijugador

• Suscribirse a las notificaciones de cambios de sesión de Multiplayer Session Directory (MPSD)
• Crear una sesión de MPSD
• Establecer un árbitro para una sesión de MPSD
• Administrar la activación del título
• Hacer que el usuario admita uniones
• Enviar invitaciones de juego
• Unirse a una sesión de juego desde una sesión de sala de espera
• Unirse a una sesión de MPSD desde una activación del título
• Establecer la actividad actual del usuario
• Actualizar una sesión de MPSD
• Abandonar una sesión de MPSD
• Rellenar los espacios abiertos de la sesión durante el emparejamiento
• Crear un vale de partida
• Obtener el estado del vale de partida

​

Suscribirse a las notificaciones de cambios de sesión de Multiplayer Session Directory (MPSD)

1. Use el mismo objeto XblContextHandle para todas las llamadas del mismo usuario. Las suscripciones están vinculadas a la duración de este objeto. Si hay varios usuarios locales, use un objeto XblContextHandle distinto para cada usuario.
2. Implemente controladores de eventos para XblMultiplayerAddSessionChangedHandler y XblMultiplayerSessionSubscriptionLostHandler.
3. Si se suscribe a los cambios de más de un usuario, agregue código a su controlador de eventos XblMultiplayerAddSessionChangedHandler para evitar trabajo innecesario. Use la propiedad XblMultiplayerSessionChangeEventArgs::Branch y la propiedad XblMultiplayerSessionChangeEventArgs::ChangeNumber. El uso de estas propiedades le permite hacer un seguimiento del último cambio visto e ignorar los cambios más antiguos.
4. Llame a XblMultiplayerSetSubscriptionsEnabled para permitir las suscripciones.
5. Cree un objeto de sesión local y, a continuación, únase a esa sesión como activo.
6. Realice llamadas para cada usuario a XblMultiplayerAddSessionChangedHandler, pasando el tipo de cambio de sesión sobre el que se debe notificar.
7. Escriba la sesión en MPSD como se describe en la sección Actualizar una sesión de MPSD de este tema.

​

Análisis de notificaciones de cambios de sesión duplicadas

• Almacenar el valor más reciente de la propiedad ChangeNumber para cada valor evaluado de la propiedad Branch.
• Si un aviso tiene un valor de la propiedad ChangeNumber mayor que el último valor almacenado para ese valor de la propiedad Branch, procesar el aviso y, a continuación, actualizar el valor más reciente de la propiedad ChangeNumber.
• Si un aviso no tiene un valor de la propiedad ChangeNumber mayor para ese valor de la propiedad Branch, omitir el procesamiento del aviso. Ese cambio de sesión ya se ha controlado.

​

Crear una sesión de MPSD

1. Cree un objeto XblContextHandle nuevo. Su título crea este objeto una vez, lo almacena y lo reutiliza según sea necesario en todo el código fuente. Es necesario usar exactamente el mismo contexto, especialmente al trabajar con suscripciones de sesión.
2. Cree un XblMultiplayerSessionHandle nuevo con XblMultiplayerSessionCreateHandle para preparar todos los datos de sesión que MPSD necesita para crear una sesión nueva.
3. Realice los cambios necesarios antes de escribir la sesión en MPSD. Por ejemplo, al unir a un miembro a la sesión con una llamada a XblMultiplayerSessionJoin, el cliente agrega datos de solicitud locales ocultos que indican a MPSD que realice la unión cuando se llame a actualizar la sesión.
4. Cuando termine de realizar los cambios locales, escríbalos en MPSD como se describe en la sección Actualizar una sesión de MPSD de este tema.
5. Reciba el nuevo objeto XblMultiplayerSessionHandle de MPSD, con muchos campos rellenados.
6. Use el nuevo objeto de sesión de ahí en adelante. Descarte la copia antigua, que contiene una solicitud oculta para crear una sesión nueva.

​

Ejemplo

auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock*.

    XblMultiplayerSessionHandle sessionHandle;
    HRESULT hr = XblMultiplayerWriteSessionResult(asyncBlock, &sessionHandle);
    if (SUCCEEDED(hr))
    {
        // Process multiplayer session handle.
    }
    else
    {
        // Handle failure.
    }
};

XblMultiplayerSessionReference ref;
pal::strcpy(ref.Scid, sizeof(ref.Scid), SCID);
pal::strcpy(ref.SessionTemplateName, sizeof(ref.SessionTemplateName), SESSION_TEMPLATE_NAME);
pal::strcpy(ref.SessionName, sizeof(ref.SessionName), SESSION_NAME);

XblMultiplayerSessionInitArgs args = {};

XblMultiplayerSessionHandle sessionHandle = XblMultiplayerSessionCreateHandle(XUID, &ref, &args);

auto hr = XblMultiplayerSessionJoin(
    sessionHandle,
    memberCustomConstantsJson.c_str(),
    initializeRequested,
    joinWithActiveStatus);
    
 hr = XblMultiplayerWriteSessionAsync(xblContextHandle, sessionHandle, XblMultiplayerSessionWriteMode::CreateNew, asyncBlock.get());
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, std::unique_ptr will keep ownership and delete XAsyncBlock*.
    asyncBlock.release();
}

• XAsyncBlock
• XblMultiplayerSessionCreateHandle
• XblMultiplayerSessionInitArgs
• XblMultiplayerSessionReference
• XblMultiplayerSessionWriteMode
• XblMultiplayerWriteSessionAsync
• XblMultiplayerWriteSessionResult

​

Establecer un árbitro para una sesión de MPSD

1. Recupere de MPSD los tokens de dispositivo de los candidatos a host llamando a XblMultiplayerSessionMembers.

   [!NOTE] Si la sesión la creó el emparejamiento de SmartMatch, sus clientes pueden usar los candidatos a host disponibles en MPSD llamando a XblMultiplayerSessionHostCandidates.

2. Seleccione el host requerido en la lista de candidatos a host.
3. Llame a XblMultiplayerSessionSetHostDeviceToken para establecer el token de dispositivo en la caché local de MPSD. Si la llamada para establecer el token de dispositivo del host se realiza correctamente, el token de dispositivo local reemplaza al token del host.
4. Si se recibe un código de estado HTTP/412 al intentar establecer el token de dispositivo del host, consulte los datos de la sesión. Compruebe si el token de dispositivo del host corresponde a la consola local. Si no corresponde a la consola local, se ha designado otra consola como árbitro.

   [!NOTE] Su cliente debe controlar el código de estado HTTP/412 por separado de otros códigos HTTP porque HTTP/412 no indica un error estándar. Para obtener más información sobre este código de estado, consulte Códigos de estado de sesión multijugador.

5. Actualice la sesión en MPSD como se describe en la sección Actualizar una sesión de MPSD de este tema.

   [!NOTE] Si no dispone de un algoritmo mejor, el cliente puede implementar un algoritmo voraz en el que cada candidato a host intenta establecerse a sí mismo como host si nadie más lo ha hecho todavía. Para obtener más información, consulte la sección Árbitro de la sesión en el tema Temas avanzados de sesión multijugador.

​

Administrar la activación del título

1. Configure un controlador de eventos para el evento CoreApplicationView.Activated. Este controlador se desencadena cada vez que se produce una activación por protocolo, incluso si el título ya se está ejecutando.
2. Al activarse el título, inicie una sesión y suscríbase a las notificaciones de cambios de sesión. Para obtener más información, consulte Suscribirse a las notificaciones de cambios de sesión de MPSD en este tema.
3. Una al usuario a la sesión como activo. Para obtener más información, consulte Unirse a una sesión de MPSD desde una activación del título en este tema.
4. Establezca la sesión de sala de espera como la sesión de actividad que se expone a través de la interfaz de usuario del perfil. Para obtener más información, consulte Establecer la actividad actual del usuario en este tema.
5. Una al usuario a la sesión de juego como activo. El usuario ahora puede conectarse a otros pares y entrar en el juego o en la sala de espera.

​

Hacer que el usuario admita uniones

1. Cree un objeto de sesión y, a continuación, modifique los atributos según sea necesario.
2. Una al usuario a la sesión como activo. Para obtener más información, consulte Unirse a una sesión de MPSD desde una activación del título en este tema.
3. Determine si el usuario ha sido designado como árbitro de la sesión.
4. Si el usuario no es el árbitro, vaya al paso 7.
5. Si el usuario es el árbitro, llame a XblMultiplayerSessionSetHostDeviceToken.
6. Intente escribir la sesión mediante una llamada a XblMultiplayerWriteSessionAsync.
7. Establezca la sesión como la sesión activa. Para obtener más información, consulte Establecer la actividad actual del usuario en este tema.

​

Enviar invitaciones de juego

• Enviar las invitaciones para la sesión de sala de espera.
• Enviar las invitaciones mediante la interfaz de usuario de invitaciones genérica de la plataforma XBOX con la referencia de la sesión de juego.

1. Haga que el jugador que invita admita uniones. Para obtener más información, consulte Hacer que el usuario admita uniones en este tema.
2. Determine si las invitaciones se van a enviar a través de la sesión de sala de espera o mediante la interfaz de usuario de invitaciones.
3. Si se usa la sesión de sala de espera, envíe las invitaciones mediante una llamada a XblMultiplayerSendInvitesAsync. Este método podría requerir la creación de una lista de jugadores en la interfaz de usuario del juego llamando a XGameUiShowPlayerPickerAsync.
4. Si se usa la interfaz de usuario de invitaciones, llame a XGameUiShowSendGameInviteAsync para mostrar la interfaz de usuario de invitaciones.
5. Controle el XblMultiplayerAddSessionChangedHandler para el jugador local después de que el jugador remoto se una.
6. Para el jugador remoto, implemente código de activación del título. Para obtener más información, consulte Administrar la activación del título en este tema.

​

Unirse a una sesión de juego desde una sesión de sala de espera

1. Cuando cree la sesión de juego, use la API XblMultiplayerSetTransferHandleAsync para crear un identificador de transferencia que vincule la sesión de sala de espera y la sesión de juego.
2. Almacene el GUID del identificador de transferencia en la sesión de sala de espera en lugar de la referencia de sesión de la sesión de juego.
3. Cuando el título quiera mover miembros de la sesión de sala de espera a la sesión de juego, cada cliente usa el identificador de transferencia de la sesión de sala de espera para unirse a la sesión de juego mediante la API XblMultiplayerWriteSessionByHandleAsync.
4. MPSD busca la sesión de sala de espera para comprobar que los miembros que intentan unirse a la sesión de juego mediante el identificador de transferencia también están en la sesión de sala de espera.
5. Si los miembros están en la sesión de sala de espera, pueden acceder a la sesión de juego.

​

Unirse a una sesión de MPSD desde una activación del título

1. Implemente un controlador de eventos para el evento CoreApplicationView.Activated. Notifica las activaciones del título.
2. Cuando el controlador se desencadene, examine la propiedad IActivatedEventArgs.Kind. Si está establecida en Protocol, convierta los argumentos del evento a la clase ProtocolActivatedEventArgs.
3. Examine el objeto ProtocolActivatedEventArgs. Si el URI indicado en la propiedad ProtocolActivatedEventArgs.Uri coincide con inviteHandleAccept (correspondiente a una invitación aceptada) o con activityHandleJoin (correspondiente a una unión a través de la interfaz de usuario del shell), analice la cadena de consulta del URI. Tiene el formato de una cadena de consulta de URI normal con pares clave/valor, extrayendo los campos siguientes.
   • Para una invitación aceptada:
     1. handle
     2. invitedXuid
     3. senderXuid
   • Para una unión:
     1. handle
     2. joinerXuid
     3. joineeXuid
4. Inicie el código multijugador del título, que debe incluir una llamada a XblMultiplayerSetSubscriptionsEnabled.
5. Cree un objeto XblMultiplayerSessionHandle local llamando a XblMultiplayerSessionCreateHandle.
6. Llame a XblMultiplayerSessionJoin para unirse a la sesión. Use la configuración de parámetros siguiente para que la unión se establezca como activa.
   • memberCustomConstantsJson = null
   • initializeRequested = false
   • joinWithActiveStatus = true
7. Llame a XblMultiplayerSessionSetSessionChangeSubscription para recibir un aviso cuando la sesión cambie después de la unión.
8. Llame a XblMultiplayerWriteSessionByHandleAsync con el identificador adquirido como se describe en el paso 3. El usuario es ahora miembro de la sesión y puede usar los datos de la sesión para conectarse al juego.

​

Establecer la actividad actual del usuario

​

Actualizar una sesión de MPSD

1. Realice los cambios necesarios en la sesión actual, por ejemplo, llamando a XblMultiplayerSessionLeave.
2. Cuando haya realizado todos los cambios, escriba los cambios locales en MPSD mediante cualquiera de estos métodos.
   • XblMultiplayerWriteSessionAsync
   • XblMultiplayerWriteSessionByHandleAsync
   Establezca el modo de escritura en XblMultiplayerSessionWriteMode::SynchronizedUpdate si escribe en una parte compartida que otros títulos también pueden modificar. Para obtener más información, consulte la sección Sincronización de las actualizaciones de sesión en el tema Información general de Multiplayer Session Directory. El método de escritura escribe la unión en el servidor y obtiene la sesión más reciente, a partir de la cual se pueden descubrir los demás miembros de la sesión y las direcciones seguras de dispositivo (SDA) de sus consolas. Para obtener más información sobre cómo establecer una conexión de red entre estas consolas, consulte Introducción a Winsock en XBOX One.
3. Descarte el objeto de sesión local antiguo. Use el objeto de sesión recién recuperado para que las acciones futuras se basen en el estado de sesión más reciente conocido.

​

Abandonar una sesión de MPSD

1. Llame a XblMultiplayerSessionLeave para la sesión de juego.
2. Actualice la sesión de juego en MPSD como se describe en la sección Actualizar una sesión de MPSD de este tema.
3. Si es necesario, llame al método XblMultiplayerSessionLeave para la sesión de sala de espera y, a continuación, actualice esa sesión.
4. Si es necesario para la sesión de sala de espera, cierre la API multijugador anulando el registro mediante llamadas a XblMultiplayerRemoveSubscriptionLostHandler y XblMultiplayerRemoveSessionChangedHandler.

​

Rellenar los espacios abiertos de la sesión durante el emparejamiento

1. Acceda al estado de sesión más reciente de la sesión de vale que se creó durante el emparejamiento.
2. Agregue jugadores disponibles para el juego desde la sesión de sala de espera.
3. Determine si la sesión de vale está llena.
4. Si la sesión está llena, continúe con el juego.
5. Si la sesión aún no está llena, cree el vale de partida como se describe en Crear un vale de partida en este tema. Asegúrese de crear el vale con el parámetro preserveSession establecido en Always.
6. Continúe con el emparejamiento. Para obtener más información, consulte Información general del emparejamiento.

​

Crear un vale de partida

1. Llame a XblMatchmakingCreateMatchTicketAsync, pasando una referencia a la sesión de vale. El método lee la sesión de vale de MPSD e inicia el emparejamiento para los usuarios de la sesión. Internamente, el método llama a POST (/serviceconfigs/{scid}/hoppers/{hoppername}).
2. Establezca el parámetro preserveSession en Never si el servicio de emparejamiento debe emparejar a los miembros de la sesión en una sesión nueva u otra sesión existente. Establezca el parámetro preserveSession en Always para permitir que el título reutilice una sesión de juego existente como sesión de vale para continuar el juego. El servicio de emparejamiento puede entonces garantizar que la sesión enviada se conserve y que los jugadores emparejados se agreguen a esa sesión.
3. Use XblCreateMatchTicketResponse::EstimatedWaitTime, que se devuelve en el objeto CreateMatchTicketResponse, para establecer las expectativas del usuario sobre el tiempo de emparejamiento.
4. Use XblCreateMatchTicketResponse::MatchTicketId, que se devuelve en el objeto de respuesta, para cancelar el emparejamiento de la sesión, si es necesario, eliminando el vale. La eliminación del vale usa XblMatchmakingDeleteMatchTicketAsync.

​

Obtener el estado del vale de partida

1. Obtenga el objeto XblMultiplayerSessionHandle de la sesión de vale.
2. Llame a XblMultiplayerSessionMatchmakingServer para acceder al objeto XblMultiplayerMatchmakingServer que se usó en el emparejamiento.
3. Compruebe el objeto XblMultiplayerMatchmakingServer para determinar el estado del proceso de emparejamiento, el tiempo de espera típico de la sesión y la referencia de la sesión de destino, si se ha encontrado una coincidencia.