Referencia de UI

Notas de referencia y patrones para el dibujo de UI en CSL.

Esta página recopila reglas, patrones y ejemplos de UI que son útiles una vez que conoces los conceptos básicos.

Lee Fundamentos de UI primero.

Principios básicos

1. Y crece hacia arriba. Las coordenadas de pantalla usan (0, 0) en la esquina inferior izquierda.

2. Empieza a partir de los rectángulos de pantalla. Usa UI.get_safe_screen_rect() o UI.get_screen_rect(), luego deriva todo a partir de esos rectángulos.

3. Patrón push/pop. Usa defer para cada push para evitar filtrar el estado de la UI.

4. Primero móvil. Evita las interacciones que solo funcionan con hover.

5. Solo ASCII. Sin emojis ni Unicode en el texto de la UI.

6. La UI debe renderizar en ao_late_update. Esto es necesario para una interacción correcta.

Inicio rápido: un botón HUD simple

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

Dibujo básico

Cuadros e imágenes

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

    // Con tinte de color (RGBA 0-1)
    UI.quad(rect, texture, {1, 0, 0, 0.5});

    // Color sólido usando el sprite blanco
    UI.quad(rect, core_globals.white_sprite, {0, 0, 0, 0.75});
}

Texto

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, "¡Hola, mundo!");

    score := 1500;
    UI.text(rect, ts, "Puntuación: %", {score});

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

    // Devuelve el rectángulo realmente renderizado
    actual_rect := UI.text_sync(rect, ts, "Texto dinámico");
}

Diseño: empieza a partir de rectángulos

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

Usa cut para el diseño

Las funciones cut deben usarse para el diseño al colocar múltiples elementos de 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});
}

Autoescalado y rectángulos sin escalar

Las funciones de rectángulo se escalan por UI.get_current_scale_factor() (basado en 1080p).

Si necesitas valores exactos de píxeles, usa las variantes _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);

        // Usa offset sin escalar con valores de píxeles calculados
        list_item = list_item->offset_unscaled(0, -list_item->height());
    }
}

Botones

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, "¡Haz clic en mí!");
    if result.clicked {
        log_info("¡Se hizo clic en el botón!");
    }
}

Reglas del sprite del botón

Debes usar uno de estos sprites al dibujar botones:

• "$AO/new/modal/buttons_2/button_1.png" (Naranja)

• "$AO/new/modal/buttons_2/button_2.png" (Verde)

• "$AO/new/modal/buttons_2/button_3.png" (Rojo)

• "$AO/new/modal/buttons_2/button_5.png" (Azul)

• "$AO/new/modal/buttons_2/button_7.png" (Rosa)

• "$AO/new/modal/buttons_2/button_8.png" (Gris)

• "$AO/new/modal/buttons_2/button_9.png" (Blanco)

Gestión del estado de la UI

Usa defer para cada par 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();

    // Dibuja la UI aquí
}

IDs para elementos repetidos

Al dibujar listas o elementos repetidos, haz push de IDs únicos:

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

Tamaños comunes

Algunos tamaños que se sabe que se ven bien en todos los dispositivos:

• Texto: Título 52, Cuerpo 36, Texto en espacio mundial 0.30

• Rectángulos: Diálogo simple 600x400, Botón estándar 210x74, Botón de salida 65x65

Mejores prácticas

• Usa defer para cada par push/pop.

• Haz push de IDs para elementos repetidos.

• Usa funciones sin escalar con dimensiones calculadas.

• Ajusta las relaciones de aspecto de los iconos con rect->fit_aspect(texture->get_aspect()).

• Comprueba siempre is_local_or_server() antes de dibujar UI interactiva.