Lich:Software/Mac Installation: Difference between revisions

The official GemStone IV encyclopedia.
< Lich:Software
Jump to navigation Jump to search
m (Update interrupt notice on Mac OS X High Sierra challanges)
(change to use Saga as the primary FE choice)
 
(49 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{3rd-party}}
==Installing the Lich script engine on your Mac OS X Computer==
To install Lich on newer versions of Mac OS, you will need a bit of familiarity with the Mac Terminal application. Some familiarity with Homebrew will help, although you should be able to follow the steps below without any prior knowledge of Homebrew.


This guide installs Lich for use with [[Saga]], the official Simutronics front end for Mac, Windows and Linux (currently in beta). Saga is now the recommended front end on Mac. [[Avalon]] and other front ends also work, and are covered in [[#Front Ends|Front Ends]] below. The entire process will take 60-90 minutes to complete, but the time required will depend on how many prerequisites you need to install and how many errors you encounter. If you get stuck, see any errors or run into any problems, or for information about other front ends, please contact Doug (doug@play.net or Doug#6198 on Discord) for help.
{{equation box|'''An important note to users who updated to High Sierra (Mac OS X 10.13)''' - Apple has changed the default version of Ruby in its core software release. The version of Ruby distributed with Mac OS X 10.13 (High Sierra) is version 2.3.x, which does not work with the current Lich implementation. If you have had Lich installed in a prior version of Mac OS X (10.12 or earlier) and it was working, but you are now getting errors about SAFE variables, you are affected by this change. More detail will be provided when available as we work through these issues.


Please note that this guide will involve changing settings on your device for the technologies involved. You will need to decide whether it’s safe for you to customize these tools to work with Lich. If you have no idea what any of these technologies are, then you probably aren’t using them for any other purpose, but proceed at your own risk.
For those who desire immediate assistance, email doug@play.net for current information. When the entire solution is in place and known to be working, instructions will be provided below and this note will be removed.


[[User:DOUG|DOUG]] ([[User talk:DOUG|talk]]) 19:44, 9 October 2017 (CDT)}}


==Before You Start==
{{#lst:Lich_(software)|About}}


You will need to install Homebrew first. (You will install your front end, such as Saga, at the end of this guide.)
==Background==


# Install [https://brew.sh Homebrew] by following the instructions at the Homebrew site. You will be asked to supply your sudo password at least once, and perhaps a couple of times through this process.
Mac OS X systems for Mavericks (10.9), Yosemite (10.10) and El Capitan (10.11) have some of the elements you need to run [[Lich_(software)|Lich]] already installed. Some elements are missing, and will require you to install components on your system. While most software distributed for Mac OS X comes in the form of an automated install file, Lich is different. Lich will require that you install some components via a Terminal window command prompt. You will also start Lich from the Terminal window.
# The Homebrew setup will also install Apple's Command Line Tools. You will be asked to accept the Apple license.


When you are finished with these steps and Homebrew has installed, in the Terminal application you should run this command <code>brew doctor</code>
==Note for versions prior to Mavericks (10.9)==


Your system should respond with <code>Ready to brew</code>. If you get any other result, please seek assistance.
Installation instructions for Mac OS X versions prior to 10.9 is more complicated. The best option is to update your OS X version to current.


==Steps to Install==


==The Process==
Before you begin, it may be a good idea to download and run the 3rd party provided lich diagnostics script. This script is written to run on your Mac no matter how much, or how little of the required components you have installed. It can be useful to create a reference snapshot before you begin installing, and again after. Just run the script again, it will simply add on to your existing diagnostics file, so you have a before and after picture.


There are three general steps to installing all the packages and software needed to run Lich on Mac.
To run this script, download the [http://bit.ly/GSLichDiag file] and then:


* First we will install various packages through Homebrew. This will include installing a different version of Ruby. Apple's version of Ruby does not work well with Lich.
1) Open up your Terminal window (you can use Spotlight to search for Terminal, then open the application)
2) In your terminal window enter the following commands:
cd
chmod 744 ./Downloads/lichdiag.sh
./Downloads/lichdiag.sh
3) The output in Terminal will tell you what you have and don't have.


* Second, we will download and unzip the current Lich software.
There are six steps to getting Lich up and running on your new Mac.


* Finally, we will use Bundler to install the gems Lich needs (listed in Lich's own <code>Gemfile</code>) into the new Ruby that we installed.
1) Installing the [[Avalon]] client.
2) Installing the xQuartz windowing system.
3) Installing the software compiling tools from Apple.
4) Installing the core software Ruby will use to support gems required for Lich.
5) Installing the Ruby gems used by Lich.
6) Testing the game and finalizing the installation.


