Anpassungs-Schema-Referenz

Das ist die einzelne Referenz für Caputchins Feldtyp- und Preset-Modell, das geteilte Fundament unter jeder anpassbaren Fläche:

• Spiel-Anpassung: die Sprache, der Skin und die Konfiguration eines Marketplace-Spiels.
• Custom-Spiel-Schemas: das Schema, das du selbst für ein Custom-Spiel verfasst.
• Marketplace-Spiel-Manifeste: die locales / skins / configurations-Blöcke, die ein Spiel-Autor deklariert.
• Das Widget per White-Label anpassen: das eingebaute Schema der Widget-Hülle.

Alle vier nutzen dieselben Feldtypen und dasselbe Preset-Modell, das hier beschrieben ist. Anpassung ist aus Presets gebaut, und ein Preset ist ein Sack typisierter Felder.

Feldtypen nach Achse

Jede Achse erlaubt einen festen Satz Feldtypen:

Ein Skin ist nicht nur Farben und Assets: er kann auch die skalaren Regler boolean, number, range und list bereitstellen (ein "Schatten"-Schalter, eine Eckenradius-Zahl, eine "Muster"-Wahl). Diese verhalten sich genau wie ihre Konfigurations-Gegenstücke und lösen sich zu ihrem typisierten Wert auf (ein boolean bleibt true, eine number bleibt 8); color- und Asset-Werte lösen sich zu Strings auf. Skin erlaubt kein string oder link (freier Text gehört zur Sprache; ein Link-Ziel ist eine Konfiguration).

Was jeder Typ akzeptiert

Caputchin validiert jeden Wert, wenn du speicherst, sodass ein Wert, der nicht zu seinem Typ passt, abgelehnt wird, bevor er einen Besucher erreichen kann.

Reservierte Schlüssel

Neben seinen Inhaltsfeldern trägt ein Preset ein paar reservierte Metadaten-Schlüssel (jeder mit einem Unterstrich präfixiert), die steuern, wie es ausgewählt und aufgelöst wird, nicht was es anzeigt. Wie du sie setzt, hängt von der Fläche ab: ein Marketplace-Spiel-Autor schreibt sie wörtlich in caputchin.json; im Dashboard-Editor (Custom-Spiele, White-Label) setzt du sie über Steuerungen und tippst den Schlüssel nie. So oder so ist die Bedeutung dieselbe.

Reservierte Metadaten-Schlüssel werden während der Auflösung entfernt: _extends und _default erreichen das Spiel nie, und nur die überlebenden Metadaten (_lang, _direction, _theme) plus die abgeflachten Inhaltsfelder werden zugestellt.

Ein Preset erweitern

_extends lässt ein Preset jeden Wert von einem anderen erben, sodass du nur die Felder verfasst, die sich unterscheiden, statt ein ganzes Preset zu wiederholen. Setz _extends auf den Namen eines anderen Presets in derselben Achse; das erweiternde Preset startet von allen Werten dieses Presets und überschreibt die Schlüssel, die es selbst setzt.

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

Hier erbt brand-light-warm bg von brand-light und ändert nur accent.

Zwei Details:

• Skin-Theme-Abkürzung. Auf einem Skin-Preset darf _extends stattdessen ein Theme benennen (light oder dark) statt eines Presets. Diese Form löst sich zu dem Preset auf, das der _default für dieses Theme ist, ein bequemer Weg, eine Variante auf "dem Standard-Hell-Skin" zu basieren, ohne ihn zu benennen.
• Es löst sich weg. _extends wird gefolgt und dann entfernt; das Spiel empfängt das vollständig gemergte Ergebnis, nie den _extends-Schlüssel selbst.

Woher ein Schema kommt

Der Feldsatz, den ein Preset füllen kann (sein Schema), hat drei Quellen, alle mit denselben Feldtypen oben:

• Marketplace-Spiel: das Schema kommt aus dem Manifest des Spiel-Autors, abgerufen, wenn du den Editor öffnest. Du überschreibst die Presets des Spiels, änderst aber nicht sein Schema.
• Custom-Spiel: du definierst das Schema selbst im Dashboard, dann verfasst du Presets dagegen. Sieh dir Custom-Spiele an.
• Widget-Hülle (White-Label): ein festes, eingebautes Schema. Du überschreibst seine Presets; der Feldsatz ist nicht autor-deklariert. Sieh dir das Widget per White-Label anpassen an.

Presets und Auflösung

Innerhalb einer Achse sind Felder in benannte Presets gruppiert, und der Server löst ein effektives Preset pro Gruppe aus den geschichteten Geltungsbereichen auf, Site-Key über Team über mitgeliefertem Standard, pro Wert berechnet. Die Selektoren unterscheiden sich nach Achse: Locale wird von der Browser-Sprache des Besuchers gewählt, Skin von der Hell- oder Dunkel-Präferenz des Besuchers (ein Preset, dessen Modus any ist, ist für jeden berechtigt), und Konfiguration ist server-autoritativ (der Besucher kann sie nicht wählen). Sieh dir den Überblick für das Geltungsbereich-Modell an.

Siehe auch

• Überblick zur Spiel-Anpassung: Spiele registrieren und verwalten, plus die How-tos pro Achse für Konfigurationen, Sprache und Skin.
• Custom-Spiel-Dashboard-Schema: selbst ein Schema für ein Custom-Spiel verfassen.
• Das caputchin.json-Manifest: diese Blöcke als Marketplace-Spiel-Autor deklarieren.
• Das Widget per White-Label anpassen: dieselben Typen, angewendet auf die Widget-Hülle.