---
type: reference
title: Anpassungs-Schema-Referenz
summary: Das geteilte Feldtyp- und Preset-Modell hinter jeder anpassbaren Fläche, die Feldtypen, die jede Achse erlaubt, die Werte, die jeder akzeptiert, und wie Schemas und Presets definiert und aufgelöst werden.
---

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

- [Spiel-Anpassung](/docs/game-customization/overview): die Sprache, der Skin und die Konfiguration eines Marketplace-Spiels.
- [Custom-Spiel-Schemas](/docs/custom-game-development/dashboard-schema): das Schema, das du selbst für ein Custom-Spiel verfasst.
- [Marketplace-Spiel-Manifeste](/docs/marketplace-game-development/the-caputchin-json-manifest): die `locales` / `skins` / `configurations`-Blöcke, die ein Spiel-Autor deklariert.
- [Das Widget per White-Label anpassen](/docs/widget-customization/white-label): 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:

| Achse | Erlaubte Feldtypen |
|---|---|
| Konfiguration | `boolean`, `number`, `range`, `list`, `string`, `link` |
| Locale | nur `string` |
| Skin | `color`, `image`, `audio`, `video`, `boolean`, `number`, `range`, `list` |

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

| Typ | Wert | Regeln |
|---|---|---|
| `string` | Freier Text | Beliebiger Text. |
| `boolean` | Ein Schalter | `true` oder `false`. |
| `number` | Eine Zahl | Jede endliche Zahl. |
| `range` | Eine begrenzte Zahl | Eine endliche Zahl innerhalb des Minimums und Maximums des Feldes. Der Step ist eine Schieber-Bequemlichkeit; Werte außerhalb des Steps werden trotzdem akzeptiert. |
| `list` | Eine Wahl | Muss eine der gelisteten Optionen des Feldes sein. |
| `link` | Eine URL | Eine `http`- oder `https`-URL. Eingebettete Anmeldedaten werden abgelehnt. |
| `color` | Eine Farbe | Eine Hex-Farbe (`#rgb`, `#rgba`, `#rrggbb` oder `#rrggbbaa`) oder ein `rgb()` / `rgba()`-Wert. Benannte Farben und andere Farbräume werden nicht akzeptiert. |
| `image` | Ein Bild | Eine hochgeladene Datei oder eine `https`-URL, die auf `.png`, `.jpg`, `.jpeg`, `.webp`, `.svg` oder `.gif` endet. |
| `audio` | Ein Audio-Clip | Eine hochgeladene Datei oder eine `https`-URL, die auf `.mp3`, `.ogg` oder `.wav` endet. |
| `video` | Ein Video | Eine hochgeladene Datei oder eine `https`-URL, die auf `.mp4` oder `.webm` endet. |

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

| Schlüssel | Achse | Bedeutung |
|---|---|---|
| `_lang` | Locale | Der BCP-47-Sprach-Tag, den ein Locale-Preset bedient (`en`, `es` und so weiter). Presets sind danach gruppiert; mehrere Presets können ein `_lang` teilen (z. B. zwei englische Varianten). |
| `_direction` | Locale | `ltr` oder `rtl`. Optional, automatisch aus `_lang` für Rechts-nach-links-Sprachen abgeleitet (`ar`, `he`, `fa`, `ur`, `yi`, `ps`, `sd`); selten von Hand gesetzt. |
| `_theme` | Skin | `light`, `dark` oder `any`. Ein `light` / `dark`-Preset zeigt sich nur unter diesem Hintergrund; ein `any`-Preset funktioniert unter beiden und ist für jeden berechtigt. Standard ist `light`, wenn abwesend. |
| `_default` | Alle | Markiert das Preset, das der Server für seine Gruppe wählt, wenn der Besucher keines auswählt. Ein Standard pro Gruppe (pro Modus bei Skin); ein `any`-Skin kann der Standard für hell, dunkel oder beides sein. |
| `_extends` | Alle | Benennt ein anderes Preset, von dem geerbt wird. Sieh dir [Ein Preset erweitern](#extending-a-preset) an. |

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

`_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.

```json
{
  "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](/docs/game-customization/custom-games) 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](/docs/widget-customization/white-label) 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](/docs/game-customization/overview#troop-and-site-key-scope) für das Geltungsbereich-Modell an.

## Siehe auch

- [Überblick zur Spiel-Anpassung](/docs/game-customization/overview): Spiele registrieren und verwalten, plus die How-tos pro Achse für [Konfigurationen](/docs/game-customization/configurations), [Sprache](/docs/game-customization/locale) und [Skin](/docs/game-customization/skin).
- [Custom-Spiel-Dashboard-Schema](/docs/custom-game-development/dashboard-schema): selbst ein Schema für ein Custom-Spiel verfassen.
- [Das caputchin.json-Manifest](/docs/marketplace-game-development/the-caputchin-json-manifest): diese Blöcke als Marketplace-Spiel-Autor deklarieren.
- [Das Widget per White-Label anpassen](/docs/widget-customization/white-label): dieselben Typen, angewendet auf die Widget-Hülle.