---
type: how-to
title: 自定义一个游戏的皮肤
summary: 在皮肤标签页上覆盖一个游戏的颜色和视觉资源，按模式（亮、暗或两者）分组；从 Alpha 套餐起可用。
---

一个游戏带着一个默认外观交付。在游戏编辑器的 **皮肤** 标签页上，你可以覆盖它的颜色、替换它的视觉资源（图像，以及在游戏用到的地方，音频和视频），并设置作者暴露的任何非颜色旋钮（一个开关、一个数字、一个选择），好让挑战匹配你的品牌，而这个改动应用到渲染出的游戏上。

皮肤自定义从 **Alpha 套餐起可用**（Alpha、Troop、Apex）。

## 设置颜色、资源和其他旋钮

在一个站点密钥（或团队）的 **游戏** 页上打开游戏，然后是 **皮肤** 标签页。这个标签页显示游戏作者暴露的那些槽位。大多数是颜色和资源，但作者也能暴露一个 **开关**（开/关）、一个 **数字**（往往带一个最小值和最大值），或一个从固定列表里的 **选择**。用一个十六进制或 `rgb()` 值设一个颜色；通过上传一个文件或粘贴一个 URL 设一个资源（见下文）；用所显示的控件设其他槽位。一个槽位原封不动就保持游戏的内置值。

## 一个皮肤在运行时如何被选中

每个预设声明它在哪种 **模式** 下工作：亮、暗或 **任意**（它在两种背景上都好看）。每种模式有一个默认，于是不论访客的设备偏好哪种模式，游戏看起来都对。一个标为 `any` 的预设有资格成为亮、暗或两者的默认。挑一个分两个阶段发生。

先是组件决定要请求哪种皮肤：

1. 组件的 `skin` 属性，如果页面设了一个：一个精确的预设名（例如 `midnight`），或快捷方式 `light` / `dark`。
2. 否则，访客的系统偏好（`prefers-color-scheme`），它解析为 `light` 或 `dark`。

然后服务器在合并你的覆盖之后（站点密钥盖过团队、团队盖过游戏的内置集合），把那个与预设匹配。属性里一个精确的预设名直接胜出。否则，对于所选的模式，服务器取声明顺序里第一个对那种模式有资格且标为 **默认** 的预设（一个预设当它的模式是那种模式或 `any` 时有资格）；若没有标为默认的，它就取第一个有资格的预设。

因为一个 `any` 预设对两种模式都有资格，你可以让一个皮肤在各处都是默认，或者给一种模式一个专属皮肤、让一个 `any` 皮肤覆盖另一种。在皮肤标签页上，一个 `any` 皮肤同时出现在亮组和暗组下，而你把它设为其中一个或两个的默认。

在 `<caputchin-game>` 元素上你还可以传一个内联的 `skin` 对象：一个写作属性值的 JSON 对象，例如 `skin='{"primary":"#7c3aed"}'`。组件把它作为那次挂载的皮肤信号发给服务器，服务器解析它并把它叠在解析出的预设之上，于是你的内联颜色和资源胜过上面的一切（包括你的团队和站点密钥覆盖）。它是你自己标记的一个属性，所以它在任何套餐上都能用。复选框式的 `<caputchin-widget>` 不接受一个内联皮肤；它的 `skin` 属性只接受 `light` / `dark` 或一个预设名。这种逐嵌入的撰写为什么免费，见 [我们的理念](/docs/understanding-caputchin/philosophy)。

## 资源：上传或链接

一个资源槽位（图像、音频或视频）接受一个上传的文件或一个你粘贴的 URL：

- **上传**：Caputchin 存储这个文件的一份快照。它被冻结，所以除非你再次上传，它不会变。
- **链接**：你粘贴一个指向你托管的文件的 `https` URL。它是活的，所以替换那个 URL 处的文件会在下次加载时更新游戏。

因为游戏跑在一个沙箱化的框里，一个被链接的资源只有当它的来源被允许时才会加载。Caputchin 替你处理这件事：它恰好允许你皮肤预设所指向的那些来源，别无其他。你自己不更改任何策略。

每种资源类型接受一组固定的格式（例如图像用 PNG、JPEG、WebP、SVG 和 GIF）。确切的格式和颜色规则在 [模式参考](/docs/references/customization-schema) 里。

## 什么适用，以及在哪里

皮肤覆盖在服务器上解析，最具体者胜：一个站点密钥的预设胜过团队的预设，团队的预设又胜过游戏的内置皮肤。你可以扩展一个内置预设、只覆盖你想要的那些槽位，并继承其余的。

## 一个皮肤值如何到达游戏 [#how-a-skin-value-reaches-the-game]

服务器解析你的皮肤（你的覆盖合并在内置集合之上）并把结果交给 **游戏自己的代码**，由它用这个结果把自己画出来。颜色和资源 URL 作为文本到达；一个开关作为一个真正的 `true` / `false` 到达、一个数字作为一个真正的数字、一个选择作为所选的字符串。游戏的作者决定每个值如何被使用，所以一个槽位实际改变什么取决于游戏。你不为游戏写任何 CSS：它跑在一个你无法从你的页面设样式的沙箱化的框里。

**组件外壳**（游戏周围的 Caputchin 外饰，以及那个独立的复选框）则不同：它解析出的皮肤也作为命名为 `--cpt-skin-<token>` 的 CSS 自定义属性暴露给你的页面，你可以从你自己的样式表读它们或覆盖它们。那个面、以及如何把外壳白标化，在 [用 CSS 给组件设样式](/docs/widget-customization/css-parts) 里讲到。那些变量只属于外壳；它们不携带一个游戏的皮肤。

## 另见

- [游戏自定义概览](/docs/game-customization/overview)：注册一个游戏并管理它。
- [配置](/docs/game-customization/configurations) 和 [语言](/docs/game-customization/locale)：另外两个维度。
- [模式参考](/docs/references/customization-schema)：颜色规则、资源格式和预设模型。
- [用 CSS 给组件设样式](/docs/widget-customization/css-parts)：外壳的 `--cpt-skin-*` 变量和 shadow part。