Progetto H — Riferimento API Documentazione & Scripting

Funzioni & API Esportate 10

ph.alertDialog

Client
ph.alertDialog(options)
Apre una finestra di dialogo modale al centro dello schermo in stile vetro ossidiana con cornice dorata in gradiente. Blocca l'esecuzione della coroutine corrente finché l'utente non seleziona un'opzione o preme ESC.

Parametri & Opzioni

Parametro Tipo Stato Descrizione
options.header string Obbligatorio Titolo in maiuscolo mostrato in testata (font Cinzel).
options.content string Obbligatorio Testo descrittivo del corpo del dialog. Supporta ritorni a capo (\n).
options.centered boolean Opzionale (default: true) Se true, centra il testo del contenuto.
options.cancel boolean Opzionale (default: true) Se true, mostra il pulsante di annullamento e permette la chiusura con ESC.
options.labels table Opzionale Etichette personalizzate per i pulsanti: { confirm = 'Testo', cancel = 'Testo' }.

Valore di Ritorno

string — Restituisce 'confirm' se confermato, 'cancel' se annullato o chiuso con ESC.

Esempio d'Uso

Esempio Lua
ph.async(function()
    local action = ph.alertDialog({
        header = "CONFERMA OPERAZIONE",
        content = "Sei sicuro di voler apprendere questo incantesimo antico?\nL'azione consumerà 50 Punti Mana.",
        centered = true,
        cancel = true,
        labels = {
            confirm = "Conferma",
            cancel = "Annulla"
        }
    })

    if action == "confirm" then
        ph.notify({ title = "Incantesimo", description = "Hai appreso l'incantesimo!", type = "success" })
    end
end)

ph.registerContext

Client
ph.registerContext(menuData)
Registra un menu contestuale strutturato a schede con supporto a sottomenu multilivello, icone, stati disabilitati e trigger di eventi.

Parametri & Opzioni

Parametro Tipo Stato Descrizione
menuData.id string Obbligatorio Identificativo univoco del menu contestuale.
menuData.title string Obbligatorio Titolo del menu in maiuscolo mostrato nella testata.
menuData.menu string Opzionale ID del menu genitore (mostra automaticamente il pulsante Indietro).
menuData.canClose boolean Opzionale (default: true) Se false, nasconde il tasto X e impedisce la chiusura con ESC.
menuData.options table[] Obbligatorio Array di voci del menu: { title, description, icon, disabled, menu, arrow, onSelect, event, serverEvent, args, close }.

Valore di Ritorno

void — Nessun valore di ritorno.

Esempio d'Uso

Esempio Lua
ph.registerContext({
    id = "fabbro_principale",
    title = "FORGIA DEL FABBRO",
    options = {
        {
            title = "Ripara Armatura",
            description = "COSTO: 50 MONETE",
            icon = "shield",
            onSelect = function()
                ph.notify({ title = "Fabbro", description = "Armatura riparata!", type = "success" })
            end
        },
        {
            title = "Forgia Armi",
            description = "APRE IL CATALOGO ARMI",
            icon = "sword",
            menu = "armi_submenu",
            arrow = true
        },
        {
            title = "Incanta Oggetto",
            description = "RICHIESTO LIVELLO 5",
            icon = "sparkles",
            disabled = true
        }
    }
})

ph.showContext("fabbro_principale")

ph.showContext

Client
ph.showContext(menuId)
Apre a schermo il menu contestuale registrato e attiva il focus del cursore mouse.

Parametri & Opzioni

Parametro Tipo Stato Descrizione
menuId string | table Obbligatorio ID del menu da aprire (o tabella di definizione del menu).

Valore di Ritorno

void — Nessun valore di ritorno.

Esempio d'Uso

Esempio Lua
ph.showContext("fabbro_principale")

ph.hideContext

Client
ph.hideContext()
Chiude il menu contestuale attualmente aperto e rilascia il focus del cursore mouse.

Valore di Ritorno

void — Nessun valore di ritorno.

Esempio d'Uso

Esempio Lua
ph.hideContext()

ph.inputDialog

Client
ph.inputDialog(heading, rows)
Apre un form universale con convalida dei campi, supporto a password, numeri, selettori cromatici a rombo, checkbox e date.

Parametri & Opzioni

Parametro Tipo Stato Descrizione
heading string Obbligatorio Titolo in maiuscolo mostrato in testata al form.
rows table[] Obbligatorio Elenco dei campi del form: 'input', 'number', 'checkbox', 'color', 'date', 'select', 'slider', 'textarea'.

Valore di Ritorno

table | nil — Restituisce un array ordinato con i valori inseriti, o nil se annullato.

Esempio d'Uso

Esempio Lua
ph.async(function()
    local input = ph.inputDialog("REGISTRAZIONE GILDA", {
        { type = "input", label = "NOME GILDA", placeholder = "I Custodi di Alabastro", required = true },
        { type = "number", label = "MASSIMO MEMBRI", min = 5, max = 50, default = 20 },
        { type = "checkbox", label = "REGOLE", text = "Accetto lo statuto", checked = true },
        { type = "color", label = "COLORE STEMMA", default = "#049098" },
        { type = "date", label = "DATA DI FONDAZIONE", format = "20/08/2026" }
    })

    if input then
        Console.Log("Gilda creata: %s, Max: %d, Colore: %s", input[1], input[2], input[4])
    end
end)

ph.progressBar

