XMLData

Overview

The XMLData class parses the game’s XML stream and provides real-time access to character status, room information, inventory, and other game state data. All properties are automatically updated as the game sends new information.

XMLData is a singleton - access properties directly via XMLData.property_name

Character Status

Health & Spirit

health

integer

Current health points

max_health

integer

Maximum health points

spirit

integer

Current spirit points

max_spirit

integer

Maximum spirit points

last_spirit

integer

Spirit value before last change (useful for death detection)

# Wait until health is restored
wait_until { XMLData.health == XMLData.max_health }

# Check if dead
if XMLData.spirit == 0 || XMLData.last_spirit == 0
  echo 'Dead!'
end

Mana & Stamina

mana

integer

Current mana points

max_mana

integer

Maximum mana points

stamina

integer

Current stamina points

max_stamina

integer

Maximum stamina points

# Wait for mana to regenerate
wait_while { XMLData.mana < 50 }

# Check stamina before running
if XMLData.stamina > 20
  fput 'run north'
end

Concentration (DragonRealms)

concentration

integer

Current concentration points (DR only)

max_concentration

integer

Maximum concentration points (DR only)

Character Info

name

string

Character name

game

string

Game identifier: ‘GSIV’, ‘GSPlat’, ‘DR’, ‘DRT’, ‘DRF’

player_id

string

Unique player ID

level

integer

Character level

next_level_text

string

Experience text (e.g., “10% remaining”)

next_level_value

integer

Experience percentage (0-100)

echo "Playing #{XMLData.name} in #{XMLData.game}"
echo "Level #{XMLData.level} - #{XMLData.next_level_text}"

Stance & Mind

stance_text

string

Current stance name (e.g., “offensive”, “guarded”)

stance_value

integer

Numeric stance value (0-100)

mind_text

string

Mind state text (e.g., “clear”, “muddled”)

mind_value

integer

Numeric mind value (0-100)

# Change to defensive stance
fput 'stance defensive' unless XMLData.stance_text == 'defensive'

# Wait for clear mind
wait_until { XMLData.mind_text == 'clear' }

Encumbrance

encumbrance_text

string

Short encumbrance text (e.g., “light”, “heavy”)

encumbrance_full_text

string

Full encumbrance description

encumbrance_value

integer

Numeric encumbrance value (0-100)

if XMLData.encumbrance_value > 50
  echo 'Too heavy! Dropping items...'
end

Room Information

room_title

string

Current room title including brackets: “[Room Name]”

room_description

string

Room description text

room_exits

array

Array of exit strings (e.g., [‘north’, ‘south’, ‘gate’])

room_exits_string

string

Formatted exit string from game

room_count

integer

Increments each time you move to a new room

room_id

integer

Unique room identifier (when available)

# Wait for movement
start_count = XMLData.room_count
fput 'go gate'
wait_until { XMLData.room_count > start_count }

echo "Arrived at: #{XMLData.room_title}"
echo "Exits: #{XMLData.room_exits.join(', ')}"

Time & Roundtime

server_time

integer

Current server time (Unix timestamp)

server_time_offset

float

Offset between local and server time

roundtime_end

integer

Server time when roundtime ends

cast_roundtime_end

integer

Server time when cast roundtime ends

last_pulse

integer

Last mana pulse time (Unix timestamp)

# Wait for roundtime to expire
wait_while { XMLData.roundtime_end > XMLData.server_time }

# Check time until next pulse
time_since_pulse = Time.now.to_i - XMLData.last_pulse
echo "#{60 - time_since_pulse} seconds until next pulse"

Status Indicators

indicator

hash

Hash of status indicators (bleeding, stunned, etc.) Values are ‘y’ or ‘n’

prepared_spell

string

Name of prepared spell, or “None”

# Check if stunned
if XMLData.indicator['IconSTUNNED'] == 'y'
  echo 'Stunned!'
end

# Check prepared spell
echo "Prepared: #{XMLData.prepared_spell}"

Injuries

injuries

hash

Hash of body locations with wound/scar dataStructure: { location => { 'wound' => rank, 'scar' => rank } }Locations: ‘head’, ‘neck’, ‘chest’, ‘abdomen’, ‘back’, ‘rightArm’, ‘leftArm’, ‘rightHand’, ‘leftHand’, ‘rightLeg’, ‘leftLeg’, ‘rightFoot’, ‘leftFoot’, ‘rightEye’, ‘leftEye’, ‘nsys’

