Skip to main content

​
Requirements

​
Ruby Version

Lich 5 requires Ruby to run. The version requirements are:
  • Minimum: Ruby 2.6 or higher
  • Recommended: Ruby 3.2 or higher
Lich will check your Ruby version on startup and prevent updates if the minimum version is not met.

​
System Dependencies

Depending on your platform and usage, you may need:
  • GTK3 — For the graphical login interface (optional on some platforms)
  • SQLite3 — For database functionality
  • OpenSSL — For secure connections

​
Installation by Platform

1
Install Ruby
2
First, ensure you have Ruby installed:
3
Windows
Download and install Ruby from RubyInstaller:
  1. Download the Ruby+Devkit 3.2.x (x64) installer
  2. Run the installer and follow the prompts
  3. Select “Add Ruby executables to your PATH”
  4. After installation, run ridk install in the command prompt to install the development toolchain
Verify installation:
ruby --version
macOS
Install Ruby using rbenv or Homebrew:Using Homebrew:
brew install [email protected]
Using rbenv:
brew install rbenv
rbenv install 3.2.0
rbenv global 3.2.0
Verify installation:
ruby --version
Linux
Install Ruby using your distribution’s package manager:Ubuntu/Debian:
sudo apt update
sudo apt install ruby-full build-essential
Fedora:
sudo dnf install ruby ruby-devel
Arch:
sudo pacman -S ruby
Verify installation:
ruby --version
4
Install Dependencies
5
Lich will automatically install required gems on first run, but you can pre-install them:
6
gem install gtk3 sqlite3 sequel
7
The full list of dependencies is managed in Lich’s Gemfile. Core dependencies include:
  • gtk3 — GTK3 bindings for GUI
  • sqlite3 — Database support
  • sequel — Database ORM
  • terminal-table — CLI table formatting
  • json, yaml, rexml — Data formats
  • redis — Optional caching layer
  • kramdown — Markdown processing
8
Download Lich 5
9
Clone the Lich 5 repository:
10
git clone https://github.com/elanthia-online/lich-5.git
cd lich-5
11
Or download the latest release from the releases page.
12
Install Gems
13
Install all required dependencies:
14
bundle install
15
If you don’t have Bundler installed:
gem install bundler
16
Run Lich for the First Time
17
Start Lich:
18
ruby lich.rbw
19
On first run, Lich will:
20
  • Create necessary directories for scripts, data, and logs
  • Launch the GTK3 login interface (if available)
  • Prompt you to configure your game account

    • ​
    Configuration

    ​
    Directory Structure

    Lich creates several directories for its operation: 
    ~/.lich/              # Main Lich directory
├── scripts/          # Your scripts
│   └── custom/       # Custom user scripts
├── data/             # Character data and settings
├── logs/             # Game logs
├── maps/             # Map databases
├── temp/             # Temporary files
└── backup/           # Backups
    You can customize these directories using command-line arguments:
    ruby lich.rbw --home=/custom/path --scripts=/path/to/scripts

    ​
    Command-Line Options

    Lich supports various command-line options: 
    --home=PATH           # Set Lich home directory
--scripts=PATH        # Set scripts directory
--data=PATH           # Set data directory
--logs=PATH           # Set logs directory
--maps=PATH           # Set maps directory
--backup=PATH         # Set backup directory
--temp=PATH           # Set temp directory
--gs                  # Launch for Gemstone IV
--dr                  # Launch for DragonRealms
--login=CHAR          # Auto-login with character name

    ​
    Adding Game Accounts

    ​
    Using the GUI

    When you first run Lich, the GTK3 login interface will appear:
    1. Click Add Account
    2. Enter your game account credentials
    3. Select your game (DragonRealms or Gemstone IV)
    4. Choose your character
    5. Configure your front-end (StormFront, Wizard, etc.)

    ​
    Using the Command Line

    Add an account from the command line: 
    ruby lich.rbw --add-account
    Follow the prompts to enter your credentials.
    Lich stores encrypted passwords using account-specific keys. Never share your Lich configuration files as they may contain sensitive information.

    ​
    Front-End Configuration

    Lich works with various game front-ends:
    • Wizard FE — Full XML support, recommended for Windows
    • StormFront — Simutronics official front-end
    • Wrayth — Modern web-based front-end
    • Avalon — macOS native front-end
    • Profanity — Terminal-based front-end (requires curses gem)
    The front-end you choose determines which features are available. XML-capable front-ends like Wizard provide the richest experience.

    ​
    Verifying Installation

    To verify Lich is working correctly:
    1. Launch Lich and connect to the game
    2. Once in-game, type: ;version
    3. You should see output showing Lich version 5.14.2
    4. Try running a simple script: ;go2 help
    The ; prefix is used to send commands to Lich rather than the game. You can customize this prefix in Lich settings.

    ​
    Updating Lich

    Lich includes an automatic update system: 
    ;update
    This command will:
    • Check for new versions
    • Download and install updates
    • Preserve your custom scripts and settings
    Lich keeps backups of script and data files before updating in case of errors.

    ​
    Troubleshooting

    ​
    Gem Installation Fails

    If automatic gem installation fails, Lich will attempt to use system gem installation: 
    sudo gem install <gem_name>

    ​
    GTK3 Not Available

    If GTK3 is not available, Lich falls back to command-line mode. Install GTK3 for your platform: Ubuntu/Debian: 
    sudo apt install libgtk-3-dev
    macOS: 
    brew install gtk+3

    ​
    Ruby Version Too Old

    If you see a Ruby version error, upgrade Ruby: 
    # Using rbenv
rbenv install 3.2.0
rbenv global 3.2.0

# Or download from ruby-lang.org

    ​
    Next Steps

    Quickstart Guide

    Learn how to write and run your first Lich script

    Build docs developers (and LLMs) love

    Get started for freeTalk to us