Wrayth protocol

Wrayth protocol

The Wrayth protocol is the XML protocol used to pass information between the GemStone IV game server and front-end clients. It is utilized by the official Wrayth client and unofficial frontends.

Core System Elements

Element	Description	Key Attributes
mode	Game mode indicator	id (GAME, LOGIN, CMGR)
playerID	Player identifier	id (numeric)
settingsInfo	Client/game settings	client, major, crc, instance
app	Application metadata	char, game, title
endSetup	Marks end of initial setup	(none)

Examples

<mode id="GAME"/>
<playerID id='966483'/>
<settingsInfo client='1.0.1.28' major='19313' crc='3508957330' instance='GS4'/>
<endSetup/><app char="Nisugi" game="Prime" title="GemStone IV: Nisugi [Prime]"/>

Stream Management

Streams route text output to specific UI windows.

Element	Description	Key Attributes
streamWindow	UI window definition	id, title, subtitle, location, target, ifClosed, resident, save, scroll, timestamp
clearStream	Clear stream contents	id, ifClosed
pushStream	Push content to stream	id
popStream	Pop stream context	id
stream	Individual stream content line	id
exposeStream	Expose/show a stream	id

Stream Window IDs

Stream ID	Title	Purpose
main	Story	Main game output
room	Room	Room description display
inv	My Inventory	Worn items
Spells	Spells	Available spells list
familiar	Familiar	Familiar messages
thoughts	Thoughts	ESP/telepathy
logons	Arrivals	Player arrivals
death	Deaths	Death notices
speech	Speech	Speech window
ambients	Ambients	Ambient messages
announcements	Announcements	Game announcements
bounty	Bounties	Bounty task info
society	Society Tasks	Society task info
loot	Loot	Loot window
charprofile	Character's Profile	Character profile
charsheet	Character Sheet	Character sheet

Examples

<streamWindow id='room' title='Room' subtitle=" - [Icemule Trace, South Road]" location='center' target='drop' ifClosed='' resident='true'/>
<streamWindow id='inv' title='My Inventory' target='wear' ifClosed='' resident='true'/>
<streamWindow id="Spells" title="Spells" ifClosed="" resident="true" scroll="manual"/>
<clearStream id='inv' ifClosed=''/>
<pushStream id='inv'/>Your worn items are:
<popStream/>
<clearStream id="Spells"/>

Stream content example (thoughts/ESP):

<pushStream id="thoughts"/>You hear the faint thoughts of Nisugi echo in your mind:
"Hello everyone!"
<popStream/>

Component System

Components represent dynamic room/area content.

Element	Description	Key Attributes
compDef	Component definition	id
component	Component instance	id

Component IDs:

• room desc - Room description
• room objs - Room objects
• room players - Players in room
• room exits - Available exits
• sprite - Player's familiar/sprite

Examples

<compDef id='room players'></compDef>
<compDef id='room exits'>Obvious paths: <d>east</d>, <d>west</d></compDef>
<compDef id='sprite'></compDef>

<component id='room players'>Also here: Lord <a exist="-10939058" noun="Huras">Huras</a></component>
<component id='room players'></component>
<component id='room objs'>  You also see<b> <pushBold/>a <a exist="103330" noun="resident">disheveled resident</a><popBold/></b>.</component>

Container/Inventory System

Element	Description	Key Attributes
container	Container window	id, title, location, target, resident, save
exposeContainer	Expose container	id
clearContainer	Clear container contents	id
deleteContainer	Delete container from UI	id
inv	Inventory item line	id

Examples

Looking in a container:

<container id='393944944' title='Chest' target='#393944944' location='right'/>
<clearContainer id="393944944"/>
<inv id='393944944'>In the <a exist="393944944" noun="chest">chest</a>:</inv>
<inv id='393944944'> <a exist="393944946" noun="coins">some silver coins</a></inv>
<inv id='393944944'> a <a exist="393944945" noun="garnet">dark red-violet garnet</a></inv>

Stow container (default storage):

