Tablas de botín y botín aleatorio en Economy v2

Economy v2 ya está disponible con carácter general. Para soporte y comentarios, vaya al Foro de PlayFab.

Economy v1 (heredado) tenía una característica integrada de tablas de botín que le permitía definir distribuciones aleatorias ponderadas de objetos directamente en Game Manager. Economy v2 no incluye las tablas de botín como característica nativa, pero puede implementar el mismo comportamiento —y con más flexibilidad— mediante Azure Functions en combinación con la API ExecuteInventoryOperations. Este tutorial le muestra cómo crear un sistema completo de botín aleatorio que:

Define tablas de botín con grupos de objetos ponderados en Title Data.
Usa una función de Azure para sortear objetos aleatorios de una tabla de botín.
Resta de forma atómica un token de contenedor y otorga los objetos seleccionados aleatoriamente en una sola llamada.

Cómo funciona

Definir tablas de botín en Title Data: almacene las configuraciones de sus tablas de botín (identificadores de objetos, pesos, cantidades) como JSON en Title Data para poder actualizarlas sin volver a implementar código.
Representar los contenedores como moneda virtual: use el mismo patrón de token de contenedor que los contenedores de contenido fijo: una moneda virtual que actúa como una caja de botín sin abrir.
Llamar a una función de Azure para abrir el contenedor: la función lee la tabla de botín, ejecuta una selección aleatoria ponderada y luego llama a ExecuteInventoryOperations para restar de forma atómica 1 token de contenedor y agregar los objetos seleccionados aleatoriamente.

Requisitos previos

Una cuenta de desarrollador de PlayFab.
Un título creado en Game Manager.
Elementos de catálogo publicados que pueda otorgar como recompensas de botín.
Una moneda virtual que represente el contenedor (consulte Contenedores con contenido fijo para ver las instrucciones de configuración).
Un proyecto de Azure Functions conectado a su título de PlayFab.

Paso 1: definir tablas de botín en Title Data

Almacene las definiciones de sus tablas de botín en Title Data para que los diseñadores puedan actualizar las tasas de caída sin cambios de código.

Estructura de ejemplo de una tabla de botín

Cree una clave de Title Data llamada LootTables con un valor JSON:

{
  "TreasureChest": {
    "Rolls": 1,
    "Items": [
      { "ItemId": "{{CommonSwordID}}", "Weight": 1000, "MinQuantity": 1, "MaxQuantity": 1 },
      { "ItemId": "{{UncommonSwordID}}", "Weight": 100, "MinQuantity": 1, "MaxQuantity": 1 },
      { "ItemId": "{{RareSwordID}}", "Weight": 10, "MinQuantity": 1, "MaxQuantity": 1 },
      { "ItemId": "{{LegendarySwordID}}", "Weight": 1, "MinQuantity": 1, "MaxQuantity": 1 }
    ]
  },
  "SupplyCrate": {
    "Rolls": 3,
    "Items": [
      { "ItemId": "{{HealthPotionID}}", "Weight": 50, "MinQuantity": 1, "MaxQuantity": 5 },
      { "ItemId": "{{ManaPotionID}}", "Weight": 50, "MinQuantity": 1, "MaxQuantity": 3 },
      { "ItemId": "{{GoldCurrencyID}}", "Weight": 80, "MinQuantity": 10, "MaxQuantity": 100 },
      { "ItemId": "{{RareGemID}}", "Weight": 5, "MinQuantity": 1, "MaxQuantity": 1 }
    ]
  }
}

Cada tabla de botín incluye las siguientes propiedades:

Propiedad	Descripción
Rolls	Cuántas veces se sortea en la tabla cuando se abre el contenedor.
Items	El grupo de recompensas posibles, cada una con un peso y un intervalo de cantidad.
Weight	Probabilidad relativa. Un peso mayor significa que es más probable que el objeto caiga.
MinQuantity / MaxQuantity	Intervalo de cuántas unidades de ese objeto se otorgan por sorteo.

Establecer Title Data

Game Manager

