Referencia del esquema de personalización

Esta es la única referencia para el modelo de tipo-de-campo y preset de Caputchin, el cimiento compartido bajo cada superficie personalizable:

• Personalización de juego: el idioma, el skin, y la configuración de un juego del marketplace.
• Esquemas de juego a medida: el esquema que creas tú mismo para un juego a medida.
• Manifiestos de juego del marketplace: los bloques locales / skins / configurations que un autor de juego declara.
• White-labeling del widget: el esquema integrado del shell del widget.

Los cuatro usan los mismos tipos de campo y el mismo modelo de preset descrito aquí. La personalización se construye a partir de presets, y un preset es una bolsa de campos tipados.

Tipos de campo por eje

Cada eje permite un conjunto fijo de tipos de campo:

Un skin no es solo colores y assets: también puede exponer las perillas escalares boolean, number, range, y list (un interruptor de "sombras", un número de radio de esquina, una elección de "patrón"). Estos se comportan exactamente como sus contrapartes de configuración y resuelven a su valor tipado (un boolean se queda true, un number se queda 8); los valores color y de asset resuelven a cadenas. El skin no permite string ni link (el texto libre pertenece al idioma; un destino de enlace es una configuración).

Qué acepta cada tipo

Caputchin valida cada valor cuando guardas, así que un valor que no encaja con su tipo se rechaza antes de que pueda llegar a un visitante.

Claves reservadas

Junto a sus campos de contenido, un preset lleva unas pocas claves de metadato reservadas (cada una con un guion bajo de prefijo) que controlan cómo se selecciona y resuelve, no lo que muestra. Cómo las fijas depende de la superficie: un autor de juego del marketplace las escribe literalmente en caputchin.json; en el editor del dashboard (juegos a medida, white-label) las fijas a través de controles y nunca escribes la clave. De una forma u otra el significado es el mismo.

Las claves de metadato reservadas se eliminan durante la resolución: _extends y _default nunca llegan al juego, y solo el metadato que sobrevive (_lang, _direction, _theme) más los campos de contenido aplanados se entregan.

Extender un preset

_extends deja que un preset herede cada valor de otro, para que crees solo los campos que difieren en vez de repetir un preset entero. Fija _extends al nombre de otro preset en el mismo eje; el preset que extiende empieza desde todos los valores de ese preset y sobrescribe las claves que fija él mismo.

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

Aquí brand-light-warm hereda bg de brand-light y cambia solo accent.

Dos detalles:

• Atajo de tema del skin. En un preset de skin, _extends puede en su lugar nombrar un tema (light o dark) en vez de un preset. Esa forma resuelve a cualquiera que sea el preset _default para ese tema, una forma conveniente de basar una variante en "el skin claro por defecto" sin nombrarlo.
• Se resuelve y desaparece. _extends se sigue y luego se elimina; el juego recibe el resultado totalmente fusionado, nunca la propia clave _extends.

De dónde viene un esquema

El conjunto de campos que un preset puede rellenar (su esquema) tiene tres fuentes, todas usando los mismos tipos de campo de arriba:

• Juego del marketplace: el esquema viene del manifiesto del autor del juego, descargado cuando abres el editor. Sobrescribes los presets del juego pero no cambias su esquema.
• Juego a medida: defines el esquema tú mismo en el dashboard, luego creas presets contra él. Mira juegos a medida.
• Shell del widget (white-label): un esquema fijo e integrado. Sobrescribes sus presets; el conjunto de campos no lo declara el autor. Mira white-label del widget.

Presets y resolución

Dentro de un eje, los campos se agrupan en presets con nombre, y el servidor resuelve un preset efectivo por grupo de los alcances en capas, clave de sitio sobre equipo sobre el valor por defecto incluido, calculado por valor. Los selectores difieren por eje: el locale lo elige el idioma del navegador del visitante, el skin la preferencia clara u oscura del visitante (un preset cuyo modo es any es elegible para cualquiera), y la configuración es autoritativa del servidor (el visitante no puede elegirla). Mira la visión general para el modelo de alcance.

Véase también

• Visión general de personalización de juego: registrar y gestionar juegos, más los how-to por eje para configuraciones, idioma, y skin.
• Esquema del dashboard de un juego a medida: crear un esquema tú mismo para un juego a medida.
• El manifiesto caputchin.json: declarar estos bloques como autor de juego del marketplace.
• White-label del widget: los mismos tipos aplicados al shell del widget.