UI 参考

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

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

先阅读 UI 基础 。

核心原则

1. Y 轴向上增长。 屏幕坐标以左下角的 (0, 0) 为原点。

2. 从屏幕矩形开始。 使用 UI.get_safe_screen_rect() 或 UI.get_screen_rect()，然后从这些矩形派生出所有内容。

3. 推入/弹出模式。 使用 defer 每次 push 都要使用，以避免泄漏 UI 状态。

4. 移动端优先。 避免仅悬停可用的交互。

5. 仅使用 ASCII。 UI 文本中不要使用 emoji 或 Unicode。

6. UI 必须在 ao_late_update. 中渲染。

快速开始：一个简单的 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 {
        do_action(player);
    }
}

基础绘制

四边形和图片

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, "你好，世界！");

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

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

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

布局：从矩形开始

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});
}

自动缩放和未缩放矩形

Rect 函数会按以下比例缩放： UI.get_current_scale_factor() （基于 1080p）。

如果你需要精确像素值，请使用 _unscaled 变体：

layout_with_unscaled :: proc(window_rect: Rect) {
    list_item := window_rect->top_rect()->grow_bottom(20);

    for item: items {
        draw_item(list_item, item);

        // 对计算出的像素值使用未缩放偏移
        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("按钮被点击了！");
    }
}

按钮精灵规则

绘制按钮时必须使用以下精灵之一：

• "$AO/new/modal/buttons_2/button_1.png" （橙色）

• "$AO/new/modal/buttons_2/button_2.png" （绿色）

• "$AO/new/modal/buttons_2/button_3.png" （红色）

• "$AO/new/modal/buttons_2/button_5.png" （蓝色）

• "$AO/new/modal/buttons_2/button_7.png" （粉色）

• "$AO/new/modal/buttons_2/button_8.png" （灰色）

• "$AO/new/modal/buttons_2/button_9.png" （白色）

UI 状态管理

使用 defer 对于每一对 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

绘制列表或重复项时，请推入唯一 ID：

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

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

        item_rect := rect->cut_top(60);
        if UI.button(item_rect, bs, ts, items[i].name).clicked {
            select_item(i);
        }
    }
}

常用尺寸

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

• 文本：标题 52，正文 36，世界空间文本 0.30

• 矩形：简单对话框 600x400，标准按钮 210x74，退出按钮 65x65

最佳实践

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

• 为重复元素推入 ID。

• 使用未缩放函数和计算出的尺寸。

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

• 始终检查 is_local_or_server() 之后再绘制可交互 UI。