Personalize o skin de um jogo

Um jogo vem com uma aparência padrão. Na aba Skin do editor do jogo você pode sobrescrever suas cores, trocar seus ativos visuais (imagens e, onde o jogo os usa, áudio e vídeo), e definir quaisquer controles não-cor que o autor expôs (um botão, um número, uma escolha) para que o desafio combine com sua marca, e a mudança se aplica ao jogo renderizado.

A personalização de skin está disponível do plano Alpha em diante (Alpha, Troop, Apex).

Defina cores, ativos e outros controles

Abra o jogo na página Jogos de uma chave de site (ou da equipe), depois a aba Skin. A aba mostra os slots que o autor do jogo expôs. A maioria são cores e ativos, mas um autor também pode expor um botão (ligado/desligado), um número (muitas vezes com um mínimo e um máximo), ou uma escolha de uma lista fixa. Defina uma cor com um valor hex ou rgb(); defina um ativo fazendo upload de um arquivo ou colando uma URL (veja abaixo); defina os outros slots com o controle mostrado. Deixe um slot intocado e ele mantém o valor empacotado do jogo.

Como um skin é escolhido em tempo de execução

Cada preset declara o modo em que funciona: claro, escuro ou any (lê bem em ambos os fundos). Há um padrão por modo, então o jogo fica certo qualquer que seja o modo que o aparelho do visitante prefere. Um preset marcado any é elegível para ser o padrão de claro, escuro, ou ambos. Escolher um acontece em duas etapas.

Primeiro o widget decide qual skin pedir:

1. O atributo skin do widget, se a página definiu um: um nome exato de preset (por exemplo midnight), ou o atalho light / dark.
2. Senão, a preferência de sistema do visitante (prefers-color-scheme), que resolve para light ou dark.

Depois o servidor casa isso contra os presets, após mesclar suas substituições (chave de site sobre equipe sobre o conjunto empacotado do jogo). Um nome exato de preset no atributo vence de imediato. Senão, para o modo escolhido o servidor pega o primeiro preset, na ordem de declaração, que é elegível para esse modo e marcado como padrão (um preset é elegível quando seu modo é esse modo ou any); se nenhum está marcado como padrão ele pega o primeiro preset elegível.

Como um preset any é elegível para os dois modos, você pode fazer um skin ser o padrão em todo lugar, ou dar a um modo um skin dedicado e deixar um skin any cobrir o outro. Na aba Skin um skin any aparece tanto sob o grupo claro quanto o escuro, e você o define como o padrão de um ou de ambos.

No elemento <caputchin-game> você também pode passar um objeto skin inline: um objeto JSON escrito como o valor do atributo, por exemplo skin='{"primary":"#7c3aed"}'. O widget o envia ao servidor como o sinal de skin daquela montagem, e o servidor o faz parse e o sobrepõe aos presets resolvidos, então suas cores e ativos inline vencem tudo acima (incluindo suas substituições de equipe e de chave de site). É uma propriedade do seu próprio markup, então funciona em qualquer plano. A checkbox <caputchin-widget> não aceita um skin inline; seu atributo skin aceita só light / dark ou um nome de preset. Veja nossa filosofia para saber por que essa autoria por embed é grátis.

Ativos: upload ou link

Um slot de ativo (imagem, áudio ou vídeo) aceita ou um arquivo enviado por upload ou uma URL que você cola:

• Upload: o Caputchin guarda um instantâneo do arquivo. Ele fica congelado, então não vai mudar a menos que você faça upload de novo.
• Link: você cola uma URL https para um arquivo que você hospeda. Ela é ativa, então substituir o arquivo nessa URL atualiza o jogo no próximo carregamento.

Como o jogo roda em um frame em sandbox, um ativo linkado só carrega se sua origem for permitida. O Caputchin cuida disso por você: ele permite exatamente as origens para as quais seus presets de skin apontam, e nada mais. Você não muda nenhuma política por conta própria.

Cada tipo de ativo aceita um conjunto fixo de formatos (por exemplo PNG, JPEG, WebP, SVG e GIF para imagens). Os formatos exatos e as regras de cor estão na referência de esquema.

O que se aplica, e onde

As substituições de skin resolvem no servidor, o mais específico vence: um preset de chave de site vence o preset da equipe, que vence o skin empacotado do jogo. Você pode estender um preset empacotado e sobrescrever só os slots que quer, herdando o resto.

Como um valor de skin chega ao jogo

O servidor resolve seu skin (suas substituições mescladas sobre o conjunto empacotado) e entrega o resultado ao código do próprio jogo, que se desenha com ele. Cores e URLs de ativos chegam como texto; um botão chega como um true / false de verdade, um número como um número de verdade, uma escolha como a string escolhida. O autor do jogo decide como cada valor é usado, então o que um slot de fato muda depende do jogo. Você não escreve nenhum CSS para o jogo: ele roda em um frame em sandbox que você não consegue estilizar da sua página.

O shell do widget (a moldura do Caputchin ao redor do jogo, e a checkbox autônoma) é diferente: seu skin resolvido também é exposto à sua página como propriedades CSS personalizadas chamadas --cpt-skin-<token>, que você pode ler ou sobrescrever a partir da sua própria folha de estilo. Essa superfície, e como fazer white-label do shell, é coberta em Estilize o widget com CSS. Essas variáveis são só do shell; elas não carregam o skin de um jogo.

Veja também

• Visão geral da personalização de jogo: registrar um jogo e gerenciá-lo.
• Configurações e idioma: os outros dois eixos.
• Referência de esquema: regras de cor, formatos de ativos e o modelo de preset.
• Estilize o widget com CSS: as variáveis --cpt-skin-* do shell e os shadow parts.