Updates - Lich 5

Overview

Lich 5 includes a built-in update system that can automatically download and install updates from GitHub. The update system supports:

Stable releases - Production-ready versions
Beta releases - Pre-release testing versions
Branch updates - Development branches for testing
Individual file updates - Update specific scripts or libraries
Snapshots & rollback - Backup and restore functionality

Update Channels

Stable Channel (Main)

The default update channel tracks stable releases:

;lich5-update --announce    # Check for updates
;lich5-update --update      # Install stable update

Stable updates come from the main branch and are tagged as releases on GitHub.

Beta Channel

Test pre-release versions before they become stable:

;lich5-update --beta        # Install latest beta

Beta requirements:

Beta version must have higher minor version than stable
Example: If stable is 5.14.3, beta must be 5.15.0 or higher

Branch Updates (Advanced)

Update to a specific development branch:

# Update to a branch in the main repository
;lich5-update --branch=feature-name

# Update to a fork's branch
;lich5-update --branch=username:branch-name

Branch updates are for advanced users and developers. They may contain unstable code.

Update Commands

Check for Updates

;lich5-update --announce
;lich5-update -a

Displays:

Current version
Available update version
Release notes/changelog

Example output:

*** NEW VERSION AVAILABLE ***

Version 5.15.0 is now available!

[Release notes displayed here]

If you are interested in updating, run ';lich5-update --update' now.

Install Updates

;lich5-update --update
;lich5-update -u

This will:

Create automatic snapshot backup
Download new version from GitHub
Verify Ruby compatibility
Update Lich core files
Update core scripts and data files
Prompt you to restart

Version Status

;lich5-update --status

Displays:

Lich5 Version Information:
  Version: 5.14.3
  Type: Release Package

To check for updates: ;lich5-update --announce

For branch installations:

Lich5 Version Information:
  Version: 5.15.0-beta.1
  Type: Branch (Development)
  Branch: pre/beta/5.15
  Repository: elanthia-online/lich-5
  Updated: 2024-12-15 14:30:00 (5 days ago)

You are running a development branch, not a release package.

Update Process Details

1. Snapshot Creation

Before any update, Lich creates a snapshot backup:

lib/update.rb

snapshot_subdir = File.join(
  BACKUP_DIR, 
  "L5-snapshot-#{Time.now.strftime("%Y-%m-%d-%H-%M-%S")}"
)

The snapshot includes:

lich.rbw - Main Lich executable
lib/ - All library files
Core scripts:
- alias.lic
- autostart.lic
- go2.lic
- jinx.lic
- log.lic
- logxml.lic
- map.lic
- repository.lic
- vars.lic
- version.lic
- dependency.lic (DR)
- ewaggle.lic (GS)
- foreach.lic (GS)

Snapshots do not include your personal scripts, settings, or data files.

2. Download and Extraction

lib/update.rb

# Download from GitHub
tarball_url = "https://github.com/elanthia-online/lich-5/archive/refs/tags/v#{version}.tar.gz"

# Extract tarball
Gem::Package.new("").extract_tar_gz(
  File.open(tarball_path, "rb"),
  extract_dir
)

3. Ruby Version Check

Before installing, Lich verifies Ruby compatibility:

lib/update.rb

if Gem::Version.new(current_ruby_version) < Gem::Version.new(required_ruby_version)
  respond "*** UPDATE ABORTED ***"
  respond "Lich version #{version} requires Ruby #{required_ruby_version} or higher."
  respond "Your current Ruby version is #{current_ruby_version}."
  return false
end

4. File Updates

lib/update.rb

# Delete all existing lib files
FileUtils.rm_rf(Dir.glob(File.join(LIB_DIR, "*")))

# Copy new lib files
FileUtils.copy_entry(source_lib, LIB_DIR)

# Update core scripts and data
update_core_data_and_scripts(version)

# Update lich.rbw
File.open(lich_to_update, 'wb') { |w| w.write(new_lich_content) }

5. Core Files Update

The update system refreshes core data files:

lib/update.rb

# Game-specific core scripts
updatable_scripts = {
  "all" => ["alias.lic", "autostart.lic", "go2.lic", "jinx.lic", 
            "log.lic", "logxml.lic", "map.lic", "repository.lic", 
            "vars.lic", "version.lic"],
  "gs"  => ["ewaggle.lic", "foreach.lic"],
  "dr"  => ["dependency.lic"]
}

# Update effect-list.xml (backs up old version)
update_file('data', 'effect-list.xml')

gameobj-data.xml and spell-list.xml are not automatically updated to preserve local modifications.

Snapshot and Rollback

Create Manual Snapshot

;lich5-update --snapshot
;lich5-update -s

Creates a timestamped backup:

backup/L5-snapshot-2024-12-15-14-30-00/
  ├── lich.rbw
  ├── lib/
  └── scripts/
      ├── alias.lic
      ├── autostart.lic
      └── ...

Rollback to Previous Version

;lich5-update --revert
;lich5-update -r

This will:

Find most recent snapshot
Restore all lib files
Restore core scripts
Restore lich.rbw
Clear branch tracking
Prompt you to restart

Revert is destructive and cannot be undone. It restores the most recent snapshot only.

Individual File Updates

Update a Script

;lich5-update --script=go2.lic
;lich5-update --script=repository.lic

Downloads from:

https://raw.githubusercontent.com/elanthia-online/scripts/master/scripts/
Special case: dependency.lic comes from elanthia-online/dr-scripts

Update a Library File

;lich5-update --library=update.rb
;lich5-update --library=version.rb

Downloads from:

Production: https://raw.githubusercontent.com/elanthia-online/lich-5/main/lib/
Beta: Uses latest beta branch

Update a Data File

