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

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

Эта страница собирает правила интерфейса, шаблоны и примеры, полезные после изучения основ.

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

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

1. Y растёт вверх. Координаты экрана используют (0, 0) в нижнем левом углу.

2. Начинайте с прямоугольников экрана. Используйте UI.get_safe_screen_rect() или UI.get_screen_rect(), затем выводите всё из этих прямоугольников.

3. Шаблон push/pop. Используйте defer для каждого push, чтобы избежать утечек состояния UI.

4. С ориентацией на мобильные устройства. Избегайте взаимодействий, зависящих только от наведения.

5. Только ASCII. Никаких эмодзи или 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});
}

Авто-масштабирование и немасштабированные прямоугольники

Функции 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, "Click Me!");
    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:

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.

• Используйте push ID для повторяющихся элементов.

• Используйте немасштабированные функции с вычисленными размерами.

• Подгоняйте соотношение сторон иконок с помощью rect->fit_aspect(texture->get_aspect()).

• Всегда проверяйте is_local_or_server() перед отрисовкой интерактивного UI.