Lich:Software/Installation/macOS: Difference between revisions

The official GemStone IV encyclopedia.
< Lich:Software‎ | Installation
Jump to navigation Jump to search
(→‎The Process: update Ruby notes to 3.4.2)
(Restructure Mac guide as numbered steps; front ends moved to Lich:Software/Front ends; add Parallels)
 
(11 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{3rd-party}}
{{3rd-party}}
{{Lich install nav}}
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.
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.


This guide will attempt to install Lich for the Avalon Front End only. 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.
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].


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


{{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.}}


* '''Already have Lich?''' See [[Lich:Software/Installation/Upgrading|Upgrading Lich]] instead.
==Before You Start==
<span id="Before_You_Start"></span><span id="The_Process"></span>


==Step 1: Install Homebrew==
You will need to install a few things.
[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.
# Install the [https://www.play.net/gs4/play/avalon-info.asp Avalon Front End] from the play.net site.
# 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.
# The Hombrew 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 Hombrew has installed, in the Terminal application you should run this command <code>brew doctor</code>

Your system should respond with <code>Ready to brew</code>. 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 install the gems in the new Ruby that we installed.

* Finally, we will download and unzip the current Lich software so that we can run Lich.

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.


==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.
# <code>brew install gtk+3</code>
# <code>brew install gtk+3</code>
# <code>brew install gobject-introspection</code>
# <code>brew install gobject-introspection</code>
# <code>brew install rbenv</code>
# <code>brew install rbenv</code>
# <code>brew install adwaita-icon-theme</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==
Now we need to set up your SHELL environment to take advantage of these packages.
Now set up your Terminal so it can use these packages. First check which shell you have:


Enter the following command to check your shell: <p><code>echo $SHELL</code></p>
<code>echo $SHELL</code>


* 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>
* 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>
* 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>
* 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:
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.


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


It should print one line that looks like <code>* system</code>. If it does, continue. If not, ask for help.
* <code>rbenv versions</code>


==Step 4: Install Ruby {{Lich version|ruby}}==
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.
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>.
# <code>rbenv install 3.4.2</code>

# <code>rbenv global 3.4.2</code>
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.
# <code>ruby -v</code>


==Step 5: Download Lich==
If everything worked, the last line will return the version of Ruby that is currently active. It should look something like this:
# 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.)
<code>ruby 3.2.3 (2024-01-16 revision 5124f9ac75) [arm64-darwin22]</code>
# 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.


==Step 6: Install the gems Lich needs==
If you did not receive that line, or if you received a line like this:
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>ruby 2.6.10p210 (2022-04-12 revision 67958) [universal.arm64e-darwin22]</code>
# <code>cd ~/Desktop/Lich5</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).
# <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.
The key is the ruby 3.4.2 part -> it needs to read 3.4.2


:<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>
'''3.4.2 is expected'''. If your version reflects 3.4.2, proceed to the next steps. Enter these commands, one at a time, and press ENTER. Wait for the system to finish before moving on to the next.


'''Quick test:'''
# <code>gem install ascii_charts concurrent-ruby curses gtk3 jwt logger mechanize nokogiri redis sequel sqlite3 terminal-table tomlib tzinfo tzinfo-data webrick xmpp4r --no-document</code>
# Start the Ruby shell (the prompt will change): <code>irb</code>
Now run a quick test to see if things work:
# 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.
* Run the following command to start the Ruby shell (you will see the command prompt change): <p><code>irb</code></p>
# 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>


==Step 7: Start Lich==
If all of these activities show the right results, the hard part is behind you. Now we simply need to get the Lich files:
To start Lich on its own, run this command in Terminal:
# 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 it 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.


<code>ruby ~/Desktop/Lich5/lich.rbw</code>
'''That's it!''' You will start / access Lich and the game from the Terminal window.


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.
# Run the following command in the Terminal: <p><code>ruby ~/Desktop/Lich5/lich.rbw</code></p>
<span id="Starting_Lich"></span>
# After a couple seconds, you should see the Lich login window.
# Enter your login information, and click CONNECT.
# Select your character, select the Avalon Front End, and click PLAY.
# The game will start! You will see some new Lich-related text in the scroll, including a repository error (normal).


==Step 8: Set up a front end==
Lich5 will then automatically start downloading the map database and associated image files for the game. After that's complete, you're ready to play. Good luck and have fun!
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==
==Lich for Other Front Ends==
<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.
No guides are available at this time, please email doug@play.net for help.


==Resources==
==Resources==
* [[Lich:Software]]: what Lich is, FAQ and common commands
* [[Lich scripting reference]]
* [[Lich:Software/Scripting reference|Lich scripting reference]]
* Playershops by Lich: https://ps.lichproject.org/
* [[Lich:Script Repository#Popular_Lich_Scripts|Popular Lich scripts]]
* Unofficial Support for Lich: http://forum.gsplayers.com/forumdisplay.php?f=104
* [https://discord.gg/KF9Wr8u GemStone IV Discord]: #scripting channel for Lich help
* 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: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"