<exposeContainer id='stow'/>
<container id='stow' title="My Cloak" target='#225766691' location='right' save='' resident='true'/>
<clearContainer id="stow"/>
<inv id='stow'>In the <a exist="225766691" noun="cloak">cloak</a>:</inv>
<inv id='stow'> a <a exist="225766734" noun="feather">nacreous disir feather</a></inv>

Dialog System

Dialogs are UI panels with controls and data.

Element	Description	Key Attributes
openDialog	Create dialog window	id, type, title, location, target, height, width, resident
dialogData	Dialog content	id, clear
closeDialog	Close a dialog window	id
exposeDialog	Show a hidden dialog	id

Dialog IDs

Dialog ID	Purpose
combat	Combat controls
injuries	Injury display (player)
minivitals	Health/mana/stamina bars
stance	Stance indicator
expr	Experience/level info
encum	Encumbrance
Active Spells	Active spell list
Buffs	Active buffs
Debuffs	Active debuffs
Cooldowns	Ability cooldowns
mapMaster	Map controls
mapViewMain	Map view
espMasterDialog	ESP/telepathy controls
quick	Quick action bar (main)
quick-combat	Combat quick bar
quick-simu	Information quick bar
BetrayerPanel	Blood Points tracking
befriend	Friends & Enemies list
bank	Banking interface
injuries-{existID}	Target character injuries appraisal

Examples

Opening and populating a dialog:

<openDialog type='dynamic' id='minivitals' title='Stats' location='statBar'>
  <dialogData id='minivitals'></dialogData>
</openDialog>

<openDialog type='dynamic' id='stance' title='Stance' location='right' height='50' width='190' resident='true'>
  <dialogData id='stance'>
    <progressBar id='pbarStance' value='100' text='defensive (100%)' top='5' left='-5' height='16' width='160' align='n' tooltip='Percent of stance contributing to defense'/>
  </dialogData>
</openDialog>

Updating dialog data:

<dialogData id='combat'>
  <progressBar id='pbarStance' value='100' text='defensive (100%)' top='51' width='130' height='16' left='0' align='n' tooltip='Percent of stance contributing to defense'/>
</dialogData>

Banking dialog:

<dialogData id='bank'>
  <link id='depositallLnk' value='Deposit All' cmd='deposit all' align='w' top='30' left='0' height='30' width='90' echo='deposit all'/>
  <link id='wealthnotesLnk' value='Check Notes' cmd='wealth notes' align='e' top='30' left='0' height='30' width='90' echo='wealth notes'/>
  <closeButton id='closeMe' value='Close' cmd='' align='s' left='0' top='0' width='80'/>
</dialogData>
<exposeDialog id='bank'/>
<closeDialog id="bank"/>

Target Injuries Appraisal Dialog

When you appraise another character, a dynamic injuries dialog opens showing their wounds:

<openDialog type='dynamic' id='injuries-10070682' title='Dicate's Injuries' location='right'>
  <dialogData id='injuries'>
    <skin id='injuredSkin' name='InjuriesPanel'
          controls='nsys,leftArm,rightArm,rightLeg,leftLeg,head,rightFoot,leftFoot,rightHand,leftHand,rightEye,leftEye,back,neck,chest,abdomen'/>
    <closeButton id='cancel' value='Close' cmd=''/>
  </dialogData>
</openDialog>
<dialogData id="injuries-10070682">
  <image id="head" name="Injury1"/>
  <image id="neck" name="Injury2" cmd="tend Dicate neck" tooltip="tend Dicate's neck"/>
  <image id="rightArm" name="Injury3" cmd="tend Dicate right arm"/>
  ...
</dialogData>

Key Elements:

• Dialog ID: injuries-{existID} where existID is the target's object ID
• Body part images with injury levels: Injury1 (minor), Injury2 (moderate), Injury3 (severe)
• Clickable cmd attributes for tending wounds
• Body parts tracked: head, neck, rightArm, leftArm, rightLeg, leftLeg, rightHand, leftHand, chest, abdomen, back, rightEye, leftEye, rightFoot, leftFoot, nsys

