Recompensas (XP y monedas)

Cuando un estudiante completa una partida, Ecotic le acredita automáticamente XP (experiencia) y monedas. Aquí explicamos cómo funciona ese sistema.

¿Qué son el XP y las monedas?

XP (Experience Points): acumulan experiencia de nivel. Cuando el jugador acumula suficiente XP sube de nivel en su perfil de Ecotic, lo que puede desbloquear badges, nuevas misiones o ítems de avatar.

Monedas: moneda virtual que el estudiante puede gastar en la tienda de avatares de Ecotic (ropa, accesorios, fondos, etc.).

¿Cómo se calcula la recompensa?

La recompensa exacta la define el equipo admin de Ecotic en la configuración de cada juego (campo points_policy en la tabla games). Sin embargo, todos los juegos están sujetos a límites duros que el backend aplica sin excepción:

Recurso	Máximo por sesión	Máximo por día
XP	60	240
Monedas	15	60

Aunque tu juego defina una recompensa mayor, nunca se otorgará más allá de estos límites.

Recibir la recompensa en tu código

Hay dos formas de saber cuánto ganó el jugador:

1. Callback `onReward`

Se llama automáticamente después de un complete() exitoso:

const sdk = EcoticSDK.init({
  gameSlug: 'mi-juego',
  onReward(reward) {
    console.log(`El jugador ganó: +${reward.xp} XP, +${reward.coins} monedas`);
    console.log(`Saldo total de monedas: ${reward.wallet_balance}`);
    mostrarBannerRecompensa(reward);
  },
});

2. Promesa de `complete()`

const resultado = await sdk.complete(puntuacion);

if (resultado && resultado.reward) {
  const { xp, coins, wallet_balance } = resultado.reward;
  mostrarBannerRecompensa({ xp, coins });
}

Ambos métodos reciben el mismo objeto GameReward:

interface GameReward {
  xp:              number;   // XP acreditado en esta sesión
  coins:           number;   // monedas acreditadas en esta sesión
  wallet_balance?: number;   // saldo total de monedas del jugador
}

¿Qué pasa si la partida dura menos de 15 segundos?

El backend tiene un tiempo mínimo de sesión configurado (por defecto 15 segundos). Si complete() llega antes de ese tiempo desde que se creó el token, la partida se registra pero la recompensa es { xp: 0, coins: 0 }.

Esto protege el sistema contra bots. Para una partida legítima de un humano real, 15 segundos es un tiempo mínimo muy razonable.

Ciclo de recompensa del estudiante

Partida completada
       │
       ▼
Backend valida token + tiempo mínimo
       │
       ▼
Calcula recompensa (según points_policy del juego)
       │
       ▼
Aplica límites: min(recompensa, cap_sesión - ya_ganado_hoy)
       │
       ├─► Acredita XP → puede subir de nivel → badge de nivel
       └─► Acredita monedas → disponibles en la tienda de avatares

Mostrar la recompensa: ejemplo

function mostrarRecompensa(reward) {
  if (!reward || (reward.xp === 0 && reward.coins === 0)) {
    document.getElementById('banner').textContent =
      'Partida registrada (sin recompensa esta vez)';
    return;
  }

  document.getElementById('banner').innerHTML = `
    <strong>🎉 ¡Bien jugado!</strong><br>
    🔮 +${reward.xp} XP &nbsp;&nbsp; 🪙 +${reward.coins} monedas<br>
    <small>Saldo: ${reward.wallet_balance ?? '–'} monedas</small>
  `;
}