UI 参考

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

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

阅读 UI 基础 首先。

核心原则

1. Y 轴向上。 屏幕坐标以左下角的 (0, 0) 为原点。
2. 从屏幕矩形开始。 使用 UI.get_safe_screen_rect() 或 UI.get_screen_rect()，然后基于这些矩形推导出所有内容。
3. push/pop 模式。 使用 延后执行 以避免每次 push 都泄漏 UI 状态。
4. 移动优先。 避免仅依赖悬停的交互。
5. 文本使用 UTF-8，但字符覆盖并不完整。 字符仍然需要在所选字体或其回退字体中有对应字形。某些字符，包括表情符号，尚不受支持。
6. 使用玩家的 late-update 栈。 将该玩家的所有 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, "Action").clicked {
        log_info("来自 % 的操作", {player.get_username()});
    }
}

基础绘制

四边形和图像

draw_ui :: proc() {
    rect := UI.get_screen_rect().center_rect().grow(100); // 200x200
    texture := get_asset(Texture_Asset, "my_icon.png");
    UI.quad(rect, texture);

    // 带颜色色调（RGBA 0-1）
    UI.quad(rect, texture, {1, 0, 0, 0.5});

    // 使用白色精灵图作为纯色
    UI.quad(rect, core_globals.white_sprite, {0, 0, 0, 0.75});
}

文本

draw_text :: proc() {
    rect := UI.get_screen_rect().center_rect().grow(200, 300, 50, 300);

    ts := UI.default_text_settings();
    ts.size = 48;
    ts.color = {1, 1, 1, 1};
    ts.halign = .CENTER;
    ts.valign = .CENTER;

    UI.text(rect, ts, "Hello, World!");

    score := 1500;
    UI.text(rect, ts, "分数：%", {score});

    pct := 67;
    UI.text(rect, ts, "% %%", {pct}); // "67 %"

    // 返回实际渲染出的矩形
    actual_rect := UI.text_sync(rect, ts, "Dynamic text");
}

布局：从矩形开始

layout_example :: proc() {
    screen := UI.get_screen_rect();
    safe := UI.get_safe_screen_rect();

    center := screen.center_rect();
    top_left := screen.top_left_rect();
    bottom_right := screen.bottom_right_rect();

    button_rect := center.grow(50, 150, 50, 150);
    icon_rect := center.grow(64);
}

布局使用 cut

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

draw_panel :: proc() {
    rect := UI.get_safe_screen_rect().inset(20);

    header := rect.cut_top(80);
    footer := rect.cut_bottom(60);
    body := rect;

    UI.quad(header, core_globals.white_sprite, {0.1, 0.1, 0.1, 0.8});
    UI.quad(footer, core_globals.white_sprite, {0.1, 0.1, 0.1, 0.8});
    UI.quad(body, core_globals.white_sprite, {0.05, 0.05, 0.05, 0.8});
}

自动缩放与未缩放矩形

常规矩形函数接受 点 并按以下比例缩放 UI.get_current_scale_factor() （基于高度为 1080 点的参考画布）。

使用 _unscaled 变体，仅当某个值已经以实际屏幕像素表示时使用，例如从现有矩形测得的尺寸：

layout_with_unscaled :: proc(window_rect: Rect, items: []string) {
    ts := UI.default_text_settings();
    list_item := window_rect.top_rect().grow_bottom(20);

    for item: items {
        UI.text(list_item, ts, item);

        // height() 已经是屏幕像素，因此不要再次缩放
        list_item = list_item.offset_unscaled(0, -list_item.height());
    }
}

按钮

draw_buttons :: proc() {
    rect := UI.get_safe_screen_rect()
        .bottom_center_rect()
        .grow(40, 150, 40, 150)
        .offset(0, 100);

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

    bs.sprite = get_asset(Texture_Asset, "$AO/new/modal/buttons_2/button_2.png");
    bs.press_scaling = 0.35;

    result := UI.button(rect, bs, ts, "点击我！");
    if result.clicked {
        log_info("按钮被点击了！");
    }
}

按钮精灵规则

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

模态窗口

使用 UI.begin_modal / UI.end_modal 用于显示变暗的背景；当玩家点击模态窗口外部或按下 Escape 时会关闭。

Player :: class : Player_Base {
    settings_open: bool;
}

draw_settings_modal :: proc(player: Player) {
    if !player.settings_open return;

    UI.begin_modal(UI.get_screen_rect(), "settings_modal", ref player.settings_open);
    defer UI.end_modal();

    window := UI.get_safe_screen_rect().center_rect().grow(240, 360, 240, 360);
    UI.quad(window, core_globals.white_sprite, {0, 0, 0, 0.9});

    ts := UI.default_text_settings();
    ts.halign = .CENTER;
    ts.valign = .CENTER;
    UI.text(window, ts, "设置");
}

UI 状态管理

使用 延后执行 针对每一对 push/pop：

draw_layered_ui :: proc() {
    UI.push_screen_draw_context();
    defer UI.pop_draw_context();

    UI.push_layer(100);
    defer UI.pop_layer();

    UI.push_color_multiplier({1, 1, 1, 0.5});
    defer UI.pop_color_multiplier();

    // 在此绘制 UI
}

重复元素的 ID

在绘制列表或重复项时，请 push 唯一 ID：

draw_list :: proc(items: []string) {
    rect := UI.get_safe_screen_rect().inset(20);
    bs := UI.default_button_settings();
    ts := UI.default_text_settings();

    for i: 0..<items.count {
        UI.push_id("item_%", {i});
        defer UI.pop_id();

        item_rect := rect.cut_top(60);
        if UI.button(item_rect, bs, ts, items[i]).clicked {
            log_info("已选择项目 %", {i});
        }
    }
}

常用尺寸

以下尺寸已知在各种设备上都表现良好：

• 屏幕文字点数：标题 52，正文 36
• 屏幕矩形点数：简单对话框 600x400，标准按钮 210x74，退出按钮 65x65
• 世界空间文字大小：0.30 米

最佳实践

• 使用 延后执行 针对每一对 push/pop。
• 为重复元素 push ID。
• 在使用计算出的尺寸时，请使用未缩放函数。
• 使用以下方式适配图标宽高比 rect.fit_aspect(texture.get_aspect()).
• 始终检查 is_local_or_server() 在绘制交互式 UI 之前。