Lich:Software/Installation/macOS: Difference between revisions

The official GemStone IV encyclopedia.
< Lich:Software‎ | Installation
Jump to navigation Jump to search
(Restructure Mac guide as numbered steps; front ends moved to Lich:Software/Front ends; add Parallels)
 
(61 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{3rd-party}}
==Installing the Lich script engine on your Mac OS X Computer==
{{Lich install nav}}
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 [[Wizard (front end)|The Wizard]]). See [[#Windows_in_Parallels|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 [https://discord.gg/KF9Wr8u GemStone IV Discord].
{{#lst:Lich_(software)|About}}


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.
==Background==


{{blue|These instructions are for GemStone IV. DragonRealms players: see the [https://elanthipedia.play.net/Lich_script_repository#Setup_and_Installation DragonRealms Lich setup guide] on Elanthipedia.}}
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.


* '''Already have Lich?''' See [[Lich:Software/Installation/Upgrading|Upgrading Lich]] instead.
==Note for versions prior to Mavericks (10.9)==
<span id="Before_You_Start"></span><span id="The_Process"></span>


==Step 1: Install Homebrew==
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.
[https://brew.sh Homebrew] installs the software Lich needs. (You will install your front end, such as Saga, at the end of this guide.)
# Install Homebrew by following the instructions on the [https://brew.sh Homebrew site]. You will be asked for your password at least once.
# Homebrew also installs Apple's Command Line Tools. Accept the Apple license when asked.
# When Homebrew has finished, run this command in the Terminal app: <code>brew doctor</code>


It should reply <code>Your system is ready to brew.</code> If you get any other result, ask for help before you continue.
==Steps to Install==


==Step 2: Install the required packages==
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.
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.
# <code>brew install gtk+3</code>
# <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>


==Step 3: Set up your shell==
To run this script, download the [https://www.dropbox.com/s/itj42g2bdza50se/lichdiag.sh?dl=0 file] and then:
Now set up your Terminal so it can use these packages. First check which shell you have:


<code>echo $SHELL</code>
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.


* If Terminal shows <code>/bin/zsh</code> (the default on current macOS), run:<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>
There are six steps to getting Lich up and running on your new Mac.
* If Terminal shows <code>/bin/bash</code>, run:<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>


Check that rbenv works:
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.


<code>rbenv versions</code>


It should print one line that looks like <code>* system</code>. If it does, continue. If not, ask for help.
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.


==Step 4: Install Ruby {{Lich version|ruby}}==
==Detailed Installation Instructions==
Enter these commands one at a time. The first one takes several minutes.
# <code>rbenv install {{Lich version|ruby}}</code>
# <code>rbenv global {{Lich version|ruby}}</code>
# <code>ruby -v</code>


The last command shows which Ruby is active. It should start with '''<code>ruby {{Lich version|ruby}}</code>''', for example <code>ruby {{Lich version|ruby}} (…) +PRISM [arm64-darwin25]</code>.
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 the installer file and let it do most of the work for you, or you can manually install the necessary components. '''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 it shows anything else, for example <code>ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.arm64e-darwin22]</code>, close Terminal, open it again and run <code>ruby -v</code> once more. If it still does not start with <code>ruby {{Lich version|ruby}}</code>, ask for help.
'''To install via the 3rd party script osxlich.sh''':


==Step 5: Download Lich==
{|{{prettytable}}
# Download the [https://github.com/elanthia-online/lich-5/releases/latest/download/lich-5.zip Lich5 files]. (Windows, Mac and Linux all use the same files.)
|'''Command''' || '''Comment'''
# Unzip the file in your Downloads folder. This creates a folder called '''Lich5'''.
|-
# Drag the '''Lich5''' folder (the folder, not the zip file) to your Desktop.
|'''Download the diagnostic file''' || You should run this before and after the installation to get a snapshot of your system to troubleshoot from.
|-
|'''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.
|}


==Step 6: Install the gems Lich needs==
'''If you would rather manually install the required components:'''
Lich lists the gems (Ruby add-on libraries) it needs in a file named <code>Gemfile</code>, and '''Bundler''' installs exactly that set. The Gemfile also lists some gems only Lich's developers need (the <code>development</code> and <code>vscode</code> groups), so we tell Bundler to skip them. Enter these commands one at a time:
# <code>cd ~/Desktop/Lich5</code>
# <code>bundle config set --local without 'development vscode'</code>
# <code>bundle install</code>


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


:<small>Older guides use <code>bundle install --without development vscode</code>. That option was removed from the Bundler that comes with Ruby {{Lich version|ruby-series}}, so use the <code>bundle config set</code> command above instead.</small>
Now we get serious.


'''Quick test:'''
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.
# Start the Ruby shell (the prompt will change): <code>irb</code>
# Check the first gem: <code>require 'sqlite3'</code> &mdash; it should reply <code>true</code>.
# Check the second gem: <code>require 'gtk3'</code> &mdash; this should also reply <code>true</code>. It might take a second or two.
# Return to the normal prompt: <code>exit</code>


If both replied <code>true</code>, the hard part is done.
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.


==Step 7: Start Lich==
{|{{prettytable}}
To start Lich on its own, run this command in Terminal:
|'''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 tap Caskroom/casks''' || we're going to use Homebrew to install XQuartz
|-
|'''brew install Caskroom/casks/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''' || 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
|}


<code>ruby ~/Desktop/Lich5/lich.rbw</code>


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.
That is everything we should need to worry about to get into the game with Lich operating.
<span id="Starting_Lich"></span>


==Running Lich for the First Time==
==Step 8: Set up a front end==
Follow the setup for your front end on the [[Lich:Software/Front ends|Front ends]] page:
* [[Lich:Software/Front ends#Saga|Saga]] (recommended): the official front end. Saga can start Lich for you. When Saga asks for your Lich folder, use <code>~/Desktop/Lich5</code>.
* [[Lich:Software/Front ends#Avalon|Avalon]]: the older official Mac front end.
* [[Lich:Software/Front ends#Warlock|Warlock]] or [[Lich:Software/Front ends#Profanity|Profanity]]: third-party front ends.
<span id="Front_Ends"></span><span id="Saga_(recommended)"></span><span id="Saga_.28recommended.29"></span><span id="Avalon"></span><span id="Other_Front_Ends"></span>


==Windows in Parallels==
In order to start the game with Lich, from Terminal we'll have to run the following command:
<span id="Parallels_Windows"></span>
The Ruby4Lich5 installer works in Windows running under [https://www.parallels.com/ Parallels] on both Intel and Apple Silicon Macs. That lets you use the Windows-only front ends, [[Wrayth]] and [[Wizard (front end)|The Wizard]].
# Inside Windows, install Wrayth or The Wizard and check that you can log in '''without''' Lich.
# Follow the [[Lich:Software/Installation/Windows|Windows installation]] guide inside Windows, keeping the default installer options.
# 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 <code>rubyw</code> file in <code>C:\Ruby4Lich5\X.X.X\bin</code> may be set to run in compatibility mode for Windows 7. Right-click it, choose '''Properties &rarr; Compatibility''', and turn compatibility mode off.
sudo ruby lich/lich.rbw --gemstone --avalon

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!

'''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!

==Final Steps==
After confirming everything is working the way you want, don't forget! Open up Terminal and type the following three commands:

brew pin gtk+
brew pin cairo
brew pin pango


Enjoy!


==Resources==
==Resources==
* [[Lich:Software]]: what Lich is, FAQ and common commands
* [https://www.dropbox.com/s/itj42g2bdza50se/lichdiag.sh?dl=0 Lich Diagnostics] 3rd party, not supported by Simutronics
* [[Lich scripting reference]]
* [[Lich:Software/Scripting reference|Lich scripting reference]]
* [[Lich:Script Repository#Popular_Lich_Scripts|Popular Lich scripts]]
* Tillmen's Lich Update (v4.6.33): https://lichproject.org/
* [https://discord.gg/KF9Wr8u GemStone IV Discord]: #scripting channel for Lich help
* Playershops by Lich: https://ps.lichproject.org/
* Unofficial Support for Lich: http://forum.gsplayers.com/forumdisplay.php?f=104
* Popular Lich script thread: http://forum.gsplayers.com/showthread.php?81229-What-Lich-Scripts-Do-You-Regularly-Use


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

Latest revision as of 11:39, 14 November 2026

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.

Lich installation guides — current release: Lich 5.24.2 (Ruby 4.0.9)
Start here · Windows · macOS · Linux · Upgrading · Front ends · Changelog · About Lich

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.

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

Third-Party Software - edit
Lich: About Lich · Installation guides · Front ends
Downloadable Lich Scripts: Go2 | Map | Repository | Popular Scripts
Retrieved from "https://gswiki.play.net/index.php?title=Lich:Software/Installation/macOS&oldid=267893"