> For the complete documentation index, see [llms.txt](https://docs.allout.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.allout.game/all-out-docs/docs-zh/ui/ui-reference.md).

# UI 参考

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

阅读 [UI 基础](/all-out-docs/docs-zh/ui/fundamentals.md) 首先。

### 核心原则

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 按钮

```go
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()});
    }
}
```

### 基础绘制

#### 四边形和图像

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

#### 文本

```go
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");
}
```

### 布局：从矩形开始

```go
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 元素时用于布局：

```go
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` 变体，仅当某个值已经以实际屏幕像素表示时使用，例如从现有矩形测得的尺寸：

```go
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());
    }
}
```

### 按钮

```go
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 时会关闭。

```go
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：

```go
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：

```go
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 之前。