Lich:Profanity

The official GemStone IV encyclopedia.
Revision as of 10:37, 12 July 2018 by JELL01 (talk | contribs)
Jump to navigation Jump to search
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.

Download: https://github.com/matt-lowe/ProfanityFE

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. Once the file profanity.rb is download, it is most sensible to move or save it in the Lich directory. It must then be given executable permission in UNIX-like operating systems:

~ % cd ~/lich
~/lich % chmod +x profanity.rb

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.

Firstly, launch Lich from the command line, whereever it is installed on your computer (most likely the $HOME/lich directory)

~/lich % ./lich.rb

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

One needs to launch two separate commands to login, typically performed in two separate Terminal windows. To log in the character Kaldonis, one would firstly issue a command like:

% ruby $HOME/lich/lich.rb --login Kaldonis --without-frontend --detachable-client=8000

One can then ignore this window, and in another window launch Profanity:

% $HOME/lich/profanity.rb --port=8000

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:

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

character="$1"

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

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

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

$(exit 1)
until $HOME/lich/profanity.rb --port=8000 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.

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!

<!-- common herbs -->
<highlight fg='399900'> bolmara potion| brostheras potion| bur-clover potion| rose-marrow potion| talneo potion| wingstem potion| acantha leaf| aloeas stem| ambrominas leaf| basal moss| calamia fruit| cothinar flower| cactacae spine| cuctucae berry| ephlox moss| strigae cactus| haphip root| marallis berry| pothinir grass| sovyn clove| spearmint leaf| torban leaf| tkaro root| wolifrew lichen| yabathilium fruit| woth flower</highlight>
<!-- FWI herbs -->
<highlight fg='399900'>a crystalline rose-marrow elixir|a crystalline talneo elixir|a crystalline brostheras elixir|a crystalline bolmara elixir|a crystalline wingstem elixir|a crystalline bur-clover elixir</highlight>
<!-- IMT herbs -->
<highlight fg='399900'> flower-shaped tart| iceberry tart| Leaftoe's lichen tart| musk ox tart| Dabbings Family special tart| gelatinous elk fat tart| elk fat gel| frog's bone porridge| Ma Leaftoe's spiced torban tart| polar bear fat soup| ram's bladder| sparrowhawk pie| walrus blubber| earthworm potion| elk horn potion| rock lizard potion| snowflake elixir| starfish potion| tundra grass| rock ptarmigan feathers| arctic moss</highlight>
<!-- Teras herbs -->
<highlight fg='399900'> olak's Ol'style ale| bloody Krolvin ale| orc's head ale| kenar's dropjaw ale| miner's muddy ale| dacra's Dream ale| lost dogwater ale| golden goose ale| bearded ladies' ale| mad mutt frothy ale| captn' Pegleg's ale| mama dwarf's ale| aged schooner ale| gert's homemade ale| wort's winter ale| volcano vision ale| semak's smooth ale| dark swampwater ale| agrak's amber ale| reaper's red ale</highlight>
<!-- Pinefar herbs -->
<highlight fg='399900'> acantha leaf tea| sassafras tea| red lichen tea| red lichen potion| valerian root tea| valerian root potion| sweetfern tea| sweetfern potion| manroot tea| manroot potion| angelica root potion| gingko nut tea| gingko nut potion| wyrmwood tea| wyrmwood potion| daggit root potion| feverfew tea| feverfew potion| pennyroyal tea| pennyroyal potion</highlight>
<!-- alchemy tinctures -->
<highlight fg='399900'> tincture of acantha| tincture of rose-marrow| tincture of tkaro| tincture of bolmara| tincture of aloeas| tincture of ambrominas| tincture of basal| tincture of cactacae| tincture of calamia| tincture of cothinar| tincture of cuctucae| tincture of ephlox| tincture of haphip| tincture of pothinir| tincture of sovyn| tincture of torban| tincture of wolifrew| tincture of talneo| tincture of woth| tincture of yabathilium| tincture of brostheras| tincture of bur-clover| tincture of wingstem</highlight>
<!-- Zul herbs -->
<highlight fg='399900'> grey mushroom potion| green mushroom potion| thick foggy ale| glowing mold tea| dark frothing ale| stalagmite brew| bubbling brown ale| crushed cavegrass tea| spotted toadstool ale| stalactite brew| grainy black potion| chunky black ale| roasted ratweed tea| brown weedroot ale| dirty crevice brew| dirty rat fur potion| resty red ale| sticky lichen tea| dull crimson ale| stone soot brew</highlight>

