Arrange Your Windows

Drag a title bar to move a window and its bottom corner to resize it. Clicking or focusing a window brings it forward. Drag near an edge of the play area to preview docking at the top, bottom, left, or right; docked windows reserve space around the terminal. Multiple windows can share an edge in an ordered row or column. Drag a docked title bar away from its edge to make it float again.

Nearby floating windows show a snap preview and align their edges. They remain independent when you move them again. Floating windows fit inside the play area, keeping the command input and application controls accessible; saved arrangements refit when the browser becomes smaller.

The close button hides a window. Open Windows in the sidebar to show it again, hide another window, lock or unlock placement, or reset one or all layouts to script defaults. A lock prevents dragging and resizing. The panel also manages windows whose scripts hide their title bars.

Each window has a Background opacity slider in Windows: 0% is transparent and 100% is solid. It previews as you drag and saves independently for that window and MUD settings scope. Text remains fully visible. Your choice overrides the Script or package default; Reset restores that default.

For keyboard placement, focus the title bar and use arrow keys to move, or Alt plus an arrow to dock to that edge. Focus the resize control and use arrows to resize. Steps are 10 pixels, or 1 pixel while holding Shift. Press Escape to cancel a drag. Buttons and clickable content support keyboard activation.

Your position, dimensions, docking, order, visibility, and locks are saved with your account for the selected MUD settings scope. Saved choices override the script's initial placement; updating window content does not move it. Settings exports and revisions include these arrangements. Log history and window content are temporary.

Disabling a Script or its folder removes its live windows but keeps the saved arrangement for re-enabling. Removing a live window also keeps its arrangement. Mobile retains these settings but displays no desktop windows.

Enable the Party UI Package

Open Packages in the desktop sidebar and enable Party UI under BatMUD. It opens a live 3×3 party formation window with member names, HP/SP/EP, and status flags. It starts disabled and uses the party data supplied by your BatMUD connection. Until data arrives, it shows an empty formation.

Members outside the formation, or without a usable formation position, appear below the grid. Missing vitals are shown as unknown. The package reads structured BatClient data; it does not send commands or install triggers.

Leaving the party clears its old roster. Stepping out of formation keeps you listed below the grid until you leave or return to a formation position.

Full HP is green, SP is blue, and EP is yellow. Each bar gradually shifts toward bright red as it depletes. Cards keep their bars aligned even when member names or statuses differ; hover a shortened label to read its full text.

Drag, resize, dock, and lock it like any other window. Close hides it; use Open on its package card or Show in Windows to reopen it. Disabling the package removes the live window and keeps its saved layout. Enablement and placement are saved for the current MUD settings scope. The window is desktop-only.

Enable Buff Tracker

In Packages → Buff Tracker, enable the package to display active BatClient effects, sorted by soonest expiry. Countdown bars turn amber at the warning time and red in the final five seconds. An ended estimate stays labelled Awaiting removal until BatClient confirms that the effect has gone.

Open Options on the package card to change the warning time, hide effects by name, or exclude effects whose duration is unknown. A variable duration (timeLeft = -1) or an older snapshot without a receipt time is shown as Duration unknown. Buffs count down from the original update time across settings reloads and server switches.

Enable Communications

Enable Packages → Communications for one window with All, Party, Tells, and individual channel tabs. All contains every reported communication, including channels without their own tab. Tab switches preserve each log and its scroll position. Use the arrow, Home, and End keys while a tab is focused to switch tabs.

The package card's Options controls the All, Party, and Tells tabs, a comma-separated list of channel tabs, automatic channel discovery, timestamps for new messages, unread counts, and Auto-scroll. Auto-scroll follows new messages while you are at the bottom; scrolling up pauses it until you return to the bottom. Turn it off to hold your position even at the bottom. Up to 16 individual channel tabs are available. Options and window placement are saved for the current MUD settings scope and included in settings exports and revisions.

Routing uses BatClient code 10 with a chan_<channelname> argument. Party and tell/tells channel names feed their dedicated tabs; other names remain available in All and individual tabs. Messages remain visible in the main terminal. Untagged output is not guessed into a channel. Use the command line to reply. Outgoing tells reach the tell channel when BatMUD's set duplex_tell on setting is enabled; this package does not change that setting.

Channel and tell messages preserve their original ANSI foreground/background colours and supported text styles, using the same palette as the terminal. History is temporary and bounded: up to 1,000 messages and 120,000 characters are retained for rebuilding tabs; each visible log also obeys the shared limits below. Disabling the package, disconnecting, changing servers or accounts, or reloading the page clears its history. Closing only hides the window; incoming messages continue to accumulate while it is enabled. Both packages start disabled and show windows only on desktop.

Enable Realm Map

Enable Packages → Realm Map to open a desktop map window. It uses BatClient locations to show your character and party on the continent map. Use Focus to select a player, Follow to center on your movement, and landmark search to find a location. Drag the map to pan and use the mouse wheel or zoom controls to change scale.

