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

UI 参考

CSL UI 绘制的参考说明和模式。

本页收集了在你掌握基础后会很有帮助的 UI 规则、模式和示例。

阅读 UI 基础 首先。

核心原则

  1. Y 轴向上增长。 屏幕坐标使用左下角的 (0, 0)。

  2. 从屏幕矩形开始。 使用 UI.get_safe_screen_rect() 或 UI.get_screen_rect(),然后从这些矩形推导出其他一切。

  3. Push/pop 模式。 使用 defer 用于每一次 push,以避免泄漏 UI 状态。

  4. 移动优先。 避免仅依赖悬停的交互。

  5. 文本使用 UTF-8,但字符覆盖并不完整。 字符仍然需要在所选字体或其回退字体中有对应字形。某些字符,包括表情符号,暂时还不支持。

  6. 使用玩家的晚更新栈。 将该玩家的所有 UI 绘制都从这个玩家的 ao_late_update 中, 在 is_local_or_server().

快速开始:一个简单的 HUD 按钮

Player :: class : Player_Base {
    ao_late_update :: method(dt: float) {
        if this.is_local_or_server() {
            draw_my_hud(this);
        }
    }
}

draw_my_hud :: proc(player: Player) {
    rect := UI.get_safe_screen_rect()
        .bottom_right_rect()
        .grow(40, 150, 40, 150)
        .offset(-50, 50);

    bs := UI.default_button_settings();
    ts := UI.default_text_settings();

    if UI.button(rect, bs, ts, "操作").clicked {
        log_info("来自 % 的操作", {player.get_username()});
    }
}

基础绘制

四边形和图像

填充四边形

传入 Quad_Params.fill 来自 UI.quad_fill 即可只显示四边形的一部分。可用的 Fill_Direction 值有 .NONE, .RIGHT, .LEFT, .UP, .DOWN,以及 .RADIAL.

线性填充使用从 0 到 1的数值。径向填充从 12 点钟方向开始,使用带符号的数值: -1..0 表示逆时针填充, 0..1 表示顺时针填充。超出适用范围的值会被钳制。径向数值为 0 时不会绘制任何内容; -1 而 1 两者都会绘制完整的四边形。

对于变化中的填充,保留一个持久的 Float_Interpolation_Helper 并将其结果传给 UI.quad_fill。在调用 update之前先进行钳制;为了逆时针径向填充,必须保留符号。若同一种填充要应用于多个绘制调用,请使用 UI.push_fill_amount 而 UI.pop_fill_amount 。务必为 push 配对一个延迟的 pop。

文本

布局:从矩形开始

布局中使用 cut

cut 函数 必须 在放置多个 UI 元素时用于布局:

自动缩放和未缩放矩形

常规矩形函数接受 点 并按 UI.get_current_scale_factor() 进行缩放(基于一个 1080 点高的参考画布)。

只在数值已经以实际屏幕像素表示时,才使用 _unscaled 变体,例如从已有矩形测得的尺寸:

按钮

按钮精灵规则

UI.default_button_settings() 已经提供了完整的按钮样式。对于自定义按钮,设置 sprite ,并可选地设置 sprite_hovered 而 sprite_pressed。当可选精灵为空时,会复用基础精灵。

模态框

使用 UI.begin_modal / UI.end_modal 用于一个变暗的背景;当玩家点到模态框外部或按下 Escape 时,它会关闭。

UI 状态管理

使用 defer 用于每一对 push/pop:

重复元素的 ID

在绘制列表或重复项时,推入唯一 ID:

常见尺寸

一些在各种设备上看起来都不错的尺寸:

  • 屏幕文本点数:标题 52,正文 36

  • 屏幕矩形点数:简单对话框 600x400,标准按钮 210x74,退出按钮 65x65

  • 世界空间文本大小:0.30 米

最佳实践

  • 使用 defer 用于每一对 push/pop。

  • 为重复元素推入 ID。

  • 对计算得到的尺寸使用未缩放函数。

  • 使用以下方式让图标宽高比适配: rect.fit_aspect(texture.get_aspect()).

  • 始终检查 在 is_local_or_server() 在绘制交互式 UI 之前。

最后更新于