API de compras/productos

Los jugadores pueden comprar productos (pases de juego + consumibles) por Sparks en tu juego. Cuando se realiza una compra, All Out llama a tu controlador de compras para que puedas otorgar el objeto o la función.

Para crear productos y ver analíticas, consulta Productos dentro del juego.

Tipos de productos (resumen rápido)

• Pases de juego: desbloqueos permanentes de una sola vez (pase de administrador, habilidad permanente, propiedad de una casa)
• Consumibles: se pueden comprar varias veces (poción, mejora temporal, paquete de monedas de una sola vez)

Los tipos de productos se configuran en el portal de creadores. Consulta Productos dentro del juego.

Referencia de la API de compras

Product :: struct {
    id: string;
    name: string;
    description: string;
    price: s64;
    consumable: bool;
    icon: Texture_Asset;
}

Purchasing :: struct {
    prompt_purchase :: proc(player: Player, id: string);
    owns_product    :: proc(player: Player, id: string) -> bool;
    get_product     :: proc(id: string) -> Product;
}

Solicitar una compra

Para iniciar el flujo de compra, llama a Purchasing.prompt_purchase con un ID de producto.

BUY_DOUBLE_JUMP_ID :: "prod_double_jump";

try_prompt_double_jump :: proc(player: Player) {
    Purchasing.prompt_purchase(player, BUY_DOUBLE_JUMP_ID);
}

El ID del producto se muestra en la página de monetización/productos del portal de creadores (puedes hacer clic para copiarlo). Consulta Productos dentro del juego.

Comprobar si un jugador posee un producto (pases de juego)

Para los pases de juego, puedes restringir funciones de juego comprobando la propiedad.

ADMIN_PASS_ID :: "prod_admin";

is_admin :: proc(player: Player) -> bool {
    return Purchasing.owns_product(player, ADMIN_PASS_ID);
}

Los consumibles se pueden comprar varias veces; no debería usarse owns_product para otorgarlos. Los consumibles normalmente se otorgan en tu controlador de compras (monedas, objetos, mejoras, etc).

Leer información del producto (nombre/precio/icono)

Si quieres mostrar una interfaz de “Comprar” o registrar información del producto, obtén la definición del producto por ID:

product := Purchasing.get_product("prod_double_jump");
log_info("El producto % cuesta % Sparks", {product.name, product.price});

El controlador de compras (otorgamiento)

Cuando un jugador compra un producto en tu juego, All Out llama a:

ao_purchase_handler :: proc(player: Player, id: string) -> bool

Si tu juego no define ao_purchase_handler, los productos no consumibles se otorgan automáticamente para que funcionen con Purchasing.owns_product. Los productos consumibles siguen requiriendo un controlador y se marcan como fallos de otorgamiento sin uno.

Debes:

• Hacer un switch sobre el ID del producto
• Otorgar el objeto/la función
• Devuelve true si el otorgamiento tuvo éxito
• Devuelve false si el otorgamiento falló (inventario lleno, requisito previo faltante, etc)

COIN_PACK_ID :: "prod_coin_pack_small";
DOUBLE_JUMP_ID :: "prod_double_jump";

ao_purchase_handler :: proc(player: Player, id: string) -> bool {
    switch id {
        case COIN_PACK_ID: {
            // Ejemplo: otorgar monedas (consumible)
            Economy.deposit_currency(player, "Coins", 500);
            Notifier.notify(player, "¡Gracias! +500 monedas");
            return true;
        }
        case DOUBLE_JUMP_ID: {
            // Ejemplo: desbloqueo de pase de juego (permanente)
            // Normalmente solo lo habilitas mediante comprobaciones owns_product() en otra parte.
            // Aun así, devuelve true para que la compra se considere otorgada.
            Notifier.notify(player, "¡Doble salto desbloqueado!");
            return true;
        }
    }

    // ID desconocido
    return false;
}

Fallos de otorgamiento y reintentos

Si tu controlador de compras devuelve false, la compra se marca como un fallo de otorgamiento.

• Los fallos de otorgamiento se muestran en el portal de creadores
• Se reintentan automáticamente cuando el jugador entra hasta que tienen éxito
• Puedes volver a ejecutar manualmente un controlador de compras marcando una compra como “sin otorgar” en la interfaz de datos del jugador

Consulta:

• Productos dentro del juego (“Controladores de compras / Fallos de otorgamiento”)
• Editar/ver datos del jugador (sección “Compras”)

Entre juegos (hub + minijuegos)

Si usas la jerarquía de juegos, las compras se pueden compartir entre tus juegos. Consulta Productos/datos entre juegos.