Справочник по UI

Справочные заметки и шаблоны для отрисовки UI в CSL.

На этой странице собраны правила, шаблоны и примеры UI, которые полезны, когда вы уже знаете основы.

Прочтите Основы UI сначала.

Основные принципы

1. Y растёт вверх. Координаты экрана используют (0, 0) в левом нижнем углу.
2. Начинайте с прямоугольников экрана. Используйте UI.get_safe_screen_rect() или UI.get_screen_rect(), а затем выводите всё остальное из этих прямоугольников.
3. Паттерн push/pop. Используйте defer для каждого push, чтобы не допустить утечки состояния UI.
4. Mobile-first. Избегайте взаимодействий только по наведению.
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, "Action").clicked {
        log_info("action from %", {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 %"

    // Возвращает фактический отрисованный rect
    actual_rect := UI.text_sync(rect, ts, "Dynamic text");
}

Макет: начинайте с rect'ов

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'ы

Обычные функции rect принимают точки и масштабируют их с помощью UI.get_current_scale_factor() (на основе эталонного холста высотой 1080 пунктов).

Используйте _unscaled варианты только тогда, когда значение уже выражено в фактических пикселях экрана, например размер, измеренный по существующему rect:

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, "Click Me!");
    if result.clicked {
        log_info("Button was clicked!");
    }
}

Правила спрайта кнопки

UI.default_button_settings() уже предоставляет полный стиль кнопки. Для пользовательской кнопки задайте sprite и при необходимости sprite_hovered и sprite_pressed. Когда необязательные спрайты равны null, базовый спрайт используется повторно.

Модальные окна

Используйте 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

Используйте 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: []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
• Точки rect экрана: Простой диалог 600x400, Стандартная кнопка 210x74, Кнопка выхода 65x65
• Размер текста в мировом пространстве: 0.30 метра

Лучшие практики

• Используйте defer для каждой пары push/pop.
• Задавайте ID для повторяющихся элементов.
• Используйте не масштабированные функции с вычисленными размерами.
• Подгоняйте соотношение сторон иконок с помощью rect.fit_aspect(texture.get_aspect()).
• Всегда проверяйте is_local_or_server() перед рисованием интерактивного UI.