---
type: reference
title: Referência de esquema de personalização
summary: O modelo compartilhado de tipo de campo e de preset por trás de cada superfície personalizável, os tipos de campo que cada eixo permite, os valores que cada um aceita, e como esquemas e presets são definidos e resolvidos.
---

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](/docs/game-customization/overview): o idioma, o skin e a configuração de um jogo de marketplace.
- [Esquemas de jogo personalizado](/docs/custom-game-development/dashboard-schema): o esquema que você mesmo cria para um jogo personalizado.
- [Manifestos de jogo de marketplace](/docs/marketplace-game-development/the-caputchin-json-manifest): os blocos `locales` / `skins` / `configurations` que um autor de jogo declara.
- [White-label do widget](/docs/widget-customization/white-label): 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:

| Eixo | Tipos de campo permitidos |
|---|---|
| Configuração | `boolean`, `number`, `range`, `list`, `string`, `link` |
| Idioma | só `string` |
| Skin | `color`, `image`, `audio`, `video`, `boolean`, `number`, `range`, `list` |

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

| Tipo | Valor | Regras |
|---|---|---|
| `string` | Texto livre | Qualquer texto. |
| `boolean` | Um toggle | `true` ou `false`. |
| `number` | Um número | Qualquer número finito. |
| `range` | Um número delimitado | Um número finito dentro do mínimo e do máximo do campo. O passo é uma conveniência do slider; valores fora do passo ainda são aceitos. |
| `list` | Uma escolha | Precisa ser uma das opções listadas do campo. |
| `link` | Uma URL | Uma URL `http` ou `https`. Credenciais embutidas são rejeitadas. |
| `color` | Uma cor | Uma cor hex (`#rgb`, `#rgba`, `#rrggbb`, ou `#rrggbbaa`) ou um valor `rgb()` / `rgba()`. Cores nomeadas e outros espaços de cor não são aceitos. |
| `image` | Uma imagem | Um arquivo enviado por upload ou uma URL `https` terminando em `.png`, `.jpg`, `.jpeg`, `.webp`, `.svg`, ou `.gif`. |
| `audio` | Um clipe de áudio | Um arquivo enviado por upload ou uma URL `https` terminando em `.mp3`, `.ogg`, ou `.wav`. |
| `video` | Um vídeo | Um arquivo enviado por upload ou uma URL `https` terminando em `.mp4` ou `.webm`. |

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](/docs/marketplace-game-development/the-caputchin-json-manifest) 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.

| Chave | Eixo | Significado |
|---|---|---|
| `_lang` | Idioma | A tag de idioma BCP-47 que um preset de idioma serve (`en`, `es`, e assim por diante). Os presets são agrupados por ela; vários presets podem compartilhar um `_lang` (ex.: duas variantes de inglês). |
| `_direction` | Idioma | `ltr` ou `rtl`. Opcional, auto-derivada de `_lang` para idiomas da direita para a esquerda (`ar`, `he`, `fa`, `ur`, `yi`, `ps`, `sd`); raramente definida à mão. |
| `_theme` | Skin | `light`, `dark`, ou `any`. Um preset `light` / `dark` aparece só sob aquele fundo; um preset `any` funciona sob os dois e é elegível para qualquer um. O padrão é `light` quando ausente. |
| `_default` | Todos | Marca o preset que o servidor escolhe para o seu grupo quando o visitante não seleciona um. Um padrão por grupo (por modo para skin); um skin `any` pode ser o padrão de claro, escuro, ou ambos. |
| `_extends` | Todos | Nomeia outro preset do qual herdar. Veja [Estender um preset](#extending-a-preset). |

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 [#extending-a-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.

```json
{
  "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](/docs/game-customization/custom-games).
- **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](/docs/widget-customization/white-label).

## 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](/docs/game-customization/overview#troop-and-site-key-scope) para o modelo de escopo.

## Veja também

- [Visão geral da personalização de jogo](/docs/game-customization/overview): registrar e gerenciar jogos, mais os guias por eixo de [configurações](/docs/game-customization/configurations), [idioma](/docs/game-customization/locale), e [skin](/docs/game-customization/skin).
- [Esquema do painel para jogo personalizado](/docs/custom-game-development/dashboard-schema): criar um esquema você mesmo para um jogo personalizado.
- [O manifesto caputchin.json](/docs/marketplace-game-development/the-caputchin-json-manifest): declarar estes blocos como um autor de jogo de marketplace.
- [White-label do widget](/docs/widget-customization/white-label): os mesmos tipos aplicados ao shell do widget.