VellumFE

Play GemStone IV in a client you can shape around your character — and be hunting in about five minutes.

Why you’d use it

You already know the game. What you want is a screen that tells you what you need mid-swing: vitals where your eye already goes, spells and effects visible without a SPELL check, thoughts and combat in their own windows instead of scrolling past you in one column.

VellumFE gives you that on one core with five ways to play — a terminal client, a native desktop window, your phone’s browser, an Android app, and an iPhone app. The same character, the same highlights, the same settings, whether you’re at your desk or on a couch.

And you configure all of it inside the client. Every feature ships an editor. Hand-editing a config file is a thing you may do, not a thing you have to do.

Get playing

Pick how you want to start. All three paths reach the same client.

vellum-fe --port 8000 --character YourCharacter

vellum-fe --direct --account ACCOUNT --character YourCharacter --game prime

What you get

• Windows you place. Drag any window where you want it, size it, and it stays there. Add windows for thoughts, deaths, ESP, or any game stream you care about — see Text Windows.
• Highlights that do more than color. A rule can recolor a line, play a sound, rumble your controller, replace the text, send the line to a different window, or hide it outright. See Set up highlights and sound alerts.
• Connect your way. Through Lich as a detachable client, or directly to play.net with no Lich running.
• 36 built-in themes, ten of them accessibility variants — high-contrast (light and dark), deuteranopia, protanopia, tritanopia, monochrome, low-blue-light, photophobia, ADHD-focus, and reduced-motion.
• Speech built in. Windows can read new lines aloud, so a thought or a death reaches you without a glance. See Speech.
• Rebindable keys, hotbars of command buttons, and gamepad support.
• Graphics on the desktop — skins, per-window frames, an injury doll, hand icons — with the terminal and phone rendering the same information as text.

Where your settings live

Everything lands under ~/.vellum-fe. Two layers matter:

• global/ — settings shared by every character: highlights, keybinds, colors, hotbars, skins and images.
• profiles/<character>/ — that one character’s overrides of any of the above, plus their layout, history, and log.

Point the whole thing somewhere else with --data-dir or the VELLUM_FE_DIR environment variable — handy for a portable install on a stick.

You change all of this in-app: type .settings for the settings editor, or .help for every command. The full list is in the Command Reference.

Where to go next

• Getting Started — download, launcher, first connection.
• How-To Guides — build a hunting layout, make vitals flash when you’re hurt, wire a combat hotbar.
• Frontends — what each of the five can and can’t do.
• Widgets — every window type, one page each.

Getting help

• Discord: discord.gg/6nKhWRTkSN — help, layout showcases, beta testing, release announcements.
• GitHub Issues: github.com/Nisugi/VellumFE/issues
• In-game: find us on amunet.

Getting Started

Three short pages take you from a downloaded archive to a character standing in Wehnimer’s Landing.

What this section does for you

You have the game and you probably have Lich. What you don’t have yet is this client on your machine, pointed at your character. That’s the whole job of this section, and it’s three steps:

1. Installation — get the right archive for your platform (or the Android APK), extract it, and know where the binary should live. Building from source is here too, if you’d rather.
2. The Launcher — the double-click path. Save a connection per character, keep the password in your OS credential store, and start a session with one click. Launch several to play several characters at once.
3. First Launch — the command-line path, choosing a frontend, and a tour of what’s on screen once you’re connected.

Read them in order the first time. After that, the Launcher page is the only one you’ll come back to.

Before you start

• A way into the game. Either Lich running as a detachable client, or your play.net account details for a direct connection. VellumFE does both; you don’t have to pick now.
• For the terminal frontend, a terminal with 256-color or true-color support. Windows Terminal, iTerm2, Kitty, Alacritty and modern GNOME Terminal all qualify.
• For the desktop GUI, nothing extra — it’s a native window.
• For Android, version 8.0 or newer. On Android 8 and 9, update Chrome first: it provides the app’s rendering engine there.

Get connected

If you’d rather not read three pages first, this is the short version.

vellum-fe --port 8000 --character YourCharacter

vellum-fe --direct --account ACCOUNT --character YourCharacter --game prime

Once you’re in

Two commands are worth knowing on day one:

• .help lists every dot-command, grouped by what it does.
• .settings opens the settings editor. In the Desktop GUI you can also use the Settings button in the top toolbar, which stays open while you change things.

⚠️ .quit disconnects but leaves the window open — run it again to exit. .exit closes VellumFE outright. Turn off Keep Open On Quit in Settings ▸ UI if you’d rather .quit close immediately.

⚠️ Ctrl+C means different things in different frontends. In the terminal it copies your selected text. In the Desktop GUI it quits. To leave a terminal session, use .quit or .exit.

Then what

• How-To Guides — the fastest route to a screen you like: build a hunting layout, make your health bar flash when low, set up highlights and sounds.
• Frontends — what each of the five can do.
• Command Reference — the full dot-command list.

See also

• Introduction — what VellumFE is and where its config lives
• The Launcher — saved connections and keyring passwords in detail
• First Launch — every command-line flag, explained

Installing VellumFE

Get a working vellum-fe on your machine, past your operating system’s defenses, in about two minutes.

What it’s for

You want to be in Icemule by tonight, not fighting a download. VellumFE ships as a single self-contained binary per platform — no installer, no runtime to install, no Ruby, no OpenSSL. Windows and macOS releases are code-signed, so your OS should let them run without an argument. This page gets the file onto your disk and proves it works; The Launcher gets you into the game.

Set it up

Every desktop release lives on the GitHub Releases page. This is a platform split rather than a frontend split — the same binary contains the terminal frontend, the desktop GUI, and the web server, and which one you get is decided at launch, not at download.

Common setups

Verify what you downloaded

Every release publishes SHA256SUMS.txt alongside the assets. Compare before you run anything:

sha256sum -c SHA256SUMS.txt --ignore-missing

On Windows PowerShell, Get-FileHash vellum-fe-windows-x86_64.zip -Algorithm SHA256 prints a hash to match by eye against the line in SHA256SUMS.txt.

→ You see vellum-fe-windows-x86_64.zip: OK (or a matching hash), which means the archive is byte-for-byte the one CI built and signed.

Keep configs somewhere other than your home directory

VellumFE writes everything it owns — settings, layouts, highlights, skins, logs, saved connections — under ~/.vellum-fe/. It is created on first run. To put that elsewhere (a synced folder, a portable drive), point VELLUM_FE_DIR at the location before starting:

VELLUM_FE_DIR=/mnt/sync/vellum vellum-fe

The same directory can also be set per connection, in the Launcher’s Advanced fold under Data directory — handy when one character’s setup should live apart from the rest.

→ Start VellumFE and the folder you named fills with launcher.toml, global/, profiles/, and vellum-fe.log instead of your home directory.

Build it yourself

You need a recent stable Rust toolchain — CI builds on latest stable.

git clone https://github.com/Nisugi/VellumFE.git
cd VellumFE
cargo build --release

The binary lands at target/release/vellum-fe. Direct eAccess login uses your OS’s native TLS stack on Windows (SChannel) and macOS (Security.framework), so there is nothing extra to install; Linux compiles a bundled OpenSSL during the build, which needs Perl — present on effectively every distro.

→ ./target/release/vellum-fe --version prints the version you just built.

Tips & gotchas

⚠️ A bare vellum-fe opens the Launcher; a vellum-fe with any flag does not. The no-arguments case is what double-clicking produces, and it routes to the graphical launcher. The moment you pass even one flag you are on the command-line path, and that path defaults to the terminal frontend, not the GUI — add --frontend gui if you wanted a window. This catches almost everyone once. See The Launcher.

⚠️ Extract the archive before running it. Windows will happily run an exe from inside a zip preview, then fail confusingly when the process tries to spawn a session copy of itself.

• Nothing prints to your terminal. VellumFE logs to a file, because a terminal UI cannot share stdout with a log. Diagnostics live in ~/.vellum-fe/vellum-fe.log, including panics. Raise the level with RUST_LOG=debug.
• Moving the binary is fine; moving it after saving connections is fine too. Connections are stored in ~/.vellum-fe/, not next to the exe. The Launcher spawns sessions using its own current path, so a moved binary keeps working as long as you launch the moved copy.
• The apps keep their own connections; they don’t import your desktop ones. Your launcher.toml stays on the desktop, and the phone saves its logins on the device. The apps can pair with a running desktop session (Characters ▸ Scan QR to add), and a browser can act as a second screen without installing anything — two routes for two jobs, both in Put VellumFE on your phone.

See also

• The Launcher — saved connections and one-click sessions
• First Launch — connecting through Lich or directly
• Android App · iOS App
• Desktop GUI · Terminal (TUI)

The Launcher

Double-click, click Launch, you’re in — with your password in the OS credential store instead of your shell history.

What it’s for

You play more than one character, and you would rather not retype an eAccess account, a game world, and a port every time. The Launcher keeps each of those as a named connection you click once. Passwords go into Windows Credential Manager, the macOS Keychain, or the Linux secret service — never into a file, never onto a command line where every process on the machine can read it. Each Launch starts a separate session process, so running four characters at once is four clicks.

Set it up

The Launcher is a desktop window, so this is a frontend split: it belongs to the desktop GUI, and the terminal and mobile tabs say what you use instead.

vellum-fe --launch-profile "Nisugi hunting"

Common setups

One account, several characters, all at once

Make a connection per character, all pointing at the same Account:

1. ➕ New connection → Name Nisugi, Direct, Account MYACCT, Password once, Save password ticked, Game GemStone IV, Character Nisugi. Save.
2. ➕ New connection → Name Alt, same Account MYACCT, leave Password blank, Save password still ticked, Character Alt. Save.
3. Click Launch on both rows.

The saved password is keyed by account, not by connection, so the second one reuses the first’s stored password without you typing it again. Because each Launch spawns its own process, both characters run side by side with independent layouts.

→ Two session windows are open, each showing its own character, and the Launcher’s status line shows Launched Alt from the last click.

A connection that starts in the terminal instead

The Launcher defaults everything to the desktop GUI. To make one connection open the text interface:

1. Edit the connection.
2. Open the Advanced fold.
3. Set Frontend to Terminal.
4. While you are there, set Color mode to direct for true-color terminals, and tick Palette ▸ Set up on startup if you use slot mode on a 256-color terminal. These two rows only appear when Frontend is Terminal.
5. Save, then Launch.

→ A console window titled VellumFE opens running the terminal frontend, and it remembers its size and position the next time you launch that connection.

Serve this session to your phone

In the connection’s Advanced fold:

1. Tick Web dashboard ▸ Enable on port and leave 8484.
2. Set Bind address to 0.0.0.0 — the hint beside it reads 0.0.0.0 = allow LAN devices. Leaving it at 127.0.0.1 restricts the server to the machine it runs on.
3. Save, Launch, then browse to http://<your-pc-ip>:8484/play on the phone.

→ The phone shows the live session, driven by the same core the desktop window is rendering.

Tips & gotchas

⚠️ The Launcher defaults to the GUI; a hand-typed command line defaults to the TUI. A new connection is created with Frontend: GUI, but vellum-fe invoked with flags uses --frontend tui unless you say otherwise. The same character launched two ways can land in two different interfaces. Set it explicitly under Advanced ▸ Frontend, or pass --frontend gui.

⚠️ Deleting a connection can delete the saved password with it. The confirmation window Delete profile? says so: the keyring entry is removed unless another connection still uses the same account. Deleting your only MYACCT connection means the next one has to re-enter the password.

• “Password was NOT stored” in red means the credential store refused the write — common on headless Linux, inside WSL, or under a bare window manager with no secret service running. The connection still saves and still launches; you are asked for the password each time. Install a secret service (GNOME Keyring, KWallet) to fix it.
• A red line about launcher.toml on startup means the file could not be parsed. The Launcher deliberately shows the error rather than starting with an empty list, because saving from an empty list would overwrite your connections. Fix the file before saving anything.
• Connection names cannot contain " or %. The Launcher rejects them at save time, because a terminal session’s name travels through a Windows cmd command line where neither can be passed safely.
• Renaming a connection does not duplicate it. The edit form tracks the name you started with and replaces that entry.
• The account name is not shown in the list. Each row’s summary is <character> @ <game> on purpose — the list is on screen constantly, and in screenshots. The account stays inside the edit form.
• Nothing in the list? “No saved connections yet” with Create one to get started is the empty state, not an error.

The other launcher: cold-starting Lich over SSH

There is a second, separate feature with a confusingly similar name. The SSH Launcher does not manage connections — it starts a headless Lich on your home PC from wherever you are, over an existing WireGuard or Tailscale tunnel, then attaches to it. Use it when the machine that runs Lich is not the machine you are sitting at.

It lives inside a running session, not in the Launcher window:

• Type .launcher (or bare .launch) in the command input to open the SSH Launcher panel.
• Fill in Host (tunnel address), User, SSH port, Remote OS, optionally Attach host, and the Launch command template — where {character}, {game} and {port} are substituted per character.
• Click Generate new key, then Copy public key and paste that one line into ~/.ssh/authorized_keys on the home PC. The private half goes to your OS secure store; the indicator changes to ✓ key stored. Expand Harden it (recommended) to see the restrict,command="…" prefix that limits a leaked key to launching the game and nothing else.
• Add each character under Characters with its game token and its own detachable-client Port, then Save.
• Run it with .launch <character>.

If a Lich is already listening on that port, the flow skips the SSH step entirely and attaches straight away. If not, it SSHes in, spawns Lich detached so it survives the SSH channel closing, then polls the port. The open port — not the spawn’s exit code — is what counts as success, so a message like “Launched Lich but 100.64.0.5:8001 never opened” means the command template or the character name is wrong, and the spawner’s own output is appended to tell you which. On a first connection the host key’s fingerprint is pinned; if a pinned key ever changes, the launch is refused outright rather than prompting.

→ .launch Nisugi reports progress in the session and ends attached to the freshly started Lich.

See also

• Installing VellumFE — getting the binary in the first place
• First Launch — connecting with flags instead of connections
• Desktop GUI · Terminal (TUI)
• Put VellumFE on your phone — the web dashboard

First Launch

Get your character on screen from a command line — through Lich, or straight to play.net — and know what you’re looking at when the room description lands.

What it’s for

You already know how you connect: Lich on a port, or account-and-password to the game. This page is the command-line route for both, so you can put VellumFE behind a Lich launcher entry, a shell alias, or a shortcut and stop thinking about it. The last section is a tour of the screen you land on — which window is which, where you type, how you scroll back to the thing that killed you.

