Lociterm

LociTerm MUD Client Telnet

LociTerm is a Progressive Web App that provides MUD Telnet connectivity to any platform with a JavaScript enabled Web Browser, through a hosted server component.

Introduction to LociTerm

Telnet is a network protocol from the early days of the Internet that allows one computer to log into another computer. In the 1990's, before the creation of the World Wide Web, Telnet was ubiquitous. Every networked computer at the time had a Telnet Client, just as every networked computer today has a Web Browser.

MUDs ("Multi User Dungeons") are one of the first type of multi-player online games to take advantage of the growth of the Internet in the 1990's. They are typically modeled after a table top RPG Dungeons and Dragons style game, with the computer playing the role of the DM. Because MUDs started in the text-only Internet of the early 1990's, they were written to use the Telnet protocol for access.

As the Internet grew, the Telnet protocol was gradually replaced by more secure options, and the text-only Telnet Internet was replaced by the graphically rich Web Browser Internet. The Telnet Client, which was once available by default on every computer, is now increasingly difficult to install- if a Telnet Client is available for a platform at all.

MUDs, however, live on! There is a community of gamers who have been playing and adding to these text only Telnet games since their inception, and still need a Telnet Client to play them. There are MUD Telnet clients available for Windows, MacOS, Linux, Android and iOS, but they are typically built for those specific operating systems, or are available on the desktop systems, but not on the mobile ones.

This is where LociTerm comes in!

What and Why of LociTerm

First and foremost, LociTerm is a Web Enabled Telnet Client with a terminal emulator, making it more than a simple line mode MUD client with color support.