;lich5-update --data=effect-list.xml
;lich5-update --data=spell-list.xml

Downloads from:

https://raw.githubusercontent.com/elanthia-online/scripts/master/scripts/

Supported extensions:

.xml - XML data files
.ui - UI definition files

Branch Tracking

When you update to a branch, Lich stores tracking information:

lib/version.rb

# Branch tracking (added by lich5-update --branch)
LICH_BRANCH = 'pre/beta/5.15'
LICH_BRANCH_REPO = 'elanthia-online/lich-5'
LICH_BRANCH_UPDATED_AT = 1702656600

This allows --status to show which branch you’re on.

Clear Branch Tracking

Installing a stable release automatically clears branch tracking:

lib/update.rb

def self.clear_branch_tracking
  # Removes LICH_BRANCH constants from version.rb
end

Update Cache

To reduce GitHub API calls, Lich caches responses:

lib/update.rb

@_http_cache = {}
@_http_cache_ttl = 60  # seconds

def self.fetch_github_json(url)
  # Returns cached response if < 60 seconds old
end

Autostart Updates

To automatically check for updates on login:

# Check and announce updates
;autostart add --global lich5-update --announce

# Automatically install updates (not recommended)
;autostart add --global lich5-update --update

Auto-installing updates (;autostart add --global lich5-update --update) is not recommended. You should review changes before updating.

Help Command

;lich5-update --help
;lich5-update -h

Displays full command reference:

--help                   Display this message
--announce               Get summary of changes for next version
--update                 Update all changes for next version
--branch=<name>          Update to a specific GitHub branch
--status                 Show current version and branch tracking info
--snapshot               Grab current snapshot of Lich5 ecosystem
--revert                 Roll back to most recent snapshot

Example usage:

[One time suggestions]
  ;autostart add --global lich5-update --announce
  
[On demand suggestions]
  ;lich5-update --status
  ;lich5-update --announce
  ;lich5-update --update
  ;lich5-update --branch=main
  ;lich5-update --revert
  ;lich5-update --script=go2.lic
  ;lich5-update --library=update.rb
  ;lich5-update --data=effect-list.xml

Version Management

Version Format

Lich uses semantic versioning:

5.14.3
│ │  │
│ │  └─ Patch (bug fixes)
│ └──── Minor (new features)
└────── Major (breaking changes)

Beta versions include a prerelease identifier:

5.15.0-beta.1

Version Comparison

lib/update.rb

# Compare versions using Gem::Version
if Gem::Version.new(@current) < Gem::Version.new(@update_to)
  # Update available
end

Version Constants

lib/version.rb

LICH_VERSION = "5.14.3"
REQUIRED_RUBY = "3.1.0"

Troubleshooting

Update Fails to Download

Check Internet Connection

ping github.com

Verify GitHub Access

curl -I https://api.github.com/repos/elanthia-online/lich-5/releases/latest

Check Firewall

Ensure outbound HTTPS (port 443) is allowed

Try Manual Download

Download from https://github.com/elanthia-online/lich-5/releases

Ruby Version Too Old

*** UPDATE ABORTED ***

Lich version 5.15.0 requires Ruby 3.1.0 or higher.
Your current Ruby version is 2.7.0.

Solution: Update Ruby first

DragonRealms: https://github.com/elanthia-online/lich-5/wiki/Documentation-for-Installing-and-Upgrading-Lich
GemStone IV: https://gswiki.play.net/Lich:Software/Installation

Snapshot Directory Full

Snapshots accumulate over time. To clean up old snapshots:

cd ~/lich/backup
ls -lt  # List by date

# Keep last 3, delete older ones
ls -t | tail -n +4 | xargs rm -rf

Update Breaks Something

Immediately rollback:

;lich5-update --revert

Then report the issue:

GitHub Issues: https://github.com/elanthia-online/lich-5/issues
Discord: Lich community server

Configuration

Configure update behavior

Installation

Initial Lich installation

Backup & Restore

Manual backup strategies

GitHub Releases

View all available versions

Get Started

Core Concepts

Script Development

Game Modules

Advanced

​Overview

​Update Channels

​Stable Channel (Main)

​Beta Channel

​Branch Updates (Advanced)

​Update Commands

​Check for Updates

​Install Updates

​Version Status

​Update Process Details

​1. Snapshot Creation

​2. Download and Extraction

​3. Ruby Version Check

​4. File Updates

​5. Core Files Update

​Snapshot and Rollback

​Create Manual Snapshot

​Rollback to Previous Version

​Individual File Updates

​Update a Script

​Update a Library File

​Update a Data File

​Branch Tracking

​Clear Branch Tracking

​Update Cache

​Autostart Updates

​Help Command

​Version Management

​Version Format

​Version Comparison

​Version Constants

​Troubleshooting

​Update Fails to Download

​Ruby Version Too Old

​Snapshot Directory Full

​Update Breaks Something

​Related Topics

Configuration

Installation

Backup & Restore

GitHub Releases

Build docs developers (and LLMs) love

Overview

Update Channels

Stable Channel (Main)

Beta Channel

Branch Updates (Advanced)

Update Commands

Check for Updates

Install Updates

Version Status

Update Process Details

1. Snapshot Creation

2. Download and Extraction

3. Ruby Version Check

4. File Updates

5. Core Files Update

Snapshot and Rollback

Create Manual Snapshot

Rollback to Previous Version

Individual File Updates

Update a Script

Update a Library File

Update a Data File

Branch Tracking

Clear Branch Tracking

Update Cache

Autostart Updates

Help Command

Version Management

Version Format

Version Comparison

Version Constants

Troubleshooting

Update Fails to Download

Ruby Version Too Old

Snapshot Directory Full

Update Breaks Something

Related Topics