Buff spells falling

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

<!-- MnS -->
<highlight fg='ff0000'>^The (light|deep) blue glow leaves you\.$|^Deep blue motes swirl away from you and fade\.$|^The air calms down around you\.$|^The (powerful|very powerful) look leaves you\.$|^You lose your extra internal fortitude\.$|^You notice your blood flow go back to normal\.$|^The misty halo fades from you\.$|^The dull golden nimbus fades from around you\.$|^The guiding force leaves you\.$|^The white light leaves you\.$|^The wall of force disappears from around you\.$</highlight>
<!-- MjS -->
<highlight fg='ff0000'>^The dim aura fades from around you\.$|^The replenishing effect fades, but you are left with a feeling of well-being\.$|^You feel less secure\.$|^You feel the knowledge of the treatment of injuries dissipate\.$|^Your breathing becomes more shallow\.$|^You feel less confident\.$|^The brilliant aura fades away from you\.$|^The opalescent aura fades from around you\.$</highlight>
<!-- Cleric, 313 missing-->
<highlight fg='ff0000'>^A white glow rushes away from you\.$|^Your .* returns to normal\.$|^Your sense of faith and conviction wanes\.  You are less sure of yourself\.$|^You suddenly feel less protected\.$|^You feel the protection of your deity's influence fade\.$|^An ethereal golden collection bowl drifts out of your body, then vanishes\.$</highlight>
<!-- MnE -->
<highlight fg='ff0000'>^The (silvery|bright|brilliant) luminescence fades from around you\.$|^Your senses are no longer as sharp\.$|^The scintillating light fades from your hands\.$|^The focused look leaves you\.$|^You feel less confident than before\.$|^The tingling sensation and sense of security leaves you\.$</highlight>
<!-- MjE, 540 missing -->
<highlight fg='ff0000'>^The glowing specks of energy surrounding you suddenly shoot off in all directions, then quickly fade away\.$|^You suddenly feel less light-footed\.$|^You feel a slight tingling as the shimmering field fades away\.$|^You feel your extra magical awareness leave you\.$|^You feel your extra strength departing\.$|^You no longer bristle with energy\.$|^The layer of raw elemental energy surrounding you dissipates\.$</highlight>
<!-- Ranger, 650 missing -->
<highlight fg='ff0000'>^You return to normal color\.$|^The air about you stops shimmering\.$|^You feel less in tune with your natural surroundings\.$|^You feel your vision return to normal\.$|^You feel less nimble\.$|^You no longer hear voices in your mind\.$|^You feel the inner strength leave you\.$|^You feel the aura of confidence leave you\.$|^You are no longer moving silently\.$|^You no longer feel so dextrous\.$|^You feel the gathering of nature's power leave you\.$|^You seem to lose the thorny barrier that surrounds you\.$</highlight>
<!-- Sorcerer -->
<highlight fg='ff0000'>^Your body pulses momentarily into semi transparency and then returns to normal\.$|^Your murky complexion fades away, and you feel less deft\.$|^A dark shadow seems to detach itself from your body, swiftly dissipating into the air\.$|^You exhale the last of a virulent green mist\.$</highlight>
<!-- Wizard -->
<highlight fg='ff0000'>^Your .* stops glowing\.$|^The shimmering multicolored sphere fades from around you\.$|^Faint ripples in the floor beneath you become apparent before quickly dissipating\.$|^You become solid again\.$|^A luminescent aura fades from around you\.$|^The translucent sphere fades from around you\.|it is not well suited for duplicating\.$|It is currently tempering</highlight>
<!-- Bard, 1006,1010,... missing -->
<highlight fg='ff0000'>^You no longer feel a sense of confidence\.$|^Your spirits are no longer lifted by stories of Kai's Triumphs\.$</highlight>
<!-- Empath, 1130 missing -->
<highlight fg='ff0000'>^Your mind's keen focus fades away\.$|^Your aura of resolve dissipates\.$|^Your heart staggers briefly before slowing to a more regular speed\. Dark red droplets seep out of your skin and evaporate as the influence of Troll's Blood leaves you\.$</highlight>
<!-- MnM, 1220 missing -->
<highlight fg='ff0000'>^You feel the tension in your skin ease and notice that your complexion returns to normal\.$|^Like sand through an hourglass, your visions of the future slip away and fade from your mind\.$|^You feel your forehead pulse as your mind relaxes\.$|^The scales covering your hands turn brittle and flake away\.$|^You feel your muscles begin to strain for an instant\. The sense of body control has left you\.$|^The thick plates of bone around your forearms begin to crack, then shatter into a fine white dust\.$|^Darkness punctuated by a constellation of starry pinpoints wells up to the surface of your skin and splinters away with a sound like shattering crystal\.$|^The barrier of force around you dissipates\.$</highlight>
<!-- Paladin -->
<highlight fg='ff0000'>^The dully illuminated mantle protecting you begins to falter, then completely fades away\.$|^Your sense of clarity fades\.$|^The subdued warmth embracing you fades along with the spiritual force surrounding your arms\.$|^Your boosted confidence and fearlessness fade\.$|^Your skin grows slightly numb for a moment as the warm glow fades from around you\.$|^You lose a bit of focus as the knowledge of future battles drifts from your mind\.$|^You feel your abilities diminish as the energy provided by your patron fades from around you\.$|^The dim celadon wisps about your hands flare up once more and fade completely away\.$|^The subdued warmth embracing you fades along with the spiritual force surrounding your arms\.$|^You feel slightly weakened as the blood in your veins thins\.$|^You feel less resolved as the divine urging subsides, fading into obscurity\.$|^Your bolstered defenses fade with the soft glow about you\.$|^The divine force surrounding you slowly fades away\.$|^The muted pale blue sphere surrounding you flickers once and shudders before fading completely\.$</highlight>
<!-- Arcane, 1720 missing -->
<highlight fg='ff0000'>^The brilliant, rapidly shifting aura around you shimmers and flickers briefly before fading\.$|^The brilliant, rapidly shifting aura around you shimmers and bursts in a bright flash!$|^The licks of blue flame surrounding you flare up one last time before vanishing with a staticky crackle\.$|^Like a faint wisp of a barely-remembered dream, your brief, enhanced comprehension of arcane mysteries slips away\.$|^A faint silvery glow fades from around you\.$</highlight>
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.

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 ;roomlinks 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. Although this example does not strictly use Profanity, it offers an idea of the flexibility and simplicity of the approach. 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 an executable in your PATH, for example gsiv-login.sh and simply fill the array CHARNAME with all the characters you want to log in.

