Text UI

A lightweight, highly-optimized script for rendering 2D on-screen text and button prompts. Unlike the 3D Text UI, this version is entirely static and event-driven—meaning it has zero background performance overhead. It simply acts as a visual prompt and relies completely on your own external scripts to handle the logic, input polling, and distance checks.

⚙️ Data Structures

You can configure the 2D Text UI using either a simple string or a full configuration table for advanced control.

Simple String (Shorthand) If you just need to display simple text, you can pass a string directly. The system will automatically build the necessary table structure using your default configuration settings.

The Main Configuration Table

If you pass a table, this defines where the text is positioned on your screen and what it displays.

Property	Type	Default	Description
position	string	Config.Defaults.TextUI.position	The CSS-based screen position (e.g., 'center-left', 'top-right').
options	table	Required	A list of text lines or button prompts (see below).
scale	float	1.0	Scaling factor for the UI element.

The Options Table

Because this script is purely visual, the options list only handles display parameters. It does not process action callbacks, hold timers, or isVisible checks. You must handle input processing in your own resource loops.

options = {
    { 
        label = "Access Laptop",    -- The text displayed on screen
        key = 38,                   -- (Optional) The FiveM Control Index (38 is E). Auto-fetches from Lib47.Keys
        keyName = "E",              -- (Optional) Manually override the visual key name displayed inside the box
    },
    { 
        label = "Exit Menu", 
        keyName = "ESC"             -- You can pass a keyName without a control index for pure visuals
    }
}

Supported Positions: 'top-left', 'top-right', 'top-center', 'bottom-left', 'bottom-right', 'bottom-center', 'center-left', 'center-right'

---

🛠️ API Reference

Because 2D Text UI operates natively on the screen rather than in the 3D world, there is only 1 globally active 2D Text UI allowed at a time per resource. You do not need to manage IDs; firing a new UI will instantly overwrite the previous one.

1. ShowTextUi

Renders the 2D Text UI on the screen. It stays visible until you manually hide it or overwrite it.

• Usage: Lib47.ShowTextUi(data) (where data is a table or a string)

2. HideTextUi

Instantly dismisses the active 2D Text UI.

• Usage: Lib47.HideTextUi()

---

📝 Code Examples

Example A: Simple String (Quick Prompt)

The fastest way to show a prompt. It automatically inherits the position from Config.Defaults.TextUI.position.

CreateThread(function()
    -- Show the prompt
    Lib47.ShowTextUi("Press [E] to talk to NPC")
    
    -- Wait for player to press E (You handle the input logic)
    while true do
        Wait(0)
        if IsControlJustReleased(0, 38) then
            print("Talked to NPC!")
            Lib47.HideTextUi() -- Hide it when done
            break
        end
    end
end)

Example B: Advanced Layout

Use this when you want to customize the position or show multiple keys simultaneously with clean UI button icons.

RegisterCommand('showui', function()
    Lib47.ShowTextUi({
        position = 'bottom-right',
        scale = 1.1,
        options = {
            { 
                label = "LOCK/UNLOCK", 
                key = 303, -- 'U' key
            },
            { 
                label = "ENGINE", 
                keyName = "G", -- Manual override
            }
        }
    })
end)

RegisterCommand('hideui', function()
    Lib47.HideTextUi()
end)

Example C: Using Exports Directly

If you do not use the Lib47 global wrapper, you can use the resource exports directly via the Interface wrapper.

exports['ak47_lib']:ShowTextUi({
    position = 'top-center',
    options = {
        { label = "Entering Restricted Zone..." }
    }
})

-- Later
exports['ak47_lib']:HideTextUi()