Vaya a Content > Title Data.
Cree una clave llamada LootTables.
Pegue su configuración JSON de tablas de botín como valor.
Seleccione Save.

API

Use SetTitleData:

{
  "Key": "LootTables",
  "Value": "{\"TreasureChest\":{\"Rolls\":1,\"Items\":[...]}}"
}

Paso 2: crear la función de Azure

Cree una función de Azure a la que llame el cliente de su juego cuando un jugador quiera abrir un contenedor. La función:

Comprueba que el jugador tiene al menos un token de contenedor.
Lee la tabla de botín desde Title Data.
Ejecuta la selección aleatoria ponderada.
Llama a ExecuteInventoryOperations para restar de forma atómica el token y otorgar las recompensas.

Modelos de datos

public class OpenContainerRequest
{
    public string LootTableId { get; set; }  // e.g., "TreasureChest"
}

public class LootTable
{
    public int Rolls { get; set; }
    public List<LootTableEntry> Items { get; set; }
}

public class LootTableEntry
{
    public string ItemId { get; set; }
    public int Weight { get; set; }
    public int MinQuantity { get; set; }
    public int MaxQuantity { get; set; }
}

Selección aleatoria ponderada

public static LootTableEntry RollOnTable(LootTable table, Random rng)
{
    int totalWeight = table.Items.Sum(e => e.Weight);
    int roll = rng.Next(0, totalWeight);

    int cumulative = 0;
    foreach (var entry in table.Items)
    {
        cumulative += entry.Weight;
        if (roll < cumulative)
            return entry;
    }

    // Fallback (shouldn't reach here)
    return table.Items.Last();
}

Función de Azure completa

[FunctionName("OpenLootContainer")]
public static async Task<dynamic> Run(
    [HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] HttpRequest req,
    ILogger log)
{
    // 1. Parse the PlayFab context and request
    var context = JsonConvert.DeserializeObject<FunctionExecutionContext<dynamic>>(
        await req.ReadAsStringAsync());
    var args = context.FunctionArgument != null
        ? JsonConvert.DeserializeObject<OpenContainerRequest>(
            context.FunctionArgument.ToString())
        : null;

    if (args == null || string.IsNullOrEmpty(args.LootTableId))
        return new { Error = "LootTableId is required." };

    var playerEntity = context.CallerEntityProfile.Entity;
    var settings = new PlayFabApiSettings
    {
        TitleId = context.TitleAuthenticationContext.Id,
        DeveloperSecretKey = Environment.GetEnvironmentVariable("PLAYFAB_DEV_SECRET_KEY")
    };
    var authContext = new PlayFabAuthenticationContext
    {
        EntityToken = context.TitleAuthenticationContext.EntityToken
    };

    var serverApi = new PlayFabServerInstanceAPI(settings);
    var economyApi = new PlayFabEconomyInstanceAPI(settings, authContext);

    // 2. Read the loot table from Title Data
    var titleDataResult = await serverApi.GetTitleDataAsync(new GetTitleDataRequest
    {
        Keys = new List<string> { "LootTables" }
    });

    if (!titleDataResult.Result.Data.ContainsKey("LootTables"))
        return new { Error = "LootTables not found in Title Data." };

    var allTables = JsonConvert.DeserializeObject<Dictionary<string, LootTable>>(
        titleDataResult.Result.Data["LootTables"]);

    if (!allTables.ContainsKey(args.LootTableId))
        return new { Error = $"Loot table '{args.LootTableId}' not found." };

    var lootTable = allTables[args.LootTableId];

    // 3. Roll for rewards
    var rng = new Random();
    var rewards = new Dictionary<string, int>(); // ItemId -> total quantity

    for (int i = 0; i < lootTable.Rolls; i++)
    {
        var entry = RollOnTable(lootTable, rng);
        int quantity = rng.Next(entry.MinQuantity, entry.MaxQuantity + 1);

        if (rewards.ContainsKey(entry.ItemId))
            rewards[entry.ItemId] += quantity;
        else
            rewards[entry.ItemId] = quantity;
    }

    // 4. Build the atomic operation: subtract 1 container token + add rewards
    var operations = new List<InventoryOperation>();

    // Subtract the container token
    // The container currency ID must match the LootTableId mapping
    // Store this mapping in Title Data or use a naming convention
    operations.Add(new InventoryOperation
    {
        Subtract = new SubtractInventoryItemsOperation
        {
            Item = new InventoryItemReference
            {
                Id = GetContainerCurrencyId(args.LootTableId) // Your mapping logic
            },
            Amount = 1
        }
    });

    // Add each reward
    foreach (var reward in rewards)
    {
        operations.Add(new InventoryOperation
        {
            Add = new AddInventoryItemsOperation
            {
                Item = new InventoryItemReference { Id = reward.Key },
                Amount = reward.Value
            }
        });
    }

    // 5. Execute atomically
    var executeResult = await economyApi.ExecuteInventoryOperationsAsync(
        new ExecuteInventoryOperationsRequest
        {
            Entity = new EntityKey
            {
                Id = playerEntity.Id,
                Type = playerEntity.Type
            },
            Operations = operations,
            IdempotencyId = Guid.NewGuid().ToString()
        });

    if (executeResult.Error != null)
    {
        log.LogError($"Failed to execute operations: {executeResult.Error.ErrorMessage}");
        return new { Error = executeResult.Error.ErrorMessage };
    }

    log.LogInformation($"Player {playerEntity.Id} opened {args.LootTableId}, received: " +
        string.Join(", ", rewards.Select(r => $"{r.Value}x {r.Key}")));

    return new { Rewards = rewards, TransactionIds = executeResult.Result.TransactionIds };
}

