World Space UI

Use world space UI to draw text above players heads and any other text that should feel like it's part of the game world itself.

World space UI is drawn in the 2D world instead of on the screen. Use it for nameplates, health bars, signs, and any text that should feel anchored to game objects.

World space UI uses meters for sizing. If you use screen-style pixel sizes, your UI will be enormous.

Core Rules

• Always call UI.push_world_draw_context() and defer UI.pop_draw_context().

• Use meters for rect sizes and offsets.

• Push Z for proper depth sorting (commonly use pos.y).

• Use subrect only for percentage fills (like health bars).

Examples

Displaying a player's level

draw_player_level :: proc(player: Player) {
    UI.push_world_draw_context();
    defer UI.pop_draw_context();

    pos := player.world_position;
    UI.push_z(pos.y);
    defer UI.pop_z();

    ts := UI.default_text_settings();
    ts.size = 0.30; // World space text size
    ts.halign = .CENTER;
    ts.valign = .CENTER;

    text_pos := pos + v2{0, 1.7};
    rect := Rect{text_pos, text_pos}->grow(0.05, 0.4, 0.05, 0.4);
    UI.text(rect, ts, "Lvl %", {player.level});
}

Player base signs

draw_base_sign :: proc(sign: Entity, label: string) {
    UI.push_world_draw_context();
    defer UI.pop_draw_context();

    pos := sign.world_position;
    UI.push_z(pos.y);
    defer UI.pop_z();

    ts := UI.default_text_settings();
    ts.size = 0.30;
    ts.halign = .CENTER;
    ts.valign = .CENTER;

    text_pos := pos + v2{0, 2.2};
    rect := Rect{text_pos, text_pos}->grow(0.06, 0.8, 0.06, 0.8);

    // Optional dark backing for readability
    UI.quad(rect, core_globals.white_sprite, {0, 0, 0, 0.6});
    UI.text(rect, ts, label);
}

Health bars

draw_world_ui :: proc(entity: Entity) {
    UI.push_world_draw_context();
    defer UI.pop_draw_context();

    pos := entity.world_position;
    UI.push_z(pos.y);
    defer UI.pop_z();

    bar_pos := pos + v2{0, 1.5};
    bar_rect := Rect{bar_pos, bar_pos}->grow(0.1, 0.5, 0.1, 0.5);

    UI.quad(bar_rect, core_globals.white_sprite, {0, 0, 0, 0.8});

    health_pct := entity.health / entity.max_health;
    fill_rect := bar_rect->inset(0.02)->subrect(0, 0, health_pct, 1);
    fill_color := lerp(v4{1, 0, 0, 1}, {0, 1, 0, 1}, health_pct);
    UI.quad(fill_rect, core_globals.white_sprite, fill_color);
}

Coordinate Conversion

// Convert world position to screen position
screen_pos := world_to_screen(entity.world_position);

// Convert screen position to world position
world_pos := screen_to_world(get_mouse_screen_position());

Tips

• Keep world UI minimal and readable at distance. If you have a zoomable camera, make sure to adjust text size when you zoom out.

• Use fit_aspect() if you draw icons in world space.

• If text flickers or overlaps, check your Z values and spacing.