To get started, enter these commands in Terminal, one at a time, and press ENTER. Allow the system to complete the command before moving on to the next one.


# <code>brew install gtk+3</code>
Depending on the capabilities of your Mac and your network, you should anticipate that this installation process will take between 15 minutes and 45 minutes for most Macbook Pros and MacPros.
# <code>brew install gobject-introspection</code>
# <code>brew install rbenv</code>
# <code>brew install adwaita-icon-theme</code>
# <code>brew install openssl@3</code>
# <code>brew upgrade ca-certificates</code>


Now we need to set up your SHELL environment to take advantage of these packages.
==Detailed Installation Instructions==


Enter the following command to check your shell: <p><code>echo $SHELL</code></p>
Let's get you set up to use Lich on your Mac system. You have two choices in how you can install Lich on your Mac OS X system. You can download a 3rd party installer file and let it do most of the work for you, or you can manually install the necessary components. The 3rd party installer file is not supported by Simutronics. '''NOTE:''' when running the installer file, you will be asked for your password twice - once to install Homebrew, and once to install xQuartz. This should happen within the first 5 to 10 minutes of the install. Thereafter the script should run without any further interaction required.


* If the Terminal displays <code>/bin/bash</code>, run the following commands: <p><code>echo 'eval "$(rbenv init -)"' >> ~/.bash_profile</code></p><p><code>echo 'if [ -z $DISPLAY ]; then export DISPLAY=:0.0; fi' >> ~/.bash_profile</code></p><p><code>source ~/.bash_profile</code></p>
''Note: For most current Mac systems, the install script will take about 20 to 30 minutes to complete if it has to install everything.''
* If the Terminal displays <code>/bin/zsh</code>, run the following commands: <p><code>echo 'eval "$(rbenv init -)"' >> ~/.zshrc</code></p><p><code>echo 'if [ -z $DISPLAY ]; then export DISPLAY=:0.0; fi' >> ~/.zshrc</code></p><p><code>source ~/.zshrc</code></p>


This completes the installation of the core packages you will need. Now we'll use rbenv to install the new Ruby. You're welcome to select a Ruby version if you are comfortable with any particular one.
'''To install via the 3rd party script osxlich.sh''':


Before we begin, let's check to be sure rbenv is working properly. Enter this command in Terminal and press ENTER.
{|{{prettytable}}
|'''Command''' || '''Comment'''
|-
|'''[http://bit.ly/GSLichDiag Download the diagnostic file]''' || You should run this before and after the installation to get a snapshot of your system to troubleshoot from.
|-
|'''[http://bit.ly/GSLichInstall Download the installer file]''' || After you've run the diagnostics, you'll run this program to install what you need.
|-
|'''Open the Terminal Application''' || You can find Terminal by using Spotlight.
|-
|'''cd''' || type (or copy / paste this and the following commands into your Terminal window.
|-
|'''chmod 744 ./Downloads/lichdiag.sh''' || make the diagnostic file executable only by you.
|-
|'''chmod 744 ./Downloads/osxlich.sh''' || make the installer program executable only by you.
|-
|'''./Downloads/lichdiag.sh''' || run the diagnostics program. It will create a text file on your desktop for reference.
|-
|'''./Downloads/osxlich.sh''' || run the installer program. You will be asked for your password twice during the install.
|-
|'''./Downloads/lichdiag.sh''' || after the installer completes, run the diagnostics again.
|-
|'''You are now ready to play''' || scroll down to the section on Running Lich for the First Time.
|}


* <code>rbenv versions</code>
'''If you would rather manually install the required components:'''


This should return one line that looks like <code>* system</code>. If you see that line, you can proceed. If not, seek assistance. If you are proceeding, then enter these commands in Terminal, one at a time, and press ENTER. Allow the system to complete the command before moving on to the next one.
First, if you haven't already, download Avalon 4.3.3 (beta) from http://www.play.net/playdotnet/play/avalon-info.asp
''You'll want to scroll down to the bottom to find the right one.'' After you've downloaded it, double click on the download to unzip it. Then, I would recommend you drag the application onto your desktop where it can be handy!


# <code>rbenv install 4.0.9</code>
Now we get serious.
# <code>rbenv global 4.0.9</code>
# <code>ruby -v</code>


If everything worked, the last line will return the version of Ruby that is currently active. It should look something like this:
Below, you'll find a list of commands that you'll need to enter in Terminal. Terminal is an application on every Mac system that allows you to enter Unix-style commands. If you've never used Terminal before, it is simply a console that you type information (commands) into and the system responds. It is in the Applications / Utilities folder, or you can simply use Spotlight (magnifying glass upper right corner on most Macs) to search for Terminal, and open it.
<code>ruby 4.0.9 (2026-10-23 revision 3e93b23afc) +PRISM [arm64-darwin25]</code>


If you did not receive that line, or if you received a line like this:
In Terminal, you're going to type (or copy / paste) the commands below. It is absolutely ok to copy and paste these commands into Terminal rather than type them in. You only need to copy the bold part. Anything in comment column is to help inform what's going on. Don't copy that portion. Be sure to copy the complete command, though.
<code>ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.arm64e-darwin22]</code>
seek assistance (restarting the terminal you used to run commands up to this point may be required for `ruby -v` to show the proper, updated version of ruby).


