QuestLines GUI

What It Is

QuestLines GUI lets server admins build custom in-game UI screens without writing any Hytale UI code. Each screen is a .gui.json file in mods/QuestLinesGUI/. The plugin loads these files at startup and exposes them via the /qlgui command and the opengui: Core action.

Because the plugin hooks into QuestLines Core’s action and requirement systems, GUIs are first-class quest citizens: a button that awards gold, completes a quest, or navigates to another screen uses the exact same action strings as dialogue responses. Elements can be hidden or shown based on any requirement the player currently meets.

Data Model

Each file in mods/QuestLinesGUI/ named <id>.gui.json defines one GUI screen. The ID is taken from the filename; an explicit "Id" field inside the JSON overrides it. All JSON keys are PascalCase.

GuiDefinition

{
  "Title":               "The Blacksmith",
  "Width":               400,
  "Height":              320,
  "DefaultCloseOnClick": false,
  "DefaultRefresh":      true,
  "Elements": [ /* element objects */ ]
}

Element Types

Every element has a "Type" field and an optional "Id" string. Most elements also accept a "Requirements" list — if any requirement fails, the element is hidden entirely. Requirements use the same format as quest page requirements.

label

button

spacer

divider

panel

A container element that groups child elements. The entire panel — including all its children — is hidden if any of its Requirements fail. This is useful for showing or hiding whole sections based on quest state.

image

itemicon

progressbar

The Value field supports Core text variables and resolves to a number. A value of 0.0–1.0 is used directly as the fill fraction. A value > 1.0 is treated as a percentage (divided by 100). Use Max together with a raw tracker value to compute the fraction automatically.

// Fixed fraction
{ "Type": "progressbar", "Value": "0.75", "Width": 200 }

// From a named tracker (kill 10 bosses)
{ "Type": "progressbar", "Value": "{track:killboss}", "Max": 10, "Width": 200 }

// Circular
{ "Type": "progressbar", "Value": "0.5", "Circular": true, "Width": 48, "Height": 48 }

checkbox

The checkbox renders as checked or unchecked based on whether the player meets all CheckedRequirements at render time. Clicking a checked box fires UncheckActions; clicking an unchecked box fires CheckActions.

{
  "Type":                "checkbox",
  "Label":               "Show quest notifications",
  "CheckedRequirements": ["hasTag:notif_on"],
  "CheckActions":        ["addTag:notif_on"],
  "UncheckActions":      ["removeTag:notif_on"],
  "Refresh":             true
}

hyvatar

Renders a Hytale player avatar. Use "{player}" as the username to show the viewing player’s own skin.

itemgrid

An inventory-style grid of item slots. Each slot can have its own actions, requirements, and click requirements. ItemId, Name, and Description in each slot support Core text variables.

Each slot in Slots:

Core Integration

opengui: action

When both QuestLines GUI and QuestLines Core are installed, the plugin registers an opengui:<guiId> action with Core. This action can be used anywhere Core actions are accepted: response Actions lists, page LoadActions, button actions in other GUIs, or via the developer API.

// Open a shop screen from a dialogue response
"opengui:blacksmith_shop"

// Auto-open a welcome screen once (via LoadActions)
Requirements: ["questNotStarted:welcome"]
LoadActions:  ["questStarted:welcome", "opengui:welcome_screen"]

Requirements on elements

Any element or slot that has a "Requirements" list is hidden when any requirement in that list fails. Requirements use the same format as quest page requirements — hasTag:vip, questCompleted:intro, track:killboss:5, etc.

{
  "Type":         "button",
  "Text":         "VIP Shop",
  "Requirements": ["hasTag:vip"],
  "Actions":      ["opengui:vip_shop"]
}

Text variables in elements

label.Text, progressbar.Value, image.Src, itemicon.ItemId, hyvatar.Username, and itemgrid slot fields all pass through the Core text variable engine. Every variable available in dialogue is also available in GUIs — {player}, {track:id}, {variable:name}, etc.

Actions in buttons

Button and itemgrid slot Actions lists accept any Core action string. This includes quest actions (questCompleted:), economy actions (economy:give:500), navigation (opengui:otherId), and everything else in the Actions reference.

In-Game Editor

QuestLines GUI ships with a basic in-game editor accessible via /qlgui editor or /qlgui edit <id>. The editor lets you inspect and modify GUI definitions directly in-game without editing JSON files by hand.

The editor supports a preview mode: clicking Preview opens the GUI as a player would see it. Closing the preview automatically reopens the editor session. Changes are only written to disk when you explicitly save.

Commands

Root command: /qlgui. Requires questlines.admin permission.

Permissions

Data Directory

QuestLines GUI stores all GUI definitions in mods/QuestLinesGUI/. Each file is named <guiId>.gui.json. The plugin scans this directory at startup and on /qlgui reload.

Files edited in the in-game editor are saved back to this directory and reloaded immediately into the in-memory cache without requiring a server restart or a manual reload command.

Full Example

A simple shop screen with a VIP-only section and a progress bar:

// mods/QuestLinesGUI/blacksmith_shop.gui.json
{
  "Title":               "Aldric's Forge",
  "Width":               420,
  "Height":              380,
  "DefaultCloseOnClick": false,
  "Elements": [
    {
      "Type":  "label",
      "Text":  "Welcome, {player}!",
      "Bold":  true,
      "Align": "Center"
    },
    { "Type": "divider" },
    {
      "Type":    "label",
      "Text":    "Smith reputation: {track:smith_rep} / 100",
      "Color":   "#aabbcc"
    },
    {
      "Type":  "progressbar",
      "Value": "{track:smith_rep}",
      "Max":   100,
      "Color": "#e08040",
      "Width": 380
    },
    { "Type": "spacer", "Height": 8 },
    {
      "Type":    "button",
      "Text":    "Buy Iron Sword (50g)",
      "Actions": ["economy:take:50", "item:iron_sword:1"]
    },
    {
      "Type":         "button",
      "Text":         "Buy Legendary Blade (VIP only)",
      "Requirements": ["hasTag:vip"],
      "Actions":      ["economy:take:500", "item:legendary_blade:1"]
    },
    {
      "Type":         "button",
      "Text":         "Close",
      "CloseOnClick": true,
      "Actions":      []
    }
  ]
}