API de compra/producto

Los jugadores pueden comprar productos (pases de juego + consumibles) por Sparks en tu juego. Cuando ocurre una compra, All Out llama a tu manejador de compras para que puedas otorgar el objeto o la característica.

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

Tipos de productos (resumen rápido)

• Pases de juego: desbloqueos persistentes de una sola vez (pase de admin, habilidad permanente, propiedad de 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 del creador. Consulta Productos dentro del juego.

Referencia de la API de compras

Producto :: 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 en el portal del creador (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 limitar funciones del 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 se debe usar owns_product para otorgarlos. Los consumibles normalmente se conceden en tu manejador 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 manejador de compras (concesión)

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 conceden automáticamente para que funcionen con Purchasing.owns_product. Los productos consumibles siguen requiriendo un manejador y se marcan como fallos de concesión si no hay uno.

Deberías:

• Hacer switch sobre el ID del producto

• Conceder el objeto/la característica

• Devolver true si la concesión tuvo éxito

• Devolver false si la concesión falló (inventario lleno, prerrequisito 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: conceder 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 (persistente)
            // Normalmente solo lo habilitas mediante comprobaciones de owns_product() en otra parte.
            // Aun así, devuelve true para que la compra se considere concedida.
            Notifier.notify(player, "¡Doble salto desbloqueado!");
            return true;
        }
    }

    // ID desconocido
    return false;
}

Fallos de concesión y reintentos

Si tu manejador de compras devuelve false, la compra se marca como un fallo de concesión.

• Los fallos de concesión se muestran en el portal del creador

• Se reintentan automáticamente cuando el jugador entra hasta que tienen éxito

• Puedes volver a ejecutar manualmente un manejador de compras marcando una compra como “no concedida” en la interfaz de datos del jugador

Consulta:

• Productos dentro del juego (“Manejadores de compra / Fallos de concesión”)

• Editar/ver datos del jugador (sección “Compras”)

Probar compras

En un juego iniciado desde el editor (Iniciar juego o run_tests), Purchasing.prompt_purchase abre un aviso de compra de prueba marcado como "Compra de prueba: no se gastan Sparks". Ofrece Comprar según tu saldo de Sparks. Comprar ejecuta tu ao_purchase_handler a través del mismo flujo del servidor que una compra real, y un pase de juego concedido entonces pasa Purchasing.owns_product.

• El producto ya debe existir para tu juego (consulta Productos dentro del juego).

• El aviso dice "Compra completada" incluso cuando tu manejador devuelve false, así que revisa la concesión en sí.

• Las compras de prueba no dejan registro de compra. Después de que el jugador vuelva a entrar, owns_product vuelve a ser false y un fallo de concesión no se reintenta. Cualquier cosa que tu manejador haya guardado por su cuenta, como la moneda, se mantiene.

• Llamar a ao_purchase_handler tú mismo, por ejemplo desde un comando de chat, ejecuta solo tu código de concesión. Omite el flujo del servidor y nunca establece owns_product.

En una prueba, pulsa los botones del aviso por nombre:

test_buy_coin_pack :: proc() {
    Test.click_button("coin_pack_button");    // tu UI que llama a Purchasing.prompt_purchase
    Test.click_button("purchase modal/Buy");  // espera hasta ~3 s a que se cargue el producto
    Test.wait_seconds(3);                     // el manejador se ejecuta 1-2 s después de Buy
    Test.click_button("purchase modal/Okay"); // cierra "Compra completada"
    Test.assert_balance("coin pack granted", "Coins", 500);
}

Entre juegos (hub + minijuegos)

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