#!/bin/bash
# Script to automate GSIV logins for Rewards!
# This script requires that you have ;log in your global autostart
# Author: daid

# Put each character name here, separated by spaces
declare -a CHARNAME=(Kaldonis Ceilingcat Goatface Yourmom)

i=0
DATE=$(date "+%Y-%m-%d")
PORT=8000

echo "Running GSIV logins at `date`"

while [ $i -lt ${#CHARNAME[@]}  ];do
  DIR="$HOME/lich/logs/GSIV-${CHARNAME[$i]}"
  printf "Logging in ${CHARNAME[$i]}..."
  ruby $HOME/lich/lich.rb --login "${CHARNAME[$i]}" --without-frontend --detachable-client=$PORT &
  PID=$!
  LOGIN=2
  while [ $LOGIN -ne 0 ];do
    sleep 1
    ls $DIR/$DATE-*.log &> /dev/null
    LOGIN=$?
    sleep 5
    printf "."
  done
  kill -9 $PID &> /dev/null
  # kill will exit by the time the message is generated, so we have to wait for it...
  wait $PID 2>/dev/null
  printf "done!\n"
  let "i += 1"
done

One needs to download the ;log.lic script and add it to Lich's global autostart. In the game issue:

;repo download log
;autostart add --global log

Note that the script uses the local computer's time and date to establish if a login successfully occurred, but Login Rewards are tracked for the start of each day based on game time (EST/EDT).

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://lichproject.org/download/lich-4.6.44.zip
unzip lich-4.6.44.zip

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

cd ~/
git clone https://github.com/matt-lowe/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 ~/lich/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.