If you’d rather click a saved connection than type flags, use the Launcher; it covers the same ground with stored passwords. Running vellum-fe with no arguments at all opens it.

⚠️ The same character, started two ways, lands in two different interfaces. A hand-typed command line defaults to the terminal UI; a saved Launcher connection defaults to the GUI. Pass --frontend gui (or -f gui) to make the command line match.

Set it up

Common setups

Recipe 1 — Make Lich launch VellumFE for you

In Lich’s launcher, add VellumFE as a custom frontend and set the command to:

path\to\vellum-fe.exe --frontend gui --port %port% --key %key%

Lich substitutes %port% with the port it opened and %key% with the login key it received from the game; --key hands that key straight to the game server, so you are never asked for credentials. Drop --frontend gui from the line if you want the terminal UI.

Outcome: picking your character in Lich opens VellumFE already in the room you logged out in — no password prompt, no port to copy.

Recipe 2 — One set of settings, several characters

--character is your login name. --profile is your config name, and it picks which folder under ~/.vellum-fe/profiles/ holds your layout, highlights, keybinds, and hotbars. When you leave --profile off, it silently copies --character — which is why every new character starts with a blank-slate layout.

Point three characters at one shared config folder:

vellum-fe --port 8000 --character Rysk    --profile hunting
vellum-fe --port 8000 --character Nisugi  --profile hunting
vellum-fe --port 8000 --character Vellum  --profile hunting

Outcome: all three log in under their own names, and all three read and write ~/.vellum-fe/profiles/hunting/ — so a layout you save on one is there when you log in as the next.

Tips & gotchas

⚠️ In the terminal UI, Ctrl+C copies your selection — it does not quit. In the GUI, Ctrl+C quits. To leave either one, type .quit. Note that .quit disconnects but keeps the window open — run it again, or use .exit, to close the client outright.

⚠️ --profile is not --character. Omitting --profile makes your config folder follow your character name. If you rename the flag you pass, you land in a different folder and your layout looks lost. It is not lost — it is under the old profile name in ~/.vellum-fe/profiles/.

⚠️ The DragonRealms world names are spelled differently in two places. On the command line they are hyphenated: dr, dr-platinum, dr-fallen, dr-test. In config.toml and in saved Launcher connections they are not: dr, drplatinum, drfallen, drtest. A misspelled value in config.toml does not error — it falls back to GemStone IV Prime, and you find out at the character list.

The tour — what you’re looking at once you’re in. The default layout places six windows:

Everything else — vitals bars, a compass, an injury doll, hotbars — is a window you add yourself. In the GUI that’s the Windows button in the top toolbar, which opens a stay-open catalog with a checkbox per window. In the terminal, type .addwindow with no arguments to get a picker. See Widgets.

Where things are. Your command line is the bottom row of the screen; press Enter to send, Up and Down to walk back through history, and Ctrl+R to repeat your last command. Scrolling back is PageUp / PageDown a page at a time and Alt+PageUp / Alt+PageDown a line at a time in the terminal, or the mouse wheel and scrollbar in the GUI. Tab moves focus between windows in the terminal; in the GUI you click the window you want.

Getting help. Anything you type starting with a dot is a client command, not game input. Three worth knowing on day one:

• .help — the full dot-command list, grouped by section
• .menu — the main menu tree (the GUI also has toolbar hubs)
• .settings — the in-app settings editor

Copying text. In the terminal, drag-select and the text is on your clipboard the moment you release. In the GUI, drag-select (double-click for a word, triple for a line) and press Ctrl+C. Copy is plain text in both, deliberately.

Direct mode and TLS. Direct connections use your operating system’s own TLS stack, so Windows and macOS need nothing extra. On Linux, see Installation.

See also

• Installation — getting the binary, and Linux TLS notes
• The Launcher — saved connections, stored passwords, per-connection frontend
• Command Reference — every dot-command
• keybinds.toml — rebinding anything in the tour above
• Widgets — the windows you add to the default six

How-To Guides

Complete tasks, start to finish — each one ends with something working on your screen.

The rest of this manual is organized by thing: a page per widget, a page per frontend, a page per config file. That is the right shape when you know what you’re looking for and the wrong shape when you don’t. These guides are organized by goal instead.

Each one walks a single job end to end, and each one crosses features on the way. Building a hunting layout touches the window catalog, five shell zones, three widget types, and a saved layout file — four manual sections you’d otherwise have to find and sequence yourself. The guide sequences them for you.

They teach a path. The feature pages own the facts, so every step links back to the page behind it — when you want the full field list for a widget, follow the link rather than expecting a guide to repeat it.

The guides

Build a hunting layout Reach for this when your default screen is still the six windows it shipped with and you want the screen you’ll actually fight in — vitals, roundtime, targets, and a compass, saved so you can get it back.

Make your health bar shout when you’re hurt Reach for this when you’ve died to a health bar you didn’t look at, and you want your screen to demand attention instead of waiting for it. (Nothing blinks — the guide explains what actually happens instead.)

Set up highlights and sound alerts Reach for this when the line that matters — your bounty creature, a bleeder, someone saying your name — scrolls past in the same color as everything else.

Put VellumFE on your phone Reach for this when you want your character on a second screen beside the keyboard, or in your hand away from the desk.

Wire a hotbar for combat Reach for this when you’re retyping the same attack, stance, and spell-prep sequence every hunt and want them as buttons that gray out while they’re on cooldown.

Before any of them

Every guide assumes you are connected and looking at a session. If you are not there yet, start with Installation and First Launch, then come back.

Each guide is tabbed by frontend — Desktop GUI, Terminal (TUI), Mobile — and the tabs move together across the whole page, so picking your frontend once at the top carries through to the end. Where a frontend genuinely can’t do the task, its tab says so plainly and points at what it does instead.

See also

• Frontends — all five, and how to choose between them
• Widgets — the reference for everything a window can hold
• Customization — layouts, highlights, keybinds, themes, skins
• Command Reference — every dot-command in one table

Build a hunting layout

By the end you’ll have a combat screen — vitals, roundtime, targets, compass, hands — saved under a name you can load on any character, in either desktop frontend.

What you’ll build

VellumFE ships a deliberately plain screen. The default layout is six windows: main, command_input, thoughts, speech, room, and society. That is a reading screen. This guide turns it into a fighting screen.

You’ll finish with your story text still front and center, a vitals bar and a roundtime timer across the top where you can read them without leaving the text, and a right-hand column carrying targets, a compass, and your hands. Then you’ll save it as hunting, which makes it reproducible — on your next character, after a bad drag, or on the terminal.

Before you start

• You’re connected and looking at a session. If not, see First Launch.
• Two of these windows are GemStone IV only. minivitals and Reserve are gated to GS4 and won’t appear in the catalog on a DragonRealms character. Use the individual Health, Mana, Stamina, and Spirit bars there instead — they’re ungated, and step 2 tells you how.
• Nothing here needs Lich, and nothing here edits a file by hand.

Steps

.addwindow minivitals minivitals 0 0 40 3
.addwindow roundtime countdown 40 0 14 3
.addwindow targets targets 92 3 28 12
.addwindow compass compass 92 15 28 7
.addwindow left hand 92 22 28 3
.addwindow right hand 92 25 28 3

.addwindow health progress 0 0 28 3
.addwindow mana progress 28 0 28 3
.addwindow stamina progress 56 0 28 3
.addwindow spirit progress 84 0 28 3

Make it yours

If you fight in melee, trade the compass for the injury doll. A caster watches exits and mana; a melee character watches wounds. Untick Compass in the catalog and tick Injuries, sending it to Right Bar. The GUI draws it as a body diagram colored by wound and scar severity, and with a skin that ships doll art you can place the wound dots yourself through Calibrate doll… in the doll window’s right-click section. In the TUI, swap the .addwindow compass line for .addwindow injuries injury_doll 92 15 28 8.

You’ll see: a body diagram that colors a limb the moment you take a wound there, instead of you parsing the wound line out of scrolling text.

If you’re a spellcaster, add the effects trio to a Left Bar. Turn on the left zone (Zones ▸ Left Bar, or .leftbar on) and send Buffs, Debuffs, and Cooldowns there — three separate catalog rows, each an active-effects window carrying one category. Keeping them apart from the right column means your defensive spell timers never compete with your target list for the same glance.

You’ll see: three stacked lists counting down independently, so a lapsing 401 is visible before it drops rather than after.

If your terminal is small, put your side windows in a tabbed window instead of a column. Four windows down a 40-column right bar leaves nothing for text. Add one tabbedtext window and give it the streams you’d have split out, then switch tabs with a click. In the GUI, the tab list is Edit tabs… in the window’s own right-click section; in the TUI it’s the .editwindow form.

You’ll see: one window’s worth of screen doing four windows’ work, at the cost of only seeing one at a time.

When it doesn’t work

A window you ticked in the catalog doesn’t appear anywhere. Check its zone. If the zone is one you have switched off, the window is real and placed but the strip holding it isn’t drawn. Open Zones and turn that zone on, or move the window with right-click ▸ Arrange ▸ Move to ▸ Center.

You can’t find a row in the catalog. Two causes. The categories start collapsed — click a category heading to expand it before concluding the row is absent. And rows are sorted and labeled by title, so RT files under R, not under “roundtime” — search for what the window is called on screen, not what you’d type.

minivitals or Reserve is genuinely missing. Both are GemStone IV only and are filtered out of the catalog on a DragonRealms character. That’s gating working correctly, not a bug. Use the individual Health / Mana / Stamina / Spirit bars.

.addwindow compass prints a usage line and adds nothing. The command takes either no arguments (which opens the picker) or all six — name, type, x, y, width, and optionally height. A partial command falls through to the usage message. Type .addwindow alone and pick from the list instead.

A .addwindow window landed at the top-left corner in the wrong size. Numbers that fail to parse fall back silently rather than erroring — x and y to 0, width to 40, height to 10. Check for a stray character in the coordinates, delete it with .deletewindow <name>, and retype the line.

Dragging a TUI window’s middle selects text instead of moving it. That’s correct behavior: the TUI moves a window from its title bar only, unlike the GUI, which drags from anywhere. Grab the top row.

A TUI window won’t resize from its bottom edge. If it’s two rows tall or shorter, its bottom row is content, not a handle. Resize from the right column, or set the size in .editwindow.

A window snaps flush against an edge you want it away from. Hold Shift while dropping to suspend snapping for that gesture. If a window keeps drifting back to an edge on later resizes, it has a persistent anchor — right-click ▸ Arrange ▸ Release Anchors to forget it. The window stays exactly where it is and stops following. If snapping misbehaves in a way you can’t explain, .snapdebug writes a trace to ~/.vellum-fe/vellum-fe.log.

You resized the app window and everything is proportionally wrong. In the GUI, right-click the windows that shouldn’t stretch ▸ Arrange ▸ Advanced ▸ Fixed size — a compass and a hands widget want it, a text window doesn’t. In the TUI, run .resize to refit the layout to the terminal’s new dimensions.

You deleted a window and want it back. In the GUI, Windows ▸ ↩ Restore deleted… returns it with its position, streams, and widget type intact. That button only appears when something is waiting to be restored, so an empty stash means it’s genuinely not there. In the TUI, restore via .loadlayout hunting — which is the strongest argument for saving early and saving often.

⚠️ .deletewindow truly removes a window and .hidewindow only hides it — in both desktop frontends. There is no asymmetry between the GUI and the TUI to remember. Both refuse to remove your only main-feed window, so you cannot strand yourself without game text.

⚠️ In the Terminal (TUI), Ctrl+C copies your selection — it does not quit. In the Desktop GUI the same combination quits. Leave the TUI with .quit or .exit. This is the difference most likely to bite you while you’re moving between frontends mid-build.

See also

• Desktop GUI — the Windows catalog, zones, snapping, and the full right-click menu
• Terminal (TUI) — title-bar dragging, the resize handles, and .editwindow
• Creating Layouts — .savelayout / .loadlayout and the shared layout pool
• layout.toml — every window field, its type, and its default
• Mini Vitals · Countdowns · Targets · Compass · Hands
• Injury Display · Active Effects — the two variations above
• Wire a hotbar for combat — the next thing to add to this screen

Make your health bar shout when you’re hurt

One glance — or one sound — tells you you’re at 30%, without reading a single number.

What you’ll build

A low-health alarm that works when your eyes are on the creature, not on your bars. You’ll wire three things that fire together at 25% health: a hotbar button that flips to red text on a dark red field, an indicator window that lights up, and a sound plus a controller buzz on the game’s own wound messaging. By the end, dropping below a quarter health changes what your screen looks like and what your chair feels like.

⚠️ Nothing in VellumFE blinks or animates a vitals bar. There is no flashing bar, no pulsing fill, no threshold color on the bar itself. The minivitals and progress windows expose Layout, Bar height, Bar text, Depleted color, and which bars show — and that is all. What this guide builds is louder and more reliable than a blink: a color change on a button, an icon that lights, a sound, and a controller rumble. Read the outcome as “your screen shouts,” not “your bar flashes.”

Before you start

• The visual half of this guide is condition-driven, and only the Desktop GUI can author conditions. The TUI hotbar editor covers a button’s label, command, hotkey, tooltip, category, and countdown — it shows states as a count and tells you to edit them elsewhere. The TUI indicator editor edits id, title, icon, and active/inactive colors, with no conditions. The TUI displays everything you author in the GUI perfectly; it just doesn’t build it. Each tab below says which parts it can do.
• For the sound step: put an audio file in ~/.vellum-fe/global/sounds/. A bare name like lowhp works — the extension is tried for you.
• For the rumble step: a connected controller, plus a rumble pattern defined in the Controller editor’s Rumble tab. Skip this step without one; the sound and colors work on their own.

Steps

Make it yours

Alarm on the wound, not the number. Health percent lags a big hit — you can be at 40% with a rank-3 chest wound and in more danger than someone at 20% clean. Add a state using the Injury condition instead: area chest, comparison >=, level 2. Levels 1-3 are wounds and 4-6 are scars, so >= 2 catches a serious wound and ignores old scars. Put it above your percentage states and it wins whenever it matches.

One alarm for “actually in trouble.” A single low number rarely means death; a low number while stunned does. Add a state, set its group combo to all of, and click + condition twice to build: Vital · health · < · 40 · % and Indicator · stunned · active. Only the combination lights it, so the alarm stays rare enough that you believe it.

Make it an absolute number. Percentages mislead at low levels, where 25% can be nine hit points. Switch the Vital row’s unit combo from % to abs and set the value to a real number of hit points you know is dangerous for your character.

