Lich:Software/Installation/macOS

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

There are two ways to play GemStone IV with Lich on a Mac:

• Native (this guide): Lich runs directly on macOS with Saga, the official front end (in beta), or Avalon. You will need to use the Terminal app a little; no prior experience is required.
• Windows in Parallels: run Windows in a virtual machine and use the Windows front ends (Wrayth or The Wizard). See Windows in Parallels below.

The native install takes 60 to 90 minutes, depending on how many prerequisites you already have. If you get stuck or see errors, contact Doug (doug@play.net or Doug#6198 on Discord), or ask in the GemStone IV Discord.

This guide changes settings for the tools it installs (Homebrew, rbenv and Ruby). Decide whether that is safe for your Mac before you start. If you have never heard of these tools, you are probably not using them for anything else, but proceed at your own risk.

These instructions are for GemStone IV. DragonRealms players: see the DragonRealms Lich setup guide on Elanthipedia.

• Already have Lich? See Upgrading Lich instead.

Step 1: Install Homebrew

Homebrew installs the software Lich needs. (You will install your front end, such as Saga, at the end of this guide.)

1. Install Homebrew by following the instructions on the Homebrew site. You will be asked for your password at least once.
2. Homebrew also installs Apple's Command Line Tools. Accept the Apple license when asked.
3. When Homebrew has finished, run this command in the Terminal app: brew doctor

It should reply Your system is ready to brew. If you get any other result, ask for help before you continue.

Step 2: Install the required packages

Apple's own Ruby does not work well with Lich, so we install a newer one with rbenv, a Ruby version manager, plus the graphics libraries Lich's login window uses. Enter these commands in Terminal one at a time, pressing Enter after each. Let each one finish before you enter the next.

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

Step 3: Set up your shell

Now set up your Terminal so it can use these packages. First check which shell you have:

echo $SHELL

• If Terminal shows /bin/zsh (the default on current macOS), run:

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

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

  source ~/.zshrc

• If Terminal shows /bin/bash, run:

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

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

  source ~/.bash_profile

Check that rbenv works:

rbenv versions

It should print one line that looks like * system. If it does, continue. If not, ask for help.

Step 4: Install Ruby 4.0.9

Enter these commands one at a time. The first one takes several minutes.

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

The last command shows which Ruby is active. It should start with ruby 4.0.9, for example ruby 4.0.9 (…) +PRISM [arm64-darwin25].

If it shows anything else, for example ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.arm64e-darwin22], close Terminal, open it again and run ruby -v once more. If it still does not start with ruby 4.0.9, ask for help.

Step 5: Download Lich

1. Download the Lich5 files. (Windows, Mac and Linux all use the same files.)
2. Unzip the file in your Downloads folder. This creates a folder called Lich5.
3. Drag the Lich5 folder (the folder, not the zip file) to your Desktop.

Step 6: Install the gems Lich needs

Lich lists the gems (Ruby add-on libraries) it needs in a file named Gemfile, and Bundler installs exactly that set. The Gemfile also lists some gems only Lich's developers need (the development and vscode groups), so we tell Bundler to skip them. Enter these commands one at a time:

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

bundle install 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, ask for help.

Older guides use bundle install --without development vscode. That option was removed from the Bundler that comes with Ruby 4.0, so use the bundle config set command above instead.

Quick test:

1. Start the Ruby shell (the prompt will change): irb
2. Check the first gem: require 'sqlite3' — it should reply true.
3. Check the second gem: require 'gtk3' — this should also reply true. It might take a second or two.
4. Return to the normal prompt: exit

If both replied true, the hard part is done.

Step 7: Start Lich

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

ruby ~/Desktop/Lich5/lich.rbw

After a few seconds the Lich login window opens. The first time Lich connects to the game, it downloads its map database and images, and you will see some Lich text in the game window, including a repository error. The error is normal.

Step 8: Set up a front end

Follow the setup for your front end on the Front ends page:

• Saga (recommended): the official front end. Saga can start Lich for you. When Saga asks for your Lich folder, use ~/Desktop/Lich5.
• Avalon: the older official Mac front end.
• Warlock or Profanity: third-party front ends.

Windows in Parallels

The Ruby4Lich5 installer works in Windows running under Parallels on both Intel and Apple Silicon Macs. That lets you use the Windows-only front ends, Wrayth and The Wizard.

1. Inside Windows, install Wrayth or The Wizard and check that you can log in without Lich.
2. Follow the Windows installation guide inside Windows, keeping the default installer options.
3. Start Lich by double-clicking lich.rbw in the Lich5 folder, then log in and play as usual.

If Wrayth scripts do not run on an Apple Silicon Mac: the rubyw file in C:\Ruby4Lich5\X.X.X\bin may be set to run in compatibility mode for Windows 7. Right-click it, choose Properties → Compatibility, and turn compatibility mode off.

Resources

• Lich:Software: what Lich is, FAQ and common commands
• Lich scripting reference
• Popular Lich scripts
• GemStone IV Discord: #scripting channel for Lich help