Caputchin
参考

自定义模式参考

这是 Caputchin 的 字段类型和预设模型 的那一份参考，即每个可自定义的面之下那个共享的根基：

四者都用这里描述的同样的字段类型和同样的预设模型。自定义由 预设 构建，而一个预设是一袋带类型的 字段。

按维度的字段类型

每个维度允许一组固定的字段类型：

维度允许的字段类型
Configurationboolean、number、range、list、string、link
Locale只 string
Skincolor、image、audio、video、boolean、number、range、list

一个皮肤不只是颜色和资源：它也能暴露标量旋钮 boolean、number、range 和 list（一个“阴影”开关、一个圆角半径数字、一个“图案”选择）。这些的行为恰好像它们的配置对应物，并解析为它们的带类型值（一个 boolean 保持 true、一个 number 保持 8）；color 和资源值解析为字符串。皮肤不允许 string 或 link（自由文本属于语言；一个链接目标是一个配置）。

每种类型接受什么

类型值规则
string自由文本任何文本。
boolean一个开关true 或 false。
number一个数字任何有限的数。
range一个有界的数字字段的最小值和最大值之内的一个有限数。step 是一个滑块便利；偏离 step 的值仍被接受。
list一个选择必须是字段所列选项之一。
link一个 URL一个 http 或 https URL。内嵌的凭据被拒绝。
color一个颜色一个十六进制颜色（#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 在你保存时校验每一个值，所以一个不合它类型的值在它能到达一位访客之前就被拒绝。

保留键

在它的内容字段之外，一个预设携带几个保留的 元数据键（每个以一个下划线为前缀），它们控制它如何被选中和解析，而非它显示什么。你如何设置它们取决于那个面：一个 应用市场游戏作者 在 caputchin.json 里字面地写它们；在仪表盘编辑器里（自定义游戏、白标）你通过控件设置它们，而从不键入那个键。无论哪种方式，含义都一样。

键维度含义
_langLocale一个 locale 预设服务的 BCP-47 语言标签（en、es，等等）。预设按它分组；几个预设可以共享一个 _lang（例如两个英语变体）。
_directionLocaleltr 或 rtl。可选，对从右到左的语言（ar、he、fa、ur、yi、ps、sd）从 _lang 自动派生；很少手工设置。
_themeSkinlight、dark 或 any。一个 light / dark 预设只在那种背景下显示；一个 any 预设在两种下都工作且对任一都有资格。缺失时默认为 light。
_default全部当访客不选一个时，标记服务器为它那组挑的那个预设。每组一个默认（皮肤按模式）；一个 any 皮肤可以是亮、暗或两者的默认。
_extends全部点名另一个要从之继承的预设。见 扩展一个预设。

保留的元数据键在 解析期间被剥离：_extends 和 _default 绝不到达游戏，只有幸存的元数据（_lang、_direction、_theme）加上扁平化的内容字段被交付。

扩展一个预设

_extends 让一个预设从另一个继承每一个值，于是你只撰写有差异的那些字段，而不是重复一整个预设。把 _extends 设为 同一维度里另一个预设的名字；这个扩展的预设从那个预设所有的值起步，并覆盖它自己设置的那些键。

{
  "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 键本身。

一个模式从哪里来

一个预设能填的那个字段集（它的 模式）有三个来源，全都用上面同样的字段类型：

  • 应用市场游戏：模式来自游戏作者的清单，在你打开编辑器时拉取。你覆盖游戏的预设，但不改它的模式。
  • 自定义游戏：你自己在仪表盘里定义模式，然后对着它撰写预设。见 自定义游戏。
  • 组件外壳（白标）：一个固定的、内置的模式。你覆盖它的预设；那个字段集不是作者声明的。见 给组件做白标。

预设与解析

在一个维度内，字段被归入命名的预设，而服务器从分层的范围为每组解析一个有效预设，站点密钥盖过团队、团队盖过捆绑默认，逐个值计算。选择器按维度不同：locale 由访客的浏览器语言选中、skin 由访客的亮或暗偏好选中（一个模式为 any 的预设对任一都有资格），而 configuration 是服务端权威的（访客无法选它）。范围模型见 概览。

另见

组件方法与事件

上一页

本页内容

按维度的字段类型每种类型接受什么保留键扩展一个预设一个模式从哪里来预设与解析另见