---
type: reference
title: 맞춤화 스키마 레퍼런스
summary: 모든 맞춤화 가능한 표면 뒤의 공유 필드 타입과 프리셋 모델, 각 축이 허용하는 필드 타입, 각각이 받는 값, 그리고 스키마와 프리셋이 어떻게 정의되고 해소되는지.
---

이것은 Caputchin의 **필드 타입과 프리셋 모델**, 모든 맞춤화 가능한 표면 아래의 공유 기반을 위한 단일 레퍼런스입니다:

- [게임 맞춤화](/docs/game-customization/overview): 마켓플레이스 게임의 언어, 스킨, 구성.
- [커스텀 게임 스키마](/docs/custom-game-development/dashboard-schema): 커스텀 게임을 위해 당신이 직접 작성하는 스키마.
- [마켓플레이스 게임 매니페스트](/docs/marketplace-game-development/the-caputchin-json-manifest): 게임 작성자가 선언하는 `locales` / `skins` / `configurations` 블록.
- [위젯 화이트라벨링](/docs/widget-customization/white-label): 위젯 셸의 내장 스키마.

넷 모두 여기 설명된 같은 필드 타입과 같은 프리셋 모델을 씁니다. 맞춤화는 **프리셋**으로 지어지고, 프리셋은 타입 지정된 **필드**의 주머니입니다.

## 축별 필드 타입

각 축은 고정된 필드 타입 묶음을 허용합니다:

| 축 | 허용된 필드 타입 |
|---|---|
| Configuration | `boolean`, `number`, `range`, `list`, `string`, `link` |
| Locale | `string`만 |
| Skin | `color`, `image`, `audio`, `video`, `boolean`, `number`, `range`, `list` |

스킨은 색상과 자산만이 아닙니다: 그것은 스칼라 손잡이 `boolean`,
`number`, `range`, `list`("그림자" 토글, 모서리 반지름 숫자, "패턴" 선택)도 노출할 수 있습니다.
이것들은 그 구성 짝과 정확히 똑같이 동작하고 그 타입 지정 값으로 해소됩니다(
`boolean`은 `true`로 남고, `number`는 `8`로 남음); `color`와 자산 값은 문자열로 해소됩니다.
스킨은 `string`이나 `link`를 허용하지 않습니다(자유 텍스트는 언어에 속하고; 링크 대상은
구성입니다).

## 각 타입이 받는 것

| 타입 | 값 | 규칙 |
|---|---|---|
| `string` | 자유 텍스트 | 임의의 텍스트. |
| `boolean` | 토글 | `true` 또는 `false`. |
| `number` | 숫자 | 임의의 유한한 숫자. |
| `range` | 한정된 숫자 | 필드의 최솟값과 최댓값 안의 유한한 숫자. 스텝은 슬라이더 편의입니다; 스텝 밖 값도 여전히 받아들여집니다. |
| `list` | 하나의 선택 | 필드의 나열된 옵션 중 하나여야 함. |
| `link` | URL | `http` 또는 `https` URL. 임베드된 자격 증명은 거부됨. |
| `color` | 색상 | hex 색상(`#rgb`, `#rgba`, `#rrggbb`, 또는 `#rrggbbaa`)이나 `rgb()` / `rgba()` 값. 이름 붙은 색상과 다른 색 공간은 받아들여지지 않음. |
| `image` | 이미지 | 업로드된 파일이나 `.png`, `.jpg`, `.jpeg`, `.webp`, `.svg`, 또는 `.gif`로 끝나는 `https` URL. |
| `audio` | 오디오 클립 | 업로드된 파일이나 `.mp3`, `.ogg`, 또는 `.wav`로 끝나는 `https` URL. |
| `video` | 비디오 | 업로드된 파일이나 `.mp4` 또는 `.webm`으로 끝나는 `https` URL. |

Caputchin은 당신이 저장할 때 모든 값을 검증하니, 자기 타입에 맞지 않는 값은 방문자에 닿을 수 있기 전에 거부됩니다.

## 예약된 키

콘텐츠 필드와 나란히, 프리셋은 그것이 무엇을 표시하는지가 아니라 어떻게 선택되고 해소되는지를 제어하는 몇 개의 예약된 **메타데이터 키**(각각 밑줄 접두사)를 지닙니다. 그것들을 설정하는 법은 표면에 달렸습니다: [마켓플레이스 게임 작성자](/docs/marketplace-game-development/the-caputchin-json-manifest)는 그것들을 `caputchin.json`에 문자 그대로 씁니다; 대시보드 편집기(커스텀 게임, 화이트라벨)에서는 컨트롤로 설정하고 결코 키를 입력하지 않습니다. 어느 쪽이든 의미는 같습니다.

