UIDoc 游戏 UI 套件

使用引擎手绘的 Game UI 套件为 UIDoc 界面套上皮肤：@import 机制、类引用、程序集规则以及完整示例。

---

Game UI 套件是美术团队手绘的 UI 组件集（$AO/ui/kit/Game UI/**）：模态框、按钮、选项卡、进度条、横幅、舷窗、物品槽、复选框和切换开关。引擎附带匹配的样式表，因此任何 UIDoc 资源都可以直接采用该套件外观，而无需复制 CSS。

将套件作为最后的样式调整步骤应用。 先搭建界面——布局、绑定、事件、视口行为——确认它能正常工作，然后再进行皮肤化。套件样式只是涂装和内边距；它绝不能用来修复布局。

启用套件

在资源的 index.css:

@import "game-ui-kit";

在烘焙时，引擎会将 res/ui/kit/kit.css 替换为该导入，因此请把 import 放在最前面，并把你自己的规则写在下面——在级联冲突中，你的规则会获胜。该导入可与 Tailwind 工具类组合。编辑引擎样式表后，会在下一次构建时重新烘焙导入它的资源；UIDoc 在运行中的游戏里仍然不会热重载。

唯一需要掌握的模式

UIDoc 不支持位图 CSS 背景，因此套件素材通过普通的 img 元素引入。每个套件容器都是一个定位元素，它的第一个子元素是 .kit-bg 图像；div 负责形状和布局，图像只负责绘制，通过随套件提供的资源设置进行九宫切片：

<div class="kit-modal">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_grey1.png">
  <!-- 内容 -->
</div>

.kit-bg 是 object-fit: fill 用于九宫切片素材（模态框、按钮、选项卡、进度条、横幅）。固定纵横比素材（复选框、切换开关、舷窗、槽位图标）使用 .kit-bg--contain 以及容器自身的宽/高。

在以下情况使用 .kit-bg--shadow 作为实际底图 img ，当素材需要投下阴影时。它使用支持 alpha 的 drop-shadow(...)，因此透明角和九宫切片后的绘制结果共同决定轮廓。 box-shadow 则会遵循容器矩形边框盒；而把 drop-shadow(...) 加在容器上还会把其文本和其他后代元素也包含进去。

将可见的按钮/选项卡文案放在素材之后的前景标签元素中。由容器直接拥有的原始文本可以绘制在其子图像下方：

<button class="kit-btn kit-btn--green">
  <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_green1.png">
  <span class="kit-btn-label">开始</span>
</button>

套件会在视觉上将直接按钮标签下移 5px，以匹配素材。对于图标加价格这类复合前景，请把整个前景包在 .kit-btn-content 中，这样图标和文字会一起移动：

<button class="kit-btn kit-btn--green">
  <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/shiny_buttons/button_large_green1.png">
  <span class="kit-btn-content price">
    <img src="coin.png">
    <span class="kit-btn-label">300</span>
  </span>
</button>

类参考

类	在以下情况使用
.kit-bg, .kit-bg--contain, .kit-bg--shadow	素材底图、固定纵横比适配，以及支持 alpha 的图像阴影
.kit-fg	上方的通用前景层 .kit-bg
.kit-modal	带有套件内边距的定位 flex-column 面板
.kit-modal-header	居中的标题安全区，两侧各预留 72px
.kit-modal-title	居中的标题行；可与 .kit-text-header
.kit-title-banner	pointy_banner_* 一起使用，作为模态标题后方的底图，且完全位于模态框内部
.kit-header-band	modal_header_* 横跨模态框已绘制顶部边缘的横条
.kit-dim	模态框后方的全屏暗化层
.kit-btn, .kit-btn-label, .kit-btn-content, .kit-btn--<colour>	按钮素材加上一个视觉下移的前景标签/组合，并带有与颜色匹配的描边
.kit-tab-row, .kit-tab, .kit-tab-label, .kit-tab--active	带有前景标签的胶囊式选项卡导航行
.kit-progress, .kit-progress-fill, .kit-progress--N, .kit-progress--compact	轨道加绑定的填充；family 修饰符可对齐填充，compact 则选择 30px 尺寸
.kit-card, .kit-list-row	用于带素材底图的卡片和行的结构容器
.kit-close	位于模态框右上角、绝对定位的前景关闭控件
.kit-slot, .kit-slot-icon, .kit-slot-qty	带图标和数量的背包/商店方块
.kit-porthole	圆形边框；堆叠 *_back.png 在 *_ring.png
.kit-checkbox, .kit-toggle	固定纵横比状态控件
.kit-text-header/body/body-dark/info	美术文档中四种获准使用的文本样式

在标准逻辑视口下，文本尺寸遵循美术文档（65/55/45/40）；当某个界面需要不同缩放时，可在资源中覆盖。

组装规则

这些来自美术团队的 Game UI 文档和既定实践；类名编码了其中大部分，其余部分由标记模式覆盖。

• 标题：白色、粗体、黑色描边、投影（.kit-text-header），可以直接设置在模态框上，或者设置在 .kit-title-banner 上（深色横幅底图，完全位于模态框内部——避免棕色的“黄色”尖角横幅），也可以设置在 .kit-header-band 上，只要配色搭配合适：亮色模态上的高饱和色条（如白底红字）效果很好；低饱和配低饱和（如灰底金色）则不行。不确定时，普通标题文字始终安全。
• 可关闭的模态标题栏：保持 .kit-close 作为 .kit-modal的直接子元素， .kit-modal-header；其左右对称的 72px 侧边预留可让标题视觉居中，并避开关闭控件。模态框宽度应按所需标题/横幅宽度，加上左右两个 72px 预留，再加上面板的左、右内边距来预算。这会刻意让可关闭模态框比紧凑贴合的正文内容略宽一些。
• 素材阴影: box-shadow 遵循矩形边框盒。对于不规则或九宫切片的套件素材，请将 .kit-bg--shadow 作为实际底图 img 这样阴影就会跟随其绘制出的 alpha 轮廓。不要把滤镜加在 .kit-modal上，因为那样会把模态框的文本和子素材也算进阴影轮廓里。
• 按钮：文本为白色，并带有 颜色描边 ，以补足按钮素材——绝不能用黑色。将普通标签直接放入 .kit-btn-label 中，这样它会绘制在素材之上，并获得套件 5px 的视觉基线下移。对于图标加文字的内容，请把两者都放在一个直接的 .kit-btn-content 子元素中，让这对元素一起获得该偏移。使用 shiny_buttons 用于购买和特殊交互， basic_buttons 用于其他所有情况，并为文字留足内边距。灰色按钮表示禁用状态。
• 正文文本：在有颜色的模态框上使用细微的 20% 不透明描边（.kit-text-body）；在白色/灰色模态框上使用纯深色文本（.kit-text-body-dark）。
• 选项卡：一个胶囊式行 位于 模态框主体内部，而不是贴着顶部边缘。将文案放在 .kit-tab-label中。当前激活的选项卡使用有颜色的素材变体（例如 tabs_blue）并配以匹配的文字描边；未激活选项卡使用 tabs_black。对动态标签使用 tab_med.png 或 tab_large.png 。 tab_small.png 源文件不一致，而且其中一些包含已烘焙的标签，所以它们有意不做九宫切片。
• 进度条：每个 progress_bar_N 文件夹都会配对一个 backing.png 以及一个专门制作的 fill_*.png，但内部偏移会因系列而异，而且由于下边缘/投影，往往是不对称的。轨道素材放在 .kit-bg中；匹配的系列填充放在 .kit-progress-fill中，它使用 object-fit: fill；向容器添加匹配的 .kit-progress--N 修饰符，并绑定 data-style-image-fill-amount。不要用着色的图标或装饰性的透明图像替代：着色会保留源 alpha，而 cover 可能会把方形素材裁切到缝隙中，或者在较窄的轨道上裁成对角楔形。请在 0, 0.25, 0.5，以及 1处预览该条；当前诊断无法检测不适合的纹理 alpha。默认组件厚度为 40px；为按比例缩放的 30px 形式添加 .kit-progress--compact 。对于自定义厚度，请在容器上设置相等的 font-size 和 height 值，这样基于 em 的系列内边距也会随之缩放。套件轨道使用 flex-shrink: 0；应显式选择厚度，而不要依赖 flex 父容器压缩轨道，因为那样轨道及其填充可能会以不同尺寸解析。
• 物品槽：有颜色的方块（inv_square_<colour>1.png）用于已填充槽位； inv_square_empty2.png 是设计好的空状态。
• 模态框系列素材共享同一缩放比例 （源像素中角为 37px、轮廓为 6px——随附的切片内边距已经考虑了这一点）。诸如模态框上方的标题横条这类需要组合的部件之所以能对齐，是因为它们按同一缩放绘制；不要手动编辑各个切片值。

示例：设置模态框

条纹模态框（modal_stripe_*）带有更深色的底部横带——将操作行作为最后一个普通流子元素放在其上。

<div class="kit-modal settings">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_stripe_blue1.png">
  <div class="kit-modal-header">
    <div class="kit-modal-title kit-text-header">设置</div>
  </div>
  <button class="kit-close" data-on-click="event:settings:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <div class="rows">
    <div class="row">
      <span class="kit-text-body">音乐</span>
      <button class="kit-toggle" data-on-click="event:toggle:music">
        <img class="kit-bg kit-bg--contain" data-if="music.on" src="$AO/ui/kit/Game UI/Additional Elements/Sliders + Toggles/switch_long_on.png">
        <img class="kit-bg kit-bg--contain" data-if="music.off" src="$AO/ui/kit/Game UI/Additional Elements/Sliders + Toggles/switch_long_off.png">
      </button>
    </div>
    <div class="row">
      <span class="kit-text-body">季票</span>
      <div class="kit-progress kit-progress--1 pass-progress">
        <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/backing.png">
        <img class="kit-progress-fill" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/fill_yellow.png"
             data-style-image-fill-amount="pass.progress">
      </div>
    </div>
  </div>
  <div class="actions">
    <button class="kit-btn kit-btn--yellow" data-on-click="event:settings:save">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_yellow1.png">
      <span class="kit-btn-label">保存</span>
    </button>
    <button class="kit-btn kit-btn--red" data-on-click="event:settings:reset">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_red1.png">
      <span class="kit-btn-label">重置</span>
    </button>
  </div>
</div>

@import "game-ui-kit";

.settings { width: 620px; }
.settings .rows { display: flex; flex-direction: column; gap: 18px; margin-bottom: 26px; }
.settings .row { display: flex; align-items: center; justify-content: space-between; gap: 20px; }
.settings .pass-progress { width: 260px; }
.settings .actions { display: flex; gap: 16px; justify-content: center; }

UI.uidoc_bind_bool("music.on", player.music_enabled);
UI.uidoc_bind_bool("music.off", !player.music_enabled);
UI.uidoc_bind_float("pass.progress", clamp(player.pass_progress, 0.0, 1.0));

示例：确认对话框（战斗请求）

亮色模态框上的高饱和标题横条、深色正文文本，以及一对黄色/红色的接受/拒绝按钮。

<div class="kit-modal battle">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_white1.png">
  <div class="kit-header-band">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_header_red1.png">
    <div class="kit-modal-header">
      <span class="kit-text-header band-title">战斗请求</span>
    </div>
  </div>
  <button class="kit-close" data-on-click="event:battle:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <div class="kit-porthole challenger">
    <img class="kit-bg kit-bg--contain" src="$AO/ui/kit/Game UI/Additional Elements/Circle Portholes/blue_back.png">
    <img class="kit-bg kit-bg--contain" src="$AO/ui/kit/Game UI/Additional Elements/Circle Portholes/gold_ring.png">
  </div>
  <span class="kit-text-body-dark message">{{challenger.name}} 向你发起战斗挑战！</span>
  <div class="actions">
    <button class="kit-btn kit-btn--yellow" data-on-click="event:battle:accept">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_yellow1.png">
      <span class="kit-btn-label">接受</span>
    </button>
    <button class="kit-btn kit-btn--red" data-on-click="event:battle:decline">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_red1.png">
      <span class="kit-btn-label">拒绝</span>
    </button>
  </div>
</div>

@import "game-ui-kit";

.battle { width: 680px; align-items: center; }
.battle .band-title { font-size: 55px; }
.battle .challenger { margin-bottom: 10px; }
.battle .message { text-align: center; margin-bottom: 24px; }
.battle .actions { display: flex; gap: 16px; }

示例：每日奖励

灰色模态框上的横幅标题、奖励槽位、连胜条，以及一个闪亮的领取按钮。

<div class="kit-modal reward">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_grey1.png">
  <div class="kit-modal-header">
    <div class="kit-title-banner">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Horizontal Banners/pointy_banner_blue.png">
      <span class="kit-text-header banner-title">每日奖励</span>
    </div>
  </div>
  <button class="kit-close" data-on-click="event:reward:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <span class="kit-text-body-dark streak">第 {{streak.day}} 天——继续保持！</span>
  <div class="slots">
    <div class="kit-slot" data-for="reward in rewards" data-for-key="reward.id">
      <img class="kit-bg kit-bg--contain" src="{{reward.back}}">
      <img class="kit-slot-icon" src="{{reward.icon}}">
      <span class="kit-slot-qty">{{reward.count}}</span>
    </div>
  </div>
  <div class="kit-progress kit-progress--1 streak-bar">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/backing.png">
    <img class="kit-progress-fill" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/fill_yellow.png"
         data-style-image-fill-amount="streak.progress">
  </div>
  <button class="kit-btn kit-btn--yellow claim" data-on-click="event:reward:claim">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/shiny_buttons/button_large_yellow1.png">
    <span class="kit-btn-label">领取</span>
  </button>
</div>

@import "game-ui-kit";

.reward { width: 600px; align-items: center; }
.reward .banner-title { font-size: 50px; }
.reward .streak { margin-bottom: 16px; }
.reward .slots { display: flex; gap: 12px; margin-bottom: 18px; }
.reward .streak-bar { width: 320px; margin-bottom: 22px; }

已填充槽位绑定 reward.back 到 $AO/ui/kit/Game UI/Item Backs/inventory_squares_1/inv_square_blue1.png （或其他颜色）；空槽位使用 inv_square_empty2.png 且不带图标。

素材覆盖范围

九宫切片内边距随附于 res/ui/kit/Game UI/.asset_settings ，适用于：基础模态框（simple、stripe、headers）、基础和闪亮按钮、中/大型模态框选项卡胶囊和梯形、水平进度条底图/填充（不包括分段精灵和固定纵横比的 bar 12）、水平尖角横幅，以及水平内部面板。固定纵横比部件——包括物品方块、复选框、滑块和切换开关、舷窗、辅助遮罩和高光——不需要切片。其他系列（卡片、对话气泡、华丽横幅、排名底图）虽然也在套件中，但尚未调整内边距——在切片前先测量，并让需要组合的部件保持在同一共享缩放比例下。