Referencia técnica

SDK de cliente de PlayDrop para juegos de navegador

SDK de navegador opcional para cualquier juego de PlayDrop: ciclo de vida del host, inicio de sesión, partidas guardadas, clasificaciones, compras, anuncios, amigos, mandos, multijugador y bibliotecas compartidas, con una sola etiqueta script.

El SDK de PlayDrop es opcional: los juegos que no lo usan también se pueden jugar en PlayDrop. Añádelo para usar funciones de la plataforma como el inicio de sesión de los jugadores, las partidas guardadas, los logros y las tablas de clasificación, las compras con Créditos, los anuncios, los amigos y las tarjetas de juego en PlayDrop Chat, los enlaces para compartir, la pausa y el audio gestionados por el host, los mandos, el multijugador alojado y la generación con IA. PlayDrop Cloud lo integra por ti; con PlayDrop Connector, tu agente añade una sola etiqueta script.

Añade el SDK y sigue el ciclo de vida del host

html

<script src="https://assets.playdrop.ai/sdk/playdrop.js"></script>
<script type="module">
  const sdk = await playdrop.init();
  // Render the game and prepare input, then:
  sdk.host.ready();
  sdk.host.onPause(() => pauseGame());
  sdk.host.onResume(() => resumeGame());
  sdk.host.onAudioPolicyChange(({ enabled }) => setAudioEnabled(enabled));
</script>

Carga el SDK desde la CDN de PlayDrop; no hace falta instalar ningún paquete. Renderiza el primer fotograma jugable y prepara la entrada antes de llamar a sdk.host.ready(). Pausa la simulación cuando el host entre en pausa, reanúdala sin duplicar bucles y respeta la política de audio del host.

Identidad, partidas guardadas e idioma

sdk.me expone la identidad del jugador y sdk.me.appData almacena sus partidas guardadas privadas; sdk.achievements y sdk.leaderboards gestionan los logros y las puntuaciones. Las partidas guardadas, los logros y las tablas de clasificación funcionan sin comprobar previamente el inicio de sesión. Usa sdk.me.isLoggedIn para las funciones que requieren una cuenta real, como las compras o el multijugador. Los modos de vista previa y de captura no deben guardar el progreso del jugador. sdk.host.language proporciona el idioma del jugador: ofrece tu juego en inglés y también en tu propio idioma si es distinto. Traducir una ficha no traduce el contenido del juego. En una pausa natural, como una victoria, sdk.host.requestReview() permite que PlayDrop pida una reseña al jugador, como máximo una vez por juego; tu juego nunca conoce la respuesta, así que nunca la premies.

Bibliotecas, recursos y multijugador

sdk.libs carga versiones compatibles de Three.js, Phaser, Rapier, nipplejs y Colyseus. sdk.assets proporciona referencias de catálogo, de paquetes y de recursos; sdk.social ofrece amigos, tarjetas de juego y acciones para compartir. Para el multijugador alojado, sdk.multiplayer.getConnection() devuelve la dirección del servidor y el token del jugador que ha iniciado sesión; únete con el cliente de Colyseus. La página del SDK de servidor cubre los servidores alojados; un servidor que gestiones tú mismo no necesita nada del SDK. Las antiguas API de salas de retransmisión se han retirado.

Prueba con el SDK antes de publicar

Ejecuta tu servidor de desarrollo habitual y abre https://www.playdrop.ai/creators/<username>/apps/game/<slug>/dev?url=http://localhost:5173/ en Chrome para jugar dentro del marco real de PlayDrop con el host del SDK. Funciona cualquier puerto de localhost o URL https. Las funciones que requieren una cuenta, como las partidas guardadas y las compras, funcionan en cuanto el juego se ha subido una vez; basta con una subida privada. La generación de contenido multimedia desde el navegador se ejecuta como tareas asíncronas con un costo en Créditos confirmado por el host. Consulta catalogue.json para los metadatos de la ficha.

Jugar juntos

Durante el juego, usa await sdk.multiplayer.join("game") para unirte a una sala o utilizar la reserva del grupo del anfitrión. Si el grupo falla, la solicitud se rechaza en vez de separar a los jugadores. getConnection() sigue proporcionando los datos de conexión inmediatamente a los juegos existentes. Conserva la misma sala entre rondas y mantén la red activa cuando las interfaces del anfitrión pausen los controles.

Usa sdk.social.openParty() desde una acción del jugador para abrir el grupo en el anfitrión. Consulta los miembros con await sdk.social.getParty() o sdk.social.onPartyChange(callback). Los juegos no pueden modificar grupos de la plataforma ni controlar micrófonos. La voz reside en el anfitrión web o nativo y respeta el consentimiento, el silencio, los bloqueos y la disponibilidad.

Para una voz espacial fluida, llama a sdk.multiplayer.voice.updateSpatialState({ listener: { position, forward, up }, speakers: [{ userId, position }] }) con vectores finitos { x, y, z }. Estas indicaciones afectan al volumen y la panorámica, nunca a la autorización. El servidor aplica las reglas de equipos y proximidad.

Usa sdk.device.localPlayers y sdk.device.onLocalPlayersChange(callback) para las posiciones locales seleccionadas { playerIndex, gamepadKey }. El inventario de mandos conectados es independiente; una posición desconectada conserva su identidad. El modo local no puede entrar en salas en línea. La receta copiable playdrop-metagame/recipes/play-together muestra ambos modos, dos destinos y las políticas de sala.

Mandos

Lee los mandos físicos y los mandos de teléfono de PlayDrop con sdk.device, igual en todas las plataformas. Llama a enableControllerInput() una vez después de init(), lee gamepad(playerIndex) en el bucle del juego (0 es P1) y usa onButton para las pulsaciones y liberaciones. Los ejes y botones siguen el orden estándar de gamepad del navegador; los botones tienen nombres por posición, como south y east, y pad.label("south") devuelve la indicación de ese mando, como "A" o "Cross". El botón Menú pertenece a PlayDrop y pausa el juego.

await sdk.device.enableControllerInput();
const stop = sdk.device.onButton(({ playerIndex, button, pressed }) => {
  if (button === "south" && pressed) jump(playerIndex);
});
function update() {
  const pad = sdk.device.gamepad(0);
  if (pad?.connected) move(pad.axes[0], pad.axes[1]);
  requestAnimationFrame(update);
}
update();

No llames a navigator.getGamepads(): los mandos de teléfono solo llegan a los juegos a través del SDK, y PlayDrop registra una advertencia cuando un juego lee directamente la API del navegador. Si el host no puede proporcionar la entrada de los mandos, enableControllerInput() se rechaza con controller_input_unavailable o controller_input_timeout y el juego sigue funcionando. pad.has("dpad") indica si un control existe; declara los controles que necesita tu juego en catalogue.json.