Client
ph.progressBar(options)
Mostra la barra di progresso a parallelogramma con animazione e riflessi dorati. Blocca la coroutine fino al completamento.

Parametri & Opzioni

Parametro Tipo Stato Descrizione
options.duration number Obbligatorio Durata in millisecondi (es. 4000 = 4 secondi).
options.label string Obbligatorio Testo descrittivo centrato nella barra.
options.position string Opzionale (default: 'bottom') Posizione a schermo: 'bottom', 'middle' / 'center', 'top'.
options.canCancel boolean Opzionale (default: true) Se true, permette l'annullamento premendo ESC o X.
options.freeze boolean Opzionale (default: false) Se true, blocca i movimenti del personaggio per tutta la durata.

Valore di Ritorno

boolean — Restituisce true se completata, false se interrotta dal giocatore.

Esempio d'Uso

Esempio Lua
ph.async(function()
    local ok = ph.progressBar({
        duration = 4500,
        label = "Riparazione in corso...",
        position = "bottom",
        canCancel = true,
        freeze = true
    })

    if ok then
        ph.notify({ title = "Completato", description = "Oggetto riparato!", type = "success" })
    else
        ph.notify({ title = "Interrotto", description = "Azione annullata.", type = "error" })
    end
end)

ph.progressCircle

Client
ph.progressCircle(options)
Mostra un cerchio di avanzamento HUD concentrico con percentuale centrale fluida ed etichetta inferiore.

Parametri & Opzioni

Parametro Tipo Stato Descrizione
options.duration number Obbligatorio Durata in millisecondi (es. 3500).
options.label string Opzionale Etichetta descrittiva posizionata sotto il cerchio.
options.position string Opzionale (default: 'middle') Posizione: 'middle', 'bottom', 'top', 'right-center', 'left-center'.
options.canCancel boolean Opzionale (default: true) Consente l'annullamento con ESC o X.
options.freeze boolean Opzionale (default: false) Blocca i movimenti del personaggio.

Valore di Ritorno

boolean — Restituisce true se completato, false se annullato.

Esempio d'Uso

Esempio Lua
ph.async(function()
    local ok = ph.progressCircle({
        duration = 3500,
        label = "Canalizzazione Magica",
        position = "middle",
        canCancel = true,
        freeze = true
    })
end)

ph.skillCheck

Client
ph.skillCheck(difficulties, inputs)
Avvia il minigioco QTE a doppio anello concentrico con ago rotante, badge tasto e rilevamento istantaneo a 0ms di latenza.

Parametri & Opzioni

Parametro Tipo Stato Descrizione
difficulties string | string[] | table[] Opzionale (default: 'medium') Difficoltà del round: 'easy' (55°), 'medium' (35°), 'hard' (20°), oppure array per sequenze.
inputs string | string[] Opzionale (default: { 'e' }) Tasto o array di tasti richiesti per ciascun round (es. { 'e', 'space' }).

Valore di Ritorno

boolean — Restituisce true se tutti i round sono superati, false al primo errore.

Esempio d'Uso

Esempio Lua
ph.async(function()
    -- Due round: prima medium con 'e', poi hard con 'space'
    local passed = ph.skillCheck({ "medium", "hard" }, { "e", "space" })

    if passed then
        ph.notify({ title = "Scasso", description = "Serratura sbloccata!", type = "success" })
    else
        ph.notify({ title = "Fallito", description = "Grimaldello spezzato.", type = "error" })
    end
end)

ph.notify

Client
ph.notify(data)
Mostra notifiche toast separate con linee dorate sopra e sotto, o banner Quest con rombo e stemma dorato a sinistra.

Parametri & Opzioni

Parametro Tipo Stato Descrizione
data.title string Obbligatorio Titolo in maiuscolo (font Cinzel).
data.description string Opzionale Testo descrittivo del corpo (font Taviraj).
data.type string Opzionale (default: 'info') Tipo notifica: 'success' (verde), 'fail' / 'error' (arancio/rosso), 'warning' / 'info' (campanella oro), 'quest' (banner con rombo).
data.duration number Opzionale (default: 4500) Durata di visualizzazione in millisecondi (default 6000 per quest).

Valore di Ritorno

void — Nessun valore di ritorno.

Esempio d'Uso

Esempio Lua
-- Toast di Successo
ph.notify({
    type = "success",
    title = "SUCCESSO",
    description = "Hai imparato l'incantesimo.",
    duration = 4500
})

-- Banner Nuova Quest
ph.notify({
    type = "quest",
    title = "NUOVA QUEST SECONDARIA",
    description = "Torneo dell'Arcanum",
    duration = 6000
})

ph.showTextUI

Client
ph.showTextUI(text, options)
Mostra un prompt di interazione a schermo in vetro ossidiana e bordo dorato.

Parametri & Opzioni

Parametro Tipo Stato Descrizione
text string Obbligatorio Testo mostrato nel prompt (es. '[E] - Parla con NPC').
options.position string Opzionale (default: 'right-center') Posizione: 'right-center', 'left-center', 'top-center', 'bottom-center', 'top-right', 'top-left', 'bottom-right', 'bottom-left'.

Valore di Ritorno

void — Nessun valore di ritorno.

Esempio d'Uso

Esempio Lua
ph.showTextUI("[E] - Parla con l'Alchimista", { position = "right-center" })

-- Per nasconderlo:
ph.hideTextUI()