The key is the ruby 4.0.9 part -> it needs to read 4.0.9
{|{{prettytable}}
|'''Command''' || '''Comment'''
|-
|'''cd''' || just making sure we're in our home directory
|-
|'''/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"''' || copy and paste this whole command - don't just click on the link. You'll be asked for your password here.
|-
|'''brew install Caskroom/cask/xquartz''' || Install xQuartz. This might ask you for your password again.
|-
|'''brew install rbenv''' || this command will install the rbenv manager to manage ruby versions
|-
|'''rbenv init''' || Initialize the environment
|-
|-'''echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bash_profile''' || set up the environment to 'see' rbenv
|-
|'''echo 'eval "$(rbenv init -)"' >> ~/.bash_profile''' || make sure this works every time we open terminal
|-
|'''exit''' || log out of the terminal window
|-
|'''From the Terminal > Shell menu, open a new window''' || If you need to, you can use Spotlight to search for Terminal
|-
|'''brew install --build-from-source --with-x11 cairo''' || this command should take a few minutes to complete
|-
|'''brew install https://raw.githubusercontent.com/Homebrew/homebrew/bb3fe5f2de87f76bc0a3f3480635c8fd0d68cec3/Library/Formula/gtk+.rb''' || copy and paste this whole command - don't just click on the link
|-
|'''rbenv install 2.2.5''' || Install Ruby version 2.2.5
|-
|'''rbenv global 2.2.5''' || Set 2.2.5 as the Ruby the system will use
|-
|'''rbenv rehash''' || Setting up to install the gems needed
|-
|'''gem install sqlite3''' || Install the database Lich uses This command may fail on some systems complaining that it is already installed. That's ok.
|-
|'''gem install gtk2 -v 3.0.8''' || Install the graphics interface Lich uses for advanced scripts like narost
|-
|'''cd''' || just making sure we're in our home directory
|-
|'''curl -OL http://lichproject.org/download/lich-4.6.33.zip''' || download the current Lich software
|-
|'''unzip lich-4.6.33.zip || unzip the lich software for use
|}


If your version reflects 4.0.9, proceed to get the Lich files:
# Download the [https://github.com/elanthia-online/lich-5/releases/latest/download/lich-5.zip Lich5] files. (Windows/Mac all run the same files).
# Unzip the file in your Downloads folder. This will create a folder called Lich5. Drag the Lich5 folder (not the zip file, the folder) to your Desktop.


Now we will install the gems Lich needs. Lich includes a file called <code>Gemfile</code> that lists them, so Bundler can install exactly the right set. The Gemfile also lists some developer-only gems (the <code>development</code> and <code>vscode</code> groups) that you do not need, so we tell Bundler to skip them. Enter these commands in Terminal, one at a time, and press ENTER. Wait for the system to finish before moving on to the next.
That is everything we should need to worry about to get into the game with Lich operating.


# <code>cd ~/Desktop/Lich5</code>
==Running Lich for the First Time==
# <code>bundle config set --local without 'development vscode'</code>
# <code>bundle install</code>


The <code>bundle install</code> step can take several minutes (building the GTK gems is the slow part). When it finishes you should see a line beginning with <code>Bundle complete!</code>. If you see an error instead, seek assistance.
In order to start the game with Lich, from Terminal we'll have to run the following command:


Note: you may see other guides use <code>bundle install --without development vscode</code>. That flag has been removed from the version of Bundler that ships with Ruby 4.0, so use the <code>bundle config set</code> command above instead.
sudo ruby lich/lich.rbw --gemstone --avalon


Now run a quick test to see if things work:
You will be prompted for your password. Then, you should see in Terminal that Lich is waiting for the game client to connect. Just fire up Avalon, log in and enjoy!


* Run the following command to start the Ruby shell (you will see the command prompt change): <p><code>irb</code></p>
'''Quick pro tip:''' The next time you want to play, just open up Terminal and hit your 'up arrow' one time. You should see the sudo ruby line above in your Terminal window. You can just press enter, fire up Avalon and enjoy again!
# Run this command to test if the first gem is working: <p><code>require 'sqlite3'</code></p><p>The system should respond <code>true</code></p>
# Run this command to test if the second gem is working: <p><code>require 'gtk3'</code></p><p>This should also respond <code>true</code> in the Terminal. It might take a second or two.</p>
# Now, run this command to return to your regular shell prompt: <p><code>exit</code></p>


If all of these activities show the right results, the hard part is behind you.
==Final Steps==
After confirming everything is working the way you want, don't forget! Open up Terminal and type the following three commands:


==Starting Lich==
brew pin gtk+
brew pin cairo
brew pin pango


To start Lich on its own, run the following command in the Terminal: <p><code>ruby ~/Desktop/Lich5/lich.rbw</code></p>
After a couple seconds, you should see the Lich login window. How you use it depends on your front end; see below.


The first time Lich connects to the game, it will automatically download the map database and associated image files. You will also see some new Lich-related text in the game window, including a repository error (normal).
Enjoy!


==Front Ends==
==A Few Quick Pro Tips==


===Saga (recommended)===
If you've read this far, you're going to benefit!
[[Saga]] is the official Simutronics front end for GemStone IV and DragonRealms, currently in beta. It replaces Wrayth and the old Simutronics launcher (SGE) with its own login screen, and it works with Lich.


'''caffeinate -di [command]'''
'''Install Saga'''
# Go to the [https://www.play.net/gs4/play/saga-info.asp Saga info page] and click '''Download for Mac'''. Choose the '''Apple Silicon''' build for M1/M2/M3/M4 Macs, or '''Intel''' for older Macs. (Apple menu &rarr; About This Mac shows which you have.)
# Open the downloaded <code>.dmg</code> file and drag Saga into your Applications folder.
# Start Saga from Applications. During the beta the Mac builds are not signed, so macOS may refuse to open it the first time. If so, open System Settings &rarr; Privacy & Security, scroll down, and click '''Open Anyway''' next to the Saga message.
# Log in to the game from inside Saga once, without Lich, to make sure Saga itself works.


The Mac build of Saga does not update itself yet. Check the Saga info page now and then and download the newest version the same way.
Sometimes your Mac will want to go to sleep, and will disrupt your processes - even sometimes causing the dread 'SEGFAULT' that reboots your Mac with cryptic information that no one really can use (despite claims to the contrary). If you use the 'caffeinate' command in Terminal, your Mac will not sleep ( [d]isplay or computer [i]dle ) until the command completes. Suggested usage might be 'caffeinate -di ./osxinstall.sh' as one (very pertinent) example.


'''Install Wine'''
'''Use Saga with Lich'''


Saga starts Lich for you:
Took the plunge from a Windows PC to Mac OS X, but not quite ready to give up on your Stormfront or Wizard (my personal fav) yet? Great news! You don't have to. While Avalon is a tried and tested Mac front end, let's face it - the PC crowd presently has the better collection of front ends. So, how do you make this magic all happen? Just follow these instructions (wine installs are as long or longer than the core OS X Lich installs, so make sure you have time!) And now might just be a good time to test 'caffeinate' on that first command - it takes a while and might abort if the machine tries to sleep.
# Log in with Saga normally, then choose '''File &rarr; Enable Login with Lich'''.
# Choose '''File &rarr; Return to login'''.
# Click '''Connect''', then '''Via Lich''', and point it to your Lich folder (<code>~/Desktop/Lich5</code>).
# If Saga asks where Ruby is, or Lich will not start, run <code>rbenv which ruby</code> in the Terminal and give Saga the path it prints (it ends in <code>.rbenv/versions/4.0.9/bin/ruby</code>). Apps started from Finder do not see the Ruby that rbenv set up in your Terminal.
# Log in. The game will start in Saga with Lich running.


Once that works, you can also start from the Lich login window instead (see [[#Starting Lich|Starting Lich]]): select your character, choose '''Saga''' as the front end, and click '''PLAY'''. Lich will open Saga and Saga logs in with its own saved login, so make sure Saga has saved your account and quit Saga before you do this.
{|{{prettytable}}
|'''Command''' || '''Explanation'''
|-
|'''Open Terminal''' || Yes, we love this application to do heavy work!
|-
|'''cd''' || Always a good idea anytime you're not sure exactly where you are (which folder) on your Mac
|-
|'''caffeinate -di brew install wine''' || This will take a bit of time to complete, so we'll pour in some caffeine.
|-
|'''curl -OL http://www.play.net/software/lnchInst.exe''' || Don't just click the link, copy (or type) the entire command.
|-
|'''wine lnchInst.exe''' || You might see a few errors / warnings, but it'll work as of 8/2016
|-
|'''ruby ./lich/lich.rbw''' || Note! No SUDO (yay!) and no specifying --gemstone --avalon. Simple.
|}


