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. 仅限 ASCII。 UI 文本中不得使用表情或 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, "Action").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, "Hello, World!");

    score := 1500;
    UI.text(rect, ts, "Score: %", {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() （基于 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, "Click Me!");
    if result.clicked {
        log_info("Button was clicked!");
    }
}

按钮精灵规则

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

• "$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 之前。