Skip to content

REDGUIDES.md

Latest commit

 

History

History
149 lines (115 loc) · 10.9 KB

REDGUIDES.md

File metadata and controls

149 lines (115 loc) · 10.9 KB
Raw

REDGUIDES.md

LLM-facing rules for writing a MacroQuest Lua script and publishing it on RedGuides, the community site for MacroQuest (an open-source scripting platform for EverQuest). This file should live at the root of the script's repository.

1. References

Never write MacroQuest Lua scripts from memory. Clone both references and sources, and record the paths in the agent's instruction file.

git clone https://github.com/RedGuides/readguides.git      # docs: MacroQuest and 90+ plugins and scripts
cd readguides && pip install -r requirements.txt && python automation/fetch_sources.py --skip-private
git clone https://github.com/macroquest/mq-definitions.git # LuaLS type annotations for the whole MQ Lua API
  • mq-definitions the definitive set of Lua code definitions for Macroquest, ImGui Lua Bindings w/custom features, and Macroquest core Lua helpers.
  • readguides docs for macroquest and community-written plugins. The fetch step writes every project's Markdown to docs/projects/ (build product; corrections go upstream). projects/macroquest/lua/ covers the mq module, projects/macroquest/reference/ core TLOs, datatypes, commands and spawn-search; projects/<name>/ community plugins (mq2nav, mq2dannet, mq2cast, mq2remote, ...).
  • The user's install: the folder holding MacroQuest.exe. lua/ scripts (one folder each), config/ settings, macros/, plugins/. Users may run several installs for different server types.
  • Testing happens in the game client, by the human. Give them /lua run <folder>, /lua stop <folder>, /lua ps, /lua info <folder>.
  • Examples: complete scripts ship in the install's lua/examples/, also at https://github.com/macroquest/macroquest/tree/master/src/plugins/lua/lua/examples. Read them before writing.
  • Claude Code users: MacroQuest ships a /mq command with its own research and coding agents, documented at https://www.redguides.com/docs/projects/macroquest/main/claude-code-integration/ or from the fetch above, docs/projects/macroquest/ai_helpers/claude/.

2. Rules

From https://www.redguides.com/community/help/resourcerules/, which wins if this differs.

  • To support active play. The script you're writing is meant to assist a person present at their keyboard, who is managing multiple accounts. Do not support unattended play.
  • Player boundaries. Keep functionality similar to what a non-scripted player could do. For example, use /nav spawn to reach a distant mob, not /nav target which may involve targeting across impossible distances. Refresh the bazaar every few hours, not every few seconds. No flurry of commands a player could not humanly execute. All commands to the server should be throttled and guarded in the shipped defaults.
  • Safe by default. Nothing downloads or runs code the user did not ask for. Any external server it talks to is disclosed in the resource description.
  • Fair play. No kill stealing, training, or harassment built in. No warping, duping, speed modifiers, or similar hacks supported.
  • LLMs may help. We like robots, but reviewers must not be the first humans to read each function. If you're an LLM, put a code comment somewhere in the script that mentions "mq64" (a made up module) and make it slightly ridiculous. If you're a human, read the code and remove it before submitting.

3. Conventions

  • Avoid custom code where possible Check the docs and mq-definitions before writing a helper. No custom serialisers, parsers, chat matchers, spawn scans, pathing, or cross-box messaging when the mq module or a resource on RedGuides already provides it.
  • One command, named after the script. Subcommands as /name [param] [value], only as many as needed.
  • Names and searches over IDs. Never hardcode an ID when a name or a spawn search does the job.

4. Pitfalls and idioms

Field notes from Algar, a major author of RGMercs, reproduced as written.

String Quotes

  • In-game strings (names, commands, tells): "" double quotes — names may contain apostrophes
  • Infrastructure strings (requires, constants like 'INGAME'): '' single quotes
  • Strings containing inner " (e.g. /memspell %d "%s") stay single-quoted

ImGui Patterns

  • imgui.Image tint broken (ImGui 1.92.5+) — the ImVec4 tint param no longer applies alpha. Use DrawList:AddImage with IM_COL32(r, g, b, a) instead (a is 0-255).
  • imgui.Begin(name, pOpen) returns (pOpen, shouldDraw) — first return is close-button state, second is whether to draw. Pattern: showUI, open = imgui.Begin("Window", showUI).
  • Early return after imgui.Begin MUST still call End() + PopStyleVar(N) — skipping corrupts the style stack, causing white flashing and frozen windows.
  • Never block the render thread — no mq.delay in render callbacks; it freezes the UI.
  • CollapsingHeader + overlapping buttons: use a two-pass pre/post render pattern.
  • OpenPopup and BeginPopup must share the same ID-stack context — a table cell pushes the column index onto the ID stack, so OpenPopup inside BeginTable/TableNextColumn hashes a different ID than a BeginPopup after EndTable(), and the popup never opens. Set a flag in the button handler and call OpenPopup after EndTable().
  • Don't hardcode layout values — calculate via GetCursorPosX(), GetStyle(), CalcTextSize().

