Don't forget: You can log in with your Play.net account

Lich:Profanity

The official GemStone IV encyclopedia.
Revision as of 17:01, 13 January 2025 by SDANIEL (talk | contribs) (→‎The power of scripting: commas are not good for bash arrays)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Lich:Profanity is a third party script and is not maintained by Simutronics. Simutronics is not responsible for the accuracy of the information presented on this page, nor is it liable for issues stemming from the use of the application on players' personal devices.

Screenshot of Profanity with ;narost

Profanity is a lightweight, unofficial front end (FE) written in Ruby by Tillmen. Its name likely reflects the author's sense of humor, or possibly the response of most people the first time they encounter it. Snarky speculation aside, it remains a fact that Profanity relies on the curses library, perhaps being the true origin of the name. That is important, because the user will need a Ruby gem for curses to run Profanity (e.g., "gem install curses").

Overview

The main features and advantages of Profanity compared to other FEs are generally:

  • Free software (the user can freely see and modify all code)
  • Lightweight with a minimalist look-and-feel (i.e. no graphics)
  • Runs natively in most operating systems
  • Regular expression highlighting
  • Easily launched by other programs (e.g. for bots)
  • Optimized screen real-estate usage

Because Profanity is a script and not compiled software, it can easily be run on any computer which has a proper version of the Ruby interpreter installed. Anyone using Lich will already have most if not all the necessary tools available on their computer. This is important because Simutronics only releases FEs for Windows and macOS; thus, Profanity is particularly popular among users of other operating systems, such as GNU/Linux. It it also used by player-created robots, such as TownCrier and the GSIVDeathLog, owing to the minimal resources it consumes as well as the ease with which it can be launched from a command-line interface (e.g. directly from another program or script written by the author). It is also one of the easiest interfaces to play via a tablet or smartphone because it does not waste screen real-estate with bells and whistles; Profanity automatically resolves the dimensions of the window it is called from, for instance automagically moving death messaging directly into the main game feed if the screen is under a certain size. To play via a smartphone, the best approach would be running Lich and Profanity remotely (such as on one's home PC) and then accessing the game via ssh.

Owing to its minimalist approach, Profanity could be considered slightly more difficult to install and configure than other FEs. Another possible disadvantage is that it is not officially supported, thus some game defaults give blind errors (the user can tell there is a problem but there is no feedback to indicate what went wrong) or simply behave in an unusual manner. Conversely, as free software, any person can improve it unlike official FEs which are only developed by a small number of Simutronics contractors and/or employees. At present, this article assumes some basic familiarity with the command line and UNIX-like operating systems, but it may be expanded in the future with clear instructions even for a novice who has never used the command line before.

Launching Profanity

Profanity is not a full FE itself as it requires Lich to be installed. Lich is used to login to GemStone, as well as for many of the features such as scripting, logging, squelching, etc. Profanity might be best thought of as an add-on to Lich which together create a full FE. Profanity must be downloaded first as outlined in the Lich installation page.

Saving login data with Lich

Lich Game Entry
  • Because Profanity cannot login to GemStone, one must login via Lich's Game Entry and save the information.
ruby ~/lich5/lich.rbw

A graphical interface will pop up (shown on the right), and one should navigate to the Game Entry tab at the top, enter their Simutronics user name and password, and hit 'Connect'. Assuming the user name and password are correct, the list will then be populated with the player's characters to choose from. The most important step is to check the box 'Save this info for quick game entry'. It doesn't matter what is done with the radio buttons for Wizard / Stormfront (we won't be using either one) nor the 'Custom launch command'. The present step is only done once, simply to tell Lich (and thus Profanity) how to login a character, not to actually perform said login. As the Wizard radio button is selected by default, it is assumed the user simply leaves it as it is. Once these things are done, simply hit 'Play' and the pop-up will close, saving your login details.

This step must be done for each character a player wishes to play. Note that the login data are saved only based on the character's name and not the game instance (Prime, Platinum, Shattered, Test); thus if a player has characters with the same name in different instances—which is always the case for the Test server—the above login step must be performed each time the player wants to switch game instances.

Logging in

To log in the character Rinualdo, one would firstly issue a command like:

ruby ~/lich5/lich.rbw --login Rinualdo --without-frontend --detachable-client=8000 &

A default installation will need a template. Two default templates are provided. Make sure to rename your template after your character name ProfanityFE/templates/charname.xml and is not empty. If you do not have a template, it will default to load the default.xml template. You can copy the template tysong.xml file with the character name you are logging in as:

cp ~/ProfanityFE/templates/tysong.xml ~/ProfanityFE/templates/rinualdo.xml 

After which, one can now launch Profanity to connect to the previously previously ran Lich login:

ruby ~/ProfanityFE/profanity.rb --port=8000 --char=Rinualdo

To see any existing running Lich sessions prior to launching Profanity to connect to one, use the following:

ps aux | grep ruby

The above command might not connect, depending on whether or not the game entry was completed in the previous step or not, thus one either needs to wait a few seconds, or simply issue the command until a game connection is established.

Of course, one probably does not want to type all the above commands in full every time s/he wants to play. Thus it can be easily scripted. One can create executables somewhere in their PATH.

To perform the game login, one might create a script called gsiv.sh as follows:

#!/usr/bin/env bash
# Script to automate login to Tillmen's lich in detached mode
# Author: daid

character="$1"

if [ -z "$character" ];then
  echo "Usage: $0 character_name"
  exit
fi
echo "Logging in $character in detached mode."
echo "call profanity in another terminal"
ruby $HOME/lich5/lich.rbw --login $character --without-frontend --detachable-client=8000

To launch Profanity repeatedly until a connection is established, one can create a script called profanity.sh:

#!/usr/bin/env bash
# Profanity login wrapper
# Author: daid

character="$1" 

if [ -z "$character" ];then
  echo "Usage: $0 character_name"
  exit
fi
    
$(exit 1)
until ruby $HOME/ProfanityFE/profanity.rb --port=8000 --char=$character 2> /dev/null ;do
  printf "."
  sleep 1
done
Return to the top of this page.

Features and Customization

All of Profanity's macros and highlights are controlled with XML in a file called $HOME/.profanity.xml which will be created with some defaults the first time you launch Profanity. One can use the default examples to create their own.

Status Displays

As Profanity runs through a terminal emulator, all information is displayed via ASCII (unless a lich script popout is used), including the character's status. Numerical data are underlayed with a color bar graph for:

Health

Wounds are displayed in different colors as a stick figure framed with indicators for specialized locations as well as general ailments such as diseased, poisoned and bleeding. Even with perfect health, the indicator characters will be displayed by default in a dark grey as:

 e   e  ns 
   O       
  /|\   nk 
 o | o     
  / \   bk 
 o   o     
dis psn bld

Minor injuries appear in yellow with more severe injuries progressing into light and dark red, respectively. Scars appear in light to deeper shades of blue. It should be noted that nervous system scars and injuries are sent through the game data stream in the same manner, so Profanity does not distinguish between an injury and a scar and a nervous scar always appears in the color of an injury. All of these characters and colors are fully customizable in .profanity.xml.

As a silly example, why have "dis psn bld" when it can read "113 114 !!!". It can be fun to customize for yourself. We have matched the character length and replaced it with the issue. Ideally back-highlighted (rather than foreground highlighting) with eye-bleeding read. We can see the problem and also the solution straight up!

Directional Movements

A directional compass indicator displays what movements are available from the current room, normally in yellow:

 ^   * ^ * 
 o   <   > 
 v   * v * 

A sample customization, where slashes and backslashes are used for the diagonal directions (ne, se, sw, & nw) would look like:

 ^   \ ^ / 
 o   <   > 
 v   / v \

Macros and Key Shortcuts

Macros in Profanity work much the same as in other FEs, and the default XML config file shows examples. It should be noted, however, that many terminal emulators have their own hot-keys which, by default, would override or get mixed up with Profanity's own macros. These will vary somewhat based on one's terminal program and operating system. There may be ways to disable said terminal hot keys, but this would disable them for all terminal instances, so one either would want a dedicated terminal program for Profanity or to create a profile. Another alternative is to avoid macros on said keys. A third option is to mix and match them in an interesting way.

A few examples of common terminal macros are:

  • Shift+Insert: This will paste the normal paste buffer (since Ctrl+V doesn't usually work)
  • Ctrl+U: This normally clears the line, much like the GSIV down arrow
  • Ctrl+I: This is the same as the Tab key (ordinarily used for auto-completion). This is an interesting feature since it means we can make a macro on the Tab key by mapping a macro to Ctrl+I, such as TARGET NEXT. However, note that the Tab key is ordinarily used in Profanity to switch the focus of the scrollbar (e.g. from the game feed to thought window)
  • Ctrl+Z: This will suspend the program.
  • Ctrl+C: This will kill the program (i.e. quit Profanity!)

Highlights

One of the beauties of Profanity is not only that regular expression highlighting is supported, but sharing highlights with friends is as easy as copy and pasting XML into the config file. As it is in XML, it even allows for comments to explain the purpose or origin of the highlights, which can be readily grouped into sensible blocks. Below are some common examples.

Herbs

Ever move to a new location and don't recognize what items are herbs? Click on [Expand] to the right!

Buff spells falling

Want (nearly) all the buff spells highlighted in red when they drop? Blue for positive effects? Click on [Expand] to the right!

Return to the top of this page.

Special Commands

A series of commands specific to Profanity are built in. They are accessed beginning the command with a period ('.'). Below is a list of known Profanity commands and their function:

  • .arrow : Switches between the two arrow modes. By default, up and down arrows scroll the command history. The alternate mode is to scroll the active feed.
  • .copy : (Does nothing. Has fixme note in code.)
  • .fixcolor : Related with loading CUSTOM_COLORS which are not set by default.
  • .layout $1 : Loads the layout $1.
  • .quit : Quits Profanity (but does not exit the game).
  • .reload : Reloads highlights only. Can sometimes fix buffer issues.
  • .resync : Forces a synchronization between Lich server and Profanity.

Common problems

As mentioned above, because Profanity is not an official FE nor widely used, there are some quirks which should be considered.

Dialogs

Some aspects of the game use pop-up dialogs. However, the game will silently fail if your FE does not support dialogs; that is, if dialogs are enabled, and you happen to issue a command that has dialog support, literally nothing will happen at all. There is no failure message because the game apparently does not detect if a dialog was launched successfully or not, nor even if your FE can even support them. To make matters worse, this feature is enabled by default for all characters. An example of such a command is Profile. To fix this, issue the game command

>FLAG Dialogs Off

Training

Training via the traditional means of going to a local inn and check in works fine. However, if one instead wishes to use the modern web-browser approach offered by GOALS then sometimes Profanity's display will get filled with some of the feedback which does not scroll nor get cleared correctly. To rectify this, simply quit profanity (not the game, note the preceding period below) and re-launch Profanity

>.quit
% profanity.sh

Strange markup

For some reason, sometimes the game feed's markup is not handled correctly by Profanity. A known instance of this is when the character is idle, which is sandwiched between nonsense ('^G') which is probably used in official FEs to produce some sort of added emphasis. So far there is no solution, and a Profanity user should simply know that this is SNAFU:

^GYOU HAVE BEEN IDLE TOO LONG. PLEASE RESPOND.^G

Lich scripts with fancy output

Lich scripts that use the echo call for fancy output will unfortunately output to the window which connected to GemStone not to the attached window. Thus all such messages appear in the login window rather than the game feed. There is no known solution, and script writers should be aware of this inconsistent behavior of the echo call and avoid using it. This includes ;bigshot and ;zzherb for example.

Failure to update resource bars

Profanity assumes that the player has never customized the formatting of the resource bars in StormFront. This can produce failures to update mana, health, stamina, and/or spirit trackers in Profanity. A workaround is to remove all such customizations. These are literal game commands (as though _progba was a verb) that can be typed by the player or Lich scripted using a "put":

_progba health 0
_progba stamina 0
_progba spirit 0
_progba mana 0
Return to the top of this page.

Useful Lich scripts

Due to its simplicity, Profanity does not support common features of other FEs such as squelching and highlighting nouns. These are instead accomplished by Lich scripts

Link highlighting

Since Profanity is a strictly text-based, then of course the mouse is useless and one cannot click on any links to access verbs etc. However, at least in room descriptions it is often nice to see which items are links, because it distinguishes items which can be interacted with from the flowery description, for example looking for the entrance to a hidden room. The Lich script ;linktothefast makes this possible by wrapping links around a "link" preset, which can then be colored with:

<preset id='link' fg='ff0000'/>

Alternatively, one can use ;roomlinks, which was written for exactly this purpose. As its default is to sandwich such nouns between % symbols (underlined font is not supported), then one can add a highlight for them:

<highlight fg='88aaff'>%.*?%</highlight>

The above highlight may erroneously highlight parts of links to websites, but these should generally only be occurring in OOC whispers and ;lnet chats and is this not too obnoxious. If one wishes to instead highlight all links, s/he is encouraged to check out the script ;drizzleback from which ;roomlinks was inspired. Be warned that your eyes will probably bleed.

Logging

To get game logs, simply download Tillmen's ;log script from the repo and add it to the global autostart.

Squelching

This section has not been added yet; please add to it now!

(In the mean time, one can check out other scripts with squelching behavior, such as ;dreavening, ;carousel2016, ;squelch, etc. Note the ;squelch script is specifically for squelching given characters without removing the 'Also here' line when they are in the room, which is a common problem of squelching in other FEs, and is not a generalized squelching script.)

Return to the top of this page.

The power of scripting

Here we show a simple example to showcase the power of using Lich in detached mode. With the advent of Login Rewards, one likely wishes to log in all their characters each day, yet this is a tedious process. It can be easily scripted.

Create a lich script in your scripts folder called quit.lic and fill it with something simple like:

puts "#{Time.now} - #{Char.name} - Logged in successfully!"
sleep(5)
multifput "info", "skills full", "inventory", "bank account", "resource", "ticket balance", "boost info"
Script.run("invdb", "refresh")
puts "#{Time.now} - #{Char.name} - Login finished, exiting!"
fput "exit"

Then create an shell script, for example gsiv-login.sh and simply fill the array CHAR_LIST with all the characters you want to log in. Then add that script to your crontab. With the shell script consisting of:

#!/bin/bash
set -e

port=8000
LICH_BIN=/home/servermc/lich5/lich.rbw
RUBY_BIN=/home/servermc/.rbenv/versions/3.3.3/bin/ruby
CHAR_LIST=("Character1" "Character2" "Character3")

echo ""
echo "Daily logins beginning!"
/bin/date

for i in "${CHAR_LIST[@]}"
do
    echo ""
    echo "Attempting to login as $i..."
    if ps a | \grep [d]etachable-client; then
        max_port=$(ps a | grep -Eo "\-\-detachable-client=([0-9]+)" | egrep -o "[0-9]+" | sort | tail -n1)
        port=$(expr $max_port + 1)
    fi
    echo "Launching with: $RUBY_BIN $LICH_BIN --login $i --detachable-client=$port --without-frontend --start-scripts=quit &"
    $RUBY_BIN $LICH_BIN --login $i --detachable-client=$port --without-frontend --start-scripts=quit &
    sleep 30
done

echo ""
echo "Daily logins finished."

Return to the top of this page.

Quick and Dirty: What to do for a GUI-less VM

If you want to install Profanity on a VM (like an AWS EC2 machine or Google VM) without a GUI, there are a couple things you must do:

1. Install the appropriate ruby packages and gems from the lich instructions -- HOWEVER -- do NOT install gtk2 or wine. I used the following:

sudo apt-get install ruby-dev libsqlite3-dev
sudo gem install sqlite3 --no-ri --no-rdoc

2. Grab lich and unzip it

wget https://github.com/elanthia-online/lich-5/releases/latest/download/lich-5.zip
unzip lich-5.zip

3. Grab profanity from GitHub and unzip it, and copy it into your lich folder

cd ~/
git clone https://github.com/elanthia-online/ProfanityFE.git
cp ~/ProfanityFE/profanity.rb ~/lich

4. This is an important step. You will not be able to run the GUI configuration interface for lich from the VM. You MUST first run the GUI config from another computer and save your settings. Go to lichproject.org and follow the instructions and connect to the game at least once from a Windows, Mac, Linux or other computer with a GUI interface to lich.

5. Next, you need to zip up the data folder on the GUI computer located at lich/data. Then you need to SFTP it to your VM, unzip it, and copy it over your ~/lich/data folder. I cannot give specific instructions here because everyone has a different way of doing this.

6. Lastly, you can run lich and profanity as shown above now that you have a character profile saved in the data folder.

ruby ~/lich5/lich.rb --login <character> --without-frontend --detachable-client=8000 2> /dev/null &
ruby ~/profanity.rb --port=8000

A couple more things:

You'll want to modify lich because the newer version of ruby doesn't play well with lich. cd into your lich folder and run

sed -i -e 's/\(SAFE [<=]\) 3/\1 1/' lich.rbw

to update lich.rbw.

You'll also want to keep lich from updating itself and overwriting your updates, so in the game run

;repo unset-lich-updatable
and also in the filesystem set lich.rbw to read-only for the everyone group.