Referencia del SDK

El SDK de Gamealia es window.Gamealia. Cargalo en index.html antes de los scripts del juego:

<script src="https://gamealia.app/sdk/v1.js"></script>

El SDK no está publicado en npm. Los shims de CrazyGames y Poki (/sdk/crazygames.js, /sdk/poki.js) también lo incluyen, así que una página carga uno solo de los tres archivos.

Cómo se comportan las llamadas

• Promesas que nunca fallan. Toda llamada asíncrona se resuelve, con un valor seguro si algo sale mal (por ejemplo { shown: false, rewarded: false } para un anuncio, null para un usuario). Nunca necesitás try/catch alrededor del SDK.
• Primero init. Llamá a Gamealia.init() una vez al arrancar. Las demás llamadas lo esperan (y lo inician si no lo hiciste), así que el orden siempre es correcto, pero llamalo vos primero: el chequeo sdk_init del autotest exige que init sea el primer mensaje del SDK.
• Tiempos de espera. Dentro del portal, una llamada sin respuesta devuelve su valor por defecto a los 15 s; los anuncios y requestLogin esperan hasta 120 s. init() espera hasta 5 s al portal y después pasa al mock.
• Modo mock. Cuando la página no está dentro del portal (tu servidor de desarrollo, un archivo abierto, el sitio propio de tu juego), el SDK usa un mock local, descrito en cada método. Agregá ?gamealia_debug=1 a la URL para ver un panelcito que registra cada llamada al SDK.

Tipos

interface InitResult {
  environment: "gamealia" | "preview" | "autotest" | "mock";
  locale: string;          // el idioma del jugador en el portal, ej. "es", "en", "pt-BR", "ja"
  gameId: string;          // el id de tu juego ("local" en el mock)
  user: PublicUser | null; // null para invitados
  joinRoom: string | null; // el código de sala al que invitaron al jugador
  device: "mobile" | "desktop";
}
interface PublicUser { id: string; username: string; avatarUrl: string | null }
interface AdResult { shown: boolean; rewarded: boolean }
interface RoomInfo { code: string; name: string; players: number; max: number; inProgress: boolean }
type EventType = "adStart" | "adEnd" | "userChange" | "roomJoin" | "pause" | "resume" | "mute" | "unmute";

PublicUser.id es por juego: el mismo jugador tiene un id distinto en cada juego, así los juegos no pueden cruzar jugadores entre sí. environment es "preview" en la vista previa del desarrollador y del revisor, "autotest" durante el autotest y "gamealia" en el portal publicado.

Ciclo de vida

Gamealia.init(): Promise<InitResult>

La primera llamada, una vez, al arrancar. Si la llamás de nuevo devuelve la misma promesa.

const { locale, user, device, joinRoom } = await Gamealia.init();
setLanguage(locale.startsWith("es") ? "es" : "en");

Mock: environment: "mock", gameId: "local", locale según los idiomas del navegador, user: null (hasta requestLogin), joinRoom desde ?gamealia_join=CODIGO, device "mobile" cuando la ventana mide menos de 768 px o es táctil.

Gamealia.peekInit(): InitResult | null

El resultado de init una vez que init() terminó; si no, null. Sincrónica, para código que no puede esperar.

Gamealia.game.loadingStart(): Promise<void>

Empezó la carga. Opcional.

Gamealia.game.loadingStop(): Promise<void>

Obligatoria. El juego terminó de cargar y se puede jugar. El autotest falla si no llega dentro de los 15 s de cargada la página.

Gamealia.game.gameplayStart(): Promise<void> / Gamealia.game.gameplayStop(): Promise<void>

Empieza el juego en sí (primer input, inicio de nivel, salir de pausa) y se detiene (game over, menú de pausa, fin de nivel, un anuncio). Alimentan las estadísticas y la presencia de tus amigos; el autotest avisa si gameplayStart no llega después del primer input.

Gamealia.game.happyTime(): Promise<void>

Un gran momento: una victoria, un récord, un nivel superado.

Ninguna llamada game.* hace algo visible en el mock (aparecen en el panel de debug).

Anuncios

Las reglas y la frecuencia están en Anuncios.

Gamealia.ad.requestMidgame(): Promise<AdResult>

Una pausa con anuncio intersticial en un corte natural. Se resuelve cuando termina la pausa (o si se saltea), con shown: true solo si se mostró un anuncio. El portal puede saltearla (límite de frecuencia, anuncios desactivados, sin anuncio disponible): entonces resuelve { shown: false, rewarded: false } enseguida.

Gamealia.ad.requestRewarded(): Promise<AdResult>

Un anuncio con recompensa que el jugador eligió ver. Dá la recompensa solo cuando rewarded es true.