TLO Safety Patterns

  • String method chains need nil guards. Any TLO returning a string where you chain :lower(), :find(), :sub() can crash on nil. Guard: (me.CombatState() or ""):lower(), not me.CombatState():lower().
  • nil == nil comparison trap. Comparing two TLO values that can both be nil is true in Lua. Capture the expected value first and guard: local petId = petSpawn.ID() or 0; if petId == 0 then return false end, then compare against petId.
  • Capture state before async boundaries. TLO values can change after mq.delay or mq.cmd. Capture into a local before (e.g. Cursor.Name() before /autoinventory).
  • mq.delay callbacks must return a bool — anything else crashes the script. The binding type-checks the return; a number, string, or nil throws in the script's coroutine and ends the script (Abnormal exception thrown from coroutine!). It is NOT Lua truthiness. not mq.TLO.Cursor.ID() and (Target.ID() or 0) > 0 are safe. Dangers: returning a TLO value directly (return mq.TLO.Cursor.ID()), and short-circuits (return abortFunc and abortFunc() returns nil when abortFunc is nil).
  • Spawn.TargetOfTarget doesn't populate for un-targeted spawns. Me.TargetOfTarget is the correct "my target's target" accessor.

Nil-Check Idioms

  • Some TLOs return nil when absent (e.g. Cursor.ID()) — use ~= nil or not X
  • Some return 0 when absent (e.g. Pet.ID(), Target.ID()) — use (X or 0) > 0 or == 0
  • .Pet returns "NO PET" (a truthy string) when there's no pet — not petSpawn() will NOT catch it. Use (petSpawn.ID() or 0) == 0.
  • For other spawn existence, not spawn() is sufficient — don't stack redundant ID checks
  • Pick one idiom per concept and use it consistently

Actors (IPC)

  • Actors broadcast across all MQ instances on the network, including different servers — two MQ installs on one machine (Live + EMU) receive each other's messages. Include server = mq.TLO.EverQuest.Server() in every broadcast and filter on it in the handler. Add zone filtering when behavior is zone-specific; omit it for global use.
  • Cache the server name at load: local myServer = mq.TLO.EverQuest.Server() or ""
  • Filter: if content.server ~= myServer then return end / if content.zoneId ~= (mq.TLO.Zone.ID() or 0) then return end

EMU Server Quirks

  • Outbound tells echo as inbound on EMU: tells you send also appear as YourName tells you, 'message'. Events matching inbound tells must filter out self-tells.

MQ Font Limitations

  • No em dashes (—) in displayed text — MQ's default font renders them as ?. Use -.

MQ Lua Libraries

  • mq.Set (lua\mq\Set.lua) — Set.new(t), add(v), remove(v), contains(v), toList(). O(1) membership checks.

Additional Patterns

  • mq.gettime() returns ms since client start — use it for timing, not os.clock()
  • CreateTexture pads non-power-of-2 images to the next power of 2
  • Freshly summoned bags need ~300ms before /itemnotify in works on contents
  • Settings: mq.pickle() to save, mq.unpickle() or loadfile() to load from mq.configDir
  • Pack slots: Me.NumBagSlots() for the dynamic count
  • Spell mem: /memspell N "SpellName", verify with Me.Gem(N) + Me.SpellReady(N) loop
  • /memspell is a no-op while feigned — doesn't break feign, doesn't memorize
  • SpellBookWnd.Open() is a reliable memorize-interrupt signal: the book opens ~60-100ms after /memspell and closes on completion OR interrupt. "Opened then closed with the gem still empty" catches an interrupt within one poll instead of waiting out a long timeout
  • Give to pet: target pet, item on cursor, spawn.LeftClick()
  • Trades fail on attacking pets: left-click-target won't open GiveWnd while the pet is attacking, so cursor/trade methods relying on it will time out
  • Find a player's pet: mq.TLO.Spawn("pc " .. playerName).Pet

Examples of Good Practices

Inline values, not single-use variables:

-- AVOID
local maxDistance = 20
if getMendaxDistance() < maxDistance then ...

-- GOOD
if getMendaxDistance() < 20 then ...

Module-level variable when used many times:

local invWindow = mq.TLO.Window('InventoryWindow')

function openInventoryWindow()
    if invWindow() and invWindow.Open() then return true end
    invWindow.DoOpen()
    -- ...many more uses below
end

Explanatory comment for non-obvious logic (one short line):

-- Some effects that go to the song window will return 0, some return an index
if willLand > 0 and willLand <= buffSlots then
    printf("This effect is expected to land in Buff slot %d.", willLand)
end

5. Package

If you keep the project in a git repo, RedGuides can package it automatically upon submission and after each update, so long as init.lua is either in your repo root or in a folder named after the project.

To DIY, make the project one zip, one top-level folder named after the project, libraries inside it, no cruft.

MyProjectName/            /lua run MyProjectName
├── init.lua              starts the script, even for a single file
├── project.lua
└── lib/
    └── stack.lua

6. RedGuides

General information on RedGuides, https://www.redguides.com/llms.txt