Referência técnica

SDK de cliente do PlayDrop para jogos de navegador

SDK de navegador opcional para qualquer jogo do PlayDrop: ciclo de vida do host, login, salvamentos, placares, compras, anúncios, amigos, controles, multijogador e bibliotecas compartilhadas, com uma única tag de script.

O SDK do PlayDrop é opcional: jogos sem ele também rodam no PlayDrop. Adicione-o para ter recursos da plataforma, como login do jogador, salvamentos, conquistas e placares, compras com Créditos, anúncios, amigos e cards de jogo no PlayDrop Chat, links de compartilhamento, pausa e áudio gerenciados pelo host, entrada de controles, multijogador hospedado e geração com IA. O PlayDrop Cloud faz a integração para você; com o PlayDrop Connector, seu agente adiciona uma tag de script.

Adicione o SDK e siga o ciclo de vida do 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>

Carregue o SDK pela CDN do PlayDrop; não é preciso instalar nenhum pacote. Renderize o primeiro quadro jogável e prepare a entrada antes de chamar sdk.host.ready(). Pause a simulação quando o host pausar, retome sem loops duplicados e siga a política de áudio do host.

Identidade, salvamentos e idioma

sdk.me expõe a identidade do jogador e sdk.me.appData armazena salvamentos privados; sdk.achievements e sdk.leaderboards cuidam de conquistas e pontuações. Salvamentos, conquistas e placares funcionam sem verificação prévia de login. Use sdk.me.isLoggedIn para recursos que exigem uma conta real, como compras ou multijogador. Os modos de prévia e de captura não devem gravar o progresso do jogador. sdk.host.language fornece o idioma do jogador: ofereça o jogo em inglês e também no seu idioma, se for diferente. Traduzir uma listagem não traduz o conteúdo do jogo. Em uma pausa natural, como uma vitória, sdk.host.requestReview() permite que o PlayDrop peça uma avaliação ao jogador, no máximo uma vez por jogo; o seu jogo nunca sabe a resposta, então nunca a recompense.

Bibliotecas, assets e multijogador

sdk.libs carrega versões compatíveis de Three.js, Phaser, Rapier, nipplejs e Colyseus. sdk.assets fornece referências de catálogo, de pacote e de asset; sdk.social oferece amigos, cards de jogo e ações de compartilhamento. Para o multijogador hospedado, sdk.multiplayer.getConnection() retorna o endereço do servidor e o token do jogador logado; entre na sala com o cliente Colyseus. A página do SDK de servidor aborda os servidores hospedados; um servidor que você mesmo executa não precisa de nada do SDK. As antigas APIs de salas de retransmissão foram descontinuadas.

Teste com o SDK antes de publicar

Rode seu servidor de desenvolvimento de sempre e abra https://www.playdrop.ai/creators/<username>/apps/game/<slug>/dev?url=http://localhost:5173/ no Chrome para jogar dentro do frame real do PlayDrop, com o host do SDK. Qualquer porta de localhost ou URL https funciona. Recursos que exigem uma conta, como salvamentos e compras, funcionam depois que o jogo é enviado uma vez; um envio privado basta. A geração de mídia no navegador é executada como tarefas assíncronas, com custo em Créditos confirmado pelo host. Consulte catalogue.json para ver os metadados da listagem.

Jogar juntos

Durante o jogo, use await sdk.multiplayer.join("game") para entrar em uma sala ou usar a reserva do grupo feita pelo host. Se o grupo falhar, a solicitação é rejeitada em vez de separar os jogadores. getConnection() continua fornecendo imediatamente os dados de conexão aos jogos existentes. Mantenha a mesma sala entre rodadas e a rede ativa quando as interfaces do host pausarem os controles.

Use sdk.social.openParty() após uma ação do jogador para abrir o grupo no host. Consulte os membros com await sdk.social.getParty() ou sdk.social.onPartyChange(callback). Jogos não podem modificar grupos da plataforma nem controlar microfones. A voz é gerenciada pelo host web ou nativo e respeita consentimento, silenciamento, bloqueios e disponibilidade.

Para voz espacial fluida, chame sdk.multiplayer.voice.updateSpatialState({ listener: { position, forward, up }, speakers: [{ userId, position }] }) com vetores finitos { x, y, z }. Essas indicações afetam volume e posição estéreo, nunca autorização. O servidor aplica as regras de equipe e proximidade.

Use sdk.device.localPlayers e sdk.device.onLocalPlayersChange(callback) para as posições locais selecionadas { playerIndex, gamepadKey }. A lista de controles conectados é independente; uma posição desconectada mantém sua identidade. O modo local não entra em salas online. A receita copiável playdrop-metagame/recipes/play-together demonstra ambos os modos, dois destinos e as políticas das salas.

Controles

Leia controles físicos e controles de celular do PlayDrop com sdk.device, do mesmo jeito em todas as plataformas. Chame enableControllerInput() uma vez depois de init(), leia gamepad(playerIndex) no loop do jogo (0 é P1) e use onButton para pressionamentos e liberações. Eixos e botões seguem a ordem padrão de gamepad do navegador; os botões têm nomes de posição, como south e east, e pad.label("south") retorna o rótulo desse controle, como "A" ou "Cross". O botão Menu pertence ao PlayDrop e pausa o jogo.

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();

Não chame navigator.getGamepads(): controles de celular só chegam aos jogos pelo SDK, e o PlayDrop registra um aviso quando um jogo lê a API do navegador diretamente. Se o host não puder fornecer a entrada dos controles, enableControllerInput() é rejeitada com controller_input_unavailable ou controller_input_timeout e o jogo continua rodando. pad.has("dpad") informa se um controle existe; declare os controles de que seu jogo precisa em catalogue.json.