See the [[Saga]] page for more about Saga, including importing Wrayth settings.
''Troubleshooting - you may get this strange error message: "concat': no implicit conversion of Errno::EACCES into String (TypeError)" . If you've used Avalon and Lich previously (in particular, using 'sudo ruby' as the instructions say), then we have one step we need to take to remove this error. Don't worry, it is an expected outcome of using sudo with lich, and can be fixed with one line.''


===Avalon===
{|{{prettytable}}
[[Avalon]] is the older official Mac front end. Install it from the [https://www.play.net/gs4/play/avalon-info.asp Avalon info page], then:
|'''Command''' || '''Explanation'''
# Start Lich (see [[#Starting Lich|Starting Lich]]).
|-
# Enter your login information, and click CONNECT.
|'''cd''' || Absolutely ensure we're in the right directory
# Select your character, select the Avalon Front End, and click PLAY.
|-
# The game will start!
|'''sudo chown -R $(whoami):staff ./lich''' || change ownership of all content in the lich directory to your username
|-
|'''ruby ./lich/lich.rbw''' || continue on with the login
|}


===Other Front Ends===
At this point, you'll see the Lich login window - just type in your account information, select your character, and then '''look at the two radio buttons'''. One of them is Wizard, and the other Stormfront. Select your preference, and click PLAY. Your front end will be downloaded and you'll be guided to install (please just select the default locations - wine knows what it's doing).
[https://warlockfe.github.io/ Warlock] is a third-party front end that also works with Lich. Configuration for Mac (and other OS types) is here:


https://github.com/sproctor/warlock3/wiki/Lich-support
''Caution - sometimes wine takes a bit of time 'searching' for a previous installation of a file, especially the Wizard. No panic, let the process complete. Then you may not connect, especially the Wizard, the first time. No worries - wait it out and close up Terminal, then start Terminal again, and re-enter the command. You'll get in the second time.''

''Note: Stormfront is a very nice looking front end, but it has a memory leak in it. This situation is really exacerbated on a Mac / wine installation. You'll notice the front end start to get sluggish. When it does - simply move someplace safe, log out, and log back in. Voilà!''

'''Use those config files!'''

If you've been playing for a while, you'll have a couple of challenges to overcome - migrating any non-lich scripts you may have, and migrating your existing highlights, macros and other settings. The process is slightly different for each front end, but in general:

Wine installs all Windows programs under the user directory at the following path:

~/.wine/drive_c/Program\ Files

So our Simutronics front ends are stored at

~/.wine/drive_c/Program\ Files/SIMU/STORM

~/.wine/drive_c/Program\ Files/SIMU/WIZARD

To move your existing Stormfront configuration, take these steps:

1) Check to see if your scripts and such are saved on the server. If they are - confirm they're available to you
2) If they're not, on your old system with Stormfront - click on the Options button, then select SETTINGS and EXPORT
3) This will create an XML file. Copy this file over to your Mac (desktop is fine if you wish)
4) Start the game on your Mac with Lich and Stormfront, and then on that system, click Options > SETTINGS and IMPORT
5) Confirm your settings / highlights / scripts are available to you.

To move over your existing Wizard configuration (it's a bit harder), take these steps:

1) On your old system, copy the directory under Wizard called Gemstone
2) On your new Mac you'll need to use Terminal to put them in the right place
3) On your new Mac, you need to have the Wizard front end (via wine) already installed
4) Put the Gemstone folder on your desktop
5) In Terminal, type in
cd
cp -R ./Desktop/Gemstone ./.wine/drive_c/Program\ Files/SIMU/WIZARD/
6) Log into the game and see if your files made the transfer


'''Don't forget, Terminal remembers your command history'''

Just like in the game front ends, if you want to repeat a command that you've already typed in, you can simply hit the UP ARROW on your keyboard, and scroll backwards to find the command. If you go too far, DOWN ARROW will scroll you forwards. Admittedly, this is most advantageous when you're getting ready to play, and you hit UP ARROW to get your 'ruby ./lich/lich.rbw' command back.

From time to time, contributors may make changes / modifications to these tips (and the article in general), so bookmark this page, and check it periodically to see what's new and exciting!

'''If you're lazy, like a good Unix admin, use AUTOCOMPLETE in your Terminal window'''

Your Terminal window in Mac OS X will allow you to zip through long filenames and directory paths, if you use the TAB key (autocomplete). For example, in the Wizard instructions above, you can simply type in the following (and hit the TAB key where the field has [T]ab

5) cp -R ./Desk[T]ab/Gem[T]ab ./.wine/driv[T]ab/Prog[T]ab/SIMU/WIZ[T]ab

Autocomplete makes things much easier, and much less error prone! This will work if the file or directory already exists. If you hit TAB and it doesn't autocomplete, the capitalization is off - Unix is case sensitive!


==Resources==
==Resources==
* [http://bit.ly/GSLichDiag OS X Lich Diagnostics] 3rd party, not supported by Simutronics
* [http://bit.ly/GSLichInstall OS X Lich Installation Script] 3rd party, not supported by Simutronics
* [[Lich scripting reference]]
* [[Lich scripting reference]]
* Tillmen's Lich Update (v4.6.33): https://lichproject.org/
* Playershops by Lich: https://ps.lichproject.org/
* Playershops by Lich: https://ps.lichproject.org/
* Unofficial Support for Lich: http://forum.gsplayers.com/forumdisplay.php?f=104
* Unofficial Support for Lich: http://forum.gsplayers.com/forumdisplay.php?f=104
Line 254: Line 141:


{{Third-Party Software}}
{{Third-Party Software}}
[[Category:Third-Party Software]]

Latest revision as of 07:09, 28 October 2026

Lich:Software/Mac Installation 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.

To install Lich on newer versions of Mac OS, you will need a bit of familiarity with the Mac Terminal application. Some familiarity with Homebrew will help, although you should be able to follow the steps below without any prior knowledge of Homebrew.

This guide installs Lich for use with Saga, the official Simutronics front end for Mac, Windows and Linux (currently in beta). Saga is now the recommended front end on Mac. Avalon and other front ends also work, and are covered in Front Ends below. The entire process will take 60-90 minutes to complete, but the time required will depend on how many prerequisites you need to install and how many errors you encounter. If you get stuck, see any errors or run into any problems, or for information about other front ends, please contact Doug (doug@play.net or Doug#6198 on Discord) for help.

Please note that this guide will involve changing settings on your device for the technologies involved. You will need to decide whether it’s safe for you to customize these tools to work with Lich. If you have no idea what any of these technologies are, then you probably aren’t using them for any other purpose, but proceed at your own risk.


Before You Start

You will need to install Homebrew first. (You will install your front end, such as Saga, at the end of this guide.)

  1. Install Homebrew by following the instructions at the Homebrew site. You will be asked to supply your sudo password at least once, and perhaps a couple of times through this process.
  2. The Homebrew setup will also install Apple's Command Line Tools. You will be asked to accept the Apple license.

When you are finished with these steps and Homebrew has installed, in the Terminal application you should run this command brew doctor

Your system should respond with Ready to brew. If you get any other result, please seek assistance.


The Process

There are three general steps to installing all the packages and software needed to run Lich on Mac.

  • First we will install various packages through Homebrew. This will include installing a different version of Ruby. Apple's version of Ruby does not work well with Lich.
  • Second, we will download and unzip the current Lich software.
  • Finally, we will use Bundler to install the gems Lich needs (listed in Lich's own Gemfile) into the new Ruby that we installed.

To get started, enter these commands in Terminal, one at a time, and press ENTER. Allow the system to complete the command before moving on to the next one.

  1. brew install gtk+3
  2. brew install gobject-introspection
  3. brew install rbenv
  4. brew install adwaita-icon-theme
  5. brew install openssl@3
  6. brew upgrade ca-certificates

Now we need to set up your SHELL environment to take advantage of these packages.

Enter the following command to check your shell:

echo $SHELL

  • If the Terminal displays /bin/bash, run the following commands:

    echo 'eval "$(rbenv init -)"' >> ~/.bash_profile

    echo 'if [ -z $DISPLAY ]; then export DISPLAY=:0.0; fi' >> ~/.bash_profile

    source ~/.bash_profile

  • If the Terminal displays /bin/zsh, run the following commands:

    echo 'eval "$(rbenv init -)"' >> ~/.zshrc

    echo 'if [ -z $DISPLAY ]; then export DISPLAY=:0.0; fi' >> ~/.zshrc

    source ~/.zshrc

This completes the installation of the core packages you will need. Now we'll use rbenv to install the new Ruby. You're welcome to select a Ruby version if you are comfortable with any particular one.

Before we begin, let's check to be sure rbenv is working properly. Enter this command in Terminal and press ENTER.

  • rbenv versions

This should return one line that looks like * system. If you see that line, you can proceed. If not, seek assistance. If you are proceeding, then enter these commands in Terminal, one at a time, and press ENTER. Allow the system to complete the command before moving on to the next one.

  1. rbenv install 4.0.9
  2. rbenv global 4.0.9
  3. ruby -v

If everything worked, the last line will return the version of Ruby that is currently active. It should look something like this: ruby 4.0.9 (2026-10-23 revision 3e93b23afc) +PRISM [arm64-darwin25]

If you did not receive that line, or if you received a line like this: ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.arm64e-darwin22] seek assistance (restarting the terminal you used to run commands up to this point may be required for `ruby -v` to show the proper, updated version of ruby).

The key is the ruby 4.0.9 part -> it needs to read 4.0.9

If your version reflects 4.0.9, proceed to get the Lich files:

  1. Download the Lich5 files. (Windows/Mac all run the same files).
  2. Unzip the file in your Downloads folder. This will create a folder called Lich5. Drag the Lich5 folder (not the zip file, the folder) to your Desktop.

Now we will install the gems Lich needs. Lich includes a file called Gemfile that lists them, so Bundler can install exactly the right set. The Gemfile also lists some developer-only gems (the development and vscode groups) that you do not need, so we tell Bundler to skip them. Enter these commands in Terminal, one at a time, and press ENTER. Wait for the system to finish before moving on to the next.

  1. cd ~/Desktop/Lich5
  2. bundle config set --local without 'development vscode'
  3. bundle install

The bundle install step can take several minutes (building the GTK gems is the slow part). When it finishes you should see a line beginning with Bundle complete!. If you see an error instead, seek assistance.

Note: you may see other guides use bundle install --without development vscode. That flag has been removed from the version of Bundler that ships with Ruby 4.0, so use the bundle config set command above instead.

Now run a quick test to see if things work:

  • Run the following command to start the Ruby shell (you will see the command prompt change):

    irb

  1. Run this command to test if the first gem is working:

    require 'sqlite3'

    The system should respond true

  2. Run this command to test if the second gem is working:

    require 'gtk3'

    This should also respond true in the Terminal. It might take a second or two.

  3. Now, run this command to return to your regular shell prompt:

    exit

If all of these activities show the right results, the hard part is behind you.

Starting Lich

To start Lich on its own, run the following command in the Terminal:

ruby ~/Desktop/Lich5/lich.rbw

After a couple seconds, you should see the Lich login window. How you use it depends on your front end; see below.

The first time Lich connects to the game, it will automatically download the map database and associated image files. You will also see some new Lich-related text in the game window, including a repository error (normal).

Front Ends

Saga (recommended)

Saga is the official Simutronics front end for GemStone IV and DragonRealms, currently in beta. It replaces Wrayth and the old Simutronics launcher (SGE) with its own login screen, and it works with Lich.

Install Saga

  1. Go to the Saga info page and click Download for Mac. Choose the Apple Silicon build for M1/M2/M3/M4 Macs, or Intel for older Macs. (Apple menu → About This Mac shows which you have.)
  2. Open the downloaded .dmg file and drag Saga into your Applications folder.
  3. Start Saga from Applications. During the beta the Mac builds are not signed, so macOS may refuse to open it the first time. If so, open System Settings → Privacy & Security, scroll down, and click Open Anyway next to the Saga message.
  4. Log in to the game from inside Saga once, without Lich, to make sure Saga itself works.

The Mac build of Saga does not update itself yet. Check the Saga info page now and then and download the newest version the same way.

Use Saga with Lich

Saga starts Lich for you:

  1. Log in with Saga normally, then choose File → Enable Login with Lich.
  2. Choose File → Return to login.
  3. Click Connect, then Via Lich, and point it to your Lich folder (~/Desktop/Lich5).
  4. If Saga asks where Ruby is, or Lich will not start, run rbenv which ruby in the Terminal and give Saga the path it prints (it ends in .rbenv/versions/4.0.9/bin/ruby). Apps started from Finder do not see the Ruby that rbenv set up in your Terminal.
  5. Log in. The game will start in Saga with Lich running.

Once that works, you can also start from the Lich login window instead (see Starting Lich): select your character, choose Saga as the front end, and click PLAY. Lich will open Saga and Saga logs in with its own saved login, so make sure Saga has saved your account and quit Saga before you do this.

See the Saga page for more about Saga, including importing Wrayth settings.

Avalon

Avalon is the older official Mac front end. Install it from the Avalon info page, then:

  1. Start Lich (see Starting Lich).
  2. Enter your login information, and click CONNECT.
  3. Select your character, select the Avalon Front End, and click PLAY.
  4. The game will start!

Other Front Ends

Warlock is a third-party front end that also works with Lich. Configuration for Mac (and other OS types) is here:

https://github.com/sproctor/warlock3/wiki/Lich-support

Resources

Third-Party Software - edit
Lich Installation: Lich
Downloadable Lich Scripts: Go2 | Map | Repository | Popular Scripts
Retrieved from "https://gswiki.play.net/index.php?title=Lich:Software/Mac_Installation&oldid=267452"