Skip to main content

​
Overview

The Script class is the foundation of Lich’s script execution system. It manages script lifecycles, handles script-to-script communication, and provides methods for starting, stopping, and monitoring running scripts. All scripts run in isolated threads with their own execution context, but can communicate through shared buffers and the global script registry.

​
Class Methods

​
Script.start

Starts a new script and returns immediately.
​
script_name
string
required
Name of the script to start (without file extension)
​
args
string
Arguments to pass to the script
​
options
hash
Optional configuration hash
  • :quiet - Suppress startup messages
  • :force - Force start even if already running
  • :args - Alternative way to pass arguments
​
return
Script | nil
Returns the Script object if successful, nil if the script couldn’t be started
# Start a script with arguments
Script.start('hunting', 'kobolds')

# Start with options hash
Script.start('hunting', args: 'kobolds', quiet: true)

# Force restart a running script
Script.start('hunting', 'kobolds', force: true)

​
Script.run

Starts a script and waits for it to complete before returning.
​
script_name
string
required
Name of the script to run
​
args
string
Arguments to pass to the script
# Run a script and wait for completion
Script.run('sell-loot')
echo 'Loot sold!' # This runs after sell-loot finishes

​
Script.kill

Terminates a running script.
​
script_name
string
required
Name of the script to kill (case-insensitive regex match)
​
return
boolean
Returns true if script was found and killed, false otherwise
Script.kill('hunting')

​
Script.running?

Checks if a script is currently running.
​
script_name
string
required
Name of the script to check
​
return
boolean
Returns true if the script is running
if Script.running?('hunting')
  echo 'Already hunting'
else
  Script.start('hunting')
end

​
Script.pause / Script.unpause

Pauses or resumes a running script.
​
script_name
string
Name of script to pause/unpause. If omitted, pauses the current script.
​
return
boolean | Script
Returns true/false for named scripts, or the Script object when pausing self
# Pause another script
Script.pause('hunting')

# Pause current script
Script.pause

# Resume a paused script
Script.unpause('hunting')

​
Script.paused?

Checks if a script is paused.
​
script_name
string
required
Name of the script to check
​
return
boolean | nil
Returns true if paused, false if running, nil if not found

​
Script.list

Returns all running scripts (including hidden ones).
​
return
array
Array of all Script objects currently running
Script.list.each { |s| echo s.name }

​
Script.running

Returns visible running scripts (excludes hidden scripts).
​
return
array
Array of visible Script objects

​
Script.hidden

Returns only hidden scripts.
​
return
array
Array of hidden Script objects

​
Script.current

Gets the currently executing script object.
​
return
Script | nil
The Script object for the calling script, or nil if called outside a script
script_name = Script.current.name
echo "Running in: #{script_name}"

​
Script.exists?

Checks if a script file exists in the script directory.
​
script_name
string
required
Name of the script to look for
​
return
boolean
Returns true if the script file exists
if Script.exists?('hunting')
  Script.start('hunting')
else
  echo 'Script not found'
end

​
Script.version

Retrieve script version from header comments.
​
script_name
string
required
Name of the script
​
required_version
string
If provided, returns true/false if script version meets requirement
​
return
Gem::Version | boolean
Version object, or boolean if comparing versions
# Get version
version = Script.version('hunting')  # => Gem::Version

# Check if version meets requirement
if Script.version('hunting', '2.0.0')
  echo 'Version too old!'
end

​
Script.at_exit

Registers a block to run when the script exits. 
Script.at_exit {
  echo 'Cleaning up...'
  # Cleanup code here
}

​
Script.log

Writes a message to the script’s log file in the logs directory.
​
message
string
required
Message to write to the log
Script.log "Started hunting at #{Time.now}"

​
Script.db

Opens a SQLite database for the current script.
​
return
SQLite3::Database
Database connection object for the script
db = Script.db
db.execute('CREATE TABLE IF NOT EXISTS items (name TEXT)')

​
Script.open_file

Opens a data file specific to the current script.
​
extension
string
required
File extension (e.g., ‘txt’, ‘csv’)
​
mode
string
File mode (‘r’, ‘w’, ‘a’, etc.). Defaults to ‘r’
​
return
File
File handle for the script’s data file
# Write to script data file
Script.open_file('txt', 'w') { |f|
  f.puts "Data saved at #{Time.now}"
}

# Read from script data file
data = Script.open_file('txt', 'r').read

​
Instance Methods

​
name

The script’s name (without path or extension). 
script = Script.current
echo script.name  # => "hunting"

​
vars

Array of command-line arguments passed to the script. 
# Script started with: ;hunting kobolds --fast
script.vars[0]  # => "kobolds --fast" (full string)
script.vars[1]  # => "kobolds"
script.vars[2]  # => "--fast"

​
pause / unpause

Pauses or resumes the current script. 
Script.current.pause
Script.current.unpause

​
paused?

Checks if the script is paused.
​
return
boolean
Returns true if the script is paused

​
kill

Terminates the script. 
Script.current.kill if some_condition

​
exit / exit!

Exits the script. exit! skips at_exit handlers. 
exit           # Runs at_exit blocks
exit!          # Skips at_exit blocks
Script.exit!   # Class method version

​
Properties

​
quiet

Suppresses script start/stop messages. 
script = Script.current
script.quiet = true

​
hidden

Hides script from Script.running (but shows in Script.list). 
script = Script.current
script.hidden = true

​
want_downstream

Controls whether script receives game output in its buffer. 
script = Script.current
script.want_downstream = true

​
want_downstream_xml

Controls whether script receives raw XML game output. 
script.want_downstream_xml = true

​
ExecScript

ExecScript is a lightweight script type for one-off code execution.

​
ExecScript.start

Executes Ruby code as a script.
​
code
string
required
Ruby code to execute
​
options
hash
Options hash (:quiet, :name)
ExecScript.start('echo "Hello from exec!"', quiet: true)

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us