La función auxiliar GetContainerCurrencyId asigna el nombre de una tabla de botín al identificador de la moneda de contenedor correspondiente. Puede almacenar esta asignación en Title Data junto con las tablas de botín, o usar una convención de nomenclatura.

Paso 3: otorgar tokens de contenedor a los jugadores

Otorgue tokens de contenedor a los jugadores mediante el propio juego, compras en la tienda o recompensas. Use el mismo enfoque descrito en Contenedores con contenido fijo.

Paso 4: llamar a la función desde el cliente del juego

Cuando el jugador quiera abrir un contenedor, llame a la función de Azure mediante ExecuteFunction:

{
    "FunctionName": "OpenLootContainer",
    "FunctionParameter": {
        "LootTableId": "TreasureChest"
    },
    "GeneratePlayStreamEvent": true
}

La respuesta contiene las recompensas seleccionadas aleatoriamente:

{
    "FunctionResult": {
        "Rewards": {
            "{{UncommonSwordID}}": 1
        },
        "TransactionIds": ["txn-abc-123"]
    }
}

Patrones de diseño de tablas de botín

Niveles de rareza

El clásico sistema de rareza con pesos que decrecen exponencialmente:

{
  "Items": [
    { "ItemId": "CommonItem",     "Weight": 1000, "MinQuantity": 1, "MaxQuantity": 1 },
    { "ItemId": "UncommonItem",   "Weight": 100,  "MinQuantity": 1, "MaxQuantity": 1 },
    { "ItemId": "RareItem",       "Weight": 10,   "MinQuantity": 1, "MaxQuantity": 1 },
    { "ItemId": "LegendaryItem",  "Weight": 1,    "MinQuantity": 1, "MaxQuantity": 1 }
  ]
}

Probabilidades de caída:

Común: ~90,0 %
Poco común: ~9,0 %
Raro: ~0,9 %
Legendario: ~0,09 %

Sorteo múltiple con recompensas mixtas

Una caja de suministros que da tres objetos aleatorios de un grupo mixto:

{
  "Rolls": 3,
  "Items": [
    { "ItemId": "{{HealthPotionID}}", "Weight": 40, "MinQuantity": 1, "MaxQuantity": 3 },
    { "ItemId": "{{ManaPotionID}}",   "Weight": 40, "MinQuantity": 1, "MaxQuantity": 3 },
    { "ItemId": "{{GoldCurrencyID}}", "Weight": 30, "MinQuantity": 10, "MaxQuantity": 50 },
    { "ItemId": "{{RareGemID}}",      "Weight": 5,  "MinQuantity": 1, "MaxQuantity": 1 }
  ]
}