UI Control Elements

Element	Description	Key Attributes
progressBar	Progress indicator	id, value, text, customText, top, left, height, width
cmdButton	Command button	id, value, cmd, echo, tooltip
dropDownBox	Dropdown selector	id, value, cmd, content_text, content_value
upDownEditBox	Numeric input	id, value, min, max
label	Text label	id, value, justify
link	Clickable link	id, value, cmd, echo, URL
menuLink	Menu link	id, value, exist, noun
image	UI image/button	id, name, cmd, echo, tooltip
radio	Radio button	id, value, text, cmd, group
skin	UI skin/theme	id, name, controls
closeButton	Close button	id, value, cmd
sep	Separator	(none)

Progress Bar IDs

ProgressBar ID	Dialog	Purpose
health	minivitals	Health bar (main)
health2	injuries	Health bar (injuries)
mana	minivitals	Mana bar
spirit	minivitals	Spirit bar
stamina	minivitals	Stamina bar
pbarStance	combat/stance	Stance indicator
encumlevel	encum	Encumbrance level
mindState	expr	Mind state (experience absorption)
nextLvlPB	expr	Progress to next level

Examples

Progress bars (vitals):

<progressBar id='health' value='100' text='health 223/223' customText='t' left='0%' top='0%' width='25%' height='100%'/>
<progressBar id='mana' value='98' text='mana 426/431' left='25%' customText='t' top='0%' width='25%' height='100%'/>
<progressBar id='spirit' value='100' text='spirit 10/10' left='50%' customText='t' top='0%' width='25%' height='100%'/>
<progressBar id='stamina' value='100' text='stamina 112/112' left='75%' customText='t' top='0%' width='25%' height='100%'/>
<progressBar id='encumlevel' value='0' text='None' top='5' left='-5' align='n' width='160' height='15'/>

Command buttons:

<cmdButton id='cmdDefStance' value='defense' cmd='_stance defensive' tooltip='Assume a Defensive Stance' echo='stance defensive' height='20' width='55' top='70' left='0' align='nw'/>
<cmdButton id='cmdTarget' value='target' cmd='target random' tooltip='Select a Random Target' height='20' width='55' top='93' left='0' align='nw'/>
<cmdButton id='cmdAttack' value='attack' cmd='attack' height='20' width='50' left='0' top='93' tooltip='Attack Current Target' align='ne'/>

Dropdown box:

<dropDownBox id='dDBStance' value="defensive" cmd='_stance %dDBStance%' content_text='offensive,advance,forward,neutral,guarded,defensive' content_value='offensive,advance,forward,neutral,guarded,defensive' align='n' top='70' left='0' height='20' width='80' tooltip='Stance Selection'/>

Labels:

<label id='encumblurb' value='You are not encumbered enough to notice.' top='10' left='0' align='n' width='160' height='50' justify='0'/>

Navigation Elements

Element	Description	Key Attributes
nav	Navigation/room info	rm (room ID)
compass	Compass container	(contains dir elements)
dir	Direction indicator	value (n, s, e, w, ne, nw, se, sw, up, down, out)

Examples

<nav rm='12345'/>
<compass><dir value="e"/><dir value="out"/></compass>
<compass><dir value="n"/><dir value="s"/><dir value="e"/><dir value="w"/></compass>

Interactive/Link Elements

Hyperlink Element (<a>)

Creates clickable links for objects, players, and coordinates.

Attribute	Description
exist	Game object ID (numeric, can be negative)
noun	Object noun/type
coord	Click coordinates (x,y format)
char	Character name (for player links)
game	Game code (GSIV, GST)

Examples

<a exist="225766824" noun="bandolier">leather bandolier</a>
<a exist="-11225598" noun="Ludge">Ludge</a>
<a exist="103330" noun="resident">disheveled resident</a>
<a exist="-10939058" noun="Huras">Huras</a>

Direct Command Link Element (<d>)