injury_mode

integer

Display mode: 0 = wounds, 1 = scars, 2 = both

# Check for head wounds
if XMLData.injuries['head']['wound'] > 0
  echo "Head wound rank: #{XMLData.injuries['head']['wound']}"
end

# Find all wounded locations
XMLData.injuries.each do |location, data|
  if data['wound'] > 0
    echo "#{location}: rank #{data['wound']}"
  end
end

Tasks

bounty_task

string

Current bounty task description

society_task

string

Current society task description

Active Spells & Dialogs

dialogs

hash

Hash of dialog data from PSM 3.0, including active spells, buffs, debuffs, cooldownsStructure: { dialog_name => { spell_name => expiry_time } }

active_spells

hash

Legacy method - returns combined hash of all active spells with expiry times

# Check if a spell is active
if XMLData.active_spells.key?('Haste')
  expires = XMLData.active_spells['Haste']
  remaining = expires - Time.now
  echo "Haste expires in #{remaining.round} seconds"
end

# Check specific dialog category
XMLData.dialogs['Buffs'].each do |spell, expires|
  echo "#{spell}: #{(expires - Time.now).round}s"
end

DragonRealms Specific

dr_active_spells

hash

Hash of active spells with durations (DR only)

dr_active_spells_stellar_percentage

integer

Stellar Collector percentage (DR Moon Mage)

dr_active_spells_slivers

boolean

Whether character has slivers active (DR Moon Mage)

Familiar (GemStone)

familiar_room_title

string

Familiar’s current room title

familiar_room_description

string

Familiar’s room description

familiar_room_exits

array

Familiar’s available exits

Other Properties

stow_container_id

string

ID of the designated stow container

prompt

string

Current game prompt text

current_target_ids

array

Array of current target IDs

current_target_id

string

Primary target ID

room_window_disabled

boolean

Whether room window is disabled in current location

Usage Examples

Combat Monitoring

# Wait until healthy and ready
wait_until { 
  XMLData.health == XMLData.max_health &&
  XMLData.mana > 30 &&
  XMLData.indicator['IconSTUNNED'] != 'y' &&
  XMLData.roundtime_end <= XMLData.server_time
}

echo 'Ready for combat!'

Movement Tracking

start_room = XMLData.room_count
start_title = XMLData.room_title

fput 'go door'

if wait_until(5) { XMLData.room_count > start_room }
  echo "Moved from #{start_title} to #{XMLData.room_title}"
else
  echo 'Movement failed or timed out'
end

Buff Management

required_buffs = ['Haste', 'Spirit Defense', 'Elemental Defense']

required_buffs.each do |buff|
  unless XMLData.active_spells.key?(buff)
    echo "Missing #{buff} - recasting"
    # Cast spell logic here
  end
end

Core

Game Objects

Gemstone IV

DragonRealms

Utilities

Overview

Character Status

Health & Spirit

Mana & Stamina

Concentration (DragonRealms)

Character Info

Stance & Mind

Encumbrance

Room Information

Time & Roundtime

Status Indicators

Injuries

Tasks

Active Spells & Dialogs

DragonRealms Specific

Familiar (GemStone)

Other Properties

Usage Examples

Combat Monitoring

Movement Tracking

Buff Management

See Also

Build docs developers (and LLMs) love

Core

Game Objects

Gemstone IV

DragonRealms

Utilities

​Overview

​Character Status

​Health & Spirit

​Mana & Stamina

​Concentration (DragonRealms)

​Character Info

​Stance & Mind

​Encumbrance

​Room Information

​Time & Roundtime

​Status Indicators

​Injuries

​Tasks

​Active Spells & Dialogs

​DragonRealms Specific

​Familiar (GemStone)

​Other Properties

​Usage Examples

​Combat Monitoring

​Movement Tracking

​Buff Management

​See Also

Build docs developers (and LLMs) love

Overview

Character Status

Health & Spirit

Mana & Stamina

Concentration (DragonRealms)

Character Info

Stance & Mind

Encumbrance

Room Information

Time & Roundtime

Status Indicators

Injuries

Tasks

Active Spells & Dialogs

DragonRealms Specific

Familiar (GemStone)

Other Properties

Usage Examples

Combat Monitoring

Movement Tracking

Buff Management

See Also