| 키 | 축 | 의미 |
|---|---|---|
| `_lang` | Locale | 로케일 프리셋이 내는 BCP-47 언어 태그(`en`, `es` 등). 프리셋은 그것으로 묶임; 여러 프리셋이 하나의 `_lang`을 공유할 수 있음(예: 두 영어 변형). |
| `_direction` | Locale | `ltr` 또는 `rtl`. 선택, 오른쪽에서 왼쪽 언어(`ar`, `he`, `fa`, `ur`, `yi`, `ps`, `sd`)에는 `_lang`에서 자동 도출됨; 손으로 거의 설정 안 함. |
| `_theme` | Skin | `light`, `dark`, 또는 `any`. `light` / `dark` 프리셋은 그 배경 아래에서만 보임; `any` 프리셋은 둘 다 아래에서 동작하고 어느 쪽에도 자격이 있음. 없을 때 `light`로 기본 설정. |
| `_default` | 전부 | 방문자가 하나를 고르지 않을 때 서버가 그 그룹에 고르는 프리셋을 표시. 그룹당 하나의 기본값(스킨은 모드당); `any` 스킨은 라이트, 다크, 또는 둘 다의 기본값이 될 수 있음. |
| `_extends` | 전부 | 물려받을 다른 프리셋의 이름을 댐. [프리셋 확장하기](#extending-a-preset)를 보세요. |

예약된 메타데이터 키는 **해소 동안 제거됩니다**: `_extends`와 `_default`는 결코 게임에 닿지 않으며, 살아남는 메타데이터(`_lang`, `_direction`, `_theme`)에 평탄화된 콘텐츠 필드만 전달됩니다.

## 프리셋 확장하기 [#extending-a-preset]

`_extends`는 한 프리셋이 다른 것에서 모든 값을 물려받게 하니, 전체 프리셋을 되풀이하는 대신 다른 필드만 작성합니다. `_extends`를 **같은 축의 다른 프리셋 이름**으로 설정하세요; 확장하는 프리셋은 그 프리셋의 모든 값에서 시작해 자기가 설정하는 키를 재정의합니다.

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

여기서 `brand-light-warm`은 `brand-light`에서 `bg`를 물려받고 `accent`만 바꿉니다.

두 세부:

- **스킨 테마 단축.** 스킨 프리셋에서, `_extends`는 프리셋 대신 테마(`light` 또는 `dark`)를 댈 수도 있습니다. 그 형태는 그 테마의 `_default`인 어떤 프리셋이든으로 해소되며, 변형을 이름 짓지 않고 "기본 라이트 스킨"에 기반하는 편리한 방법입니다.
- **그것은 해소되어 사라집니다.** `_extends`는 따라간 뒤 제거됩니다; 게임은 완전히 병합된 결과를 받지, 결코 `_extends` 키 자체를 받지 않습니다.

## 스키마가 어디서 오는가

프리셋이 채울 수 있는 필드 묶음(그 **스키마**)에는 세 소스가 있으며, 모두 위의 같은 필드 타입을 씁니다:

- **마켓플레이스 게임**: 스키마가 게임 작성자의 매니페스트에서 오며, 당신이 편집기를 열 때 가져옴. 당신은 게임의 프리셋을 재정의하지만 그 스키마를 바꾸지 않음.
- **커스텀 게임**: 당신이 대시보드에서 스키마를 직접 정의한 다음, 그것을 상대로 프리셋을 작성함. [커스텀 게임](/docs/game-customization/custom-games)을 보세요.
- **위젯 셸(화이트라벨)**: 고정된, 내장 스키마. 당신은 그 프리셋을 재정의함; 필드 묶음은 작성자가 선언하지 않음. [위젯 화이트라벨링](/docs/widget-customization/white-label)을 보세요.

## 프리셋과 해소

한 축 안에서, 필드는 이름 붙은 프리셋으로 묶이고, 서버는 계층화된 범위에서 그룹당 하나의 유효 프리셋을 해소합니다, 사이트 키가 팀 위, 팀이 번들 기본값 위, 값별로 계산됨. 선택자는 축별로 다릅니다: 로케일은 방문자의 브라우저 언어로, 스킨은 방문자의 라이트나 다크 선호로(모드가 `any`인 프리셋은 어느 쪽에도 자격이 있음), 구성은 서버 권위입니다(방문자가 고를 수 없음). 범위 모델은 [개요](/docs/game-customization/overview#troop-and-site-key-scope)를 보세요.

## 함께 보기

- [게임 맞춤화 개요](/docs/game-customization/overview): 게임을 등록하고 관리하기, 더해 [구성](/docs/game-customization/configurations), [언어](/docs/game-customization/locale), [스킨](/docs/game-customization/skin)의 축별 사용법.
- [커스텀 게임 대시보드 스키마](/docs/custom-game-development/dashboard-schema): 커스텀 게임을 위해 스키마를 직접 작성하기.
- [caputchin.json 매니페스트](/docs/marketplace-game-development/the-caputchin-json-manifest): 마켓플레이스 게임 작성자로서 이 블록을 선언하기.
- [위젯 화이트라벨링](/docs/widget-customization/white-label): 위젯 셸에 적용된 같은 타입.