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 la IU primero.

Principios básicos

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

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

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 requerido 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

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 real renderizado
    actual_rect := UI.text_sync(rect, ts, "Dynamic text");
}

Maquetación: empieza desde rects

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 la maquetación

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

Las funciones de Rect se escalan por UI.get_current_scale_factor() (basado en 1080p).

Si necesitas valores de píxeles exactos, 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, 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 lucen bien en varios dispositivos:

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

• Rects: 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 no escaladas con dimensiones calculadas.

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

• Revisa siempre is_local_or_server() antes de dibujar IU interactiva.