Legion-Scripting

Legion Scripting

TazUO has implemented a scripting engine directly into the client.

You can access Legion Scripting by going to Top menu -> Legion Script

Introduction

Legion Scripting setup guide

Legion API

Legion Script Recording

Legion Script Documentation.

Public Script Library set up here for people to contribute to.

ZIP Script Packages — bundle a script and its assets into a single .zip.

Running scripts from a hotkey

You can bind a Legion script directly to a hotkey. Right-click the script and choose Set Hotkey, then press the key combination you want. The binding is saved per script path and persists globally (across characters), and pressing the key toggles that script on and off. See Hotkeys.

You can also drive a script from an Action Bar Script slot, which toggles the script and highlights green while it runs.

The Script Manager window remembers its size and position and restores them when reopened.

Recent API additions

API.Virtue("justice") — the virtue API now supports justice in addition to honor, sacrifice, and valor.
API.OpenQuestLog() — opens the quest log gump.
API.OpenHelp() — opens the help menu.
API.Pathfind(x, y, z, distance, wait, timeout, run) and API.PathfindEntity(entity, distance, wait, timeout, run) — a new run parameter controls whether the character runs (default true) or walks along the path.
.IsParalyzed — a boolean property on mobile objects.
API.UpdateCooldown(name, maxValue, currentValue), API.RestartCooldown(name), API.DeleteCooldown(name) and API.CooldownExists(name) — manage cooldown bars created with API.CreateCooldownBar.
API.Gumps.CreateGumpTextBox(text, width, height, multiline, fontSize) — a new fontSize parameter (default 20) sizes the TTF font of the text input field, and ApiUiTtfTextInputField.FontSize exposes it as a property.
API.ActiveSpells(), API.ActiveSpellNames() and API.IsSpellActive(spell) — see which toggle spells/moves are currently active (the same ones action bars highlight).
API.ListRunningScripts() and API.IsScriptRunning(path). API.PlayScript, API.StopScript and API.ToggleScript now match scripts by their path relative to the LegionScripts folder, so scripts that share a file name are no longer ambiguous.
API.ContextMenu(serial, entry) — a string-based overload that selects a context menu entry by its text.
SetTooltip(text), SetEntityTooltip(serial) and ClearTooltip() on the base UI control, so scripts can attach plain-text or entity-property tooltips to any control. Setting a tooltip enables mouse input automatically, and a dedicated SetAcceptMouseInput(enabled) is also available.
Highlight(hue) on game objects and mobiles — sets a highlight hue (remembering the original so it can be restored with Highlight(None)); on mobiles it also recolors all equipped items.
API.GetAllMobiles(graphic, distance, notoriety, sortby) — a new sortby parameter (case-insensitive) orders the result by "Distance" (default), "Hits" (current hits, lowest first), or "MaxHits". It also accepts optional filters, each ignored unless supplied: name (case-insensitive partial match), graphics, hues, minDistance, isHuman, isFemale, isGhost (dead mobiles), isFriend (friends list), poisoned, paralyzed, and hasLineOfSight; the boolean ones accept True/False to include or exclude.
API.TargetRel(xOffset, yOffset, tilesOnly=True) — targets the topmost visible object (entity, static/multi, or land) at a tile offset from the player, resolved the same way a click would. With tilesOnly true (the default) entities are ignored.
Target() and TargetRel(xOffset, yOffset, tilesOnly=True) on entity objects — target the entity itself, or a tile relative to its position.
API.SetLastTarget(serial=None, x=None, y=None, z=None, graphic=None) — overrides the client’s last target. Pass an entity serial, or a location (x, y, z) for a land tile; include graphic to set it as a static instead.
API.TargetTileRel(xOffset, yOffset, graphic, tilesOnly=True) — now targets the highest non-land object at the location (instead of the base land tile) and accepts tilesOnly (default true) to ignore entities.
API.GetSpellsInSpellbook(serial) — returns the names of all spells in a spellbook, given the spellbook’s serial.
API.Gumps.CreateGumpRenderedMapArea(...) — builds a rendered area of the world map inside a gump (ApiUiRenderedMapArea).
API.Pause() — the previous hard 30-second pause limit was removed.
API.IsKeyPressed("CTRL+SHIFT+F1") — returns whether the given key or key combination (modifiers + key) is currently held down.
API.RequestHotkey(prompt, timeout) — pops up the in-game hotkey capture window and returns the chosen key combination as a string (e.g. "CTRL+SHIFT+F1"), ready to pass straight to API.OnHotKey() or API.IsKeyPressed(). Only keyboard bindings are accepted, and it returns an empty string if the window is cancelled or the timeout elapses.
ApiItem.GetContainerGump() — now reliably finds the container window for a ground item whose overhead name is also showing (previously the name-overhead gump could be returned instead of the container window).

Script warnings

TazUO prints warnings to the journal/chat when a script is likely to misbehave:

Unbounded while loop — starting a script that contains while True, while (true) or while(true) warns you, because a pure CPU loop never blocks and cannot be interrupted by API.StopScript. Use while API.StopRequested: (Python) or while (API.StopRequested) (C#) instead.
Script did not stop — if a script ignores the stop request (e.g. it is stuck in a loop), it is detached after a short grace period and keeps running in the background. It is inert (its API is disposed) and exits when the client closes, but it cannot be restarted until that background thread exits.
Deprecated gump helpers — the legacy top-level gump methods (API.CreateGump, API.CreateGumpButton, API.CreateGumpLabel, API.AddGump, API.AddControlOnClick, and the rest of the API.Create* family) are deprecated and will be removed after 11-1-26. Using them now prints a warning. Move to the equivalent API.Gumps.* methods (e.g. API.Gumps.CreateGumpButton).