Lich:Software/Installation/macOS: Difference between revisions
Jump to navigation
Jump to search
m (Minor updates to conform to wiki styles and to correct a step or two.) |
(Restructure Mac guide as numbered steps; front ends moved to Lich:Software/Front ends; add Parallels) |
||
| (36 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
{{3rd-party}} |
|||
With Mac Mojave and Catalina, Ruby 2.6 and 2.7, and changes to various gems used to support the game, the old script does not work. |
|||
{{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]. |
|||
To install Lich on newer versions of Mac OS, you will need to install formulas using Homebrew that recreate the way older technologies worked. You will need a bit of familiarity with the Mac Terminal application to get this done. Some familiarity with Homebrew will help, although you should be able to follow the steps below without any prior knowledge of Homebrew. |
|||
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. |
|||
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, or for information about other front ends, please contact Doug (doug@play.net or Doug#6198 on Discord) for help. |
|||
{{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.}} |
|||
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. |
|||
* '''Already have Lich?''' See [[Lich:Software/Installation/Upgrading|Upgrading Lich]] instead. |
|||
This guide has only been tested under a limited number of system conditions. Systems with different initial states or versions of these tools installed will behave differently and errors will occur. Your mileage may vary, but these steps should provide hints to what may be going wrong and accelerate any debugging of the issues. |
|||
<span id="Before_You_Start"></span><span id="The_Process"></span> |
|||
==Step 1: Install Homebrew== |
|||
==Before You Start== |
|||
[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. |
|||
You will need to install a few things. |
|||
==Step 2: Install the required packages== |
|||
# Install the [https://www.play.net/gs4/play/avalon-info.asp Avalon Front End] from the play.net site. |
|||
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. |
|||
# Install the [https://www.xquartz.org DMG file] from the Xquartz site. |
|||
# <code>brew install gtk+3</code> |
|||
# After you've installed the Xquartz DMG, this is the best time to log out and log back in on your Mac. You will be required to do so before everything will work, but right now is the best time. So log out, then log back in. |
|||
# <code>brew install gobject-introspection</code> |
|||
# Install [https://brew.sh Homebrew] by following the instructions at the Homebrew site. |
|||
# <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== |
|||
Now set up your Terminal so it can use these packages. First check which shell you have: |
|||
<code>echo $SHELL</code> |
|||
==The Process== |
|||
* 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> |
|||
# Open the Terminal application and move to a folder where you would like to install this project. The following steps will all be run in the Terminal. |
|||
* 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> |
|||
# Enter the following command to fetch Doug's ‘Old Skool Brew’ package: <p><code>curl -OL https://github.com/OSXLich-Doug/OSXLich-Install/raw/master/OldSkoolBrew.zip</code></p> |
|||
# Enter the following command to expand the package: <p><code>unzip OldSkoolBrew.zip</code></p> |
|||
# Run the following command to copy the files to your Homebrew formulas folder: <p><code>cp ./OldSkoolBrew/* /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/</code></p> |
|||
# Run the following command to install the first set of required formulas: <p><code>HOMEBREW_NO_AUTO_UPDATE=1 brew install cairo</code></p><p>Note, this may take 20-30 minutes to complete. You will see Homebrew performing a long list of installations. If the process completes successfully, you will return to a new Terminal prompt once all the packages are installed.</p> |
|||
# Run the following command to make sure these new formulas do not update automatically: <p><code>brew pin cairo</code></p> |
|||
# Run the following command to install the second set of required formulas: <p><code>HOMEBREW_NO_AUTO_UPDATE=1 brew install gtk+</code></p><p>Note, this may take 20-30 minutes to complete. You will see Homebrew performing a long list of installations. If the process completes successfully, you will return to a new Terminal prompt once all the packages are installed.</p> |
|||
# Run the following command to make sure these new formulas do not update automatically: <p><code>brew pin pango gtk+</code></p> |
|||
# Run the following command to update the system Ruby (this has been tested to work with 2.6.5 and 2.7.1): <p><code>HOMEBREW_NO_AUTO_UPDATE=1 brew install ruby</code></p> |
|||
# Now you will need to check if you are running Bash or the Z shell. Enter the following command to check your shell: <p><code>echo $SHELL</code></p> |
|||
## If the Terminal displays <code>/bin/bash</code>, run the following commands: <p><code>echo 'export PATH=/usr/local/opt/ruby/bin:$PATH' >> ~/.bash_profile</code></p><p><code>source ~/.bash_profile</code></p> |
|||
## If the Terminal displays <code>/bin/zsh</code>, run the following commands: <p><code>echo 'export PATH=/usr/local/opt/ruby/bin:$PATH' >> ~/.zshrc</code></p><p><code>source ~/.zshrc</code></p> |
|||
# We have two required Ruby gems to install. Run the following command to install the first gem: <p><code>gem install sqlite3 --no-document</code></p> |
|||
# Run the following command to install the second gem: <p><code>gem install gtk2 --no-document</code></p> |
|||
# 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): <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 'gtk2'</code></p><p>This should start Xquartz in the background and respond <code>true</code> in the Terminal. It might take a few seconds!</p> |
|||
# Nearly there! Now get the Lich files: |
|||
## Download the [https://lichproject.org/download/lich-4.6.52.zip Lich files] (Windows/Mac all run the same files). |
|||
## Put the file in a location you know the path to (for example, your desktop or a folder for this project). |
|||
## Unzip it. |
|||
# Run the following command in the Terminal (note, you must enter the correct path to the folder where you put Lich): <p><code>ruby ~/[PATH TO LICH]/lich/lich.rbw</code></p><p>(From now on, you must use this command to start the game, rather than opening the Front End directly.)</p> |
|||
# After a couple seconds, this will open the Lich login window. |
|||
## Give it your login information, and click connect. |
|||
## Select your character, select the Avalon Front End, and click Play. (Don’t bother to save, that doesn’t work.) |
|||
## The game will start! You will see some new Lich-related text in the scroll, including a repository error (normal). |
|||
# Get started by installing the maps database with the following command (in game): <code>;repo download-mapdb</code> |
|||
# Good luck and have fun! For more instructions on Lich, look for guides elsewhere. |
|||
Check that rbenv works: |
|||
==Lich for Other Front Ends== |
|||
<code>rbenv versions</code> |
|||
No guides are available at this time, please email doug@play.net for help. |
|||
It should print one line that looks like <code>* system</code>. If it does, continue. If not, ask for help. |
|||
==Step 4: Install Ruby {{Lich version|ruby}}== |
|||
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>. |
|||
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. |
|||
==Step 5: Download Lich== |
|||
# 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.) |
|||
# 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== |
|||
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. |
|||
:<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> |
|||
'''Quick test:''' |
|||
# Start the Ruby shell (the prompt will change): <code>irb</code> |
|||
# Check the first gem: <code>require 'sqlite3'</code> — it should reply <code>true</code>. |
|||
# Check the second gem: <code>require 'gtk3'</code> — 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. |
|||
==Step 7: Start Lich== |
|||
To start Lich on its own, run this command in Terminal: |
|||
<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. |
|||
<span id="Starting_Lich"></span> |
|||
==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== |
|||
<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 → Compatibility''', and turn compatibility mode off. |
|||
==Resources== |
==Resources== |
||
* [[Lich:Software]]: what Lich is, FAQ and common commands |
|||
* [[Lich scripting reference]] |
|||
* [[Lich:Software/Scripting reference|Lich scripting reference]] |
|||
* Tillmen's Lich Update (v4.6.52): https://lichproject.org/ |
|||
* [[Lich:Script Repository#Popular_Lich_Scripts|Popular Lich scripts]] |
|||
* Playershops by Lich: https://ps.lichproject.org/ |
|||
* [https://discord.gg/KF9Wr8u GemStone IV Discord]: #scripting channel for Lich help |
|||
* 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: |
[[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.
- 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.)
- Install Homebrew by following the instructions on the 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:
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.
brew install gtk+3brew install gobject-introspectionbrew install rbenvbrew install adwaita-icon-themebrew install openssl@3brew 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 -)"' >> ~/.zshrcecho 'if [ -z $DISPLAY ]; then export DISPLAY=:0.0; fi' >> ~/.zshrcsource ~/.zshrc - If Terminal shows
/bin/bash, run:echo 'eval "$(rbenv init -)"' >> ~/.bash_profileecho 'if [ -z $DISPLAY ]; then export DISPLAY=:0.0; fi' >> ~/.bash_profilesource ~/.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.
rbenv install 4.0.9rbenv global 4.0.9ruby -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
- Download the Lich5 files. (Windows, Mac and Linux all use the same files.)
- 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
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:
cd ~/Desktop/Lich5bundle config set --local without 'development vscode'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 thebundle config setcommand above instead.
Quick test:
- Start the Ruby shell (the prompt will change):
irb - Check the first gem:
require 'sqlite3'— it should replytrue. - Check the second gem:
require 'gtk3'— this should also replytrue. It might take a second or two. - 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.
- Inside Windows, install Wrayth or The Wizard and check that you can log in without Lich.
- Follow the 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 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
| Third-Party Software - edit |
|---|
| Lich: About Lich · Installation guides · Front ends |
| Downloadable Lich Scripts: Go2 | Map | Repository | Popular Scripts |