Código de ejemplo para Multiplayer Activity

Este tema está pensado como una guía de inicio rápido para el uso básico de las API de cliente de Multiplayer Activity. Este tema trata la administración de actividades, el envío de invitaciones y la adición de jugadores a la lista de jugadores recientes. Actividades Invitaciones Jugadores recientes

Actividades

Establecimiento de una actividad

Siempre que un título inicia o se une a una experiencia multijugador, debe crear una actividad. Hacerlo permite que el shell, junto con otros jugadores de su título, vea la actividad del jugador y permite que otros jugadores puedan unirse a la partida en curso. Si un jugador quiere unirse a una actividad de su título y este no se está ejecutando, se activa y se le pasa la cadena de conexión. Los títulos deben actualizar la actividad a medida que los jugadores se unen o se van. Esto proporciona una vista más completa de la actividad a otros jugadores y les informa si la actividad está llena. Para obtener información sobre los campos de la actividad, consulte Contenido de la actividad. Un ejemplo de código para establecer una actividad es el siguiente. Se aplica tanto a la creación de una actividad como a la actualización de una actividad existente.

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

XblMultiplayerActivityInfo info{};
info.connectionString = "dummyConnectionString";
info.joinRestriction = XblMultiplayerActivityJoinRestriction::Followed;
info.maxPlayers = 10;
info.currentPlayers = 1;
info.groupId = "dummyGroupId";

HRESULT hr = XblMultiplayerActivitySetActivityAsync(
    xblContext,
    &info,
    false,
    async.get()
);

if (SUCCEEDED(hr))
{
    async.release();
}

Para obtener más información, consulte lo siguiente:

Volver al principio de este tema.

Obtención de actividades

Es posible que los títulos quieran conocer las actividades de otros jugadores. Por ejemplo, un título puede querer mostrar una interfaz dentro del juego con los amigos de un jugador en el título junto con sus actividades. Un ejemplo de código para recuperar una actividad es el siguiente.

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

    size_t resultSize{};
    HRESULT hr = XblMultiplayerActivityGetActivityResultSize(async, &resultSize);
    if (SUCCEEDED(hr))
    {
        std::vector<uint8_t> buffer(resultSize);
        XblMultiplayerActivityInfo* activityInfo{};
        size_t resultCount{};
        hr = XblMultiplayerActivityGetActivityResult(async, buffer.size(), buffer.data(), &activityInfo, &resultCount, nullptr);
        if (SUCCEEDED(hr))
        {
            // ...
        }
    }
};

HRESULT hr = XblMultiplayerActivityGetActivityAsync(
    xblContext,
    &xuid,
    1,
    async.get()
);

if (SUCCEEDED(hr))
{
    async.release();
}

Para obtener más información, consulte lo siguiente:

Volver al principio de este tema.

Eliminación de una actividad

Cuando un jugador finaliza o abandona una actividad multijugador, el título debe eliminar la actividad mediante el código siguiente.

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

HRESULT hr = XblMultiplayerActivityDeleteActivityAsync(xblContext, async.get());

if (SUCCEEDED(hr))
{
    async.release();
}

Para obtener más información, consulte lo siguiente:

Volver al principio de este tema.

Invitaciones

Envío de invitaciones sin interfaz de usuario

Es posible que los jugadores quieran enviar invitaciones directamente a uno o varios jugadores. Antes de enviar una invitación, el título debe asegurarse de que hay una actividad establecida. Esto garantiza que haya continuidad entre el shell y su título, porque el shell envía invitaciones basadas en la actividad actual. Para enviar una invitación sin interfaz de usuario, después de establecer una actividad mediante XblMultiplayerActivitySetActivityAsync (consulte el ejemplo anterior), el título debe llamar a la API XblMultiplayerActivitySendInvitesAsync, pasando una matriz de jugadores a los que invitar y la misma cadena de conexión que se usa en su actividad actual. Para obtener información sobre el contenido de una invitación, consulte Envío de una solicitud para que otro jugador se una a una experiencia multijugador.. Un ejemplo de código para enviar invitaciones sin interfaz de usuario es el siguiente.

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

HRESULT hr = XblMultiplayerActivitySendInvitesAsync(
    xblContext,
    &xuid,
    1,
    true, // Setting false will send the invite to only players on the sender's platform.
    "dummyConnectionString",
    async.get()
);

if (SUCCEEDED(hr))
{
    async.release();
}

Para obtener más información, consulte lo siguiente:

Envío de invitaciones con interfaz de usuario

Es posible que los jugadores quieran enviar invitaciones directamente a uno o varios jugadores. Antes de enviar una invitación, el título debe asegurarse de que hay una actividad establecida. Esto garantiza que haya continuidad entre el shell y su título, porque el shell envía invitaciones basadas en la actividad actual. Para enviar una invitación con interfaz de usuario, después de establecer una actividad mediante XblMultiplayerActivitySetActivityAsync (consulte el ejemplo anterior), el título debe llamar a la API XGameUiShowMultiplayerActivityGameInviteAsync, pasando el usuario solicitante. Usará la actividad actual del título e invitará a los jugadores usando su cadena de conexión y su configuración. Para obtener información sobre el contenido de una invitación, consulte Envío de una solicitud para que otro jugador se una a una experiencia multijugador.. Un ejemplo de código para enviar invitaciones con interfaz de usuario es el siguiente.

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XGameUiShowMultiplayerActivityGameInviteResult(async);
    if (hrAsync == S_OK) 
    { 
        // Handle success 
    } 
    else 
    { 
        // Likely will only happen during development - usually indicates 
        // an invalid user was passed in or that there is no multiplayer activity set
    }     
};

