Referencia de UI

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

Esta página recopila reglas, patrones y ejemplos de IU que son útiles una vez que conoces lo básico.

Leer Fundamentos de IU primero.

Principios básicos

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

2. Comienza desde 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 IU.

4. Primero móvil. Evita interacciones solo por hover.

5. Solo ASCII. No emoji ni Unicode en el texto de la IU.

6. La IU debe renderizar en ao_late_update. Esto es necesario para la 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

Cuadriláteros 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, "Hello, World!");

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

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

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

Maquetación: empezar desde 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 la maquetación al colocar múltiples elementos de IU:

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 no escalados

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

Si necesitas valores exactos de píxeles, usa el _unscaled variantes:

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

Reglas de sprite para botones

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 IU

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 IU aquí
}

IDs para elementos repetidos

Al dibujar listas o elementos repetidos, push 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 lucen bien en varios 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.

• Push IDs para elementos repetidos.

• Usa funciones no escaladas con dimensiones calculadas.

• Ajusta las proporciones del icono con rect->fit_aspect(texture->get_aspect()).

• Siempre comprueba is_local_or_server() antes de dibujar IU interactiva.