Garantizado + aleatorio (sistema de compasión)

Para un patrón de “raro o mejor garantizado cada 10 aperturas”, registre el recuento de aperturas del jugador en Display Properties o en Player Data, y anule la selección aleatoria en la función de Azure cuando se alcance el umbral.

Tablas de botín anidadas

Una tabla de botín puede hacer referencia a otra tabla de botín por su identificador. Su función de Azure resuelve la referencia de forma recursiva:

{
  "BossDropTable": {
    "Rolls": 2,
    "Items": [
      { "ItemId": "TABLE:WeaponDropTable", "Weight": 50, "MinQuantity": 1, "MaxQuantity": 1 },
      { "ItemId": "TABLE:ArmorDropTable",  "Weight": 30, "MinQuantity": 1, "MaxQuantity": 1 },
      { "ItemId": "{{GoldCurrencyID}}",    "Weight": 80, "MinQuantity": 50, "MaxQuantity": 200 }
    ]
  }
}

La función comprueba si un ItemId empieza por TABLE: y, si es así, sortea en la tabla referenciada en lugar de otorgar el objeto directamente.

Consideraciones de seguridad

Ejecute siempre la lógica de botín en el lado del servidor en una función de Azure. Nunca confíe en el cliente para determinar qué objetos se sortearon. Este enfoque evita manipulaciones.
Use IdempotencyId en la llamada a ExecuteInventoryOperations para evitar otorgamientos duplicados si la función se reintenta. Para obtener más información, consulte Transacciones idempotentes y reintentos.
Valide la propiedad del contenedor comprobando el inventario del jugador antes de restar. La operación Subtract de ExecuteInventoryOperations falla si el jugador no tiene suficientes tokens, lo que revierte todo el lote.
Registre todos los sorteos con fines de auditoría. El valor devuelto de la función y los eventos de PlayStream proporcionan un rastro de lo que recibió cada jugador.

XBOX Services

PlayFab

Cómo funciona

Requisitos previos

Paso 1: definir tablas de botín en Title Data

Estructura de ejemplo de una tabla de botín

Establecer Title Data

Game Manager

API

Paso 2: crear la función de Azure

Modelos de datos

Selección aleatoria ponderada

Función de Azure completa

Paso 3: otorgar tokens de contenedor a los jugadores

Paso 4: llamar a la función desde el cliente del juego

Patrones de diseño de tablas de botín

Niveles de rareza

Sorteo múltiple con recompensas mixtas

Garantizado + aleatorio (sistema de compasión)

Tablas de botín anidadas

Consideraciones de seguridad

Consulte también

​Cómo funciona

​Requisitos previos

​Paso 1: definir tablas de botín en Title Data

​Estructura de ejemplo de una tabla de botín

​Establecer Title Data

​Game Manager

​API

​Paso 2: crear la función de Azure

​Modelos de datos

​Selección aleatoria ponderada

​Función de Azure completa

​Paso 3: otorgar tokens de contenedor a los jugadores

​Paso 4: llamar a la función desde el cliente del juego

​Patrones de diseño de tablas de botín

​Niveles de rareza

​Sorteo múltiple con recompensas mixtas

​Garantizado + aleatorio (sistema de compasión)

​Tablas de botín anidadas

​Consideraciones de seguridad

​Consulte también

Cómo funciona

Requisitos previos

Paso 1: definir tablas de botín en Title Data

Estructura de ejemplo de una tabla de botín

Establecer Title Data

Game Manager

API

Paso 2: crear la función de Azure

Modelos de datos

Selección aleatoria ponderada

Función de Azure completa

Paso 3: otorgar tokens de contenedor a los jugadores

Paso 4: llamar a la función desde el cliente del juego

Patrones de diseño de tablas de botín

Niveles de rareza

Sorteo múltiple con recompensas mixtas

Garantizado + aleatorio (sistema de compasión)

Tablas de botín anidadas

Consideraciones de seguridad

Consulte también