There are several Web Based MUD client sites that players can use to connect to MUD games. Notable among them are Grapevine (https://grapevine.haus/) , MudSlinger (https://mudslinger.net/play/), and MudPortal (http://www.mudportal.com/).

These sites are great, but they are all line mode only MUD clients rather than true Telnet Network Virtual Terminal emulators. They simply don't work with games or other services that need terminal emulation or character at a time support. Also, while those sites work and look great on a desktop browser for line mode MUD games, none of them work well on a mobile platform. They were designed for desktop use.

LociTerm started out as a dedicated client for The Last Outpost MUD (https://www.last-outpost.com/), a game that uses character mode, and is more enjoyable to play that way. None of the existing open web clients could do that mode, so the Last Outpost Client Implementation Terminal project was started out of necessity.

Who and Where of LociTerm

Players: If you are just looking to use LociTerm to connect to games, there is no need to download and build LociTerm yourself. You should be able to connect to an open LociTerm instance, suggest your favorite MUD, and connect to it from there. See SITES.md for a list of LociTerm servers.

However, if you want to avoid sending your traffic through a 3rd party LociTerm server, you can build and run your own private local instance of LociTerm that runs entirely on a single machine.

Mud Operators: LociTerm is a great way to add mobile connectivity for players. LociTerm can be configured in a dedicated mode to only allow connections to your own game, or it can be configured as an open server to allow connections to other games in addition to your own. You can run the server component on the same system as the game, on your web server, or elsewhere 'in the cloud'.

LociTerm Feature Support

• Supports Character at a Time Mode and XTERM Terminal emulation.
• Designed with a "mobile first" philosophy to enable MUDing on the go.
• Seamless support for Mobile IP address changes, so game connection stays up as client roams.
• "Reactive Web" design with CSS, same client runs on desktop or mobile.
• "Progressive Web App" can be installed as a native-feel application on most platforms.
• User selected display themes, font and UI element sizes, menu locations
• User settings saved in local browser storage between sessions.
• Touch screen and mouse enabled. Physical Keyboard or On Screen Keyboard with Speech to Text input on mobile platforms.
• Line mode entry with local history.
• User selected CRT emulation filters for nostalgic terminal look
• ARIA screen reader hinting support enabled by default
• End-to-end Encryption- HTTPS websocket for client-to-server, TELNET-SSL from server to games that offer ssl.
• End-to-end Compression- Websocket Per-Message Compression for client to server, MUD Client Compression Protocol for server to game
• Standard Supported Telnet Options- TTYPE, EOR, NAWS, ECHO, SGA, NEW-ENVIRON, Old Line Mode, Character-at-a-Time Mode
• MUD Telnet Options- MCCP2, MTTS, MSSP, GMCP
• GMCP Support for Char.Login, Loci.Hotkey, Loci.Menu, Client.Media
• Terminal support for UTF-8, Emoji, ANSI Color/256/Truecolor, fully XTERM VT compatible, Mouse tracking, SIXEL and IIP inline graphics display.
• About Game shows server MSSP data, including Icon, location, contact info and web links.
• Local function key editor and function key menu.
• CP437 fallback for Telnet BBS systems
• OSC8 Hyperlinks

How LociTerm Works

LociTerm is two programs, one that runs on a dedicated server "in the cloud", and one that runs inside each user's web browser. The two programs work together to translate the Telnet protocol from a game into one that can be displayed in the browser.

The Server side of LociTerm is written in C, and runs under Linux. It implements a web server for sending the client program to the user's web browser, and a custom WebSockets protocol (via libwebsockets) server for talking to the client side program, a MUD Telnet client for talking to game servers (via libtelnet), and a database component (via sqlite3) for managing a directory of known games. It provides service for multiple clients and games simultaneously.

The Client side of LociTerm is written in JavaScript, and runs in a web browser. It implements the same WebSockets protocol as the server, runs a terminal component (via xterm.js) that can render ANSI/XTERM data directly into a browser window, input components that handle line or keystroke entry, and some convenient on screen buttons and menus.

When a player connects to a game, the LociTerm client component contacts the LociTerm server component, and the server component connects to the game. The server bridges the data between the game and the LociTerm client running in the user's web browser.

INSTALL

LociTerm requires libglib2.0-dev, ctags, openssl, cmake, libwebsockets4.4.0, npm, libjson-c-dev. On a Debian 12 system:

apt-get install gcc libglib2.0-dev exuberant-ctags openssl cmake npm libjson-c-dev libsqlite3-dev pkg-config

Will install all of the required development packages to build LociTerm EXCEPT libwebsockets. The version of libwebsockets that ships with Debian 12 is not the right version, is missing some compile time options, and so needs to be re-built from the most up to date source.

Once the packages are installed, running make and make install will install LociTerm into the /usr/local directory. There are additional steps for making the terminal available under its own apache2 document root, and having it start up automatically from systemd.

See the file INSTALL.txt for those details.

Once the locid.conf file is configured with a service port and security model (or as a forwarded host from Apache), clients will be able to connect by going to the configured URL. For a test system, that might look like:

http://localhost:4500

For a production system with Apache port forwarding and live certificates, that might look like:

https://www.last-outpost.com/lociterm/.

When the client connects to the lociterm server for the first time, it will automatically be connected to the default game stored in the server's config file. If the user changes to a different game, that choice is stored on the client side, and will be used as the user's default game whenever they launch.

Creating a URL with host, port, ssl, and menu parameters will force the client to connect to those when the user clicks the link, overriding the last game and menu set stored on the client system. A forced connection URL might look like:

https://www.last-outpost.com/lociterm/?host=www.last-outpost.com&port=4443&ssl=1&menu=lastoutpost

This can be used to direct players to connect to a specific game that isn't the default for a particular LociTerm server.

(Note that the menu parameter should match the "name": of a menu, not the "label":. Some of the built-in menu names are, "lastputpost", "diagonal", "telnet", and "none". This list is subject to change.)

SERVER DOCS

The server config file is installed as /usr/local/etc/locid.conf by default. The server options are documented as comments in the config file.

CLI options to the server can be shown with locid -h .

    -c / --config        specify location of config file
    -d / --debug         run in debug mode
    -h / --help          this message
    -b / --browser       launch a browser
    -v / --version       show the version
    -a / --list-approved list approved games by id
    -l / --list-denied   list denied games by id
    -s / --list-scan     list scaned down games by id
    -i / --info          show game info for id
    -A / --approve <id>  Mark game approved
    -R / --redact <id>   Mark game approv