Skip to main content
This guide will walk you through writing and running your first Lich script.

​
Prerequisites

Before you begin, make sure you have:
  • Lich 5 installed (see Installation)
  • A connection to DragonRealms or Gemstone IV
  • Basic familiarity with Ruby syntax

​
Your First Script

1

Create a script file

Create a new file called hello.lic in your Lich scripts directory:
hello.lic
# hello.lic - A simple greeting script

echo "Hello from Lich!"
echo "Your character: #{Char.name}"
echo "Current room: #{Room.current.title.first}"
The .lic extension tells Lich this is a script file.
2

Run the script

From within your game client, type:
;hello
You should see output like:
Hello from Lich!
Your character: YourName
Current room: [Town Square]
3

Stop the script

To stop a running script, use:
;kill hello

​
Basic Script Structure

A Lich script is a Ruby file with access to special methods and objects:
example.lic
# Output to the user (appears in script window)
echo "Starting script..."

# Send commands to the game
put "look"

# Wait for specific text from the game
waitfor "Obvious exits:"

# Get the next line from the game
line = get

# Output back to the main game window
respond "Script complete!"

​
Core Methods

​
Output Methods

echo

Display text in the script window only
echo "Debug info"

respond

Display text in the main game window
respond "Important message"

put

Send a command to the game
put "get sword"

fput

Send command and wait for prompt/roundtime
fput "cast at orc"

​
Waiting Methods

# Wait for specific text
waitfor "arrives."

# Wait with a timeout
matchtimeout 5, "arrives.", "leaves."

# Wait for roundtime to expire
waitrt?

# Wait for a condition
wait_until { Char.mana > 50 }

​
Accessing Game State

Lich provides real-time access to game state through several objects:

​
Character Information

Char.name        # Character name
Char.level       # Character level
Char.health      # Current health
Char.mana        # Current mana
Char.stamina     # Current stamina

​
Room Information

Room.current.title.first    # Room title
Room.current.description    # Room description
Room.current.exits          # Array of exits

​
Game Objects

# Find all NPCs in the room
GameObj.npcs.each do |npc|
  echo npc.name
end

# Check what's in your right hand
GameObj.right_hand.name

# Find items in the room
GameObj.loot.find { |obj| obj.name =~ /sword/ }

​
XML Data

XMLData.room_id              # Current room ID
XMLData.room_count           # Rooms visited this session
XMLData.roundtime_end        # When roundtime expires
XMLData.active_spells        # Hash of active spells

​
Script Management

​
Starting Scripts

# Start another script
start_script "myother"

# Start with arguments
start_script "hunter", ["dirge", "careful"]

# Force start (even if already running)
force_start_script "watcher"

​
Checking Scripts

# Check if a script is running
if running? "healer"
  echo "Healer is already active"
end

# List all running scripts
Script.list.each do |script|
  echo script.name
end

​
Script Cleanup

# Run code when script exits
before_dying {
  echo "Cleaning up..."
  fput "close my container"
}

# Exit the script
exit

​
Variables

​
Local Variables

target = "orc"
count = 0

loop do
  fput "attack #{target}"
  count += 1
  break if count > 10
end

​
Persistent Variables (UserVars)

# Save data between script runs
UserVars.last_hunt ||= Time.now
UserVars.kill_count ||= 0

UserVars.kill_count += 1
echo "Total kills: #{UserVars.kill_count}"

​
Session Variables (Vars)

# Share data between scripts
Vars.hunting_area = "Abandoned Mine"
Vars.group_leader = true

​
Common Patterns

​
Looping Until Condition

loop do
  break if Char.mana >= 50
  
  fput "stance defensive"
  pause 10
  fput "stance offensive"
end

​
Waiting for Game Events

# Wait for something to arrive
wait_until { GameObj.npcs.any? { |npc| npc.name =~ /merchant/ } }

# Wait for a buff to expire
wait_until { !Spell[101].active? }

​
Error Handling

begin
  fput "cast at troll"
  waitfor "Your spell hits the troll."
rescue
  echo "Something went wrong: #{$!}"
  exit
end

​
Example: Simple Healer

Here’s a complete working script that monitors health and heals when needed:
healer.lic
# healer.lic - Simple health monitor

min_health = 75

loop do
  if Char.health < min_health
    echo "Health low (#{Char.health}), healing..."
    
    fput "stance defensive"
    waitrt?
    
    fput "prep 1101"
    wait 3
    fput "cast"
    
    waitfor "A luminescent web briefly forms"
    
    # Wait until healed
    wait_until { Char.health >= min_health }
    echo "Healed to #{Char.health}"
  end
  
  pause 5
end
Run it with: ;healer

​
Script Arguments

Scripts can accept arguments from the command line:
loot.lic
# loot.lic - Pick up items matching a pattern

# Get argument from ;loot <item>
item_pattern = script.vars[1]

if item_pattern.nil?
  echo "Usage: ;loot <item pattern>"
  exit
end

# Find and get matching items
GameObj.loot.each do |item|
  if item.name =~ /#{item_pattern}/i
    fput "get #{item.noun}"
    waitrt?
  end
end

echo "Done looting!"
Usage: ;loot sword or ;loot coin

​
Next Steps

Core Concepts

Learn about Lich’s architecture and how it works

Script Development

Deep dive into writing more complex scripts

Global Methods

Explore all available scripting methods

API Reference

Complete API documentation

​
Tips

Use echo for debug output and respond for important messages that should appear in the game window.
Always use fput instead of put when you need to wait for the command to complete before continuing.
Be careful with infinite loops - always include a way to exit your script!
Scripts are automatically reloaded when you save changes, making development fast and iterative.

Build docs developers (and LLMs) love

Get started for freeTalk to us