Skip to content
GeneStevensPublic

About

SEQ Terminal UI

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

seq-tui

seq-tui is the terminal client for SEQ. It is a thin client (seq-design docs/07): it renders state it is given and sends explicit player intents, and owns no gameplay truth.

Design lives in the seq-design repo. This repo is at milestone M9 (M8 and the playing-together layer below): a human can make a character of one of the six classes, play the placeholder zone in a terminal against a local server with the ability bar on keys 1 to 8, mana, casts, cooldowns, effects, levels and XP, open an instance, walk in, and play it, including turn-based rounds with plans; and (D50) the class menu from the server, who in the party has submitted, effects seen on login, slots changed between rounds, casts that land in a later round, gear, loot, crowns, vendors, trainers, the binder, the bank, trade between characters, and the Peril fee; and (M8 content) Thornwick and the Thornwick Downs: talking to the people, the contract board and the Contracts panel, timed world events and roaming rares, and a map that scrolls with the character and shows the whole zone on a key; and (M8n) the Watch Captain's companion quest, choosing a recruit's role, a Companion panel with stances and orders, and a second character of the account played by a stance; and (D53, D54) the world from seq-world, and the ground of its zones: buildings, rock, water, fords and bridges, forest, roads and tunnel floor, and the patrol paths of mobs; and (D55) the server's own event names, quest steps, speed, mana, markers and zone ground, owed pay, and a duo in turn-based play; and (M8 cleanup, D56) no companion UI with the default setting, directing your second character from one session, the zone map without patrol paths, markers by their display names, owed pay listed at login, and a duo through the Warren; and (M9, D58) playing together: chat, parties across accounts, who and friends, and a Warren room cleared by two accounts.

  • model/: a pure Go type built only from protocol messages (snapshot, events, intent results, zone map): you, entities in view, drops, encounters, the map, a bounded event log that keeps each event's reason, and the status of recent intents. It tracks the per-character stream number and takes each event exactly once (D39). Text() prints it as plain text.
  • client/: a Session on the agent toolkit's connection (agentkit from the seq module, which owns the WebSocket, the login and the resume); its raw-message hook records each message and feeds the model. One command per intent (Move, Stop, Target, Attack, Loot, UseDoor, Release, UseAbility, SetSlot, Logout), and Connect, CreateCharacter and Select for a new character with Result matching each intent_result. There is no transport of the TUI's own.
  • sessionlog/: the player's own log of every session (D64). The program records each session by default, under its play-session id, in a directory of its own under the data dir (~/Library/Application Support/seq-tui/sessions on macOS, $XDG_DATA_HOME/seq-tui/sessions on Linux, or -log-dir): record.jsonl (every message the server sent, the format of -record and of seq-mcp's log) and session.json (the id, server without user info or query, character, zone, versions, start and end). One recording is capped at 32 MB and the directory at 256 MB (the oldest sessions go first); the credential is scrubbed from everything written. -no-record turns it off. Ctrl+L opens the sessions view (in play, and on the character creation screen): the recordings on this machine (Enter replays one in place, with Left and Right to step; E exports it to exports/ beside the sessions) and the server's own list of the account's sessions (Enter reads the server's log as lines; E exports it). -replay takes a file, a session directory or a session id.
  • record/: records a session's incoming messages as a log (one protobuf-JSON message per line) and reads it back.
  • testdata/logs/: recorded logs the tests replay into the model with no backend. Tests only read them. fight_loot, kill_steal, crossing and drop_resume are built by hand (go run ./cmd/mkfixtures testdata/logs); play, release, door, solo_trial, quick_turns, duo_turns, wizard, casts, warrior, levelup, turn_cast and the companion_* and duo_guard logs are the sessions of the client scenarios, recorded by them (make fixtures). A scenario writes # mark NAME lines into its log at the points it names; the render tests and model tests replay a log up to a mark (file@mark), so a regenerated log moves nothing.
  • scenario/: the client scenarios (below).
  • screen/: the screen as a pure function from the model to exactly W x H cells (minimum 80x24): the top-down map (walls, bounds, doors, you, mobs with your target highlighted, drops), the You, Target and Nearby panels, the ability bar, the slot screen, the character creation screen, the event log with the reason on every denial, the status line and the help panel. Colour only repeats what glyphs and words already say, and nothing shows what drives another character (D17).
  • app/: the Bubble Tea v2 program: keys to the client's commands, the model to the screen.
  • testdata/screens/: golden screens at 80x24 and 140x45 of the recorded logs, replayed to a mark. testdata/scenarios/: golden screens drawn by the real program in a scenario, at the same two sizes. Tests only compare; make golden rewrites both (review the diff).
  • cmd/seq-tui: the program. cmd/mkscreens: half of what make golden runs. cmd/mkfixtures: the hand-built logs.

The protocol types and the connection come from the seq module (protocol/seqv1, agentkit), pinned in go.mod.

Private module access (one time)

seq is private. Go must skip the public proxy for it and fetch it with git over ssh:

go env -w GOPRIVATE='github.com/GeneStevens/*'
git config --global url."git@github.com:".insteadOf "https://github.com/"
ssh -T git@github.com            # should greet you by name

make play downloads the module itself (go mod download) before it asks Go where it is. If the download fails it retries once with that same setup applied for the run only, and if that fails too it prints the go error and the three lines above and stops; it never carries on with an empty path. It also checks that docker is running.

Playing

make play                # Thornwick, on a world that is kept between runs; asks which character to play
make play-web            # the same world, in the browser, on http://localhost:8480 (no proxy or certificate)
make play-testgrounds    # the engine's test zone (me-1), on a database thrown away on quitting: for tests and quick checks
make play-reset          # wipe the kept world, after asking

make play (scripts/play.sh) starts a local seq server on PostgreSQL in docker (OrbStack's), builds the pinned seqd, and runs the TUI on it; quitting stops both and keeps the world. The server serves seq-world's packs, so a new character starts in Thornwick (the start zone of the thornwick pack; the script stops if the server says otherwise). It needs docker and the private-module access above.

  • The picker. With no -character, the TUI connects, asks the server for the account's characters, and opens a Choose a character screen: one row for each (name, class, level, zone, last played), the one played most recently first and chosen, and Create a new character after them. A character that a connection is playing now shows online (in use) in the last column; picking it is refused by the server (character_in_use) and the picker stays open, so log it out where it is played first. Up / Down (or W / S, 1-9) choose, Enter plays, N makes a new one, Esc on the creation screen goes back, Ctrl+C quits. An account with no characters goes straight to the creation screen (a name and a class; the server puts you in Thornwick). SEQ_NEW=1 make play (-new) skips the picker for the creation screen; SEQ_CHARACTER=ID make play (-character ID) plays that character directly.
  • Where the list comes from. The server (its list_characters request, SEQ-093), so the picker shows exactly the account's characters, including ones made some other way. The TUI keeps no list of its own; the old seq-data/roster.json and the -roster flag are gone (a leftover file is ignored and can be deleted). The class column is the class id written as a name, since the class definitions arrive only with a character's first snapshot.
  • Where the world lives. In the docker volume seq-tui-world_pgdata (project seq-tui-world, PostgreSQL on 127.0.0.1:55433), which holds the characters. Quitting runs docker compose down, which keeps the volume. seqd applies the database migrations still pending each time it starts, so a kept world is brought up to the pinned server's schema before you play. Back it up with docker exec seq-tui-world-postgres-1 pg_dump -U seq seq > seq-backup.sql while make play is running (restore with psql the same way). docker volume ls shows the volume.
  • Reset. make play-reset shows what it will delete and wipes the volume only if you type yes. Characters, items and progress are gone; the next make play starts a new world.
  • Zehen. The old make play database was a throwaway (tmpfs), so a character made before this change, Zehen included, is gone; make a new one.
  • Testgrounds. make play-testgrounds (or SEQ_TESTGROUNDS=1 make play) is the old setup: the same server with new characters starting in Testgrounds (the engine's test zone, with its builder names), the development characters me-1 and me-2, me-1 played with no picker, and a database that goes with the container (docker project seq-tui-play, port 55432, no picker). From Testgrounds you can walk to the zone line in the east (D on the map; Nearby lists it) and press E there to cross, and E again at the other side to come back.
  • Settings. SEQ_ADDR (the server's address), SEQ_PG_PORT, SEQ_PLAY_PROJECT (the docker project, so the volume), SEQ_WORLD_PACKS=DIR (serve a seq-world checkout's packs instead of the pinned one), SEQ_PLAY_DRY=1 (print what would run and stop). make play starts seqd with -dev-testers=false, so the development account holds no Testgrounds testers (player-1, player-2) and the picker lists only what you made; the Testgrounds setup keeps its testers.

make play-web is make play for the browser, in one command: the same server and kept world, but it builds the page (make web) and has seqd serve it itself (-web-dir, -plain-http on loopback), so there is no Caddyfile, certificate or second terminal. It prints http://localhost:8480/ (port 8480, so it can sit beside make play's 8443; they share one database container, so do not run both at once) and, while sign-in is off, a development token to paste into the page. To try the real sign-in on a Stytch Test project, set SEQ_STYTCH_PROJECT_ID, SEQ_STYTCH_DOMAIN, SEQ_STYTCH_PUBLIC_TOKEN and SEQ_STYTCH_SECRET in the environment before make play-web; they pass through to seqd (docs/browser.md says what to set up in Stytch, with one Redirect URL per host: http://localhost:8480/auth/callback here, and the commands for bash, zsh and fish). Open the page as localhost, not 127.0.0.1: Stytch matches the Redirect URL exactly. SEQ_ADDR changes the address (it must stay on loopback).

Without the scripts:

SEQ_SESSION_TOKEN=seq_st_... go run ./cmd/seq-tui -insecure -url wss://127.0.0.1:8443/seq/v1 [-character ID | -new] [-record log.jsonl]
go run ./cmd/seq-tui -replay testdata/logs/fight_loot.jsonl [-size 140x45 | -text]

-insecure accepts the development server's in-memory certificate and works for loopback addresses only.

Play in the browser

The same program also runs in a web browser (seq-design D106): compiled to WebAssembly and drawn by xterm.js, talking to the server over the same WebSocket.

make web          # web/dist: the page, seq-tui.wasm (about 3 MB downloaded with brotli), each file also as .gz and .br
make web-smoke    # builds the wasm and runs it under Node: first screen at 80x24, a resize, q to quit (part of make verify)

Serve web/dist on the same origin as seqd (a Caddy proxy for /seq/v1, no server change), open the page and paste a session token; docs/browser.md has a sample Caddyfile, local development with an mkcert certificate, and what the page does. Not in the browser build: duo mode and session logs. Bubble Tea v2.1.0 has no js build, so third_party/bubbletea is a copy with one added file (tty_js.go); docs/upstream-bubbletea-js.md has the patch and the text for an upstream pull request.

Play on play.spielengine.com

The M11 playtest server is at https://play.spielengine.com/. Both clients need an invite code (it starts seq_inv_): ask Gene for one, and keep it private. It is read from the environment, never from a flag.

In the browser (nothing to install): open the link and choose Sign in with Google, or enter your email and choose Email me a sign-in link (open the link on the same device; Use a code instead sends a code to type in). The first time you get a new account; after that the page remembers you and shows Welcome back with one Play button (and Sign out). The game then asks which character to play. If you already have a SEQ account from an invite code, the first sign-in offers Already have a SEQ account? Link it: enter the old invite code (or a session token) once and your characters come with you. Other ways to sign in (under the sign-in) keeps the old field for a pasted invite code or session token. The page connects back to the host it came from (wss://play.spielengine.com/seq/v1, from location; there is no host in the page), so it works the same behind any TLS-terminating proxy that serves seqd with -web-dir.

In a terminal on a Mac, either way:

  • Download (no Go needed). Gene publishes seq-tui-<version>-darwin-arm64.tar.gz (Apple silicon) and ...-darwin-amd64.tar.gz (Intel) on the repo's Releases page, with SHA256SUMS. Check the sum (shasum -a 256 -c SHA256SUMS --ignore-missing), unpack (tar xzf seq-tui-*.tar.gz), then clear the quarantine flag once, since the binary is not signed: xattr -d com.apple.quarantine ./seq-tui (or right-click it in Finder, choose Open, and confirm).
  • Build from the repo (you have been invited to it): install Go, set up private module access (above), then go build -o seq-tui ./cmd/seq-tui.

Then sign in once, through the browser:

./seq-tui login -url wss://play.spielengine.com/seq/v1

It prints a code like BCDF-GHJK and an address, tries to open your browser on it, and waits. On the page (/activate) sign in if you are not already, check that the account named there is yours and the code matches, and choose Approve. The terminal notices by itself and saves the sign-in in ~/.config/seq/play.spielengine.com.session (a file only you can read; $XDG_CONFIG_HOME/seq if set). From then on a plain run needs nothing else, and lands on the character picker:

./seq-tui -url wss://play.spielengine.com/seq/v1
./seq-tui logout -url wss://play.spielengine.com/seq/v1     # forget the saved sign-in

If the saved sign-in has run out (it lasts 90 days) or is refused, the program says so and runs the login again. SEQ_SESSION_TOKEN=<an invite code or session token> still overrides all of this, for development and tests; an invite code works that way too (-new makes a character).

The server has a normal public certificate, which the program checks against the system's trusted certificates; do not use -insecure.

Found a bug? Type /bug and what went wrong (/bug the ferry sign has a typo), in the terminal or the browser. It goes to the game masters with where you were; the log answers "bug N".

Gene: publishing the Mac download. make release-mac (or make release-mac VERSION=v0.1.0) builds both architectures and writes dist/release/seq-tui-<version>-darwin-{arm64,amd64}.tar.gz and dist/release/SHA256SUMS. It publishes nothing. Check the files, then create the release yourself:

make release-mac VERSION=v0.1.0
gh release create v0.1.0 dist/release/*.tar.gz dist/release/SHA256SUMS --repo GeneStevens/seq-tui --title "seq-tui v0.1.0 for Mac" --notes "Unsigned Mac build for the play.spielengine.com playtest. First launch: xattr -d com.apple.quarantine ./seq-tui"

Playing together (M9, D58)

Chat, parties, who and friends are the server's social requests, not intents (client.Session.Social and its wrappers on the toolkit's connection): each is answered by one result, with the refusal's reason when it is refused, and the status line says it in words. The model keeps what the server tells (model.Social: the chat scrollback of 500 lines, the party, the invitation waiting, the characters the who list named, the friends list); chat is not an event, so a resume does not replay it.

/ opens the command line (the slash is in it already; Backspace takes it away to say a plain line). Enter sends, Esc cancels. Text with no command is a say, heard by the characters within 40 m.

command does
/say TEXT, /p TEXT, /tell NAME TEXT, /r TEXT say, party chat, tell one online character, answer the last tell
/mute NAME, /unmute NAME, /mute hide a character's say and tell from you; the list
/invite NAME, /accept, /decline, /leave, /kick NAME, /party parties; the leader invites and kicks
/status away, /status autopilot, /status clear your status (D79): a word beside your name in who, the party and the You panel; it has no reward effect
/who zone=NAME class=ID 3-7, /friends, /friend add NAME, /friend remove NAME, /anon on the who list (every filter optional), the friends list, hiding your zone
/chat the Social screen on the scrollback

Chat on a small screen (D101, TUI-042): the bottom row is one tabbed panel, Events | Chat | Party ([ and ] turn the tabs, and clicking a tab does too), each with an unread badge (Chat •3) that clears when the tab is shown (marked read by the program after a drawing that showed it, never by the drawing itself); while another tab is shown the newest chat line runs along the panel's top border. A say from a character in view shows as a bubble by it (24 characters, then …) for about 4 seconds, in open ground and clear of the labels; the log has the whole line, and party and tell are never bubbles. A tell, or a line with the character's own name in it (a whole word, any case), is a one-line toast on the status line (✉ Mira: group for the Warren? r reply) for a few seconds and then a count (✉ 2) until the Chat tab is shown. Shift+C lifts a drawer of chat over the lower half of the map (the vitals and Target panels stay) with scrollback (PgUp / PgDn, the wheel, End; the arrows and the other movement keys still walk the character) and a filter (Tab: all, say, party, tell); Esc drops it, it drops by itself when something starts attacking the character, and opened in a fight it says so (D75: danger is never hidden). In a fight the panel shows Events whatever tab was chosen and chat is the badge and the border line; when the fight ends one Events line says While fighting: 4 chat (2 party, 1 tells). The command line shows the channel it sends on ([say] >, [party] >, [tell Mira] >, or [cmd] > once the text is a slash command): / opens it as a command (as before), Backspace on the slash or Tab makes it a chat line, Tab goes say → party → the character told last, and R (for a living character; the dead use it to release) opens a reply to the last tell. Colour is one palette (screen.ChatPalette in screen/style.go): a colour for each channel (say plain, party cyan, tell yellow, a server or GM line bold yellow) and for each kind of name (your own green and bold, a player you can see or who is in your party blue, an NPC magenta); a line that names you starts with » in bold. Every channel is still tagged ([say], [party], [tell]), and NO_COLOR keeps all of it (your own name is underlined). The Social screen (/chat, /who, /friends) has the tabs Chat (Up / Down, PgUp / PgDn, End scroll the scrollback), Who and Friends (Up / Down choose, I invites, F makes a friend, D removes one, R asks again; Tab switches, Esc closes). OOC, reports and names (D101, TUI-043): Tab on the command line also reaches [ooc] > (/ooc TEXT says it; /ooc off and /ooc on switch hearing and speaking on it, kept by the server and told to the client at login and on every change (/ooc alone says which it is); an ooc line is grey, tagged [ooc], in the Chat tab and drawer, never a bubble). /report NAME reason files a report with the game masters and shows the server's acknowledgement. Chat from a current server comes with its parts: each character is coloured by its kind (player blue, NPC magenta, game master bold yellow, yours green and bold; the colours are slots in screen.ChatPalette, with Item left for item tiers) and is a link in the Chat tab and the drawer: click it, or Shift+N selects the first name (Tab / Shift+Tab step, Enter opens, Esc lets go) and the card (/whois NAME too) shows class, level and zone (or anonymous, offline, unknown) with Tell, Invite, N ignore and Report (asks why). Your own name opens nothing; an old server's lines, with no parts, are drawn as before without links. A party invitation is a prompt across the top: Y accepts it, N declines it. The Party panel lists the other members (* leads) with health, mana, level and zone; a member out of view is shown with the zone and level the who list gave. A friend logging in or out is a line in the log. Any member can open an instance with I; the others see instance opened for your party and enter at the door, and in a turn-based one the Round panel marks each member's plan as the server tells it. Inside an instance (D79) the Instance panel says the group tier and how many different players set it, and what the instance stirred; the Party panel lists the slots from the server's holder list (D82): each slot's character and player ("Player 2", the same for everyone and nothing of the account), marked you and yours for your own characters, empty when its holder left (open to a replacement) and reserved when nobody has entered it yet, and says when a replacement may join (between encounters) or waits; a replacement is told the tier and the Stir state of the instance it joined, and a personal reward is shown in the server's first-person words ("Your account's bonus roll for the Hollow Warren's Chief: Pate Cleaver."), with a line when the account's other character took it; a refusal (one expedition for each account, a join in the middle of an encounter) shows the server's words in the Instance panel; the log says what became of an account's personal reward. The help (?) has a page on all of this and a Group rules page drawn from the server's instance menu.

Danger and legibility (D75, D76)

Danger is never hidden. The traders, talk, board and contracts screens are panels in the map's area (on a window wide enough, 140 columns or so), with the You, Target and Nearby panels beside them; on a narrow one they take the width but keep a line of vitals (your health, your target, what attacks you) under them. Every other screen keeps that line too. When a mob attacks you (self.in_combat, attackers, and the attack_began event) the screen's border turns red and says so, the status line names the attacker and your health ("⚠ Meadow Wolf is attacking you — HP 113/130 — Esc to fight"), a hard or deadly mob is called out as DANGER (on the map as well), and the You panel says "in combat". Nothing closes by itself. The server offers the attacker as your target, so leaving the screen and pressing F fights back. -bell also rings the terminal's bell at each attack (off by default).

A window stays with its person. A traders', talk or board screen holds the NPC's id, not a place in a list sorted by distance, so a guard walking by changes nothing; it closes only when you are out of the NPC's reach, with a line on the status line saying so.

Legibility. Each role has a glyph: T trainer, $ vendor, B banker, H binder, g guard, Q quest person, & board, D door. The server's objective hints draw the marks: a gold ! for something new, a gold ? for a hand-in that is ready, a grey ? for a quest in progress, a gold board, gold quest mobs, and a gold D for the next door; an arrow at the edge of the map (◄ Gorran 23m) points to an objective that is off it, and the status line names it with its direction and distance. Titles ("Gorran Stoutarm ") and the place name come from the server. Nearby lists what matters to the quest first, with tags ([step 2], [2/3], [new], [next door]). ░ is the edge of the zone. The legend is on the second page of the help and on the zone map (M): one line for each kind (You, People, Quest, Events, Creatures, Ground), every glyph in the colour and style it has on the map (the legend and the map draw through one style table, which a test holds them to). A line above the status line says which key does what next to a door, a person, a drop or a mob.

A readable log. The log shows the server's own words for every event (Event.text, Denied.text), never an id or a coordinate, and hides regeneration ticks and movement (V shows them). A level gained is a banner across the top for a short while (the new level, health and mana gained, what can be trained and where); a contract handed in shows what it paid in the board panel; a finished contract says where to hand it in.

The mouse and the character sidebar (D77, D78)

The mouse is a convenience; every action has a key and the game is fully playable without it (-no-mouse leaves the terminal's own mouse alone). The program asks the terminal for clicks, the wheel and motion (xterm modes 1003 and 1006, SGR reports; Bubble Tea's MouseModeAllMotion). Shift+click is never used: terminals keep it for selecting text.

A plain click never moves the character; Option-click (Alt-click) is the only mouse action that walks (D109), the same in the terminal and the browser, so that clicking around to look at things cannot send you off. If your terminal keeps Option-click for itself, click the thing (or the ground) and press W: it walks to what you clicked, else your target, else the spot you clicked.

Mouse Key
Option-click the ground (on the map or the large map): the server plans the route and you walk there; routes stay inside the zone. A plain click on the ground only lets go of the selection (the first time it says how to walk) tap arrows or WASD to step 3 m, hold to walk (let go to stop); on the large map the arrows move a cursor and Enter walks there; Esc stops an Option-click walk; click, then W, walks to the spot
Option-click a mob: walk up to it (following it as it moves; the client re-sends the move, the engine has no follow) and start attacking once in melee reach (2.5 m). Esc, a movement key, or a plain click on the ground cancels click it, then W
First click on a mob or a person (a click within one cell of it counts): selects it (a mob becomes your target) and opens a small card: name, title, level and difficulty, what they offer. A first click never attacks Tab (target); the Target panel and Nearby say the same
Second click on the selected mob attacks (no movement, and not sent again when you already attack it; out of reach the hint and status lines say "Too far: N m. Option-click the target to close in"; the card says "Attacking · F: stop"); on a person it talks. A person or loot out of reach says "Too far (N m): Option-click to walk there"; Option-click walks up and talks or loots F attacks, G talks
Click loot: loot-all within reach L
Hover: a name-and-title label by the pointer (a drop also says how it compares with what you wear; a marker says its name and kind; your own @ says who you are, your level, where you stand and where you are walking to; a shut door says so) Nearby lists the same
Option-click a named marker (a scout point, a world event's spawn or goal): walks there, like the ground arrows, or the large map's cursor and Enter
Hold Alt over the map: everything on it is labelled Ctrl+A turns the labels on and off, for a terminal that sends no Alt with the mouse
Shift+L look: the full "Wears: …" of the person or mob nearest you (or the large map's cursor), on the map's card. The Target panel carries the target's "Wears:" line (agentkit's phrase; a mob's appearance), and hovering a person names their class and level (D197.10)
Scroll wheel over the map: zoom the map (and the large map) + and -
Scroll wheel over the bottom panel (Events, Chat, Party): scroll it back 3 rows (never zooms the map) PgUp / PgDn, Home, End
Right-click, or Esc: let go of the selection Esc

M opens the large map: the whole zone you have seen at full size, the places' names (streets, squares, buildings, gates, fields), the quest marks, the legend, and the vitals strip under it. Option-click a spot to walk there. The wheel (or + and -) zooms in on your character. Reading it (D120). Each named place has one label, even where it is made of several areas (Eldbury Ring, the Hoarstones, the huts), written at the middle of all of them; a name is never written over a road, water, a ford, a bridge, a door, you, your objective or any mark, and is left out if no spot beside the place is free. At the widest zoom only places spanning at least 8 columns of the map are named (the town approach, the Mere, the woods and the roads; not a hut, a stone or a sheepfold pen); each step in zoom names more, and holding Alt (or Ctrl+A) names every place. Open ground is blank, a road is a bold dotted line (·), a forest is a stipple of " on every other cell, and the camps (c) are left out until you zoom in. You are a reverse-video @. The legend lists only the marks on the map being shown: in a window 100 columns or more wide it is a column beside the map, so the map is as tall as the window; in a narrower one it is below, and in a window too short for it a line says it is on page 2 of the help.

The character sidebar (D78). Beside a vendor, trainer, bank, contract board or conversation, a sidebar keeps your character in view under the You panel: Gear (what you wear, with the slots in words: "Main hand", "Ring 1"), Bags (what you carry, identical things stacked: "Wolf Pelt ×2", with the slots used) and Stats (the server's character sheet: health, mana, armour and what it cuts, accuracy and the chance to hit, what your swing does now, bare hands too — "Fists: 7–13 / 2.0s" — and each attribute with what gear adds). C turns to the next tab, a click on a tab picks it, PgUp / PgDn or the wheel scroll. In a window too narrow for it (80 columns), the sidebar is a drawer: C swaps it in for the screen, C or Esc swaps it back, and the vendor's window is still there.

Every item says how it compares with what you wear in its slot (the server works it out, D78): ▲ upgrade, ▼ downgrade, = about the same, x your class or level cannot use it (the line says why, and it is greyed out). The mark is on vendor lists, bags, the bank, loot (Nearby, hover), and contract rewards ("Pays 21 XP and Tin Ring ▲"). The highlighted item's card says what it is, what it adds, what it costs or what a vendor pays, and how it compares ("upgrade over an empty main hand: +1.5 damage/s"). What you cannot afford is greyed out with how far short you are ("120, short 90"). At a vendor J sells all junk in one go (things with no gear slot that no contract of yours wants), A sells the whole stack under the cursor, Enter one. L loots everything within reach and the log shows one line: "You took Worn Cap, Scuttler Blade, 5 crowns". The first time you hold an item that is "tradable once", the log explains it.

Auto-retaliate (D85). The You panel shows Auto-retaliate: ON under Auto-attack (on a short screen, 24 rows, it shares the attack row: Atk ON | Retaliate ON). Ctrl+R sends the auto_retaliate intent for the opposite of what the snapshot (self.auto_retaliate) or the last auto_retaliate_changed says; the server's words ("Auto-retaliate is off") are in Events. While you are under attack with it off the hint line offers Ctrl+R.

Names on the large map, tips and grouping (D121; TUI-075). The size rule above stays for big places; a small place is also named at any zoom when it matters: it has a building, a person (a quest person, a vendor, a trainer, a binder), a door, or your current objective (model.PlaceLabel.Sig). Names are written most significant first: your objective, then quest people, then other people, then doors and buildings, then by size. A place made of pieces is named at the middle of all of them when the pieces form one cluster, and otherwise beside its largest piece. The cluster test: the pieces (areas of one name) are linked when the gap between their bounding boxes is at most 40 m (model.ClusterGapMm), hop by hop, so Eldbury Ring's four banks, 21 to 33 m apart, are one ring, and two copses a field apart are two clusters. Places left out are not lost: those near a name (within 12 columns and 6 rows of it) are counted under the most significant name there, "Goblin Hut +2". The tip. On the large map, hovering the mouse (mouse-motion reporting, where the terminal and xterm.js give it) or moving the cursor with the arrows onto a spot shows a one-line tip beside it naming the places there, "Goblin Hut · Goblin Rocks"; on a name written "Goblin Hut +2" it lists the names counted under it. The cursor works everywhere; the cursor on a person or a door also says who. Ctrl+A (everything named) leaves nothing to count. At 80 x 24 the Downs overview is only 23 columns wide and has room for fewer names; the rest are counted. The Downs goldens (testdata/downs/downs_wide_overview_*) show Barleycross, Eldbury Ring, Eelmere, Fordwatch and the Goblin Stockade named at the three sizes.

Times (D121; TUI-075). The Events, Chat and Party panels stamp each line with the player's local wall-clock time as HH:MM:SS.t (24-hour, no date), the time the client received it, replacing game-time seconds: 16:04:03.2. A line replayed at login gets the time worked out from the game time (how long before the newest game time it says it was), marked ~16:03:41 without the tenth; a line with no clock shows --:--:--.-. The terminal uses the system's time zone and the browser the browser's. A /bug report ends with [at 16:04:03.2 (game 127445.6s)] and the exported server log is unchanged (UTC wall time and the server's words, which keep their game time); the tests hold the clock fixed (model.FixClock). Gather contracts say what the count is: "Pelts for the Tanners 1/3 · looted since you took it" in the Contracts panel (shortened to "looted since taken", "looted" or the count alone as the row needs), and "1 of 3 looted since you took it" in the contract details; the client reads the kind from ContractInfo.kind. The small map's default stays ±20 m (a test pins it). The approve page shows the account's email once.

The Events panel keeps its lines. The log keeps the last 1,000 lines the short view shows and, apart from them, the last 1,000 routine ones (movement, regeneration, ticks, people coming and going), each oldest first, so a flood of routine events can never push a death out of the panel; V shows both, merged by time (the log holds at most three times that between trims, a few hundred kilobytes). Scrolling back (TUI-073). Every tab of the bottom panel (Events, Chat, Party) scrolls back: the wheel over the panel by 3 rows, PgUp / PgDn by a page, Home to the oldest kept line and End to live (while the chat drawer is open it takes these keys, and over a service's sidebar PgUp / PgDn still scroll the sidebar). The wheel over the panel never zooms the map; over the map it still does. A scrolled-back panel stays where it was as lines arrive, and its bottom border says so in words: ↓ 12 new · End (or ↓ more below · End when nothing new has come); End returns to live, and so does turning to another tab ([, ] or a click). Each tab has its own place while it is shown; V keeps the view at the same line. The live panel's bottom border lists the keys. The browser's own terminal scrollback is off; the panel's scrollback is the program's, so it works the same in the browser.

Which terminals deliver Option-click (D109). Option-click needs the terminal to send the mouse report with the Alt bit (SGR 1006, bit 8) instead of using it itself. The program reads the bit from Bubble Tea's mouse message; the scenarios and the browser check send those bytes. Not checked by hand (no GUI application may be launched where this was built): macOS Terminal.app, iTerm2 and a Linux terminal. Expect, to check: Terminal.app and iTerm2 on a Mac may keep Option-click for themselves (cursor placement, selection) and not report it; turn off iTerm2's "Option+click moves cursor" (Settings > General > Selection) and Terminal.app's "Allow Mouse Reporting" must be on (View menu); xterm.js in the browser sends it (see docs/browser.md); most Linux terminals (kitty, alacritty, wezterm, gnome-terminal, konsole) report Alt with the mouse. Where Option-click does not arrive, click, then W does the same. The table in docs/browser.md records what was and was not checked.

Terminals. Reports are the standard xterm ones, so a terminal with SGR mouse reporting (mode 1006) works. Holding Alt only labels everything when the terminal sends the modifier with the mouse report (and, for hover, with motion); where it does not, or the window system keeps Option or Alt for itself, Ctrl+A is the toggle. None of iTerm2, Terminal.app or Ghostty was tried by hand in the mission that built this: no GUI application may be launched there. What the scenarios prove is the program's side: they send the same SGR bytes (press, release, motion, wheel, Alt) to the real running program. If a terminal ignores the mouse, or reports it badly, -no-mouse turns it off and the keys do everything.

Walking (TUI-031, SEQ-088)

Tap a movement key to step, hold it to walk (D85). A tap is one Move 3 m on in that direction (StepMm), as before hold-to-walk; a key held past 200 ms (tapHold) sends the engine's Walk{heading} (whole degrees, 0 east, 90 north), and letting go sends Stop (a hold begins 200 ms after the press, once it is no longer a tap; nothing is added at its end). Two keys tapped together are one step along the diagonal. The character's own mark shows a step at once and runs ahead of the server's word along it, so a tap does not flicker. Two keys held walk a diagonal where the terminal reports them (most only repeat the last key pressed), opposite keys cancel, and turning sends a new heading. Esc stops an Option-click walk (a Move to a destination, D77, D109); an Option-click sends Move, a plain click does not. In a turn-based instance the keys are still plan steps.

Key releases. The program asks the terminal for the kitty keyboard protocol's event types. Where it answers (Kitty, Ghostty, WezTerm and recent iTerm2 implement the protocol; none was run here, only synthetic events) a key is down from its press to its release and Stop goes out the moment it comes up. Elsewhere a key is taken as let go when its repeats stop: about 150 ms after the last repeat (twice the repeat interval, 150 to 300 ms), and, until the first repeat has been seen, after the terminal's own pause before it repeats (a guess of 450 ms, learned from the first hold), so that pause does not stop a walk. A press with no repeat after it on such a terminal is one 3 m step, sent at once; the first repeat turns it into a walk, which stops about 150 ms after the key stops repeating. Taps a tenth of a second apart look like repeats there and walk. Tapping is throttled to one movement intent in 100 ms either way, so ten taps a second are never rate limited. Terminal.app, tmux without the protocol passed through, and most others report no releases.

Throttle. At most one movement intent goes out in each server tick (100 ms): repeats of the same heading are coalesced into a keep-alive every 200 ms (the server lets a walk go for 500 ms), and a change of heading or a stop waits for the tick's gap. A key repeating every 30 ms for ten seconds sends about five intents a second and is never rate limited.

Prediction. While a key is held the character's own mark runs ahead of the server's word at the speed the server's steps showed (measured off the moved events, so ground and snares count) and the picture is redrawn about 30 times a second. The mark is never more than a tick and a half ahead of the last position the server told, never runs through a wall, the zone bounds, a building, rock or water (it slides along a wall as the server does), and goes back to the server's word when the server falls silent. When the server's position arrives the mark blends toward it, and jumps if it is more than half a metre off. Other entities are not predicted.

The map's scroll. The map is drawn in whole terminal cells and a cell is already about twice as tall as wide, so the scale spends twice the millimetres on a row as on a column and the picture keeps its shape: a metre north and a metre east look the same size. Half-block or sub-cell drawing was not added: the map's glyphs (@, T, $, walls, labels) cannot be split into half cells, and a half-block map would have to give them up or draw the world twice. The mark's smoothness shows in the title ("at 12,50 m") and in the cell the @ scroll shifts at.

Instances and rounds

I opens the zone's instance menu, read from the zone map's presets: each shows its name, its time mode (real-time, or turn-based with the round length in ticks and the time the players have to plan) and its party cap. Up and Down or the number choose, Enter sends instance_open, Esc closes. The answer is in the event log in words (instance_opened, or instance_open_failed with why), and every denial reason is given as words with its code in brackets. Walk to the preset's door (gate-north in the test zone) and press E, as at any door; E at the door again leaves. The map and panels follow the handoff. An Instance panel shows what the server says the instance is (D49: the snapshot's instance, never the space's name): the preset, its time mode, party cap, difficulty and, for a turn-based one, its sleep limit; or its state when it is open, or ended with why (cleared, abandoned or expired, followed by the hand-back to the zone). The menu shows each preset's sleep limit as well.

In a turn-based instance a bare intent is refused by the server (plan_required), so the keys build a plan instead and send nothing until you submit it. The Round panel's title is the round and a live countdown to its deadline; the panel says "N of M submitted" (the server's participants, which can rise while a party gathers in round 1; the server does not announce another character's plan, so the count is what its last round event said plus your own receipt) and lists the plan being built, and the map marks + where the plan's moves end.

key adds to the plan
arrows, W A S D a move step, 3 m on from where the plan's last move ends (a turn-based plan; in real time the keys walk while held)
Tab the next target (from the plan's target)
F or Space auto-attack on or off (from the plan's state)
L loot the drop nearest where the plan ends
E use the nearest door
X, R stop; release
1 to 8 use the ability in that slot (it needs no target of its own: the server uses your current target)

A plan holds one move or door and one ability or auto-attack toggle (doc 05 §4.6), with the target steps they need: a second move, ability or toggle is not added, and the status line says why (Backspace removes the one the plan has). A cast in a plan plays through the round as in real time, and a move in the same plan cancels it. Slots are set out of play (B), not in a plan.

Enter submits the plan (at most 16 steps; an empty plan means "do nothing"), Backspace removes the last step, Esc clears it. The receipt says "plan accepted, counts even if you disconnect"; Enter again replaces the plan until the round runs. A plan sent after the deadline is denied with round_closed: plan for the next round. When a round runs, the log says why (all_submitted, deadline or instance_ended), "N of M submitted", and exactly what each character played: its own plan, a stand-in plan or the safe default (D49's plays). A new round starts an empty plan. After a reconnect (the instance may have slept) the fresh snapshot and the repeated round_started restore the Round panel, and a plan already accepted shows as submitted.

On a small screen (80x24) the right column keeps what fits: inside an instance the Nearby panel (and in a turn-based one the Target panel) is left out to make room for the Instance and Round panels, and with the ability bar the Round panel (the plan) comes before the Instance panel.

Keys (? shows them in the program): arrows or WASD walk while held; Tab cycles targets (Esc clears); F or Space toggles auto-attack; Ctrl+R toggles auto-retaliate; 1 to 8 use the abilities in those slots; B sets the slots; L loots the nearest drop; E uses the nearest door; R releases a dead character (it respawns after a short wait; the You panel says so); I opens the instance menu; O logs out; Q quits the screen and leaves the character in the world; V also shows movement, rules ticks and mana in the event log; G talks to the nearest person; K opens the Contracts screen; M shows the whole zone.

The world and the ground (D53, D54)

The world is not in this repository. The zones, people, items and contracts of Thornwick, the Thornwick Downs and the Hollow Warren are seq-world's (a pinned Go module in go.mod), and the scenarios load them from it through the test server (testserver.Options{Packs, Zones}); make play serves the same packs with seqd -packs. SEQ_WORLD_PACKS=dir points scenarios and make play at a checkout of seq-world under work instead. Move the pin with go get github.com/GeneStevens/seq-world@<commit>, then make fixtures golden and review the diff.

The map draws the ground under everything else, one glyph per kind, so it reads on a monochrome terminal and at 80x24; colour only repeats it:

glyph ground glyph ground
# building (also a wall) " forest (slows you)
^ rock · road (speeds you)
≈ water . a dungeon's floor
: ford
= bridge

In a dungeon (a zone with floor, like the Warren) only the floor is drawn, with the rock that touches it as walls. The status line gives the server's word on the character's speed (D55, self.ground and speed_pct), as in forest: slowed to 75% or road: faster, 125%. M draws the whole zone. The paths that camps and guards walk are not told (D56): the map shows them where they are, and a guard on its patrol is streamed (npc_moved) like any mover.

The ground is the zone map's (D55): its areas are drawn as sent, the model builds them from the map message (model.TerrainOf), and nothing is read from the packs by the client any more. The server states the ground and speed only in a snapshot, and a move does not refresh them, so the status line uses its word while the map's areas still put the character on the ground it named; once it has walked onto other ground it names that ground alone, until the next snapshot says the speed there. A guard is an NPC the server streams as it walks (D56), and the screen draws it where it is.

People, contracts, events and the map

G talks to the nearest person you have seen (the server decides whether they are within 5 m). Their lines and what they offer are on the Talking screen, with the options as the server sent them; an option opens the screen it leads to: buying and selling, training, binding and banking open that trader's window (the existing N screens), and taking or handing in a contract opens the contract board. A person with nothing to offer yet (the Watch Captain) says so. Up / Down or a number choose, Enter does it, Esc closes.

The contract board lists what it offers you now (name, kind, levels; Tab for the contracts you hold) with the description and the pay. Enter takes an offered contract, or hands in a held one; X gives a held one up. The client sends the intent and the server refuses with its reason (contract_limit, contract_held, contract_not_done, out_of_range). K opens the Contracts screen (and a Contracts panel appears in the right column when there is room): each contract held with its progress in words (kills, items carried, or "go to the marker" and then "marker reached"), where a scout's marker is, and the pay; X gives the selected one up. The server describes a held contract from the zone the character is in, and the Downs have no board, so the client keeps the name, text and pay it saw on the board and fills a held contract in from them.

A world event is announced to the zone with its name (D55; the client makes none from its id): a banner row across the top says what is on and, for thirty seconds after it ends, how it ended; the log has every announcement, leak and payout. A roaming rare in view is marked r on the map, RARE in Nearby and the Target panel, and a log line says it has appeared. The server marks a rare (EntityState.rare, D52), so the client keeps no list of names.

The map scrolls: it is always centred on the character at a fixed scale, and its title says where in the zone that is. & marks a contract board, ? someone who only talks, $ the other traders, % the marker of a scout contract you hold, D a door, and c a camp (the zone map's camps: where its mobs are found). Every marker of the zone map is drawn (D55): D for a zone line or an instance entrance, % for the scout marker a held contract names and ; for the other scout markers, and for a world event v where its raiders appear and ◆ where they are heading (not a letter: G read as g, the guard). The scout points (;) and your own % are gold, as the quest's marks are; a world event's two marks are purple, a colour no person, quest or loot mark has. Every named marker has a hover ("Brigands' Rise: raiders gather here (world event)", "The Overlook: a scout point"), an Option-click walks there, and Nearby lists it. NPCs stream as you walk (npc_appeared, npc_left), and the client keeps the ones it has seen, in each space, and draws them wherever they stand; a trader beyond its own reach (the NPC's reach_mm) is marked too far and greyed in the traders' list. Nothing is guessed (D52): the Peril fee, an item's tier, binding and stats (from the drop and reward events), a trainer's ability names and descriptions, the bind fee, a held contract's name, text and reward and the round a cast lands in are all read from the protocol. M shows the whole zone in the panel, with what has been seen of it.

Owed pay (D55). A world event pays a character that left the zone before it ended at its next join, and a refund owed to an opener who had left is paid at its next join too. The server sends no event for it: a stream starts from the snapshot, which already shows the join, so the reward events of the join's tick are not delivered. The client therefore says it from what it can see: a snapshot after a door shows more XP or crowns than the character had, and the log says owed pay arrived with the join: 60 XP and 30 crowns. A fresh login has nothing earlier to compare, so it says nothing; a reward event that arrives for an event whose end this program was not told of (or a refund no failed opening answers for) is told as owed as well.

Deaths (D55). A death in an instance wakes the character at the instance's entrance, inside the instance; the map, the Instance panel and the Round panel follow the new snapshot, and nothing in the client decides where the character wakes.

Classes and combat

seq-tui -new (or SEQ_NEW=1 make play) opens the creation screen: type a name (3 to 16 letters; the server makes its id the name in lower case and refuses a taken one with its reason), Tab or Down moves to the class menu the server sent with its welcome (the client has no class text of its own: each class's name, roles, description and the kit it starts with, free, all come from it; Up / Down or the number choose), Enter makes the character and plays it. A refusal (bad_name, name_taken, unknown_class, too_many_characters) is shown in words on the screen, which stays.

A character with abilities has an ability bar across the screen: eight slots, each with the ability, its mana cost on a wide screen, and one word for whether it can be used now: ready, busy (a cast is running), a cooldown's seconds left, gcd (the global cooldown), mana, tgt? (an enemy ability and no target) or range. The words are a hint from the model's own numbers; the key always sends the intent and the server decides, and its refusal (no_mana, on_cooldown, out_of_range, ...) is on the status line in words. The bar's last row lists the effects on you and on your target with the time left (a buff or damage over time counts rules ticks, so its time is marked ~; a stun, root or snare says Stunned, Rooted, Snared). The You panel has the class, an HP bar, a mana bar for casters, an XP bar with what is left to the next level, and the cast bar: the ability and the time left. A cast that does not land (you moved, damage broke it, you were stunned, the target is gone) is a red ! line in the event log and in the You panel until the next cast begins. A level-up is a + line in the log that names the new ability and its key. Mana changes are in the log under V only; the bar shows them.

Quest chains and the help (D62, D66, D68, D69; TUI-024). A new character in Thornwick is offered First Steps (a chain; the server's text). While the character is on a chain the Quest chain panel and the status line (First Steps 2/4) show it and its current step, and the log says in plain words when it is offered, a step is done (with what it paid), it is finished or dismissed. Ctrl+K (or /quest) opens the chain's screen; X there (or /dismiss) asks one question, and Y gives the chain up for good (the server never offers it again). Nothing walks the character anywhere or reminds it (D57). A fight that stops a walk (D66: attacking, a hostile ability, or a mob engaging) is a log line, "Your walk stopped"; an attack or ability with nothing targeted goes to what is attacking the character, and the status line names the mob the server picked. The zone map's standing NPCs (D69) are on the map and in Nearby by name before they are seen. ? or F1 opens the help from every view (Esc closes it, ? turns the page, Left and Right turn it either way, Up and Down scroll): nine pages: moving and doors, the map and its legend, the mouse and the sidebar, quest chains and fighting, mobs, logs and replay, a page of every key, chat and parties, and the group rules. Each page's section titles are bold in the panel-title colour and its keys are a two-column key / what-it-does table with the key names highlighted as in the line of hints. When something is refused (an intent_result that is not accepted, or a denial event), the server's own plain line (SEQ-092) is a red ! line in Events, once (an identical line within about 2 s is the same line), and the status line goes red with it until your next key; no internal prefix ("use door denied:") is put in front of it. Doors: the server tells which door can be used and why not (DoorStates); the line of hints offers "E: enter Gate North" only for a usable door, and otherwise shows the server's reason in red ("Gate North is shut: no expedition is open beyond it. Start one first."), and Nearby marks it dim with "(shut)". E at a shut door still asks, and the refusal is the answer. The page of keys is drawn from screen.Bindings, and app/bindings_internal_test.go holds the key handler to that table both ways, so the help cannot drift from the keys.

Quests v2 (D105; TUI-045). The quest chain screen (Ctrl+K) and the Quest chain panel tell the step by its kind: deliver ("Held: 2 of 3 charm bead", counting what the bags hold now), collect, kill ("Kills: 2 of 5") and watch ("Watching… 12 of 20 s"); a watch that went back to nothing says why ("started over at 12 s: you left the spot", or "stopped while you are in combat"). The engine tells a quest's progress with the quest (a step or the chain changing), not as a kill or a second is counted, so the kills and the watch seconds are the server's last word and only the bags are live (model.QuestProgressLine); a reset is seen when a fresher view shows fewer seconds. A step in another zone says "This step is in another zone: Thornwick." and names the door to take with its distance and bearing (QuestInfo.zone, target_pos). A person who holds a chain the character cannot take yet lists it in the conversation under "Quests they hold for you", [locked] with the reason ("needs level 8", "finish The Lost Beads first", "not yet: come back later") or [new] (NpcInfo.quest_offers). A quest item (ItemInfo.quest_item) carries [quest] in the bags and in every list (and is gold in the bags), the vendor lists it "no sale", the card says why, and A and Enter at a vendor, banker or trade send nothing and say it is a quest item; the log says "Quest item removed from your bags: 2 Old Relic." when a hand-in or the end of the chain takes it. The bigger Downs (420 × 450 m) is checked by screen/downs_test.go on a trimmed copy of its map (laid out as seq-world has had the Downs since WLD-053: north is the large y), with goldens in testdata/downs for Highfold and Eel Mere at both sizes, small map and large; the large map now keeps a row and a column clear so a zone as tall as the panel shows its south edge, keeps its place names inside the zone's edges, and keeps a cell between two names. testdata/quests holds the goldens of each step kind, locked offers and quest items, and scenario/questv2_test.go runs a watch, a hand-in and a quest item leaving the bags on the Testgrounds with a chain laid over it. The scenario time limit (T8): the suite's limit is 25 s (about twice its time on an idle host) and grows with the host's load, limit × (1 + load per CPU), so a moderately busy host does not fail it; past that a contended host (load per CPU of 0.5 or more) warns up to the ceiling, and a quiet one fails.

B opens the slot screen (out of combat; the server refuses it in combat with in_combat): Up / Down or 1 to 8 choose a slot, Enter picks an ability from the list of what the character knows, Backspace empties the slot, Esc closes it. In a turn-based instance a slot changes with the plan (D50): the same keys add a step, the slot screen marks it (in the plan), Enter on the main screen submits it, and the slot holds when the round opens (it is allowed in a fight there). A cast that will land in a later round says so (lands in round N) in the You panel, the Round panel and the log.

Items, traders and trade

The screens below read only what the snapshot and the events give (the snapshot carries the item catalogue, the traders in view and the trade window); the server decides every action and its refusal is on the status line in words.

  • C is the character view, the sidebar's Gear, Bags and Stats as a panel of its own with the line of vitals under it: the ten gear slots, the items carried (each with its mark ▲ ▼ = x, its tier, whether it is bound — [bound]; Rare and Named are bound on pickup, a traded item is marked ! and bound to its owner — and what it adds) and the server's character sheet. It opens on the bags when they hold anything. Tab (or 1 to 3) turns to a tab, the arrows choose, Enter wears the item in the bags or takes off the gear under the cursor (out of combat), Esc or C closes. The card under the list says how the item compares with what is worn.
  • The You panel shows crowns at the right of its first line. Drops that the server marks as not yours to take (a Rare drop you are not entitled to) are ~ on the map and not lootable in Nearby, and L says so without asking the server.
  • N lists the traders in view ($ on the map): Enter opens a vendor (the stock on the left, what you carry on the right; Enter buys one or sells one), a trainer (the abilities of your class with level and cost; Enter learns the one under the cursor into the first empty slot), a binder (Enter sets the bind point) or the bank (Tab: deposit or withdraw).
  • Using items, vault space and ferries (D115; TUI-058). On the character view's Bags tab, U uses the item under the cursor; H (on any screen) uses a healing draught, the first one that can be used now. The item's card says what it does ("Use: heals 40 hit points; cooldown 60 s") and counts the cooldown down (the server tells no remaining time, so the client keeps the end of each cooldown group from the answer to the use, as it keeps a regen's end, which shows as "resting bonus 30s" on the You line of the ability bar). A use in a fight that forbids it, one on cooldown and a heal at full health are said on the status line before anything is sent; the server's own refusals follow when it is asked. At a banker, the line above the lists names the next tier of bank slots and its price; B asks, Enter or Y buys, Esc leaves it (the bank list says "3 of 40"). A ferry (a boat-keeper who also quests is a ferry here too) lists its routes with fee and level minimum; Enter asks to sail, Enter or Y pays. A second binder says the fee and where the bind point moves from. The vendor's list of what you carry already shows what the vendor pays for each item (ItemInfo.sell_price, which carries the per-tier rate). scenario/tui058_test.go runs a draught, a loaf, the vault and the punt.
  • T is the trade window. With no window it lists the characters in view and in your group; Enter asks one, and the other presses T and Enter to agree. Then each side puts items in (Enter on what you carry), sets crowns (C, digits, Enter), takes things back (Tab to the offer, Enter), and Y confirms; any change clears both confirmations; X cancels. Bound items are refused by the server with bound.
  • The instance menu scrolls, and marks the heroic (Peril) presets: the server takes an entry fee in crowns when they open (the protocol does not say how much; the log does, once it is paid, and a refund shows there too).

Companions

Shelved (D56). The house companion is off in the server by default (seqd -companions turns it on): the snapshot then carries none, the Captain offers no quest, and the client shows nothing of it: no Companion or Quest panel, no companion lines in the help, no recruit option in the Captain's talk, and P H Y U J Z say there is no helper unless a second character is in play. Everything below is what the client does when the server has a companion.

A house companion is a server-run recruit of the Thornwick Watch (SEQ-049, D35, D43, D46): one for each account, it has your level, fights beside you at about 70 % of a player's strength, takes a party slot, and earns nothing. The client holds none of that; it shows what the server says and sends intents.

The quest. Talk to Captain Rhosyn Hartley (G beside her): her board offers the first step of her quest (a scout of the goblin lookout), the second (a hunt of five goblins) only once the first is handed in. A Quest panel lists the steps as seen ([ ] offered, [>] taken with its progress, [!] ready to hand in, [x] done) and says what to do next. The server names the quest and the step on a contract and on an offer (D55: quest, step), so the panel lists the steps by their number, and it knows only the steps it has been told of (offered or held) since the program started. The last hand-in unlocks the companion; the Captain's option Choose your recruit's role opens a screen where Up / Down or 1 to 4 choose tank, healer, melee or caster and Enter sends it (she lets you change it whenever you like).

The Companion panel (right column, once a role is chosen) shows its name and level, its hit points, its stance and what it is doing (its order, the target it is on, or what its stance does). Its mana (a healer's or a caster's) is shown as an MP bar, from the group's entry in the snapshot (D55); a snapshot carries it, and it changes between snapshots only if the server sends a resource event for the companion (the docs say others' mana changes with a snapshot). On a small screen the panel takes the place of the Target panel.

key does
P call the companion to your side, or send it away (it then comes by itself whenever you join a space, until sent away)
H the next stance: follow, assist, guard, heal, passive
Y attack my target (an order: it overrides the stance)
U come here (walk to where you stand, and stand)
J stop (stand and fight nothing until told)
Z drop the order, back to the stance
. with a second character as well, point these keys at the other helper

It is never independent (D35): it goes when your connection drops and is back when you are. In a turn-based instance the same keys add steps to the plan (a stance and an order, one of each; the plan lists them as companion: stance assist, companion: attack Plain Scuttler) and the companion does only what the plan says.

A second character on a stance (D42). seq-tui -duo bram plays the account's second character from the same program, with the toolkit's built-in stances (agentkit.Stance): it logs in on a connection of its own when P is pressed, and a Party panel shows it with the same keys. Its orders are the same words (attack my target, come here, stop); the driver is client.Duo, which reads the character's own replica about twice a second of game time and sends what the stance says. E at a door sends the second character through it as well (the server decides whether it is within reach; its refusal is on the status line). In a turn-based instance (D55) the stance plays by plan: each round that opens, client.Duo sends the plan its stance makes of its own replica (agentkit.PlanSteps of what it would send: at most one move and one action). With an agent credential for it (SEQ_DUO_AGENT_SECRET) the plan is a stand-in (D10): the server uses it at the deadline for a character with no plan of its own, it does not count as a submission, so the round runs at its deadline, and the Round panel shows what it planned (bram plans: target Plain Scuttler, attack) and then, when the round has run, bram: stand-in plan. Without that credential (a session token may not send a stand-in) the plan is sent as the character's own, and counts as a submission. O logs both characters out.

Directing the second character (D56, Pillar 10). X switches the keys and the screen to the account's other character, once it is in play (P): the screen is then its own (its hit points, abilities, round and plan), the status line says directing bram, and every key is its key, sent by this session as a command for that character (Intent.character; the server plays it as that character's and answers this session). Arrow keys move it, Tab targets, 1 to 8 cast its abilities, F attacks, E takes its door. Its stance waits while it is directed; Z hands it back to its stance (H changes the stance and does the same), X gives the session back to the first character. In a turn-based round each character has a plan of its own: the Round panel shows bram's plan (3/16) for the one directed, Enter submits it for that character (it counts as its own plan, so a round can run on this one session's say-so), and X shows the first character's plan, kept apart. The server refuses a directed command for any character that is not the account's, or not in this space (not_here), and says so on the status line. Directing is not presence for either character (D31). The stance follows its leader through a door on its own (D56): if the second character is too far to be sent through the door with E, its stance walks to the door the leader left by and takes it.

The scenarios (scenario/companion_test.go) press their own keys: the first step of the quest from the Captain; the scout of the lookout; the last step, the choice of role and calling the recruit; a camp fought with the companion on assist, then overridden with J and sent back with Y; the five stances; a drop and a fresh login with the companion; a turn-based round with a companion step in the plan; a second character on guard. The M8 cleanup scenarios (scenario/m8_test.go): no companion UI with the default setting; directing the second character (move, target, cast, then follow, then back); a directed plan in a turn-based round; owed pay listed at login; a guard that walks on the screen and no patrol path; a duo through the Hollow Warren (in by stance, a room cleared, out by direct orders). The D55 scenarios (scenario/d55_test.go): a duo on a stance planning each round of a turn-based instance by stand-in; the server's speed in a forest and out of it; a death in an instance waking at its entrance; owed pay arriving with a join; the companion's and the party's mana; every marker of a zone on the map. A scenario cannot hold the whole quest, since a contract counts in its own zone, so the quest is played in the three pieces that its two zones allow. World.LoginWithDuo (and LoginWithDuoAgent, with an agent credential for the second character) gives a player a second character that the scenario drives once each time the player syncs, so that it is deterministic. No scenario sends the second character away: logging a character out over the test server can stall Advance for five seconds when the session ends while the server settles.

Client scenarios

No test of the TUI needs a person (D49). scenario/ drives the real program: a real tea.Program runs app.App with its input a pipe the scenario writes key bytes to, on a real client.Session, against seq's in-process test server (testserver.Start). The scenario moves the server's clock with Advance; nothing sleeps for game time. A scenario is a short script:

w := scenario.New(t, testserver.Options{...})
w.Place("ann", "aria", 100000, 89000)
p := w.Login("ann", "aria")
p.Press("i", "4", "enter")       // keys, one at a time; each waits for the program and the server
w.Advance(time.Second)           // the clock, not a sleep
p.Press("e")
p.Eventually("the instance", inside) // what the server does outside the clock (a handoff)
p.Model(func(m *model.Model) { ... })
p.Golden("round_plan")           // the screen at both sizes against testdata/scenarios, and a mark in the recording
p.GoldenWithout("round_plan", "comes into view") // the same, with log lines holding the text set quiet first: a mob's arrival line is in the log of one run and not the next

The class scenarios (scenario/combat_test.go) create their characters with keys on the creation screen (w.NewCharacter, p.Type) or log in a class character the test server makes (Account.Classed), and use Options.Zone to adjust the test server's copy of the zone data where a flow needs it (for instance, the level a class learns Root at, so a level 1 Wizard can root a mob; a mob's hit points or XP). They are: create a Wizard, slot abilities with the slot screen, root a scuttler and nuke it, see the mana drop and come back; a cast cancelled by moving and one interrupted by damage; a Warrior taunts, uses Second Wind, bashes and kills; a level-up (a level no longer grants abilities: the trainer sells them); a turn-based round with a cast in the plan; the creation screen's refusals; creating a character from the server's class menu; changing a slot between rounds; logging in mid-fight to see a rooted mob.

The economy scenarios (scenario/economy_test.go): kill the trophy scuttler, loot it and wear the loot while a bystander sees the Rare drop as not lootable; buy, sell, train, bind and bank at the traders; a trade between two characters with a bound item refused; open a Peril instance and pay the fee. The Thornwick scenarios (scenario/town_test.go) run on seq's own test server with the Thornwick zones; they include walking up to a trainer (it appears by event), dying in the Downs and waking in Thornwick, a scout contract's marker and the Downs' camps from the zone map, and Old Grimtusk by its flag.

The Thornwick scenarios (scenario/town_test.go) run on scenario.StartTown, a test server built like seq's testserver (the same packages and manual clock) that runs Thornwick and the Thornwick Downs, which testserver does not: create a character, start in the square, talk to the board and take a Hunt (and the limit of three, and giving one up); walk out of the east gate, kill the wolves, come back and hand it in; buy from a vendor and train an ability; a Scout contract to a marker; the Harvest Raid announced and joined; Old Grimtusk coming into view.

The older scenarios (scenario/flows_test.go): login, move, target, attack, kill and loot; die, release and respawn; the door across and back; solo-trial from the menu to the hand-back; quick-turns round by round (plans edited with Backspace and Esc, the receipt, a missed deadline, a dropped and resumed connection, a fresh login into the open round, clear); a duo on one account entering together in the gathering round.

Speed gates (D49), enforced in the test code: each scenario under 2 s, the whole suite under 25 s (scenario.Main in TestMain). SEQ_SCENARIO_SLOW=3s go test ./scenario makes each scenario wait 3 s at its end and shows the gate failing. The suite's gate counts the whole run, so it means something with -count=1. The limit stretches with the load average per CPU, limit × (1 + load); on a host with 0.5 or more per CPU, a gate over that is a logged warning with the load (it fails past 5 times the limit, or 3 times the load per CPU if more); on a quiet host it fails at the limit (scenario/budget.go, TUI-032, T8 in TUI-045).

make fixtures runs the scenarios with SEQ_FIXTURES set, which makes the scenarios that declare a fixture write their recording to testdata/logs, and rebuilds the hand-built logs. Run make golden after it, and review both diffs. (make fixtures also rewrites the scenario goldens as it runs, so a screen that changed does not stop the recording half way.)

Verify

make verify

Runs a gofmt check, go mod download github.com/GeneStevens/seq-world, go vet ./... and go test ./... (which includes the scenarios), then make web-smoke (the browser build compiles and runs under Node), then prints the elapsed time. It must stay well under 60 seconds.

The download is a step of its own because the scenarios load seq-world's packs from the module cache (go list -m -f '{{.Dir}}'), and nothing in the code imports that module, so go build and go vet never fetch it. On a fresh machine, or after the pin moves, the first make verify needs access to the private github.com/GeneStevens/* modules (GOPRIVATE and the ssh rewrite, as above); a missing module fails the step with the module's name instead of failing every scenario with seq-world is not in the module cache.

History

The pre-reset code is preserved under the annotated tag pre-reset (commit 9d04d89). main was restarted fresh from it; history is kept. See PROVENANCE.md for what is excluded.

The map view uses the technique of the old rasterizer (mapgeo.go at pre-reset): line-to-cell rasterization in a player-centred, snapped viewport. It is written again here against the protocol's zone map; none of its code or EverQuest-derived data is carried (see PROVENANCE.md).

Colour, and NO_COLOR (TUI-029)

A panel's title is bold in one accent colour (cyan); a section inside a panel ("For sale", "You hold", "Gear worn") is bold; a help line is dim with its keys highlighted; READY is green and a refusal is red. Gold is the quest's and its kin: the quest marks (!, ?, quest mobs, the next door), your contracts' scout markers (%, ;) and where your plan ends; a world event's marks are purple and nothing else is. A refusal is red everywhere: a red ! line in Events and the status line on a red background in bold white (bold reverse under NO_COLOR) until your next key. The colours are the terminal's own 16, so they follow a dark or a light theme. With NO_COLOR set (to anything), no colour is sent at all, and bold, dim and reverse are kept: every distinction is in the words and glyphs too. The Events panel opens short (Events (short · v: all)): movement, regeneration and people coming into or going out of view are left out until V shows them (Events (all · v: short)).

North is up on the real packs (O28, D125; TUI-077). The TUI always treated +y as north (keys, map, bearings, mouse). seq-world's WLD-053 flipped the Thornwick packs to agree (layout version 2), so Highfold lies at the large y of the Downs and the North Wall at the large y of the town. scenario/north_test.go checks it on the real packs: the Downs overview draws Highfold above Eelmere and Eel Mere, the Thornwick overview draws the North Wall at the top, Up and W in Hawthorn Square walk toward it, and an Alt-click on a landmark of the large map walks toward that landmark. The scenarios and goldens that held the old y values were mirrored (y becomes the zone's height minus y: 90 m in the town, 450 m in the Downs, 140 m in the Warren).

About

SEQ Terminal UI

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages