Référence du schéma de personnalisation

C'est l'unique référence pour le modèle de type de champ et de préréglage de Caputchin, la fondation partagée sous chaque surface personnalisable :

• Personnalisation des jeux : la langue, le skin et la configuration d'un jeu du marketplace.
• Schémas de jeu personnalisé : le schéma que tu rédiges toi-même pour un jeu personnalisé.
• Manifestes de jeu du marketplace : les blocs locales / skins / configurations qu'un auteur de jeu déclare.
• Mise en marque blanche du widget : le schéma intégré du shell du widget.

Les quatre utilisent les mêmes types de champs et le même modèle de préréglage décrit ici. La personnalisation est bâtie à partir de préréglages, et un préréglage est un sac de champs typés.

Types de champs par axe

Chaque axe autorise un ensemble fixe de types de champs :

Un skin n'est pas seulement des couleurs et des ressources : il peut aussi exposer les molettes scalaires boolean, number, range et list (une bascule « ombres », un nombre de rayon de coin, un choix « motif »). Celles-ci se comportent exactement comme leurs homologues de configuration et se résolvent en leur valeur typée (un boolean reste true, un number reste 8) ; les valeurs color et de ressource se résolvent en chaînes. Le skin n'autorise pas string ni link (le texte libre appartient à la langue ; une cible de lien est une configuration).

Ce que chaque type accepte

Caputchin valide chaque valeur quand tu enregistres, donc une valeur qui ne correspond pas à son type est rejetée avant de pouvoir atteindre un visiteur.

Clés réservées

Aux côtés de ses champs de contenu, un préréglage porte quelques clés de métadonnées réservées (chacune préfixée d'un underscore) qui contrôlent comment il est sélectionné et résolu, pas ce qu'il affiche. La façon dont tu les règles dépend de la surface : un auteur de jeu du marketplace les écrit littéralement dans caputchin.json ; dans l'éditeur du tableau de bord (jeux personnalisés, marque blanche), tu les règles via des contrôles et ne tapes jamais la clé. Dans les deux cas, le sens est le même.

Les clés de métadonnées réservées sont retirées pendant la résolution : _extends et _default n'atteignent jamais le jeu, et seules les métadonnées survivantes (_lang, _direction, _theme) plus les champs de contenu aplatis sont livrées.

Étendre un préréglage

_extends laisse un préréglage hériter de chaque valeur d'un autre, pour que tu ne rédiges que les champs qui diffèrent au lieu de répéter un préréglage entier. Règle _extends au nom d'un autre préréglage du même axe ; le préréglage qui étend part de toutes les valeurs de ce préréglage et surcharge les clés qu'il règle lui-même.

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

Ici brand-light-warm hérite de bg depuis brand-light et ne change que accent.

Deux détails :

• Raccourci de thème de skin. Sur un préréglage de skin, _extends peut à la place nommer un thème (light ou dark) plutôt qu'un préréglage. Cette forme se résout vers le préréglage qui est le _default pour ce thème, une façon commode de baser une variante sur « le skin clair par défaut » sans le nommer.
• Il se résout et disparaît. _extends est suivi puis retiré ; le jeu reçoit le résultat entièrement fusionné, jamais la clé _extends elle-même.

D'où vient un schéma

L'ensemble de champs qu'un préréglage peut remplir (son schéma) a trois sources, toutes utilisant les mêmes types de champs ci-dessus :

• Jeu du marketplace : le schéma vient du manifeste de l'auteur du jeu, récupéré quand tu ouvres l'éditeur. Tu surcharges les préréglages du jeu mais ne changes pas son schéma.
• Jeu personnalisé : tu définis le schéma toi-même dans le tableau de bord, puis tu rédiges des préréglages contre lui. Vois jeux personnalisés.
• Shell du widget (marque blanche) : un schéma fixe, intégré. Tu surcharges ses préréglages ; l'ensemble de champs n'est pas déclaré par un auteur. Vois marque blanche du widget.

Préréglages et résolution

Au sein d'un axe, les champs sont regroupés en préréglages nommés, et le serveur résout un préréglage effectif par groupe à partir des portées en couches, clé de site sur équipe sur défaut embarqué, calculé par valeur. Les sélecteurs diffèrent par axe : la locale est choisie par la langue du navigateur du visiteur, le skin par la préférence claire ou sombre du visiteur (un préréglage dont le mode est any est éligible pour l'un ou l'autre), et la configuration fait autorité côté serveur (le visiteur ne peut pas la choisir). Vois la vue d'ensemble pour le modèle de portée.

Voir aussi

• Vue d'ensemble de la personnalisation des jeux : enregistrer et gérer des jeux, plus les guides pratiques par axe pour les configurations, la langue et le skin.
• Schéma de tableau de bord d'un jeu personnalisé : rédiger un schéma toi-même pour un jeu personnalisé.
• Le manifeste caputchin.json : déclarer ces blocs en tant qu'auteur de jeu du marketplace.
• Marque blanche du widget : les mêmes types appliqués au shell du widget.