HRESULT hr = XGameUiShowMultiplayerActivityGameInviteAsync(
    async.get()
    requestingUser
);

if (SUCCEEDED(hr))
{
    async.release();
}

Para obtener más información, consulte lo siguiente:

Volver al principio de este tema.

Recepción de invitaciones

Para recibir una notificación cuando un jugador acepta una invitación, los títulos pueden registrarse para las notificaciones de invitación mediante XGameInviteRegisterForEvent. Cada vez que se acepta una invitación, se pasa al título un URI con formato a través de la devolución de llamada registrada. El URI se puede analizar para determinar el remitente de la invitación, el destinatario y la cadena de conexión. La cadena de conexión es específica del título y se establece cuando se crea la actividad multijugador. Para los títulos que usan el servicio Multiplayer Activity, el formato completo del URI se muestra en la tabla siguiente.

Plataforma	Formato
Microsoft Game Development Kit (GDK) o XBOX One Software Development Kit en consola	`ms-xbl-<titleId>://inviteAccept?invitedUser=<xuid>&sender=<xuid>&connectionString=<connectionString>`
Microsoft Game Development Kit (GDK) o Plataforma universal de Windows (UWP) en PC	`ms-xbl-multiplayer://inviteAccept?invitedUser=<xuid>&sender=<xuid>&connectionString=<connectionString>`

Cuando ya no se necesiten las notificaciones de invitación, se puede anular el registro de la devolución de llamada mediante XGameInviteUnregisterForEvent. Un ejemplo de código para registrar y manejar las invitaciones aceptadas es el siguiente.

void CALLBACK MyXGameInviteEventCallback(
    _In_opt_ void* context,
    _In_ const char* inviteUri)
{
    if (inviteUri != nullptr)
    {
        std::string uri{ inviteUri };
        size_t invitedUserBegin = uri.find("invitedUser=");
        size_t senderBegin = uri.find("sender=");
        std::string invitedUser = uri.substr(invitedUserBegin, uri.find('&', invitedUserBegin) - invitedUserBegin);
        std::string sender = uri.substr(senderBegin, uri.find('&', senderBegin) - senderBegin);
        std::string connectionString = uri.substr(uri.find("connectionString="));

        // ...
    }
}

XTaskQueueRegistrationToken token = { 0 };
HRESULT hr = XGameInviteRegisterForEvent(
    queue,
    nullptr,
    MyXGameInviteEventCallback,
    &token
    );

// ...
bool result = XGameInviteUnregisterForEvent(token, true);

Para obtener más información, consulte lo siguiente:

Volver al principio de este tema.

Jugadores recientes

Para actualizar la lista de jugadores recientes del jugador, el título debe enviar listas de otros jugadores que hayan tenido una interacción significativa con el jugador actual. La lista es unidireccional, lo que significa que el cliente de cada jugador es responsable de actualizar su propia lista, y las listas de los jugadores no afectan a las listas de los demás. Por ejemplo, suponga que un grupo de jugadores está junto en una sala previa a la partida y se emparejan. Cada jugador actualizaría su lista con todos los demás xuids de la sala cuando comience la partida. Si un nuevo jugador se uniera, podría escribirse individualmente.

Puede decidir qué define una interacción significativa. Para un título, podría ser estar presente en una sala. Para otro, podría ser que un jugador dispare a otro jugador. Para un tercero, podría ser simplemente que otro jugador sea visible en pantalla.

En escenarios en los que quizás no quiera que los equipos de jugadores sean visibles hasta que comience una sesión de partida, podría retrasar la escritura de la lista de jugadores hasta el momento en que quiera que sean visibles entre sí. Para vaciar la lista de jugadores recientes del lado cliente, puede llamar a XblMultiplayerActivityFlushRecentPlayersAsync si necesita un vaciado forzado inmediato. De lo contrario, la lista de jugadores recientes se vaciará automáticamente cada cinco segundos. Los ejemplos de código para actualizar la lista de jugadores recientes y vaciar las actualizaciones son los siguientes.

Actualización de jugadores recientes

XblMultiplayerActivityRecentPlayerUpdate update{ xuid };
HRESULT hr = XblMultiplayerActivityUpdateRecentPlayers(xblContext, &update, 1);

Para obtener más información, consulte lo siguiente:

Volver al principio de este tema.

Vaciado de jugadores recientes

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

HRESULT hr = XblMultiplayerActivityFlushRecentPlayersAsync(xblContext, async.get());
if (SUCCEEDED(hr))
{
    async.release();
}

Para obtener más información, consulte lo siguiente:

Volver al principio de este tema.

XBOX Services

PlayFab

Actividades

Establecimiento de una actividad

Obtención de actividades

Eliminación de una actividad

Invitaciones

Envío de invitaciones sin interfaz de usuario

Envío de invitaciones con interfaz de usuario

Recepción de invitaciones

Jugadores recientes

Actualización de jugadores recientes

Vaciado de jugadores recientes

​Actividades

​Establecimiento de una actividad

​Obtención de actividades

​Eliminación de una actividad

​Invitaciones

​Envío de invitaciones sin interfaz de usuario

​Envío de invitaciones con interfaz de usuario

​Recepción de invitaciones

​Jugadores recientes

​Actualización de jugadores recientes

​Vaciado de jugadores recientes

Actividades

Establecimiento de una actividad

Obtención de actividades

Eliminación de una actividad

Invitaciones

Envío de invitaciones sin interfaz de usuario

Envío de invitaciones con interfaz de usuario

Recepción de invitaciones

Jugadores recientes

Actualización de jugadores recientes

Vaciado de jugadores recientes