Creates clickable command links in text. When clicked, executes the command specified in the cmd attribute (or the tag contents if cmd is omitted). Commonly used for compass directions but works for any command.

Attribute	Description
cmd	Command to execute (optional - if omitted, executes tag contents as the command)

Examples

Compass directions (no cmd attribute - executes tag contents):

<compDef id='room exits'>Obvious paths: <d>east</d>, <d>west</d></compDef>
<compDef id='room exits'>Obvious exits: <d>northeast</d>, <d>out</d></compDef>

Movement message (with cmd attribute):

Lord <a exist="-10939058" noun="Huras">Huras</a> just went <d cmd='go west'>west</d>.

Store commands:

  shield: <d cmd="store SHIELD clear">an <a exist="412277454" noun="buckler">old krodera buckler</a></d> (<d cmd='store set'>put in sheath</d>)
  weapon: <d cmd="store WEAPON clear">a <a exist="412277485" noun="baselard">sleek gleaming steel baselard</a></d> (<d cmd='store set'>put in sheath</d>)

Character State Elements

Element	Description	Key Attributes
indicator	Status indicator	id, visible (y/n)
spell	Current prepared spell	(text content)
left	Left hand item	exist, noun
right	Right hand item	exist, noun
prompt	Command prompt	time (unix timestamp)
roundTime	Action round time	value (seconds)
castTime	Spell cast time	value (seconds)

Indicator IDs

Indicator ID	Status
IconKNEELING	Kneeling
IconPRONE	Prone
IconSITTING	Sitting
IconSTANDING	Standing
IconSTUNNED	Stunned
IconHIDDEN	Hidden
IconINVISIBLE	Invisible
IconDEAD	Dead
IconWEBBED	Webbed
IconJOINED	Joined group

Examples

Character state elements:

<indicator id='IconSTANDING' visible='y'/>
<indicator id='IconHIDDEN' visible='y'/>
<indicator id='IconHIDDEN' visible='n'/>
<indicator id='IconSTUNNED' visible='y'/>
<indicator id='IconINVISIBLE' visible='n'/>

<spell>None</spell>
<spell>Fire Spirit (111)</spell>

<left exist="394466807" noun="bow">ghezyte long bow</left>
<left exist="" noun=""/>
<right exist="417169523" noun="arrows">glowbark arrows</right>

<prompt time="1767310975">></prompt>
<roundTime value='1767333503'/>
<castTime value='1767250287'/>

Text Formatting Elements

Element	Description	Key Attributes
pushBold	Start bold text	(none)
popBold	End bold text	(none)
b	Bold wrapper	(none)
output	Output formatting/font switch	class
style	Text style	id (roomName, roomDesc, etc.)
preset	Styled action text	id (speech, whisper, thought)

Output Class Values

• <output class="mono"/> - Switch to monospace font
• <output class=""/> - Switch back to normal font

Examples

Bold text (monster highlighting):

<b> <pushBold/>a <a exist="103330" noun="resident">disheveled resident</a><popBold/></b>

Room styling:

<popBold/><resource picture="0"/><style id="roomName" />[Cobblestone Path]
<style id="roomDesc"/>The narrow cobblestone path winds between aged buildings...

Speech/whisper preset:

<preset id="whisper">(OOC) You whisper,</preset> "Rallying at 0d7d2dc1." to your group.
<preset id="whisper">(OOC) <a exist="-10070682" noun="Dicate">Dicate's</a> player whispers to the group,</preset> "Joined cluster group 0d7d2dc1."
<preset id="speech">Nisugi says,</preset> "Hello!"

Font switching:

<output class="mono"/>
   Name                            Mana     Known/Cast
   Minor Elemental Edge (902)        1          Yes
   Elemental Defense I (401)         1          Yes
<output class=""/>

Menu System

Element	Description	Key Attributes
menu	Menu container	id, path, cat_list
mi	Menu item	coord
menuImage	Image in menu	(for quick bar menus)

Settings/Flags System

Element	Description	Key Attributes
flag	Player setting flag	id, status (on/off), desc

Example flags:

