bbmmorpg-tui

A terminal client (TUI) for the BBMMORPG game API — play the whole core loop from your terminal: create heroes, send them on jobs, fight PvE/PvP, shop, equip, enhance at the forge, spin the Wheel, and trade on the Babel market.

Built with Ink (React for the terminal). The client is a thin shell over the server-authoritative API: it sends intents only — every outcome is decided server-side.

Run from source

cd bbmmorpg-tui
npm install
npm run dev          # runs src/cli.tsx via tsx (no build needed)

Install globally

npm install -g bbmmorpg-tui     # once published to npm
bbmmorpg-tui

Or from a local checkout:

cd bbmmorpg-tui
npm install
npm run build        # produces dist/cli.js
npm install -g .     # installs the `bbmmorpg-tui` command
bbmmorpg-tui

(npm install -g . also triggers the prepare build automatically.)

Updating

The app checks the npm registry on launch. When a newer version exists, an Update available → vX.Y.Z entry appears at the top of the main menu — selecting it runs npm install -g bbmmorpg-tui@latest for you and tells you to relaunch.

You can also update from the shell:

bbmmorpg-tui update     # or: bbmmorpg-tui --update
bbmmorpg-tui --version  # prints version and reports if a newer one is available

If the update fails with a permissions error, your global npm prefix needs sudo or a user-owned prefix (nvm, or npm config set prefix ~/.npm-global).

Publishing (maintainers)

npm login
npm version patch        # bump version (the build embeds it via tsup `define`)
npm publish              # prepublishOnly runs typecheck + build; only dist/ ships

The published version string is read by the in-app/CLI update checker, so always bump the version before publishing.

Configuration

• The API base URL defaults to http://localhost:8000. Override it with the BBMMORPG_API_URL environment variable, or set it in-app from the auth screen (press s) / the Server settings menu entry.
• The base URL and your bearer token are stored in $XDG_CONFIG_HOME/bbmmorpg-tui/config.json (defaults to ~/.config/bbmmorpg-tui/config.json, mode 600). On next launch the token is validated against /v1/me; if it's still valid you skip straight to the menu.

BBMMORPG_API_URL=https://api.example.com bbmmorpg-tui
bbmmorpg-tui --help

Controls

• ↑ / ↓ — move within a list
• Enter — select / confirm
• Esc — go back one screen (quits from the auth screen)
• Tab — switch login ⇆ register (auth screen)
• Screen-specific keys are shown in each screen's footer (e.g. [n] new character, [a] allocate points, [c] toggle premium catalyst, [1/2/3] market tabs).

Screens / features

| Screen | API surface | |---------------|------------------------------------------------------------------------| | Auth | POST /v1/auth/register, POST /v1/auth/login, GET /v1/me | | Roster | GET/POST /v1/characters, GET /v1/character-classes (starter class) | | Dashboard | GET /v1/me/home (aggregated hub: balances, heroes, unread counts) | | Character | GET /v1/characters/{id}, allocate, POST …/respec | | Combat | pve/pvp, GET …/energy (live countdown), …/energy/refill, history | | Jobs | definitions, start, POST …/skip timer, POST /v1/jobs/extra-slot | | Inventory | list, equip/unequip, lock/unlock, sell | | Shop | offers, buy, POST /v1/shop/sell-bulk (junk ≤ rarity) | | Forge | POST /v1/items/{id}/enhance · …/repair (commit-reveal provably-fair)| | Wheel | GET /v1/gamble/wheel/odds, POST /v1/gamble/wheel/spin | | Babel market | GET /v1/market/listings · …/my-listings, list/cancel/buy | | Mail | GET /v1/mail, mark read, claim reward attachments | | Notifications | GET /v1/notifications, mark one / mark all read | | Quests | GET /v1/quests, POST /v1/quests/{code}/claim | | Daily | GET /v1/daily, POST /v1/daily/claim (from the Dashboard) | | Guild | browse / create / join / leave / my guild | | Leaderboards | GET /v1/leaderboards/level · …/pvp | | Wallet | GET /v1/wallet (header) + …/transactions ledger screen |

Mutating requests send an Idempotency-Key header so they're safe to retry.

Navigation

After login you land on the Dashboard — an aggregated hub (balances, your heroes with energy/jobs, unread mail/notifications, claimable quests, daily reward) with quick links. The full Menu is grouped into categories — Play / Heroes / Social / Economy / System — so it's not one long wall of options. Enter drills into a category; Esc steps back out, then back to the Dashboard. Selecting a hero in the Roster sets it active and returns you where you were (the character sheet is its own Heroes entry).

Theming note

The backend is theme-agnostic: it returns abstract IDs/enums (item_type: "BLADE", rarity: "LEGENDARY", slot: "WEAPON"). This TUI renders those raw abstract values. A themed content pack (Pirate / Fantasy / Space …) could later map them to display names and art without any server change.