For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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

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

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

类参考

在以下情况使用

.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.pngtab_large.pngtab_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-sizeheight 值,这样基于 em 的系列内边距也会随之缩放。套件轨道使用 flex-shrink: 0;应显式选择厚度,而不要依赖 flex 父容器压缩轨道,因为那样轨道及其填充可能会以不同尺寸解析。

  • 物品槽:有颜色的方块(inv_square_<colour>1.png)用于已填充槽位; inv_square_empty2.png 是设计好的空状态。

  • 模态框系列素材共享同一缩放比例 (源像素中角为 37px、轮廓为 6px——随附的切片内边距已经考虑了这一点)。诸如模态框上方的标题横条这类需要组合的部件之所以能对齐,是因为它们按同一缩放绘制;不要手动编辑各个切片值。

示例:设置模态框

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

示例:确认对话框(战斗请求)

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

示例:每日奖励

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

已填充槽位绑定 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)、水平尖角横幅,以及水平内部面板。固定纵横比部件——包括物品方块、复选框、滑块和切换开关、舷窗、辅助遮罩和高光——不需要切片。其他系列(卡片、对话气泡、华丽横幅、排名底图)虽然也在套件中,但尚未调整内边距——在切片前先测量,并让需要组合的部件保持在同一共享缩放比例下。

最后更新于