Referência de esquema de personalização

Esta é a referência única do modelo de tipo de campo e de preset da Caputchin, a base compartilhada sob cada superfície personalizável:

• Personalização de jogo: o idioma, o skin e a configuração de um jogo de marketplace.
• Esquemas de jogo personalizado: o esquema que você mesmo cria para um jogo personalizado.
• Manifestos de jogo de marketplace: os blocos locales / skins / configurations que um autor de jogo declara.
• White-label do widget: o esquema embutido do shell do widget.

Todos os quatro usam os mesmos tipos de campo e o mesmo modelo de preset descritos aqui. A personalização é construída de presets, e um preset é um saco de campos tipados.

Tipos de campo por eixo

Cada eixo permite um conjunto fixo de tipos de campo:

Um skin não é só cores e ativos: ele também pode expor os controles escalares boolean, number, range e list (um toggle de "sombras", um número de raio de canto, uma escolha de "padrão"). Estes se comportam exatamente como suas contrapartes de configuração e resolvem para seu valor tipado (um boolean continua true, um number continua 8); valores de color e de ativo resolvem para strings. O skin não permite string nem link (texto livre pertence ao idioma; um alvo de link é uma configuração).

O que cada tipo aceita

A Caputchin valida cada valor quando você salva, então um valor que não se encaixa no seu tipo é rejeitado antes de poder chegar a um visitante.

Chaves reservadas

Ao lado dos seus campos de conteúdo, um preset carrega algumas chaves de metadados reservadas (cada uma prefixada com um underscore) que controlam como ele é selecionado e resolvido, não o que ele exibe. Como você as define depende da superfície: um autor de jogo de marketplace as escreve literalmente no caputchin.json; no editor do painel (jogos personalizados, white-label) você as define por controles e nunca digita a chave. De um jeito ou de outro o significado é o mesmo.

As chaves de metadados reservadas são removidas durante a resolução: _extends e _default nunca chegam ao jogo, e só os metadados sobreviventes (_lang, _direction, _theme) mais os campos de conteúdo achatados são entregues.

Estender um preset

_extends deixa um preset herdar cada valor de outro, para que você crie só os campos que diferem em vez de repetir um preset inteiro. Defina _extends como o nome de outro preset no mesmo eixo; o preset que estende parte de todos os valores desse preset e sobrescreve as chaves que ele mesmo define.

{
  "skins": {
    "presets": {
      "brand-light": { "_theme": "light", "accent": "#2da44e", "bg": "#ffffff" },
      "brand-light-warm": { "_extends": "brand-light", "accent": "#d97706" }
    }
  }
}

Aqui brand-light-warm herda bg de brand-light e muda só accent.

Dois detalhes:

• Atalho de tema de skin. Em um preset de skin, _extends pode em vez disso nomear um tema (light ou dark) em vez de um preset. Essa forma resolve para qualquer preset que seja o _default daquele tema, uma forma conveniente de basear uma variante no "skin claro padrão" sem nomeá-lo.
• Ele se resolve e some. _extends é seguido e depois removido; o jogo recebe o resultado totalmente mesclado, nunca a própria chave _extends.

De onde vem um esquema

O conjunto de campos que um preset pode preencher (o seu esquema) tem três fontes, todas usando os mesmos tipos de campo acima:

• Jogo de marketplace: o esquema vem do manifesto do autor do jogo, buscado quando você abre o editor. Você sobrescreve os presets do jogo mas não muda o seu esquema.
• Jogo personalizado: você mesmo define o esquema no painel, depois cria presets contra ele. Veja jogos personalizados.
• Shell do widget (white-label): um esquema fixo e embutido. Você sobrescreve seus presets; o conjunto de campos não é declarado pelo autor. Veja white-label do widget.

Presets e resolução

Dentro de um eixo, os campos são agrupados em presets nomeados, e o servidor resolve um preset efetivo por grupo a partir dos escopos em camadas, chave de site sobre equipe sobre o padrão empacotado, calculado por valor. Os seletores diferem por eixo: o idioma é escolhido pelo idioma do navegador do visitante, o skin pela preferência clara ou escura do visitante (um preset cujo modo é any é elegível para qualquer um), e a configuração é autoritativa no servidor (o visitante não pode escolhê-la). Veja a visão geral para o modelo de escopo.

Veja também

• Visão geral da personalização de jogo: registrar e gerenciar jogos, mais os guias por eixo de configurações, idioma, e skin.
• Esquema do painel para jogo personalizado: criar um esquema você mesmo para um jogo personalizado.
• O manifesto caputchin.json: declarar estes blocos como um autor de jogo de marketplace.
• White-label do widget: os mesmos tipos aplicados ao shell do widget.