const { rewarded } = await Gamealia.ad.requestRewarded();
if (rewarded) lives++;

Mock (los dos): una capa "Mock ad" a pantalla completa durante 2 s, los eventos adStart y adEnd, y después { shown: true, rewarded: true } para uno con recompensa y { shown: true, rewarded: false } para un midgame.

Gamealia.onAdStart(cb): () => void / Gamealia.onAdEnd(cb): () => void

Atajos de Gamealia.on("adStart", cb) y Gamealia.on("adEnd", cb). Pausá el juego y silenciá el audio entre uno y otro. Cada uno devuelve una función para desuscribirse.

Jugadores

Backends y tokens en Cuentas de jugador.

Gamealia.user.get(): Promise<PublicUser | null>

El jugador con sesión iniciada, o null si es invitado. Mock: null hasta requestLogin().

Gamealia.user.getToken(): Promise<string | null>

Un token firmado (JWT ES256, válido 5 minutos) que tu propio backend verifica para identificar al jugador. null para invitados. Mock: siempre null.

Gamealia.user.requestLogin(): Promise<PublicUser | null>

Le pide al portal que muestre su inicio de sesión. Devuelve el jugador cuando entra, o null si no lo hizo. Llamala desde un botón que el jugador tocó. Nunca armes un login propio. Mock: inicia sesión con el jugador falso { id: "mock-user", username: "Mock Player", avatarUrl: null } y dispara userChange.

Gamealia.user.onChange(cb: (user: PublicUser | null) => void): () => void

El jugador inició o cerró sesión. Devuelve una función para desuscribirse. El SDK ya descartó la partida en caché: llamá a data.load() acá (ver Guardado en la nube).

Partidas guardadas

Mirá Guardado en la nube.

Gamealia.data.load(): Promise<{ ok: true; data } | { ok: false; error }>

Todos los datos guardados del jugador en este juego. A diferencia de getAll(), distingue "todavía no hay partida" ({ ok: true, data: {} }) de "no se pudo leer" ({ ok: false, error: "timeout" }). Con ok: false, no empieces una partida nueva encima de la vieja.

Gamealia.data.get(key: string): Promise<unknown>

Un valor guardado, o null si no hay (o no se pudo leer).

Gamealia.data.set(key: string, value: unknown): Promise<boolean>

Guarda un valor serializable a JSON. Devuelve false si no se guardó: el valor no es JSON, la partida completa pasaría de 1 MB (bytes UTF-8 de toda la partida como un solo objeto JSON), o el portal lo rechazó.

Gamealia.data.getAll(): Promise<Record<string, unknown>>

Todos los datos guardados ({} si no hay o no se pudieron leer).

Gamealia.data.remove(key: string): Promise<void> / Gamealia.data.clear(): Promise<void>

Borra una clave, o toda la partida guardada de este juego.

Mock: los datos quedan en el localStorage de este navegador, con claves que empiezan con gml:local:.

Multijugador

Mirá Multijugador.

Gamealia.room.getJoinCode(): string | null

El código de la sala a la que invitaron al jugador (por el link de invitación), o null. Sincrónica; válida después de init().

Gamealia.room.inviteLink(code: string): Promise<string>

Un link que abre tu juego en el portal y entra a la sala code (https://gamealia.app/game/<slug>?room=<code>). Mock: la URL actual con ?gamealia_join=<code>. Los códigos tienen de 1 a 32 caracteres de A-Z a-z 0-9 _ -.

Gamealia.room.showInvite(code: string): Promise<void>

Abre la hoja de invitación del portal (copiar link, compartir) para la sala code.

Gamealia.room.publish(room: RoomInfo): Promise<void>

Publica la sala en las salas abiertas del portal para que otros entren. El SDK la repite cada 15 s mientras la página está abierta; el portal saca una sala de la que no supo nada en 30 s. Publicar otro código reemplaza la sala anterior.

Gamealia.room.unpublish(): Promise<void>

Saca la sala (está llena, empezó o se cerró) y frena el latido.

Gamealia.presence.setStatus(text: string): Promise<void>

Un estado corto de lo que está haciendo el jugador ("Nivel 3", "En el lobby"), que sus amigos ven junto al juego que está jugando. El portal quita los caracteres de control, lo corta a 64 caracteres y reenvía como mucho un cambio cada 2 s (de una ráfaga queda el último). Un texto vacío lo borra; también se borra cuando el jugador sale del juego. Mock: solo se registra.

Eventos

Gamealia.on(event: EventType, cb): () => void

Se suscribe a un evento y devuelve una función para desuscribirse.

Exportaciones del módulo

Para código dentro de un bundle (los shims las usan): createGamealia(window) crea una instancia nueva del SDK atada a una ventana y getGamealia(window) devuelve la instancia única de la página (window.Gamealia).