Drag the title bar to arrange the window, resize it, or dock it beside the terminal. Close hides it; Open on its package card or Show in Windows reopens it. The window uses the shared desktop frame and its background opacity control; the map artwork, markers, and text remain visible. Placement and map preferences are saved for the current MUD settings scope. Disabling the package removes its live window and keeps those settings. Realm Map is desktop-only and reads location data without sending commands.

Create a Window

In Automation, add a Script, paste this code, compile, and enable it. Capture the reference at the Script's top level, then create and render the window inside onLoad().

local window = ui.window("example")

function onLoad()
  window:create({ title = "Example", width = 320, height = 180 })
  window:render({ type = "column", id = "root", style = { gap = 8 }, children = {
    { type = "text", id = "message", text = "Ready" },
    { type = "button", id = "hello", text = "Say hello", action = "hello" },
  } })
end

function onUI(event)
  if event.window == "example" and event.action == "hello" then
    window:update("message", { text = "Hello!" })
  end
end

ui.window(id) returns a reference owned by the Script containing it. IDs start with a letter and contain letters, digits, underscores, or hyphens, with at most 80 characters. Different Scripts can each have a window named example. One Script can capture several references with different IDs.

Lua reloads the enabled Script definitions for each invocation, reconstructing these references. The live window stays in place between calls. Capturing a reference has no visual effect, so it is allowed at the top level; calling create, render, or other methods there is blocked. Keep changing game data in temporary state or read the current structured data when a handler runs.

Frame Options

Pass an options table to window:create(options). Dimensions and coordinates are pixels; initial coordinates are relative to the play area. Existing user overrides take precedence over placement defaults.

Compose Content

Any node may include a plain-text tooltip of up to 1,024 characters, useful for labels shortened by a compact layout.

window:render(tree) accepts one root node. Each node has a type, an optional id, and optional style. Give elements stable, unique IDs within the window when you will update them. Keeping an ID and type preserves its element, focus, and log buffer during later renders. Logs keep your place when you scroll back and follow incoming lines when you are already at the bottom.

Containers and other nodes may also declare action and actionValue to become clickable. Action values are strings, numbers, or booleans. Mouse and keyboard activation call only the owning Script's onUI(event), with read-only event.window, event.element, event.action, and optional event.value.

Styles use validated values: color and background accept colors or theme names such as "cyan", "gold", "green", "muted", and "panel". Pixel properties are fontSize, gap, padding, borderRadius, width, height, and minHeight. Use align for start/center/end/stretch, justify for start/center/end/space-between/space-around, textAlign for left/center/right, fontWeight for normal/bold, and numeric grow for flexible space. Content is plain text; HTML and arbitrary CSS are not available.

Update Existing Windows

Export helpers that use captured references, then call those helpers from Lua triggers or aliases:

-- In the owning Script, alongside its onLoad():
local channels = ui.window("channels")

function AppendChannel(text)
  channels:append("messages", text)
end

-- In a separate Lua trigger, after that Script creates the log:
AppendChannel(line)

The helper still targets its source Script's window. Triggers and aliases update existing windows through these helpers; capture references and create frames in Scripts. Use a Lua trigger's pattern to route terminal text, or structured-data handlers to update numeric values.

Try the Optional Examples

Open each sample file and paste it into its own new Script. Compile and enable only the examples you want; nothing is installed automatically. Enable all three to see four windows at once, then arrange them using their frames or the Windows panel.

• Party window: nine invented members in a 3×3 grid with HP/SP gauges. Select a member by mouse or keyboard. A Lua alias can call DemoPartyHP(1, 45, 100) to update the first member.
• Buff window: three sample countdowns and a restart button. A Lua alias can call DemoHaste(120) to refresh one duration.
• Communications windows: separate channels and tells windows, each with its own scrolling log and clear button. Their Add sample buttons work without connecting to a MUD.

With the communications Script enabled, add a Lua trigger using regex ^\[demo-channel\]\s+(.+)$ and the example trigger code, DemoChannelLine(line). It copies matching incoming lines to the channels log. For a MUD's actual channel or tell format, choose the corresponding pattern and call DemoChannelLine(line) or DemoTellLine(line). For an offline check, make a Lua alias that calls DemoChannelLine("A sample from my alias").

These are reproducible demonstrations using synthetic data, not complete game trackers or communications parsers. BatMUD exposes party members under batclient.party.members, including hp, hpmax, placeX, and placeY; effects include timeLeft and active. Use the Inspector and BatMUD Variables to inspect what your session supplies. Read these snapshots in the corresponding BatClient handlers, or adapt onGMCP() to the packages your MUD provides. Update the relevant nodes when new data arrives.

Resource Limits

The desktop supports up to 32 live windows, including hidden windows. Each content tree supports 256 nodes and 12 levels of nesting. A text value or log append is limited to 6,000 characters. Each log keeps up to 1,000 lines, with additional text-size limits; older lines are discarded first. Up to 200 saved arrangements are retained per settings scope. Content changes are batched for display so frequent updates can share a browser frame.

Existing gauge and status APIs continue to provide their usual reactive widgets. Desktop windows add composable content and independent frames; they do not replace the main terminal or settings panels.