Wrayth protocol: Difference between revisions

Latest revision as of 16:15, 4 January 2026

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  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

Wrayth protocol: Difference between revisions

Latest revision as of 16:15, 4 January 2026

Wrayth protocol

Core System Elements

Examples

Stream Management

Stream Window IDs

Examples

Component System

Examples

Container/Inventory System

Examples

Dialog System

Dialog IDs

Examples

Target Injuries Appraisal Dialog

UI Control Elements

Progress Bar IDs

Examples

Navigation Elements

Examples

Interactive/Link Elements

Hyperlink Element (<a>)

Examples

Direct Command Link Element (<d>)

Examples

Character State Elements

Indicator IDs

Examples

Text Formatting Elements

Output Class Values

Examples

Menu System

Settings/Flags System

Examples

Client Settings (stgupd)

Nested Elements in stgupd

UI State Control

Monopolize Element

Examples

Miscellaneous Elements

Examples

Special Behaviors

Newline Suppression

Mixed Content

Negative Exist IDs

Common Attributes Reference

Complete Element Summary

Navigation menu

Search

Hyperlink Element (`<a>`)

Direct Command Link Element (`<d>`)