Global Functions

These functions are available in the global namespace and can be called from anywhere in your Lua scripts.

State Management

The state system allows your UI to be reactive. When state changes, the engine automatically re-renders the interface.

useState(key, defaultValue)

Retrieves a value from the persistent state storage. If the key does not exist, it initializes it with defaultValue.

• Parameters:
  • key (string): Unique identifier.
  • defaultValue (any): Initial value.
• Returns: The current value.

Example:

-- Initialize a counter, default to 0
local count = useState("app_counter", 0)

-- Initialize a username string
local user = useState("username", "Guest")

setState(key, newValue)

Updates the value associated with key and marks the UI for a re-render on the next frame.

• Parameters:
• key (string): Unique identifier.
• newValue (any): The new value.

Example:

local el = require("utils.core.elements")

function App()
	local count = useState("app_counter", 0)

	return el.VBox({
		style = {
			alignItems = "center",
			justifyContent = "center",
			gap = 10,
		},
		onClick = function()
			setState("app_counter", count + 1)
		end,
		children = {
			el.Text("Count: " .. count),
			el.Text("(Click to Increment)", { style = { fontSize = 12, color = "#888" } }),
		},
	})
end

The vulpis Module

Core engine functionality is exposed under the vulpis table.

Font Management

vulpis.load_font(path, [size], [flags])

Loads a font file directly from the assets folder.

• Parameters:

• path (string): Relative path to assets/.

• size (number): Font size (default 16).

• flags (table): { bold=true, italic=true, thin=true }.

• Returns: FontHandle (userdata) or nil.

Example:

-- 1. Load a specific font file
local iconFont = vulpis.load_font("fonts/MaterialIcons.ttf", 24)

-- 2. Load with synthetic Bold + Italic style
local fancyFont = vulpis.load_font("fonts/Arial.ttf", 32, { 
    bold = true, 
    italic = true 
})

if not iconFont then print("Failed to load icons!") end

vulpis.update_font_config(alias, config)

Registers or updates a global font alias at runtime.

• Parameters:
• alias (string): Family name.
• config (table): Configuration options.

Example:

-- Register a new font family named "code"
vulpis.update_font_config("code", {
    path = "fonts/FiraCode-Regular.ttf",
    size = 14
})

-- Now you can use it in components:
-- el.Text({ style = { fontFamily = "code" } })

Immediate Mode Rendering

vulpis.draw_text(text, fontHandle, x, y, [color])

Draws a text string at absolute screen coordinates. Must be called inside on_render.

• Parameters:
• text (string): Content.
• fontHandle (userdata): Handle from load_font.
• x, y (number): Coordinates.
• color (string/table): Hex or RGBA.

Example:

function on_render()
	if not debugFont then
		debugFont = vulpis.load_font("font.ttf", 16)
	end
	-- Draw FPS counter at top-left
	vulpis.draw_text("FPS: 60", debugFont, 0, 16, "#00FF00")
end

Lifecycle Callbacks

Define these global functions in your app.lua to control the application.

Window()

Called once on startup to configure the OS window.

• Returns: Table with window settings.

Example:

function Window()
    return {
        title = "My Vulpis App",
        w = 800,
        h = 600,
        resizable = true,
        mode = "windowed" -- Options: "full" (maximized), "whole screen" (fullscreen), or "windowed" (default)
    }
end

App()

The entry point for your UI. Called every frame the UI needs to update.

• Returns: The root UI component.

Example:

local el = require("utils.core.elements")

function App()
    return el.VBox({
        style = { justifyContent = "center", alignItems = "center" },
        children = {
            el.Text("Hello World!")
        }
    })
end

on_tick(dt)

Called every frame for logic updates.

• Parameters:
• dt (number): Delta time in seconds.

Example:

local timer = 0

function on_tick(dt)
    timer = timer + dt
    -- Print message every 5 seconds
    if timer > 5.0 then
        print("5 seconds have passed")
        timer = 0
    end
end

on_render()

Called after the UI renders. Use this for debug overlays or custom drawing.

Example:

function on_render()
    -- Draw a version string at the bottom right
    local font = vulpis.load_font("fonts/Small.ttf", 10)
    vulpis.draw_text("v1.0.0", font, 10, 700, "#FFFFFF")
end