When it doesn’t work

The button turned yellow but never red. Your 50% state is above your 25% state. The first matching state wins, and 22% satisfies “< 50%” perfectly well, so the yellow rule fires and the red one is never consulted. Use the ^ button on the red state’s card to move it above the yellow one, then Save bar. Order the widest condition last, always.

The button never changes at all. Check three things in order: the button has at least one entry under States (an empty state list means nothing can ever match); you clicked Save bar and the “unsaved changes” note is gone; and the hotkeybar window’s name matches the bar’s name exactly. A window named combat will not display a bar named vitals.

The indicator never lights. The indicator window’s name is its status id, and it must match the highlight’s Set status value. .addwindow LOWHP indicator … pairs with Set status LOWHP. Case doesn’t matter — ids are compared case-insensitively — but spelling does.

The indicator lights and never goes out. You left Status duration empty, which means “stay on until something clears it.” Either set a duration in seconds, or add a second highlight rule matching your recovery text with that id in Clear status.

The sound stays silent. The file must be in ~/.vellum-fe/global/sounds/. A bare name works and the extension is tried for you, so lowhp finds lowhp.wav — but a name with a typo finds nothing and fails quietly. Check the folder, and confirm sound is enabled in Settings.

Your states vanished after editing in the TUI. They didn’t. The TUI hotbar editor deliberately round-trips states untouched and displays them as a count, so a TUI save never destroys GUI-authored conditions. If they’re genuinely gone, check whether a per-character bar is shadowing your global one — a character bar with the same name replaces the global bar wholesale rather than merging with it. The editor’s bar list shows [G] for global and [C] for character so you can tell which one you’re editing.

The rumble combo is empty. Rumble patterns come from the Controller editor’s Rumble tab. Define one there first and it appears in the highlight form’s combo.

See also

• Mini Vitals — every option on the vitals window, including Depleted color and bar order
• Progress Bars — individual health/mana/stamina/spirit windows
• Hotbars — the full button, state, and countdown reference
• Indicators — indicator windows and custom status ids
• Dashboard — the grid form of the same status machinery
• Highlight Patterns — every highlight field, including set_status, status_duration, and clear_status
• Sound Alerts — the sounds directory and volume
• Controller & Gamepad — defining rumble patterns
• Wire a hotbar for combat — the same condition vocabulary, applied to attacks and spell prep
• Set up highlights and sound alerts — the highlights editor in depth

Make the game shout when something matters

By the end you’ll have a bounty line that turns gold and chimes, a web that lights an on-screen indicator, and the ambient noise you’re tired of reading gone from the feed.

What you’ll build

Three rules, each one a different kind of “tell me”:

1. Color + sound — You have completed your task prints in gold and plays a chime, so a bounty finishing lands even when you’re reading something else.
2. A status light — being webbed switches on a custom status id, and an indicator window wired to that id lights up. This is the one worth learning: any line of game text can drive a visual, without the game ever sending a status update for it.
3. Squelch — the ambient weather chatter never reaches your main window again.

You’ll prove all three with .testline, which feeds a fake game line through the live highlight pipeline, so nothing here depends on finding a mob first.

Before you start

• For the sound rule only: an audio file in ~/.vellum-fe/global/sounds/. VellumFE creates that folder and seeds it on first run. Drop a .wav or .mp3 in and it appears in the editor’s Sound dropdown. The examples below use chime.wav — substitute the name of a file you actually have.

• Coming from Wrayth or StormFront? Convert your existing rules first instead of retyping them:

  vellum-fe import-highlights 70682.xml
  

  This runs and exits without connecting. It writes 70682-highlights.toml beside the source file; add --dry-run to see what it would produce, or --out <FILE> to choose the destination.

Steps

Make it yours

Send lines somewhere else instead of hiding them. Squelch is absolute — the line is gone. If you’d rather keep it but move it out of the way, set Redirect to to another window’s name. The mode selector decides what happens to the original: redirect only removes it from the main feed, redirect copies leaves it in place and duplicates it. A rule with pattern asks you to and Redirect to thoughts puts merchant chatter in your thoughts window while your hunting feed stays clean.

Make a status clear itself. The webbed rule above stays lit until the matching Clear status rule fires — right if you have a reliable “you’re free” line, wrong if you don’t and it sticks on forever. Put 30 in Status duration instead and the status switches itself off after thirty seconds whether or not a clear rule ever matches. The two approaches combine: whichever happens first wins.

Rewrite noisy text rather than removing it. Replace rewrites the matched text in place and understands $1-style capture groups. A rule with pattern (\w+) just bit you! and Replace >>> $1 BIT YOU <<< keeps the information and makes it impossible to skim past. Set Window to scope the rewrite to one window while the colors still apply everywhere.

Buzz the controller. If you play with a gamepad, the Rumble dropdown fires a named rumble pattern on match — a low-health rule you feel rather than read. Patterns come from the Controller editor’s Rumble tab.

When it doesn’t work

The rule never fires. Confirm with .testline before blaming the rule: .testline injects your text verbatim into the live pipeline, so if the rule doesn’t fire there, the pattern is wrong. The most common cause is a regex metacharacter taken literally — (, ), [, ], ., ?, * and + all have meaning. To match a literal (2/3) you need \(2/3\). If your pattern is plain text with no regex in it at all, tick Fast parse — it uses literal matching, which is both faster and immune to this problem.

Colors don’t apply but the sound plays (or the reverse). The [highlights] section has four independent global switches, all on by default: sounds_enabled, replace_enabled, redirect_enabled and coloring_enabled. One being off disables that entire category across every rule while the others keep working. Check them in Settings before rewriting a rule that was fine all along.

No sound at all. Three things in order: the file must be in ~/.vellum-fe/global/sounds/; [sound] enabled must be true; and the master [sound] volume (default 0.7) multiplies against each rule’s Sound volume, so a low master value quietly mutes everything. On the phone, also check the sheet’s own Sound alerts toggle.

One sound machine-guns, or a repeated line only chimes once. Both are cooldown_ms (default 500). It’s a minimum gap between repeats of the same sound — a pattern that matches ten lines in a burst plays once, not ten times. The cooldown is tracked per sound, so two different rules with two different files never suppress each other. Raise it if a spammy pattern still chatters; lower it if you’re genuinely missing fast repeats.

The indicator doesn’t light. The id in Set status must match the indicator window’s id — matching ignores case, so webbed and WEBBED are the same id, but web is not. Confirm the window is actually on screen; a status firing at a hidden window looks identical to a rule that never matched.

✅ A dashboard adds unknown ids for you. If your Set status id doesn’t exist yet, a dashboard widget appends it and lights it. An indicator window does not — it only flips an id it already has. So a dashboard is the faster way to see a new status working before you commit to placing a dedicated indicator for it.

Your rules vanished when you switched characters. Rules save per-profile by default. Tick Global (all characters) in the GUI form, or use the (global) list on the phone, for rules that should follow you everywhere.

See also

• Highlight Patterns — every rule field, its type and default
• Sound Alerts — the sound system, the seeded files, and the [sound] settings
• Indicators — placing and configuring the window a set_status rule drives
• Dashboard — the grid that auto-adds unknown status ids
• Command Reference — .testline, .highlights, .addhighlight
• Browser Client — the full list of what the phone can and can’t author
• Make your health bar shout when you’re hurt — the same machinery applied to vitals

Play VellumFE on your phone

By the end you’ll have your character in your hand — either a real client you can log in from anywhere, or a second screen on the couch beside your PC.

What you’ll build

Two different things, and you probably want both eventually:

• The app — a client that logs into GemStone IV on its own. Sit on the bus, log in, play. It can also attach to your desk session when you’d rather pick the game up where you left it.
• The browser — a second screen. Nothing to install: point a phone, tablet or spare laptop at your PC on the same network and it mirrors the session you’re already playing, with your keyboard still in charge.

Neither one is the “proper” way. They do different jobs.

Before you start

• For the app: iOS is a beta — via TestFlight; Android is (in progress). See iOS App and Android App for how to get the current build.
• For the browser, and for pairing the app with your desk session: the phone and the PC must be on the same network, and VellumFE’s web server must be running and bound so LAN devices can reach it. That’s Step 1 of the browser tab below.
• Read this once before either route: pairing tokens keep strangers out, but the traffic itself is plain HTTP. Use this on a network you trust — your home Wi-Fi, not a café’s. To play from outside the house, put both devices on a Tailscale or WireGuard network and connect over that. Never forward this port to the open internet. .webinfo reprints this warning every time you run it, on purpose.

Steps

Make it yours

Set the phone up as a glance-only second screen. Leave your desktop client running and open the browser URL on a tablet propped beside the keyboard. You keep typing on the PC; the tablet shows the feed, the status drawer and your group’s condition without ever stealing focus. Nothing to install and nothing to uninstall when you’re done.

Author on the couch. The phone edits far more than people expect: macros, touch-wheel slices, highlight rules including redirects and squelch, colors, controller binds, and the entire desktop settings registry over the wire — written to the hosting machine’s config exactly as if you’d typed it there. See Make the game shout when something matters for the phone path through the highlight editor.

Know what stays at the desk. The phone cannot author layout or panel placement, window resizing, game keybinds, or macro hidden_when conditions. Its chrome is fixed by design, so windows are not yours to move there. Build the layout on the desktop; the phone renders what you built.

When it doesn’t work

.webinfo says the web server is disabled. The message is Web server is disabled. Enable [web] in config.toml or pass --web-port. The web server is off, not broken. Tick Enable on port in the Launcher’s Advanced section, or relaunch with --web-port 8040.

.webinfo says the web server is not running. A different message — Web server is not running (bind failed or still starting) — and a different cause. The server was asked to start but has no bound port. Usually another program already holds that port; pick a different one. If you launched a moment ago, give it a second and run .webinfo again.

The URL says 127.0.0.1 and the phone can’t load it. That address means “this PC only”, and no other device can ever reach it. VellumFE tells you so directly, printing Note: bind = "127.0.0.1" is this PC only. Set [web] bind = "0.0.0.0" so phones on your LAN can connect. Change Bind address to 0.0.0.0 and restart the session — the bind is fixed at startup.

