HUD Builder & In-Game Overlays

Native overlays let players toggle Cavebot / Targeting / Healing / Looting (and custom actions) without opening the Opus QML window. Layouts are .ophud.json files under hud_layouts\.

Quick start

1. Open Opus → HUD tab.
2. Click a template (Compact / Stack / Full / Panic) — buttons appear in the game window.
3. Enable Edit placement, drag buttons, click Save (or Save as to name it under My HUDs).
4. Turn Edit off to use the buttons in fight.

Important: clicking the same template again does not reset your dragged positions. Use Reset template only if you want mall defaults back.

Templates (malls)

Name	Contents
Compact	Cave / Target / Heal / Loot in a row
Stack	Same four, vertical
Full	Compact + Spell
Panic	Pause all + Safe logout (top-right)

My HUDs

Save as writes hud_layouts\saved\<name>.ophud.json. Load / delete from the list. After load you can change icons per button (select → search item → Apply icon).

Change icon / add buttons

No raw Id / Verb fields in the UI — pick a module chip (Cave, Target, Heal, Loot, Spell, Pause, Safe). Select a button in the list to change its game-sprite icon via name search (same keyboard hook as other QML fields).

.ophud.json schema (version 1)

{
  "version": 1,
  "name": "Compact",
  "editMode": false,
  "visible": true,
  "origin": "tl",
  "ox": 8,
  "oy": 72,
  "elements": [
    {
      "id": "cave",
      "type": "toggle",
      "x": 0, "y": 0, "w": 54, "h": 22,
      "label": "Cave",
      "itemId": 32753,
      "color": "#3A3A3A",
      "verb": "SET cave_enabled 1",
      "module": "cave",
      "visible": true
    }
  ]
}

Element type

type	Click	Notes
toggle	Flips SET key 0/1 when module is known	Live ON/OFF colour
action	Runs verb as-is	Any SET / DO line
icon	None	Sprite only
label	None	Text only
panel	None	Coloured background

origin: tl | tr | bl | br — ox/oy are pixel offsets from that corner.

Settings keys

Key	Meaning
hud_visible	Show overlay
hud_edit_mode	Drag vs click
hud_layout_file	Path to active .ophud.json
hud_layout_active	Preset name (compact) or stem
hud_anchor / hud_left_margin / hud_top_margin	Legacy mirror of origin/ox/oy
hud_buttons	Legacy CSV — imported once if no layout file

IPC / verbs (for AI & automation)

DO hudpreset compact
DO hudshow | hudhide | hudtoggle
DO hudeditenable | hudeditdisable
DO hudsave
DO hudmove <id> <x> <y>
DO hudorigin <ox> <oy>
DO hudaddelement id|type|label|verb|itemId|module|x|y
DO hudremove <id>
DO hudclear
DO hudexport
DO hudimport {…json…}
GET ITEMSEARCH <name substring>
GET ITEM <clientId>

Item name → sprite

GET ITEMSEARCH health potion
→ {"count":N,"hits":[{"id":266,"name":"health potion"}, …]}

Lua:

local hits = Client.findItemsByName("mana potion", 12)
for _, h in ipairs(hits) do
  print(h.id, h.name)
end

AI prompt block (paste into ChatGPT / Claude / Cursor)

You are designing an Opusbot .ophud.json overlay (schema version 1).
Rules:
- Only game item sprites via itemId (client appearance id). No PNG paths.
- Use types: toggle, action, icon, label, panel.
- Toggle verbs must be "SET <key> 1" so the client can flip 0/1.
- Known modules: cave → cave_enabled, target → enabled, heal → heal_enabled,
  loot → loot_enabled, spell → spell_enabled.
- Absolute x/y within the group; origin tl/tr/bl/br with ox/oy margins.
- Keep the first viewport clean: one row of module toggles is enough for Compact.
Return ONLY valid JSON matching the schema above.

Community sharing

1. Export from the HUD tab (or DO hudexport) → copy JSON.
2. Share the .ophud.json (Discord / pastebin).
3. Receiver: save as hud_layouts\<name>.ophud.json, then DO hudpreset <name> or Import.

Do not ship DLL code in shares — JSON only.

Advanced: OpusHUD.lua

For modals, multi-panel script HUDs, and ZeroBot-style chrome, load opusHUD.lua from the Scripts tab. Native Builder and OpusHUD can both run; they use different render paths (QML overlay vs GDI + ItemSprite).

See also: hud.md (Lua HUD.* API), config.md.