• Player Log On, Player Log Off, Player Disconnect
• Room Names, Room Descriptions, Brief Room Description
• Monster Bold, Default Group Open

Examples

<flag id="Player Log On" status='off' desc="Show logon messages."/>
<flag id="Player Log Off" status='off' desc="Show logoff messages."/>
<flag id="Player Disconnect" status='off' desc="Show disconnection messages."/>
<flag id="Room Names" status='on' desc="Display the name of the room in which you are located."/>
<flag id="Room Descriptions" status='on' desc="Display room descriptions."/>
<flag id="Brief Room Description" status='off' desc="Display room descriptions in shortened form."/>
<flag id="Monster Bold" status='on' desc="Highlight monster names."/>
<flag id="Default Group Open" status='on' desc="Allow others to join your group."/>
<flag id="Automatically Activate ESP Amulets" status='on' desc="Activate items for THINKing automatically."/>
<flag id="Automatically Gather Coins" status='on' desc="Gather coins when searching your kills."/>

Client Settings (stgupd)

Used within <!-- CLIENT --> markers for client-side settings:

<!-- CLIENT --><stgupd><panels>...</panels><!-- ENDCLIENT -->
<!-- CLIENT --><stgupd><stream>...</stream><!-- ENDCLIENT -->

Nested Elements in stgupd

Element	Description
panels	Panel layout configuration
stream	Stream window settings
misc	Miscellaneous settings
toggles	Toggle settings
group	Group container (id: Left, Right)
w	Window configuration
m	Setting value
s	Toggle state

UI State Control

Monopolize Element

Element	Description
monopolize	Game takes exclusive control of a stream

When monopolize id="main" is set, the game blocks all other text/streams until released with monopolize id="".

Examples

<monopolize id="main"/>You get a room key from the innkeeper and wander off to your room...
... (inn rest sequence) ...
<indicator id='IconINVISIBLE' visible='n'/><monopolize id=""/><output class=""/>

Miscellaneous Elements

Element	Description	Key Attributes
switchQuickBar	Switch active quick bar	id
updateverbs	Update available verbs	default
cmdlist	Command list	(none)
cmdtimestamp	Command timestamp	data
pushInputState	Input state control	state
popInputState	Pop input state	(none)

Examples

<switchQuickBar id="quick"/>
<switchQuickBar id="quick-simu"/>
<switchQuickBar id="quick-combat"/>

Special Behaviors

Newline Suppression

Tags followed by newlines suppress newline output except for:

• <a> (hyperlinks)
• <pushBold> (bold start)

Mixed Content

Output contains both XML tags and plain text on the same lines. Parsers must handle interleaved content.

Negative Exist IDs

Room/NPC objects often have negative exist values (e.g., -11225598).

Common Attributes Reference

Category	Attributes
Layout	top, left, height, width, align, anchor_top, anchor_left, anchor_right, justify, location
Identity	id, exist, noun
Behavioral	cmd, echo, value, visible, resident, ifClosed
Content	title, subtitle, text, tooltip, content_text, content_value

Complete Element Summary

Total Unique Elements: 60+

Category	Count	Elements
Core	5	mode, playerID, settingsInfo, app, endSetup
Streams	6	streamWindow, clearStream, pushStream, popStream, stream, exposeStream
Components	2	compDef, component
Containers	5	container, exposeContainer, clearContainer, deleteContainer, inv
Dialogs	4	openDialog, dialogData, closeDialog, exposeDialog
Controls	12	progressBar, cmdButton, dropDownBox, upDownEditBox, label, link, menuLink, image, radio, skin, closeButton, sep
Navigation	3	nav, compass, dir
Interactive	2	a, d
Character State	7	indicator, spell, left, right, prompt, roundTime, castTime
Formatting	6	pushBold, popBold, b, output, style, preset
Menu	3	menu, mi, menuImage
Settings	1	flag
Miscellaneous	7	switchQuickBar, updateverbs, cmdlist, cmdtimestamp, pushInputState, popInputState, monopolize