The QR scans but nothing happens. You almost certainly scanned the wrong one of the two. The camera app handles the browser code (http://…); the app’s Scan QR to add screen handles the app code (vellum://remote?…). Crossed over, both fail silently.

The page loads but never connects. Phone and PC must be on the same network. Phones drop to mobile data when Wi-Fi looks unreliable, which silently ends the LAN connection. Check the phone is really on your Wi-Fi, and that the PC’s firewall isn’t blocking the port you chose.

You want to play from outside the house. Don’t forward the port. Put both devices on a Tailscale or WireGuard network and use the address that network gives your PC — everything else on this page works unchanged, and the traffic is encrypted by the tunnel.

See also

• Browser Client — the browser client in full: its two modes, the settings sheet, and everything the phone can author
• iOS App — TestFlight, the Characters picker, and backgrounding
• Android App — installing the in-progress build, the Characters picker, and battery behavior
• The Launcher — the Advanced section that turns the web server on, and the separate SSH Launcher for cold-starting Lich
• Make the game shout when something matters — authoring highlight rules from the phone
• Command Reference — .webinfo

Wire a hotbar for combat

One-click attacks, stances, and spell prep — on buttons that dim, recolor, and count down as the fight changes.

What you’ll build

A row of combat buttons that isn’t just a row of buttons. Attack dims itself while roundtime is running and shows the seconds left. Hide goes green and reads “Hidden” once you’re in the shadows. Your 909 dims the moment you can’t afford it, and swaps to a different command while a cast is in flight. Every button also takes a hotkey, so the bar doubles as a set of bindings you can read.

Before you start

• Condition states are authored in the Desktop GUI. The TUI hotbar editor builds bars, buttons, hotkeys, and countdowns, but shows states as a count and leaves them untouched — it renders them faithfully, it just doesn’t edit them. The Mobile tab explains what the phone offers instead.
• Know the bar-to-window rule before you start: a hotkeybar window displays the bar with the same name as the window. Name them to match or nothing appears.

Steps

What the states look like on disk

You never need this file — the editor writes it — but three lines of it explain the ordering rule better than a paragraph can. Here is the Hide button from step 4:

[[bars.buttons.states]]                            # checked FIRST
[bars.buttons.states.when]
type = "indicator"
id = "hidden"
active = true
[bars.buttons.states.style]
label = "Hidden"
fg = "#80ff80"

[[bars.buttons.states]]                            # checked only if the above missed
[bars.buttons.states.when]
type = "rt_active"
[bars.buttons.states.style]
dim = true

States are checked top to bottom and the first match wins — the second block never runs while you’re hidden. Swap the two blocks and a hidden character in roundtime shows a dim “Hide” instead of a green “Hidden”. In the editor the ^ and v buttons on each state card are this same ordering; the file just makes it visible. Editors build one level of all of / any of nesting; deeper trees are file-authored, render as (nested group - edit in hotbars.toml), and still evaluate correctly.

Make it yours

A melee bar that reads your hands. Choose Hand holds on a condition row and set the hand to Right with item type weapon to light your attack button only when you’re actually armed. Pair it with a Hand empty state carrying a Command while active: of get my weapon, and one button both draws and swings depending on what you’re holding.

A caster bar that grays out what you can’t cast. Instead of writing a mana threshold per spell, use Spell affordable with the spell’s number. It reads the bundled spell table’s static costs against your current mana and fails closed — unknown numbers and formula-cost spells evaluate false — so a button grays out rather than lying to you.

A stance bar built from indicators. Give each stance button an Indicator state on standing, kneeling, sitting, or prone, styled bright, so the bar always shows your current posture as the one lit button. The same eleven ids — standing, kneeling, sitting, prone, stunned, bleeding, hidden, invisible, webbed, joined, dead — are available in every condition builder in the product.

When it doesn’t work

The window is there but empty. The window name and the bar name must match exactly — a hotkeybar window displays the bar of the same name, and there is no bar-picker in the window’s right-click menu (only Edit hotbars…, which opens this editor). Rename one to match the other.

The wrong state keeps winning. The first matching state wins, so a broad condition placed above a narrow one swallows it. Put “hidden” above “roundtime”, and “health < 25%” above “health < 50%”. Reorder with each card’s ^ and v, then Save bar.

The hotkey does nothing. Existing keybinds.toml bindings beat hotbar buttons. The editor warns you at the time — “Key is already bound by … - it wins over this button.” — and the button list marks the row (key conflict). Pick a free key, or rebind the keybind.

A duplicated button’s hotkey is gone. That’s deliberate: duplicating a key would guarantee a conflict, so Dup clears the copy’s hotkey. Give the copy its own.

The button shows text where you wanted art. Icons are GUI-only — the TUI always renders the label. In the GUI, check Face is set to Icon or Icon + label and that the bar’s Icon px is large enough to see; the default is 24, and barbar-style art reads best between 32 and 64.

Your global bar stopped responding to edits. A per-character bar with the same name replaces the global bar wholesale — it does not merge button by button. The bar list’s [G] / [C] badges tell you which copy exists; edit the [C] one, or delete it to fall back to global.

The state’s command override isn’t doing anything clever. Command while active: is literal text, not an expression. Put the logic in the command itself — a ;eq … line, which Lich intercepts and evaluates — rather than expecting the field to compute anything.

Nothing saved. Save bar is disabled until there are changes and shows “unsaved changes” beside it while there are. If it’s grayed out, your edit didn’t register; click into the field and change it again.

See also

• Hotbars — the full field, state, icon, and countdown reference
• Quickbar — the lighter-weight command bar
• Keybind Actions — the key syntax hotkeys use, and resolving conflicts
• Indicators — the same condition vocabulary driving status icons
• Hands — hand icons, also condition-driven
• Countdowns — roundtime and casttime elsewhere in the layout
• Active Effects — the effect categories conditions read from
• Skins (GUI Graphics) — registering the icon sheets buttons draw from
• Make your health bar shout when you’re hurt — the same vocabulary applied to vitals
• Build a hunting layout — where the combat bar sits among your other windows

Frontends

One character, one set of settings, five ways to sit down and play — pick the one that matches where you are right now.

What it’s for

You hunt at your desk, but you also want to check on a bounty from the couch, or keep a character parked over SSH on a box that has no desktop at all. VellumFE gives you five interfaces over one core, so the highlight that colors your critical hits, the keybind on your numpad, and the layout you spent an evening arranging follow you from the terminal to the desktop window to your phone. You configure a thing once. It shows up everywhere it can be shown.

The differences between the five are about what the surface can physically do — a terminal cannot draw a skin image, a phone cannot let you drag a window to a new corner — not about which one is the “real” client.

The five at a glance

Two of those rows carry a wrinkle worth stating plainly.

“Mobile Web” is two different products depending on how you start it. Run the TUI or GUI with the web server on and the browser is a sidecar — a second screen driving the session your PC already owns. Run --frontend headless and there is no local UI at all: the core plus the web server is the client, and the browser gets a login screen. Same code, different shape.

The Android and iOS apps are not a third thing. They are the same Rust core in a native shell, showing the web client’s UI in a WebView. What the shell adds is a saved Characters picker — the one native screen — so a phone can scan a pairing QR code and seal a saved server into the Keychain or Keystore. On a phone the login screen shows two tabs (play.net and Lich) plus that picker, reached through the person icon; a desktop browser shows three tabs, because it keeps the in-page Remote tab the phone replaces.

Set it up

Pick where you’re playing, then start the client that way. Every one of these connects the same character to the same game.

Common setups

One character, desk and couch

Start the GUI from the Launcher and enable the web server on the same run. Play at the desk normally. When you get up, run .webinfo, scan the QR with your phone, and the phone joins the same session — the same roundtime, the same room, the same active spells. Nothing syncs, because nothing needed to: there is one session and two views of it.

You’ll see: your health bar moving on the phone at the same instant it moves on the monitor, and a command typed on either one landing in the game once.

A character parked on a headless box

On a server or a Raspberry Pi with no desktop, run vellum-fe --frontend headless --port 8000 --character YourName --web-port 8080 --web-bind 0.0.0.0. There is no local UI at all. Point any browser on your network at that box’s address and the browser is the entire client — including its own login screen, since there’s no desktop session to attach to.

You’ll see: the browser presenting a login overlay rather than immediately showing a game already in progress — that is how you tell headless from sidecar at a glance.

Tips & gotchas

⚠️ Ctrl+C means two different things. In the Terminal (TUI) it copies your selection and does not quit. In the Desktop GUI it quits. To leave the client from the terminal, use .quit or .exit. This is the single biggest trap when you move between the two.

⚠️ .quit may not close the window. By default it disconnects but leaves the client open — run it again, or use .exit, to close. Turn this off with ui.keep_open_on_quit in Settings.

• The two “Launchers” are unrelated. The Launcher is the graphical connection list you get by running with no arguments. The SSH Launcher is an in-session panel (.launcher / .launch <character>) that cold-starts a headless Lich on another machine. They share a word and nothing else.
• The terminal cannot render images, and that is deliberate. Skins, per-window background art, and the graphical injury doll, compass, and hand icons are GUI-only forever — a character cell has no pixels to put them in. The TUI renders the same information with glyphs and color. Nothing is missing from your character; only the artwork is.
• Layouts are shared, appearance is not entirely. .savelayout and .loadlayout work in both desktop frontends against the same pool, so a layout you build in the GUI opens in the TUI. Skin frames inside it simply have nothing to draw on the terminal side.
• Saving a layout is always typed. There is no GUI button for it — .savelayout <name> in either desktop frontend. The Windows catalog says so itself.

See also

• Terminal (TUI) — the terminal frontend in full
• Desktop GUI — toolbar hubs, right-click window menu, skins
• Mobile Web — sidecar and headless browser modes
• Android app · iOS app
• Configuration Files — the settings all five share

Terminal (TUI)

Play GemStone IV wherever a terminal reaches — over SSH, on a Raspberry Pi, in a tmux split next to your scripts — with the same layout, highlights, and keybinds as the desktop client.

What it’s for

You already have a terminal open. The TUI puts your whole character in it: the same windows, the same highlight rules, the same numpad movement macros as the Desktop GUI, drawn on a character grid instead of pixels. It is what a hand-typed vellum-fe command gives you by default, and it is the only frontend that survives a session over SSH on a machine with no desktop at all.

It is not a stripped-down mode. Mouse works — for links, scrolling, selection, dragging windows, and right-click menus. And the TUI keeps its own window editor, a full-screen form you open with .editwindow; the GUI’s separate editor was retired in favor of a right-click menu, so this form has no direct counterpart over there.

Set it up

Working with windows

Everything in this section is mouse-and-keyboard in the terminal itself.

Move a window by left-dragging its title bar — the top row, and only the top row. (The GUI lets you drag from anywhere; the TUI reserves the body for text selection.) A window locked in place can still be grabbed there, but will not move.

Resize a window by dragging its right column, bottom row, or the bottom-right corner cell. Two details save you a puzzled minute: the bottom row only acts as a handle when the window is taller than two rows, and the right column only when it is wider than one — so a single-row bar’s bottom row stays content, not a grab handle. A locked window resizes nowhere.

Right-click a title bar for Close Window, Edit Window…, and Open Menu. (Close Window is not offered on main or command_input.) Right-clicking the performance overlay opens its own metrics toggle menu instead.

Add, hide, delete, and restore windows by command:

.deletewindow truly deletes in both the TUI and the GUI, and .hidewindow hides in both — there is no asymmetry to remember. Both refuse to remove your only main-feed window. There is no standalone .showwindow; restoring is the .menu route or .loadlayout.

The window editor

.editwindow (or .editwin) opens a full-screen form for the focused window, or .editwindow <name> for a specific one — the same form the title-bar right-click reaches via Edit Window…. It is keyboard-driven, and the bottom border always tells you the keys for wherever you are.

The base footer reads [Ctrl+S: Save] [Esc: Cancel]. Step into a sub-editor and it changes to match: reorderable lists show [Ctrl+S: Save]─[Shift+↑/↓: Reorder]─[Esc: Cancel], and the stream picker shows [Enter: Add stream]─[Esc: Back].

That Ctrl+P picker is the one to remember. Subscribing a window to a stream normally means typing an id you have to already know; on the Streams field it lists what Lich has actually pushed this session, and Enter appends the highlighted id to the field. It does nothing on any other field, so if it seems dead, check which field has focus.

Keys you get out of the box

These are the defaults in keybinds.toml, and every one of them is rebindable with .keybinds.

Text and windows

Numpad movement, pre-bound

num_1–num_9 walk the compass the way the keypad is laid out (1=southwest, 2=south, 3=southeast, 4=west, 5=out, 6=east, 7=northwest, 8=north, 9=northeast). num_0 goes down and num_decimal goes up. num_plus sends look, num_minus sends info, num_multiply sends exp, and num_divide sends health.

Editing the command line — these are fixed terminal conventions rather than entries in keybinds.toml: Ctrl+A select all, Ctrl+C copy, Ctrl+X cut, Ctrl+V paste, Ctrl+Z undo, Ctrl+Shift+Z redo, Ctrl+E jump to end, Ctrl+U clear the line, Ctrl+W delete the word behind the cursor.

As you type, the newest history entry sharing your prefix appears as muted text from the cursor onward. Tab accepts it. When there is no suggestion and no dot-command completion pending, Tab falls back to switching windows. The suggestion uses the theme’s text_secondary color; set completion_color on the command-input window to change it.

Selecting, copying, and clicking

Drag across text to select it, and it copies to your clipboard the moment you release the mouse — no second keystroke. That is selection_auto_copy, on by default. Copy is plain text by design; styling is deliberately not carried to the clipboard.

Clicking game text does what the markup says: a URL opens your browser, a command link sends its command, a coordinate link runs its command list, and a plain noun asks the server for its context menu and shows what comes back. Ctrl+drag a link onto a hand, a container, an inventory row, or another link to send _drag, which is how you move an item without typing a target.

Common setups

A 256-color terminal that still looks right

Some terminals — an older xterm, a locked-down remote console — cap at 256 colors, and true color output turns muddy. Start with vellum-fe --port 8000 --character YourName --color-mode slot --setup-palette. Slot mode maps your configured colors into palette slots and --setup-palette programs them into the terminal at startup. If you change colors mid-session, run .setpalette to reprogram, and .resetpalette to hand the terminal’s own palette back before you exit.

You’ll see: your named highlight colors rendering as the exact hues you chose in .colors, instead of the nearest muddy approximation.

A layout that survives a terminal resize

Arrange your windows by dragging title bars and edges, then save with .savelayout hunting. When you later stretch the terminal or drop into a different-sized tmux pane, run .resize to refit the saved arrangement to the new dimensions rather than rebuilding it. .layouts lists what you have saved, and .loadlayout hunting brings it back — including on the Desktop GUI, which reads the same pool.

You’ll see: your combat window still occupying the right third of the screen after the pane changes size, rather than clipped off the edge or stranded in the middle.

Tips & gotchas

⚠️ In the TUI, Ctrl+C copies your selection — it does not quit. A raw-mode terminal owns its own keys, so nothing intercepts it. To leave, type .quit or .exit. In the Desktop GUI the same combination quits, because there the OS delivers it beneath the key layer. This is the one difference most likely to bite you when you switch frontends.

⚠️ .quit disconnects but keeps the client open by default. Run it again, or use .exit, to close. Change it with ui.keep_open_on_quit in Settings.

• The terminal cannot render images, and that is by design, not a missing feature. Skins, per-window background art, and the graphical injury doll, compass, and hand icons are GUI-only forever — there are no pixels inside a character cell. The TUI shows the same underlying information with glyphs and color, so nothing about your character is hidden from you. If a layout you built in the GUI has skin frames, they load without complaint and simply have nothing to draw.
• .setpalette needs slot mode. On direct (true color) it has nothing to program. Pair it with --color-mode slot.
• Reset the palette before you leave a shared terminal. .resetpalette restores the terminal’s own colors; without it a multiplexer session can keep your palette after you disconnect.
• Use a Nerd Font if you want the default countdown glyphs and compass rendering exactly as designed. Without one they fall back to plainer characters.
• There is no Launcher in the terminal. It is an egui window, so it is GUI-only. Start a saved connection from a terminal with --launch-profile "<name>".
• A one-row window has no bottom resize handle. That is deliberate — its bottom row is content. Resize it from the right column instead, or adjust it in .editwindow.
• .menu has no default keybind. Type it, or use Open Menu from a title-bar right-click.

See also

• Frontends overview — all five, and how to choose
• Desktop GUI — the mouse-first counterpart with skins and toolbar hubs
• Mobile Web — joining a TUI session from your phone
• Widgets — what can go in a window
• Configuration Files — keybinds, highlights, colors

Desktop GUI

Build the layout you play in — drag windows anywhere, reskin them with real artwork, and change any setting from a right-click without leaving the game.

What it’s for

This is where you design your interface. Everything else — the terminal, the phone, the browser — plays the layout; the GUI is where you make it. You drag a window to the corner you want it in, right-click it to change its font, and watch the change land while combat text is still scrolling past.

It is also the only frontend with pixels. The compass is a drawn rose, the injury doll is a body diagram that colors by wound severity, and a skin can replace your window borders, backgrounds, and icons with real artwork. A character grid cannot do those things, so the GUI does them for everyone.

Set it up

Working with windows

Adding, hiding, deleting

Adding a window is the Windows catalog, not a right-click. Click Windows in the toolbar and you get every window the client can have — the built-in catalog plus game dialogs, streams, and containers — sorted by title and grouped into collapsed categories. Each row is a checkbox (tick to show, untick to hide) and a zone dropdown. Setting the zone on a hidden window decides where it appears when you show it.

Two buttons sit at the top of the catalog:

• ➕ Custom window… creates a blank widget of the type you pick and drops you into the new window’s right-click menu to configure it.
• ↩ Restore deleted… brings back a window you deleted, with its position, streams, and widget type intact. It appears only when something is waiting to be restored.

⚠️ .deletewindow truly deletes and .hidewindow hides — in both desktop frontends. There is no asymmetry to remember. Delete stashes the window so ↩ Restore deleted… can bring it back, and both commands refuse to remove your only main-feed window.

⚠️ There is no button to save a layout. .savelayout <name> is typed, in the GUI as much as the terminal. The catalog says so itself when no layouts exist yet.

Moving, resizing, snapping

Drag a window from anywhere — body or title bar, no modifier held. Interactive content still wins, so selecting text or clicking a link does not start a drag. Resize by dragging any edge or corner.

⚠️ The GUI drags from the whole window; the TUI drags from the title bar only. And Ctrl+drag is not window movement in either frontend — it is the object-drag gesture that sends _drag, for dropping an item onto a hand, a container, or another item.

While you drag or resize, edges snap to the zone’s bounds, to other windows in the same zone, and optionally to a grid. An engaged snap draws a guide line at the matched coordinate. Hold Shift to suspend snapping and place the window exactly where the pointer is — the guides disappear for as long as you hold it.

A snapped drop can promote to a persistent anchor, which makes the window keep following the edge it snapped to when the app window resizes. Right-click ▸ Arrange ▸ Release Anchors forgets them; the window stays exactly where it is and stops following. Dragging the window away from its snap does the same thing. The row is always visible, greyed when the window has no anchors, so you can tell at a glance which case you are in.

Tune the whole system under Settings ▸ GUI: snap distance, which targets participate, grid pitch, and grid sizing. .snapdebug writes a trace of the snap engine to ~/.vellum-fe/vellum-fe.log when a snap is not doing what you expect.

Zones

The GUI arranges windows in five zones — Header, Footer, Left Bar, Center, and Right Bar. Toggle them from the toolbar’s Zones hub, which stays open so you can adjust several and watch each take effect, or type .header, .footer, .leftbar, .rightbar (each takes on, off, or toggle, defaulting to toggle).

Every zone is a free canvas: windows sit exactly where you drop them, may overlap, and remember their spot. Moving a window to a different zone has three routes:

• Alt+drag the window. Hold Alt and drag, and a tinted overlay highlights the zone under your pointer; release to drop it there. Ordinary movement is suppressed while Alt is held, so the two gestures never fight.
• Right-click ▸ Arrange ▸ Move to ▸ the zone you want.
• The zone dropdown on that window’s row in the Windows catalog — the one that also works on a window that is currently hidden.

Overlapping and detaching

Where windows can overlap — Center, Header, and Footer — the right-click menu offers Send to Back, dropping the window behind anything it covers so a buried one becomes reachable. Clicking a window still raises it. The packed sidebars do not offer it, because nothing overlaps there.

Detach puts a window in its own OS window, restored across sessions. A detached window gets the same right-click menu with Reattach in place of Detach, and without Arrange, Group, or Send to Back — none of them mean anything inside an OS window. Drag its body to move it.

The right-click menu

Right-click any window body and you get every per-window setting there is. Changes apply live — there is no Save button. Text fields commit when you press Enter or click away. .editwindow <name> opens the same menu for a window by name.

⚠️ The GUI’s separate Window Editor no longer exists. If a guide tells you to open an editor window and press Save, it is describing the old client. Right-click is the one home for these settings now. (The TUI still has its own full-screen editor form.)

Three quick actions sit at the top — Hide, Detach (or Reattach), and Send to Back — then collapsible sections, each with its own Advanced fold so the menu opens short.

Window

Title, Title bar text (custom text for the bar, separate from the window’s name), Streams — the stream ids this window collects, with a + picker listing every stream seen this session so you do not have to know an id in advance — Buffer lines (scrollback size), Speak new lines (TTS), and Lock in place. A locked window can still be grabbed but will not move or resize; .lockwindows locks everything at once.

Under Advanced: Compact (condenses known content such as bounty text), Timestamps with a Timestamp at line start toggle, and Delete Window…. Delete is double-gated — the first click arms it, then the menu asks “Really delete this window from the layout?” with Delete and Cancel.

The widget section

Named for the widget itself, and present only when the widget has settings of its own:

• Timer / Bar — the feed id it tracks, its label, color, whether it shows value/max or a bare value, and Stay visible at rest for timers that should not vanish at zero.
• Effects — which category the window carries.
• Room — section toggles for Description, Objects, Players, and Exits.
• Targets — the filtered-appendage count and status position, plus Global target settings…, which jumps to Settings ▸ Targets where the colors and excluded nouns live for every targets window at once.
• Experience — Level, Mind state, Experience bar, Total exp, Ascension exp, and the two bar colors. Encumbrance — Level bar and Help text.
• Vitals — Layout (orientation), Bar height, Bar text format, Depleted color, and a checkbox per bar in display order.

Widgets with an editor of their own link to it from here: Edit tabs… (tab names, streams, and order), Edit hotbars…, Edit indicators…, Edit dashboard…, Hand icons… (status-driven icons for an empty hand, a held weapon, a prepared spell), Calibrate doll…, and Open Map Explorer.

Arrange, Appearance, Group

Arrange holds Move Window (a keyboard-friendly move that works even on a locked window), Move to ▸ each zone, and Release Anchors. Under Advanced: Fixed size, which keeps a window’s exact width and height when the app window resizes or zooms so only its position adapts — what you want for a compass or a hands widget.

Appearance splits into Text (font, text size, word wrap, content alignment), Title bar (show it, and its alignment), and Frame (border on/off and style, accent color, skin frame, background). Under Advanced sit the knobs you set once: title-bar height, which border sides draw, corner radius, and frame scale.

Group locks windows together so they move as a unit. It sets the group’s orientation (Stacked or Side by side), reorders members with ⬆ / ⬇, and ungroups one member or the whole group.

The toolbar hubs

Four stay-open menus sit across the top. None of them close when you click inside — only clicking outside dismisses them — so you can make several changes and watch each land.

The distinction between the last two is worth knowing: Settings holds the knobs that live in config.toml, while Editors holds the authored content that owns its own files — your highlight rules, your keybinds, your hotbars.

Graphics and skins

The GUI draws what the terminal spells:

• Compass rose — a vector rose with lit direction markers.
• Injury doll — a body diagram colored by wound and scar severity. With a skin that ships doll art, wounds render as dots at positions you set by clicking, through Calibrate doll… in the doll window’s own menu section.
• Status icons — vector pictograms for stance, hidden, stunned, and the rest of the indicator set.

A skin replaces all of it at once — nine-slice window borders, background art, icon sprites, a sprite compass and paperdoll. .skins lists what is installed, .setskin <name> activates one, .setskin none turns skinning off, and .makeskin <name> scaffolds a starter skin you can edit. Per-window, Appearance ▸ Frame picks which frame from the active skin a given window wears. See Skins (GUI Graphics).

Common setups

A hunting layout you can rebuild in five minutes

1. Click Zones and turn on Header and Right Bar.
2. Click Windows, tick Vitals and set its zone dropdown to Header; tick Roundtime, Compass, and Targets and set them to Right Bar.
3. Drag each one where you want it. Hold Shift while dropping the compass if the snap keeps pulling it flush against an edge you want it off of.
4. Right-click the compass ▸ Arrange ▸ Advanced ▸ tick Fixed size, so it keeps its proportions when you resize the app window.
5. Type .savelayout hunting.

You’ll see: the arrangement redraw exactly as you left it after .loadlayout hunting — including on the terminal, which reads the same layout pool.

A story window that reads the way you read

Right-click your main story window. Under Window, raise Buffer lines so a long hunt stays scrollable. Under Advanced, tick Timestamps and Timestamp at line start if you want to reconstruct a fight afterward. Under Appearance ▸ Text, pick a font and size that suit your monitor, and turn word wrap on. Under Appearance ▸ Frame, set an accent color so the window you look at most is instantly identifiable.

You’ll see: each change take effect while game text is still arriving — timestamps appear on the next line, the font reflows what is already on screen, and nothing needs saving.

Tips & gotchas

⚠️ In the Desktop GUI, Ctrl+C quits. In the Terminal (TUI) the same combination copies your selection and does not quit at all. This is the single biggest trap when you move between the two. To copy in the GUI, select with the mouse (double-click for a word, triple-click for a line) and then press Ctrl+C.

⚠️ .quit disconnects but keeps the window open by default. Run it again, or use .exit, to close. Change it with ui.keep_open_on_quit in Settings.

• There is no right-click “Add Window”. Adding is the Windows catalog or .addwindow. Right-click configures a window that already exists.
• Copy is plain text, deliberately. Selections are anchored to the text itself, so they survive scrolling — drag past the window edge to auto-scroll and the copy picks up lines currently out of view — but colors and styling are not carried to the clipboard.
• Hiding is the control for game dialogs. A hidden window stays hidden even when the game re-sends it. There is no separate blocklist to maintain.
• Even the story window can be hidden, once another window or tab carries the main stream. Hiding the command input hands typing to the built-in bottom bar.
• Terminal-only commands do nothing here. .setpalette, .resetpalette, .transparent, and .resize belong to the TUI; themes and skins handle appearance in the GUI.
• Layouts are shared; the live arrangement is not. .savelayout / .loadlayout write to the pool both desktop frontends read, but the GUI keeps its own per-character live layout (positions, zoom, fonts) apart from the TUI’s layout.toml.
• Ctrl+F opens in-window search with match highlighting. Ctrl+= / Ctrl+- / Ctrl+0 zoom the whole interface.
• The two “Launchers” are unrelated. The Launcher is the graphical connection list. The SSH Launcher (.launcher / .launch <character>) is an in-session panel that cold-starts a headless Lich on another machine.

See also

• Frontends overview — all five, and how to choose
• Terminal (TUI) — the terminal counterpart, and its own window editor
• Mobile Web — joining a GUI session from a phone or browser
• The Launcher — saved connections and per-connection frontend
• First Launch — command-line flags and the default screen
• Skins (GUI Graphics) · Widgets · Map
• Configuration Files — the settings all frontends share

Browser Client

Put a second screen beside your PC with nothing to install — your phone, tablet, or the spare laptop shows the same character you’re already playing.

What it’s for

You’re hunting at your desk and the good text is scrolling past the window you can’t see. Or you want to keep an eye on thoughts and your spell timers while your hands are busy elsewhere in the house. VellumFE ships a small web server inside the client: turn it on, open a browser on any device on your network, and you get a touch-first view of the same session — same character, same streams, same links to click.

Two shapes, both first-class:

• A second screen for a running session (sidecar). Your TUI or GUI keeps running on the PC; the browser joins that same character. This is the shape this page leads with.
• The whole client in the browser. Run VellumFE with no local UI at all and the browser is the only screen — Headless mode below.

If you want the client living on your phone rather than served from your PC, the Android and iOS apps do that job instead. Neither route is the lesser one — the app plays from anywhere, the browser sits beside your PC.

Set it up

Common setups

A phone beside the keyboard while you hunt

1. Launch your hunter in the desktop GUI with Web dashboard enabled on 8040 and Bind address 0.0.0.0.
2. Run .webinfo and scan the browser QR.
3. On the phone, tap the thoughts stream chip so the story pane filters to thoughts only.
4. Swipe in from the right edge to open the status drawer and leave it on the Targets section.

→ You now watch thoughts and your target list on the phone while the desktop window stays on room text and combat. Tapping a creature in the drawer opens its attack/look/target menu and the command fires from your PC session.

Several characters, one dashboard

Launch two or three characters with web enabled. Unpinned instances treat the configured port as a base and walk upward to the next free one, so no two fight over 8040.

1. Open http://192.168.1.50:8040/ — the bare root, not /play.
2. The dashboard lists one card per running session, health-checked and auto-refreshing.
3. Tap a card to play that character.

→ Switching characters is one tap, and a character you shut down drops off the list on its own. If you want one character to keep a fixed address you can bookmark straight to /play, set pinned = true in that character’s profile config — it then binds exactly that port or disables web for the session with a loud warning, never a silent neighbor port.

Playing from the browser

• Read the game live, with streams as filter chips carrying unread badges. Long-press a chip to reorder them; the order follows your character across devices.
• Send commands exactly as you would at the PC, dot-commands included. With a keyboard attached, Up/Down browse history; the ↻ button resends the last command and long-pressing it opens a history sheet. The newest matching history entry appears dim after the cursor — press Tab to accept it.
• Tap links, nouns, and exits. A direct link fires immediately; a plain noun opens the server’s context menu in a bottom sheet. A mini compass floats over the text pane with live exits; hold it about half a second to lift and drag it somewhere else, and the spot is remembered per device.
• Side drawers. Swipe from the left edge for the macro tray; from the right for the status drawer — Targets, Players, Room, the injury doll, hands, and active effects with live countdowns.
• Map. A map button appears in the top bar once map data exists (.mapdb download). Tap a room to walk there with native .go2, drag to pan, pinch to zoom. See Map and Travel.
• Reconnect gracefully. The session resumes where you left off with a “missed output” marker for long gaps, and several devices can be connected at once.

Settings on the phone

The gear ⚙ opens the settings sheet. What you can author from here:

• Appearance — theme presets, show/hide toggles for every piece of chrome, opacity sliders, and the Aa button for story text from 6 to 24 px. Theme, text size, and chip order roam with your character; chrome toggles and opacities stay per-device.
• Client settings (saved on host) — the full desktop settings registry over the wire, editable at character or global scope, written to the hosting machine’s config exactly as if you had edited it there.
• Highlight rules (this profile) / (global) — add and edit rules with color pickers, a sound dropdown, and a live preview.
• Colors (this profile) / (global) — stream preset and prompt colors.
• Streams (saved on host), Touch wheel (long-press ring), Controller (gamepad), Speech, and SSH launcher (cold-start Lich).
• Advanced — raw TOML editors for highlights and colors with import/export, the practical way to move a desktop config onto the phone.

✅ The phone’s highlight editor does redirects and squelch. Older documentation said it could not. The rule form has a Squelch checkbox and a redirect Off / redirect only / redirect + copy selector with a target field, so a phone-authored rule can send matching lines to another window or hide them outright.

What the phone genuinely cannot author: layout and panel placement, window resizing, game keybinds, and macro hidden_when conditions. Those stay on the desktop. Everything else on the list above is editable from the phone.

Headless mode

vellum-fe --frontend headless

This runs the core and the web server with no local UI at all. It prints the ready /play URL (token included) at startup and the browser does the rest. Give it credentials (--direct --account … --character …) to auto-connect, or give it nothing and it waits at the login screen.

The login screen is the same overlay the phone apps show. In a desktop browser it has three tabs:

• play.net (default) — play.net account, password, character, a game selector covering every GemStone IV and DragonRealms world, and Remember this login. Submit is Connect.
• Lich — host, port, label (optional), and Remember this connection (ticked by default). It attaches to a Lich session already running elsewhere; launch that Lich with --detachable-client. The tab also holds a custom launch command (optional) textarea: with one set, connecting probes the port first, SSHes to the host and runs the command if Lich is down, then attaches once the port opens. Configure the SSH side in ⚙ → SSH launcher (cold-start Lich).
• Remote — points this browser at a different machine’s VellumFE web server using its host, port, and pairing token.

⚠️ A phone shows two tabs, not three. In the Android and iOS apps the in-page Remote tab is hidden on purpose and a native Characters picker replaces it — reached from the person icon on the login screen. The picker exists so the app can scan pairing QR codes with the camera and seal saved servers into the Keychain or Keystore. Same capability, better home.

Headless sessions look after themselves: drops reconnect with backoff and typing resets it; repeated drops with no input from you stop the reconnect loop so an abandoned session winds down instead of relogging all night; a hung login is retried by a watchdog; and quit returns to the login screen.

Tips & gotchas

⚠️ bind = "127.0.0.1" is this PC only. The most common failure is a phone that cannot reach the URL at all. .webinfo tells you when this is the cause, printing: bind = “127.0.0.1” is this PC only. Set [web] bind = “0.0.0.0” so phones on your LAN can connect.

⚠️ Security: keep the port on a network you trust. Pairing keeps strangers out, but the traffic is plain HTTP. For play away from home use Tailscale or WireGuard — never forward this port to the open internet. .webinfo repeats this line every time you run it.

• .webinfo refuses when there’s nothing to pair. “Web server is disabled” means the [web] block is off and you never passed --web-port. “Web server is not running (bind failed or still starting)” means the port was taken or the server is a beat behind — run it again.
• The pairing page shows two QR codes. The browser one carries an http://…/#token=… URL for any browser. The VellumFE app one carries a vellum://remote?… link only the Android or iOS app understands. Scanning the app QR into a plain browser does nothing.
• A sidecar has no login screen. The desktop session owns the connection, so the browser gets no account fields and no login music toggle. That screen appears only in headless mode and in the phone apps.
• After editing macros.toml on the PC, run .reloadmacros — connected phones update instantly rather than on next connect.
• The wake button in the top bar keeps the phone’s screen on. Tap the title line to toggle between room name and character name.

See also

• Android app — the client living on your phone.
• iOS app — the same, on iPhone.
• The Launcher — where the Web dashboard fold lives.
• Map and Travel (.go2) — what the phone’s map button drives.
• Skins (GUI Graphics) — the injury doll art the status drawer renders when the host session has a skin active.

[web]
enabled = true
port = 8040
bind = "0.0.0.0"
pinned = false

Android App

The whole client on your phone — log in, hunt, and script from a bus stop with no PC involved. (in progress)

What it’s for

You want to play GemStone IV without being at your desk. The Android app carries the same Rust core the desktop client runs, so the phone connects to play.net by itself: enter your account, pick a character, and you are in the game. Nothing has to be running at home.

When something is running at home, the app plays that too. It attaches to a Lich session on your PC so a scripted character keeps all its scripts, and it can pair with a VellumFE session already running on your desktop and become a live second screen for it. The app is a full client and a pairing client — not one or the other.

Set it up

⚠️ The app shows two login tabs; a desktop browser shows three. The browser’s in-page Remote tab is hidden here on purpose, because the native Characters picker replaces it — the picker can use the camera to scan pairing QR codes and can seal saved servers into the Android Keystore, which a web form cannot. Nothing is lost; it moved.

Common setups

Take your desk session with you

1. On the PC, launch your character with web enabled on 0.0.0.0 and run .webinfo.
2. On the phone, open Characters → ⧉ Scan QR to add and scan the VellumFE app QR. The entry names itself after the character, because the link carries the character name.
3. Tap the new row.

→ Your PC session keeps its own GUI window open and playing; the phone shows the same character live. Lich’s one-client limit does not bite here — the web layer mirrors the session rather than replacing its client.

Add a server by hand when there’s no QR to scan

1. Characters → ＋ Add manually. The dialog is titled Add character.
2. Fill in Label (required, e.g. Rysk), Host (e.g. 192.168.1.21), Port (e.g. 8042), and Pairing token (optional). Tap Save.
3. The row appears with a dot: green and live when the machine answers, grey and offline when it does not.

→ You can tell at a glance whether the PC is up before you tap, without waiting on a failed connection.

Playing

The screen is the browser client — story pane, stream chips, tappable exits and nouns, macro tray, status drawer with the injury doll and character sheet, sounds, and the highlight and color editors. Everything on that page applies here, including the fact that the phone’s highlight editor does handle redirects and squelch.

Battery & lifecycle

The session lives in a foreground service with a quiet status notification (“Playing — session live”, “Reconnecting…”) carrying a Stop button.

• The wakelock is held only while a session is active — sitting at the login screen does not drain the battery.
• Swiping the app away mid-session keeps playing. Swiping it away at the login screen stops the service.
• Repeated drops with no input from you stop the reconnect loop, so a forgotten phone winds down instead of relogging all night.
• On first launch it asks once for a battery-optimization exemption so Android does not throttle the connection mid-hunt. Decline it and you can grant it later in system battery settings.

Tips & gotchas

⚠️ On Android 8 and 9, update Chrome — not just Android System WebView. Those releases take the rendering engine from Chrome. If the client is blank or stuck on “connecting…”, update Chrome from the Play Store first. On Android 10 and newer, update Android System WebView.

• Deleting a saved server is the ✕ on its row, which asks “Delete {name}?” with the note “Removes the saved server (and its pairing token).” Deleting the entry deletes the pairing — you re-scan to come back.
• Saved credentials never sit in plaintext. A remembered play.net password is sealed by the Rust core with a device master key, and saved servers live in remote.bin sealed by an Android Keystore key. Neither is readable off the device, and neither uses SharedPreferences.
• Scanning the wrong QR does nothing. The pairing page shows two: the browser one (http://…/#token=…) is for a browser, the VellumFE app one (vellum://remote?…) is for this app.
• A vellum://lich?host=…&port=… link prefills the Lich tab and stops there. It never auto-connects — you always press Connect yourself.
• The phone needs a private path to your PC. Home Wi-Fi, Tailscale, or a VPN. Never the open internet, for either the Lich port or the VellumFE web port.

See also

• Browser client — the interface this app renders, and the [web] settings on the PC side.
• iOS app — the same client on iPhone.
• Installation — sideloading and updates.
• The Launcher — where Web dashboard and Bind address live on the desktop.

iOS App

The whole client on your iPhone — log in and play with no PC involved. (beta — via TestFlight)

What it’s for

The iOS app carries the same Rust core the desktop client runs, so the phone talks to play.net by itself. Account, character, game world, Connect — you are in, with nothing running at home.

And when something is running at home, the app plays that as well: it attaches to a Lich session on your PC so a scripted character keeps its scripts, and it pairs with a VellumFE session already running on your desktop to become a live second screen for it. The app is a full client and a pairing client — not one or the other.

Set it up

⚠️ The app shows two login tabs; a desktop browser shows three. The browser’s in-page Remote tab is hidden here deliberately, because the native Characters picker replaces it — the picker can scan pairing QR codes with the camera and store saved servers in the iOS Keychain, which a web form cannot. The capability moved; it was not removed.

Common setups

Carry your desk session to the couch

1. On the PC, launch the character with web enabled on 0.0.0.0 and run .webinfo.
2. On the iPhone, open Characters → Scan QR to add and scan the VellumFE app QR. The saved entry names itself after the character, because the link carries the character name.
3. Tap the new row.

→ The PC session keeps its own window open and playing while the iPhone shows the same character live. Lich’s one-client limit does not apply — the web layer mirrors the session rather than replacing its client.

Add a server by hand when there’s no QR

1. Characters → Add manually. The sheet is titled Add character.
2. Fill in Label (required, e.g. Rysk), Host (e.g. 192.168.1.21), Port (e.g. 8042), and Pairing token (optional). Tap Save.
3. The row shows a dot: green and live when the machine answers, grey and offline when it does not.

→ You can see whether the PC is awake before tapping, instead of waiting out a failed connection.

Playing

The screen is the browser client — story pane, stream chips, tappable exits and nouns, macro tray, status drawer with the injury doll and character sheet, sounds, and the highlight and color editors. Everything on that page applies here, including the fact that the phone’s highlight editor does handle redirects and squelch.

Backgrounding

iOS has no equivalent of Android’s foreground service. When the app goes to the background iOS suspends it and the game connection goes stale.

• On return, the session reconnects automatically and resumes where you left off. Expect reconnect-on-return rather than a keep-alive.
• Repeated drops with no input from you stop the reconnect loop, so a forgotten phone winds down instead of relogging all night.
• While you are on a paired desktop session, the app’s embedded core sits idle — there is no game connection on the phone to go stale, and the usual web reconnect picks the mirror back up when you come back.

Tips & gotchas

⚠️ Deleting a saved character deletes its pairing token with it. Swipe a row to delete, or tap Edit in the toolbar for the multi-select delete. To come back you re-scan the QR or re-enter the token.

• Saved credentials never sit in plaintext. Saved servers live in the iOS Keychain under service dev.vellumfe.remote-server, accessible only after the first unlock and only on that device (never in a backup). A remembered play.net password is sealed by the Rust core with a device master key.
• Scanning the wrong QR does nothing. The pairing page shows two: the browser one (http://…/#token=…) is for a browser; the VellumFE app one (vellum://remote?…) is for this app.
• A vellum://lich?host=…&port=… link prefills the Lich tab and stops there. It never auto-connects — you always press Connect yourself.
• The iPhone needs a private path to your PC. Home Wi-Fi, Tailscale, or a VPN. Never the open internet, for either the Lich port or the VellumFE web port.
• The way back off a paired session is ⚙ → Leave this server (app login), which returns you to the two-tab login screen.

See also

• Browser client — the interface this app renders, and the [web] settings on the PC side.
• Android app — the same client on Android.
• The Launcher — where Web dashboard and Bind address live on the desktop.

Widgets

Your layout is made of windows, and each window is wired to one thing the game tells you. This page is the map of what you can wire up.

What a widget is here

A window is a box on your screen. A widget is what fills it — and every widget type is bound to one specific feed coming off the wire. The compass window draws the exits the game sent with the room. The health bar moves because the game pushed a number named health. A targets window lists creatures because the room’s object line marked them bold.

That binding is the whole idea, and it has a practical consequence: you do not configure a widget to go find data — you place the window and the feed arrives. A bar with no feed id draws nothing at all, not an error. A window bound to a feed your game never sends stays empty forever.

So the question this section answers is not “how do I make a health bar work.” It is “which of these thirty-odd things do I want on screen, and where do I click to get it.”

The roster

These are the groups the in-app Windows catalog uses, in the order it shows them. Inside each group, rows are sorted alphabetically by the window’s title, which is not always the type string you would type — the Type to add column is the string, and it is the one that matters at the command line.

GS4 marks a widget offered only to GemStone IV characters; DR marks DragonRealms-only. Everything unmarked appears for both.

Status

The thirteen indicators sit in a nested Indicators fold inside this group, so the Dashboard row isn’t buried under them.

Progress Bars

Custom bars are not a catalog row — see Route 2.

Countdowns

Active Effects

All four are the same widget with a different Category setting. One type string, four presets.

Entities

Hands

Text Windows

Character

Both Experience widgets carry the title Experience and both live in Character, but they are different widgets on opposite game gates. You only ever see the one for your game.

Navigation

Hotbars

The Actions row is the hotbar widget — the title differs from the type string.

Containers

Container rows are not fixed. A bag appears as a row once the game has shown you inside it this session, and ticking the row is what creates the window. There is no container row in a fresh catalog.

Dialogs

Not in the catalog at all

Six types exist and work, but no picker offers them. The only way to place one is to type the full .addwindow form.

How to add one

There are four routes, and they are not interchangeable — one of them isn’t something you do at all.

Route 1: the Windows catalog (GUI)

Click Windows in the top toolbar. The catalog stays open while you work. Every category is collapsed when it opens, so expand the group first, then tick the row. Ticking shows the window; unticking hides it. Each row also has a zone dropdown that places the window without your dragging it.

This is the route to teach a new player. It never asks for a type string, so none of the title-versus-type traps below can bite.

Route 2: the Custom window menu (GUI)

Six of the widgets are blanks rather than presets — a bar with no feed, a text window with no stream. Those are not catalog rows. They live under ➕ Custom window… at the top of the catalog, labelled Text, Tabbed text, Progress bar, Countdown, Entity list, and Active effects.

Creating one auto-opens its settings menu, because a custom bar or timer with no feed id renders as nothing until you give it one.

Route 3: .addwindow (works everywhere, including the GUI input)

.addwindow takes one argument or six or more — never two through five.

• .addwindow with no arguments opens a picker, grouped by the same categories.
• .addwindow <name> <type> <x> <y> <width> [height] creates a window directly.

⚠️ .addwindow players on its own adds nothing. Two-to-five arguments prints a usage line and stops. This surprises people constantly, because that middle form looks like the obvious one.

The <name> is a free label of your choosing — it does not have to be a catalog key, and the window is built from <type>, not from a preset. The exceptions where the name is load-bearing are called out below.

Route 4: the game does it for you

Some windows are not something you add. When the game first sends the feed, the client creates the window itself and binds it. GemStone IV’s Experience window works this way — the first time the game opens its experience dialog, the window appears. Re-sends never duplicate it.

The same discovery machinery is why a stream you’ve never seen before can turn up as an offered row later in the session.

The rules that apply to every widget

These hold for every type in the roster, so the individual pages don’t repeat them.

⚠️ An unrecognized type string does not error — it silently gives you a text window. Type .addwindow x activeeffects 0 0 30 10 and you get a blank text box, not a complaint. The type strings are exact: active_effects (never activeeffects), missingspells (never missing_spells), encum (never encumbrance). If a new window came up empty and boring, check your spelling before you check the feed.

⚠️ Catalog rows are labelled by the window’s TITLE, and several titles differ from the type string. The row that reads Encumbrance is type encum. The row that reads Actions is type hotkeybar. Story is text, RT is countdown, Injuries is injury_doll. Clicking the row is always safe; typing what the row says is not.

⚠️ Right-click is always the WINDOW menu. There is no per-row context menu anywhere — not on a target, not on an item, not on an inventory line. Left-click a row to act on that thing; right-click to configure the window holding it.

A few types accept two spellings. injury_doll and injuries are the same widget; so are command_input and commandinput, webui and lichui, dialogpanel and dialog_panel. Most types accept exactly one spelling, so don’t generalize from these four.

Not every widget has a settings section. The GUI’s right-click menu grows a widget-specific section only for types that have their own settings. Sixteen do: Countdown, Progress, Active Effects, Room, Targets, GS4 Experience, Encumbrance, MiniVitals, Tabbed Text, Hotkeybar, Indicator, Map, Injury Doll, Compass, Hand, Dashboard. Every other type — including Inventory, Reserve, Container, Players, Items, Spells, Missing Spells, Quickbar, Perception, Betrayer, Spacer, and the DragonRealms Experience widget — has no widget section, and that is not a bug. Their appearance and framing still live under Appearance; they have nothing else to configure.

A window’s name is usually a label, but twice it is a binding. An indicator window’s name is the status id it watches — there is no picker. A hotkeybar window shows the bar whose name matches the window’s name. For a countdown, the name works as a fallback feed id, which is why .addwindow roundtime countdown … works with nothing else set. A progress window has no such fallback — naming one health does nothing at all; it needs the Bar id set.

Feed ids are case-sensitive, and a widget bound to nothing draws nothing.

Game gating hides rows; it does not block the command. Both pickers filter by your game, but the six-argument .addwindow form does not check. You can force a GS4-only window onto a DragonRealms character and it will build, sit there, and stay empty. An unset game counts as GemStone IV, which is why GS4 rows show up when you connect through Lich without naming a game.

Placing, moving, and removing works the same for all of them. Drag to move, drag an edge to resize, .hidewindow to hide, .deletewindow to truly remove (deleted windows are stashed and restorable from ↩ Restore deleted…). None of that varies by widget type.

See also

• Creating Layouts — placing, saving, and loading arrangements of these windows
• Build a hunting layout — a worked example that picks eight of them and puts them somewhere
• Command Reference — .addwindow, .hidewindow, .deletewindow, and the rest
• layout.toml — the file all of this writes

[[windows]]
name = "targets"
widget_type = "targets"
title = "Targets"
row = 0
col = 92
rows = 10
cols = 28
show_border = true

Text Windows

Give a stream its own window so the traffic you care about stops scrolling past in the middle of a fight.

What it’s for

GemStone sends far more than room descriptions down the wire. Thoughts, deaths, logons, ESP, bounty updates, society chatter, and your own combat all arrive as separate streams — and by default most of them stack into one column with everything else. The result is familiar: a death message you wanted to read gets three lines of swing-and-miss on top of it before your eye lands on it.

A text window is one scrollable pane bound to one or more of those streams. Point a window at death and death messages go there and only there. Point one at a Lich script’s own stream id and you have a purpose-built readout for that script. Your story text gets quieter, and the things you were squinting for get a place to sit still.

This is also how custom windows work. There is no separate widget for “a window for my script” — a custom window is a text window subscribed to whatever stream id the script pushes.

Set it up

.addwindow thoughts text 0 0 40 10

Common setups

A quiet death log you can actually read back

Deaths matter and they’re easy to miss. Give them a window with timestamps so you can tell whether that was thirty seconds ago or twenty minutes.

In the GUI: Windows ▸ ➕ Custom window… ▸ Text, then right-click it ▸ Window ▸ set Streams to death and Buffer lines to 500. Open Window ▸ Advanced and tick Timestamps, then tick Timestamp at line start so the time leads each line and the names stay aligned down the left.

In the TUI: .addwindow deaths text 80 0 40 8, then .editwindow deaths, put death in Streams, tick timestamps, Ctrl+S.

You’ll see: a short column of death notices, each stamped with its time, sitting still while your main window scrolls.

A bounty window that stops eating a third of your screen

Bounty text is verbose. Compact rewrites it into 1-4 lines, which turns a paragraph into a glanceable objective.

Make a text window subscribed to bounty, then right-click ▸ Window ▸ Advanced ▸ tick Compact.

You’ll see: your current task condensed to a few lines — and the change applies to the bounty already on screen, not only the next update.

⚠️ Compact only affects the bounty stream. It is not a general blank-line remover or a whitespace trimmer. Ticking it on a thoughts or combat window changes nothing at all, which looks like a broken checkbox but is the flag correctly doing nothing outside its one job.

Tips & gotchas

A window that subscribes to a stream always wins. Stream routing has a strict order: a subscribed window first, then a [streams.routes] entry, then the fallback window, then main as a last resort. So adding a stream to a window’s Streams field is all it takes — you never also have to write a route.

Routes only decide where an unsubscribed stream goes. Set one when you want a stream discarded, forced to main, or parked in a window that isn’t subscribed to it. To see the whole picture at once, open the Streams panel — Editors ▸ Streams & Custom Windows, or type .streams. It lists every known stream with its effective destination and lets you change it in place.

⚠️ A route pointing at a window that doesn’t exist does not create one. Windows are never auto-created or auto-opened to satisfy a route; the stream quietly falls through to your fallback window instead. If a route seems ignored, check the window name still exists.

A hidden window still fills its buffer. Hiding is presentation only — text routed to a hidden window accumulates and is waiting when you show it again. That’s the difference between Hide and Delete.

⚠️ .deletewindow truly removes a window in both desktop frontends; .hidewindow only hides it. There is no GUI-versus-TUI asymmetry here. Delete stashes the window so Windows ▸ ↩ Restore deleted… can bring it back with its streams intact, and both frontends refuse to remove your only main-feed window.

⚠️ In the Terminal (TUI), Ctrl+C copies your selection — it does not quit. In the Desktop GUI the same combination quits. Leave the TUI with .quit or .exit.

Word wrap is not purely cosmetic here. For a text window the Appearance ▸ Text ▸ Word wrap checkbox writes to the shared layout definition, so it travels with the window into the TUI and into layout.toml. Most other Appearance settings are GUI-only.

Per-window timestamp settings override the global one. ui.timestamp_position sets the default for everything; a window that has its own Timestamp at line start state ignores it. Change the global in Settings and a window you’ve already customized will not follow.

Scrolling: PageUp / PageDown move a 20-line page in the focused TUI window, Alt+PageUp / Alt+PageDown move a single line, and the mouse wheel scrolls whatever is under the cursor in both desktop frontends. A window auto-scrolls with new text unless you have scrolled back, so reading history doesn’t get yanked out from under you.

See also

• Tabbed Text — several streams sharing one window, with unread badges
• Build a hunting layout — placing and saving a full screen
• Desktop GUI — the Windows catalog and the full right-click menu
• Terminal (TUI) — .editwindow, title-bar dragging, resize handles
• layout.toml — every window field and its default

[[windows]]
name = "deaths"
widget_type = "text"
streams = ["death"]
row = 0
col = 80
rows = 8
cols = 40
buffer_size = 500
show_timestamps = true
timestamp_position = "start"

[streams]
fallback = "main"

[streams.routes]
bounty = "window:bounty"
ambients = "discard"
loot = "main"

Tabbed Text

Stack several streams into one window and let the tab badges tell you which one moved.

What it’s for

Giving every stream its own window works right up until you run out of screen. Speech, thoughts, whispers, group chat, deaths, logons — six windows down a 40-column side bar leaves nothing for the game itself, and most of them sit empty most of the time anyway.

A tabbed text window puts them in one frame with a tab strip. You read one tab at a time, and the other tabs mark themselves unread when something lands. That’s the real payoff: you stop paying screen rent for streams that are quiet, without going blind to them. A whisper arrives while you’re watching combat, the Whispers tab lights up, and you click over when the swing is done.

Tabs you’d rather not be nagged about — a chatty group channel, a logon feed — can be set Quiet, so they still collect text but never mark themselves unread.

Set it up

.addwindow comms tabbedtext 80 0 40 20

[A: Add]─[E: Edit]─[Del: Delete]─[Shift+↑/↓: Re-order]─[Esc: Back]

Common setups

A communication hub

One window carrying every conversational channel, with the noisy one muted.

Make a Tabbed text window and open Edit tabs…. Build four rows:

Timestamps on the three you’ll read back through; Quiet on Group so a busy party channel doesn’t badge the window every few seconds. Click Save.

You’ll see: one window where four used to go, with Whispers badging itself the moment someone whispers to you — and Group collecting quietly, unread mark never lighting.

An activity feed for a hunting screen

Combat, deaths, and arrivals in one 40-column pane so your side bar keeps room for targets and a compass.

Tabs: Combat on combat, Deaths on death, and Arrivals on logons with Quiet ticked — you want to be able to check who walked in without being pulled away from a fight every time somebody logs on.

In the TUI, that’s .addwindow activity tabbedtext 80 0 40 12, then .editwindow activity and A three times.

You’ll see: your fight in the front tab, a Deaths tab that badges when something dies near you, and an Arrivals tab that fills silently until you go looking.

Tips & gotchas

⚠️ The Tab Editor is Save-buffered; the rest of the window menu applies live. This is the one place in the GUI’s per-window settings where your changes are not already in effect. If tab edits “didn’t take,” you closed the panel without clicking Save.

Unticking a stream in Known streams removes it from every tab, not just the one you’re looking at. If that untick leaves a tab with no streams, the tab goes away. Tabs that were already empty — a row you just added and haven’t filled — are left alone. Remove a stream from one tab only by editing that row’s Streams field instead.

The two stream pickers in the Tab Editor are different lists. The Known streams checklist is the full universe the client knows about. The per-row + offers only streams seen this session. A stream you expect that hasn’t fired yet appears in the checklist but not in the + menu.

Quiet is per tab, and it’s about the unread mark, not the text. A Quiet tab still receives and buffers everything; it just never badges. That’s the setting you want for a channel you check on purpose rather than react to.

buffer_size on a tabbed window is per tab, not shared across the window, and it defaults to 10,000 lines.

⚠️ Word wrap on a tabbed window is GUI-only. For a plain text window, Appearance ▸ Text ▸ Word wrap writes to the shared layout definition and travels to the TUI. A tabbed window has no wordwrap field, so the setting is remembered per GUI tab and does not reach layout.toml or the terminal.

Three tab-switching actions exist, and none has a default key. Next Tab, Previous Tab, and Next Unread Tab live under the Tabs category in the keybinds editor. Bind Next Unread Tab if you like — it jumps straight to whatever just badged, which is the whole point of the badges.

A subscribed tab outranks stream routing. A tab that lists a stream receives it regardless of any [streams.routes] entry; routes only decide where unsubscribed streams go. Check effective destinations in the Streams panel — Editors ▸ Streams & Custom Windows, or .streams.

⚠️ In the Terminal (TUI), Ctrl+C copies your selection — it does not quit. In the Desktop GUI the same combination quits. Leave the TUI with .quit or .exit.

See also

• Text Windows — one stream, one window, and the full routing rules
• Build a hunting layout — where a tabbed window earns its keep on a small screen
• Desktop GUI — the Windows catalog and the window right-click menu
• Terminal (TUI) — .editwindow and the editor’s key map
• layout.toml — every window field and its default

[[windows]]
name = "comms"
widget_type = "tabbedtext"
row = 0
col = 80
rows = 20
cols = 40
buffer_size = 3000

[[windows.tabs]]
name = "Speech"
streams = ["speech"]
show_timestamps = true

[[windows.tabs]]
name = "Thoughts"
streams = ["thoughts"]
show_timestamps = true
timestamp_position = "start"

[[windows.tabs]]
name = "Group"
streams = ["group"]
ignore_activity = true

Progress Bars

Health, mana, stamina and spirit as bars you read in a glance — so you never type health with a troll swinging at you.

What it’s for

Mid-fight you need one number: am I still safe? Typing health costs you a line of scrollback and a beat of attention, and the answer is already three exchanges old by the time you read it. A progress bar keeps that answer on screen permanently, filling and draining as the game sends updates, so checking your health becomes a glance instead of a command.

Each bar is its own window, which is the point — you place health where your eye already goes, put spirit somewhere quieter, and skip the ones you don’t care about. Bars are not limited to vitals either: the same widget draws stance, encumbrance level, mind state, and any bar a Lich script invents, because a bar is really just “a number out of a maximum, drawn as a fill.”

If you’d rather have all four vitals stacked in one compact window, that is a different widget — see Mini Vitals.

Set it up

Common setups

A compact vitals strip that shows numbers, not words

You know which bar is which by position and color, so the word “Health” is wasted space — the numbers are what you actually want.

1. Add health, mana, stamina and spirit from the Windows catalog and set each row’s zone to Header.
2. Right-click each bar and tick Show value/max in the widget section.
3. Drag each bar narrower until the four sit side by side across the header.

→ Your header reads 142/193 88/110 95/95 10/10 in dark red, dark blue, orange and gray — four numbers, one row, no labels.

A stance bar next to your roundtime

Stance is a bar like any other, and it belongs beside the timer that tells you when you can act.

1. In the Windows catalog, tick stance. It arrives bound to the feed id pbarStance, titled Stance, in navy.
2. Set its zone to match your roundtime countdown so the two sit together.
3. Right-click it, clear the Label field, and the bar draws its percentage instead.

→ Dropping to guarded shows the stance bar visibly shorter, right beside your RT bar, so “can I act, and how exposed am I?” is one glance at one corner.

Tips & gotchas

⚠️ A progress window with an empty Bar id renders as nothing. It is not broken and it is not invisible-because-of-color — a bar with no feed has no value to draw. This is why creating one from ➕ Custom window… drops you into its menu immediately. If a bar you made is a blank rectangle, that empty field is almost always why.

⚠️ Bar ids are case-sensitive. mindState works; mindstate matches nothing and draws nothing. The same goes for encumlevel and pbarStance — copy the capitalization exactly.

⚠️ Unlike countdowns, a progress window’s name is not a fallback binding. Naming a window health does not feed it; only the Bar id field does. A countdown window will fall back to its name, which is why .addwindow roundtime countdown … appears to work with no id set and the same trick fails completely for bars.

Nothing on a bar changes color at a threshold. There is no low-health red, no flash, no pulse — a bar draws in one solid color at every value, by design. Alerting on low health is a job for a hotbar button’s condition state, an indicator, a sound, or controller rumble; see Make your health bar shout when you’re hurt, which builds exactly that.

Show value only wins over Show value/max. With both ticked you get the bare current number. The precedence is: value-only, then value/max, then your Label, then a percentage when the label is empty.

Feeds that report a percentage have no maximum. Stance arrives as 0–100 with no max, so Show value/max on a stance bar reads 100/0. Leave the numbers off for percent-style feeds and let the fill do the talking.

Encumbrance has a dedicated widget too. encumlevel works as a Bar id if a plain bar is what you want, but the encum window shows the level name with its own color bands — see Encumbrance.

Colors are per bar, and the defaults are deliberately dark. Health is #6e0202, mana #08086d, stamina #bd7b00, spirit #6e727c, stance #000080 — dark enough that the text drawn over the fill stays readable. If you brighten a bar, check the label is still legible against it.

See also

• Mini Vitals — all four vitals in one window, with bar height, bar text, depleted color, and per-bar reordering
• Countdowns — roundtime and casttime, the other half of a combat corner
• Encumbrance — the dedicated encumbrance widget
• Experience — the GS4 window that consumes mindState with its full detail
• Make your health bar shout when you’re hurt — condition-driven low-health alerting, since bars themselves never change color
• Creating Layouts — placing, zoning, and saving windows

[[windows]]
name = "health"          # a label — NOT the feed binding
widget_type = "progress"
id = "health"            # the feed binding
row = 0
col = 0
rows = 3
cols = 20
color = "#6e0202"

Mini Vitals

All four vitals in one strip, the width of a header — for when four separate bar windows are three windows too many.

What it’s for

Four progress bars tell you everything you need, and cost you four windows to place, four borders to align, and four things to re-drag every time you rearrange a layout. Mini Vitals is the same information as one window: health, mana, stamina and spirit drawn side by side across a single row, sized and moved as one thing.

It is also the widget that knows your real numbers. Ordinary bars and the phone’s chrome work in percentages; this one carries 142/193 because the game sends the current value and the maximum together. Pick it when you want a compact strip and exact figures, and pick separate bars when you want each vital in a different corner of the screen.

Set it up

Common setups

A Wrayth-style stats strip across the top of the screen

This is what the widget was shaped for: one row, no title, no wasted height.

1. Add minivitals from the catalog and set its row’s zone to Header.
2. Right-click it ▸ Vitals ▸ set Layout to One row and Bar text to 191/193 — position and color already tell you which bar is which, so the word is spent space.
3. Right-click ▸ Appearance ▸ Frame and turn the border off, so the strip reads as part of the chrome rather than a box sitting on it.
4. Drag the bottom edge until the bars are the height you want, or set Bar height directly.

You’ll see: a single unbroken row across the top of your layout reading four pairs of numbers in red, blue, orange and gray, each fill draining as you take the hit that caused it.

Tips & gotchas

⚠️ In the GUI these settings are shared by every Mini Vitals window; in the terminal they belong to the window. The GUI stores Layout, Bar height, Bar text, Depleted color and the bar list once, in your per-character GUI layout — change them on one window and every Mini Vitals window changes with it. The terminal stores its own set of fields per window in layout.toml. The two frontends do not share these settings at all, so a window you tuned in the GUI arrives in the terminal with terminal defaults, and the reverse.

⚠️ The GUI version draws four bars the terminal version cannot. The GUI’s bar list offers Mind, Encumbrance, Next Level and Blood alongside the four vitals, so one window can carry your health and your encumbrance together. The terminal accepts only health, mana, stamina, spirit and concentration, and silently ignores anything else in the list — a layout using the GUI’s extra bars renders in the terminal with those bars missing rather than with an error.

⚠️ Four bars maximum in the terminal, no cap in the GUI. The terminal’s [ Edit Bars & Colors ] editor refuses a fifth tick. The GUI lets you enable all eight, and they divide the width between them.

This widget and your ordinary bars read the same feed, so both are live at once. The game sends one health update and it lands in every place that wants it: each progress window bound to health, this widget, and the phone’s status row. Running a Mini Vitals strip and a separate health bar is not a conflict and costs you nothing.

The window ships with no title on purpose, which is why the catalog row reads minivitals in lowercase where its neighbours read proper names. Give it a title under Window if you want one, or leave the title bar off entirely.

Current Only beats Numbers Only in the terminal. With both ticked you get the bare current value. The order is: current-only, then numbers-only, then the game’s own text.

Nothing here changes color at a threshold. No low-health red, no flash, no pulse — each bar draws one solid color at every value. Alerting on low health is a hotbar button’s condition state, an indicator, a sound, or controller rumble; see Make your health bar shout when you’re hurt.

Depleted color is the unfilled part of each bar. Leave it empty and the unfilled portion follows the window background, which is usually what you want. Set it to pick out how much of each bar is gone at a glance.

This widget is GemStone IV only. Both pickers hide it from DragonRealms characters — it is absent from the GUI Windows catalog and from the bare-.addwindow picker. The full six-argument form does not check, so it will build the window on a DR character. If the game is not set at all, VellumFE assumes GemStone IV and the row appears, which is why it shows up when you connect through Lich without naming a game.

See also

• Progress Bars — one bar per window, when you want them in different places
• Experience (GemStone IV) — where mind state and next-level get their full detail
• Encumbrance — the dedicated widget for the encumbrance bar
• Betrayer — where the Blood bar’s number comes from
• Dashboard — statuses in a grid, the other “several things, one window” widget
• Injury Display — where you’re hurt, where a health bar only says how much
• Make your health bar shout when you’re hurt — alerting, since bars never change color
• Creating Layouts — placing and saving these windows

[[windows]]
name = "minivitals"
widget_type = "minivitals"
row = 0
col = 0
rows = 3
cols = 80
show_border = true
numbers_only = false
current_only = false
bar_order = ["health", "mana", "stamina", "spirit"]

Countdowns

Roundtime as a shrinking bar in the corner of your eye — so you know when you can swing again without counting in your head.

What it’s for

Roundtime is the metronome of every fight, and the game gives it to you as a number buried in the prompt. Counting it yourself means either firing commands early and eating the “…but you are still recovering” line, or waiting too long and losing the exchange.

A countdown window turns that into something you don’t have to read: a number plus a row of blocks that empties as the seconds burn down. Peripheral vision handles it. When the blocks are gone, you go.

The same widget covers cast time, stun, and anything else with a deadline — a Lich script can push its own timer for a cooldown, a buff about to lapse, or a hunt window closing, and it draws in exactly the same way.

Set it up

Common setups

A combat corner that never moves

Timers that appear and disappear make your layout twitch, and a bar that jumps into existence is harder to notice than one that was always there.

1. From the Windows catalog, tick roundtime and casttime, and set both zones to Footer.
2. Right-click each and tick Stay visible at rest.
3. Leave the default colors — red for RT, deep sky blue for CT.

→ Both windows sit in the footer permanently, reading RT: 0 and Cast: 0 with empty bars at rest. When you swing, the red one fills and drains without a single element shifting position.

A stun timer that works from the game’s own text

Stun has no timer feed of its own. VellumFE ships regex patterns that read the game’s stun messages and drive a countdown from them, which is already wired up before you touch anything.

1. Tick stuntime in the Windows catalog. It arrives titled Stun in yellow, bound to the stuntime feed.
2. Get stunned. The shipped [event_patterns] rules match You are stunned for 3 rounds, multiply the captured rounds by five to get seconds, and push that into the timer. A matching rule on You recover from being stunned. clears it early.

→ A three-round stun fills the Stun window to fifteen seconds and drains it, and recovering before it expires blanks the window immediately rather than letting it run down.

Tips & gotchas

⚠️ A countdown with no Timer id and a non-matching name renders as nothing. The window is there, the border draws, and the inside stays empty forever because no feed reaches it. This is the single most common “my timer is broken” report, and it is why creating one from ➕ Custom window… opens its config straight away.

⚠️ Timer ids are case-sensitive. roundtime works; Roundtime matches nothing.

A timer window matches on its Timer id or its window name. Both are checked, which makes .addwindow roundtime countdown … work with nothing else configured. It also means a window you name after a feed picks that feed up whether you meant it to or not — worth knowing before you name a custom timer casttime.

Timers hide at zero unless you tell them not to. Default behavior is to vanish when they expire, which keeps a busy layout quiet. Stay visible at rest keeps the label and a 0 on screen with an empty bar, so the window never appears or disappears. Pick whichever bothers you less; the setting is per window, so RT can stay put while a rarely-used timer hides.

The block count is bounded by window width, not by the timer. A sixty-second timer in a twenty-column window shows the number 60 and fills every available cell — the blocks measure “how much is left of what fits,” while the number is always exact. Widen the window if you want finer-grained visual resolution on long timers.

Four things can drive a timer. Native roundtime and casttime from the game; a [event_patterns] rule whose event_type matches (this is how stuntime is fed, and stun/rt/ct are aliased to stuntime/roundtime/casttime); or a script sending <vellumTimer id='...' value='epoch'/>, where value is the absolute epoch second the timer ends and 0 clears it.

Countdown color is split across two settings. Fill color in the widget section colors the number and the blocks. The window’s own background is under Appearance ▸ Frame. The shipped presets set their color as the window’s text color, which is why RT is red and CT is blue out of the box.

See also

• Progress Bars — health, mana, and stamina, the other half of a combat corner
• Mini Vitals — all four vitals compactly, to pair with your timers
• Hotbars — buttons that gray out during roundtime, using the same Roundtime active and Casttime active conditions
• Wire a hotbar for combat — timers and buttons working together
• Highlight Patterns — the pattern system [event_patterns] sits beside
• Creating Layouts — placing, zoning, and saving windows

[[windows]]
name = "roundtime"        # also acts as a fallback feed match
widget_type = "countdown"
id = "roundtime"          # the explicit feed binding
row = 0
col = 0
rows = 3
cols = 20
text_color = "#FF0000"
show_when_zero = true

[event_patterns.stun_rounds]
pattern = '^\s*You are stunned for ([0-9]+) rounds?'
event_type = "stun"
action = "set"
duration = 0                 # 0 = use the captured value
duration_capture = 1         # 1-based regex capture group
duration_multiplier = 5.0    # rounds → seconds
enabled = true

[event_patterns.stun_recovery]
pattern = 'You recover from being stunned\.'
event_type = "stun"
action = "clear"
duration = 0
duration_multiplier = 1.0
enabled = true

Compass

See every exit the room actually has, and click one to walk it — no guessing which directions the room accepts, no typing n into a wall.

What it’s for

The Obvious exits: line tells you where you can go, then scrolls away. So you guess, and the game tells you that you can’t go that way, and you guess again — which is a small tax you pay in every unfamiliar room and a real one when something is chasing you.

The compass shows the current room’s exits as a lit rose, updating the moment you arrive. Lit directions are real exits; the rest stay faint. Click a lit one and you move. It’s the fastest way to feel out an unmapped area, and it never scrolls off.

Set it up

Common setups

A big rose in the corner of a hunting screen

Add the compass, send it to the Right Bar, then drag its corner out until it’s as large as you want. Right-click ▸ Appearance ▸ Frame and turn the border off so the art sits on your background with nothing boxing it in.

You’ll see: a large, borderless rose you can hit without aiming, with the room’s real exits lit.

A thin strip that doesn’t cost you screen

Drag the compass window’s side edge inward until it’s narrow. The rose holds its size and the window just gets tighter around it, down to a 48-point floor — narrower than any other widget is allowed to go.

You’ll see: a compass small enough to tuck beside a vitals bar while staying clickable.

Tips & gotchas

⚠️ The compass window is free-form — it is not locked to a square. The rose paints as a centered square of whichever side is shorter. Drag one edge and the window grows while the art holds its size and the extra space pads evenly around it. Drag both and the art scales up with the window.

⚠️ Compass windows have a 48-point minimum width; every other widget stops at 120. If you’re wondering why the compass shrinks past where your other windows stop, that’s why.

“Skin default” and “None” are different answers. Skin default takes whatever rose your active skin ships, so changing skins changes your compass. None pins you to the built-in vector rose, which follows your theme’s link color for lit exits and stays put across skins.

Up, down, and out are in the rose, not beside it. Skinned sets have them drawn in; the vector rose puts them at the hub. Nothing lives in a side column, which is what lets the window shrink to 48 points and stay usable.

A dim direction is not a broken compass. The rose lights what the game reports for the current room. Unlit means the game didn’t list that exit — including hidden ones you haven’t found yet.

See also

• Room Window — the same exits as text, alongside the description
• Map — where those exits lead, once you’ve walked them
• Travel (.go2) — walking somewhere further than one room
• Skins (GUI Graphics) — where compass art comes from and how to install sets
• Build a hunting layout — placing the compass in a combat screen

[[windows]]
name = "compass"
widget_type = "compass"
title = "Compass"
row = 15
col = 92
rows = 5
cols = 9
show_border = true
border_style = "rounded"

Hands

Know what’s in each hand and what spell you have prepared, at a glance — instead of burning a round on inventory to find out you’re holding a shield you meant to drop.

What it’s for

You swap weapons, you get disarmed, you prepare a spell and then take a hit and lose track of whether it’s still there. The game will tell you, but only if you ask, and asking costs you the moment you needed the answer in.

The hand windows keep all three slots on screen: left, right, and the spell you have prepared. They’re one line each, so they cost almost nothing, and the item names stay clickable. In the desktop GUI they can go further — the icon itself can change based on what you’re holding, so “empty hand” and “axe in hand” look different from across the screen.

Set it up

Common setups

Three lines stacked under your vitals

Add all three hand windows and send them to the same zone, one under another, in the order left, right, spell. Right-click each ▸ Appearance ▸ Frame and turn the border off so they read as one block instead of three boxes.

You’ll see: a three-line readout under your bars — both hands and your prepared spell, updating as you swap gear and cast.

An icon that changes when your hand is empty

Right-click your right-hand window ▸ Hand icons… and add two states, in this order:

1. Hand empty (right) → pick an open-hand image.
2. Hand holds → weapon (right) → pick a weapon image.

Save, then drop what you’re holding.

You’ll see: the icon flip to the open hand the moment the weapon leaves, and flip back when you pick it up — visible from across the screen without reading a word.

Tips & gotchas

⚠️ The first matching state wins. States are checked top to bottom, and a broad condition placed above a narrow one swallows it. Put Hand holds → a specific item above Hand holds → weapon, or the specific rule will never fire. If nothing matches, the window falls back to its static icon and colors.

⚠️ Which hand a window shows comes from its name, and the fallback is the spell hand. A name containing “left” is the left hand, one containing “right” is the right hand, and anything else — including a typo — becomes the spell hand. If a window named rigth is showing your prepared spell, that’s why.

Drag a hand window taller to get bigger art. In the GUI the icon fills the window’s height, so a one-line hand gets a small icon and a window dragged to two or four lines gets large art. The configured icon size acts as the floor, not the size.

Hand icon states use the same condition language as hotbar buttons and indicators. Learn it once and it transfers — Hand empty, Hand holds, Spell prepared, Roundtime active, Vital, Injury, and the rest, grouped with all of / any of. If you’ve built a combat hotbar, you already know this editor.

Empty reads differently in the spell slot. The two physical hands show Empty when you’re holding nothing; the spell window shows None when you have nothing prepared.

See also

• Wire a hotbar for combat — the same condition vocabulary, on buttons
• Indicators — status icons driven by those same conditions
• Inventory — everything you’re carrying, not only what’s in hand
• Skins (GUI Graphics) — where hand icon art comes from
• Build a hunting layout — where the hand windows sit in a combat screen