XML Protocol Reference

Complete reference for GemStone IV’s XML game protocol.

Protocol Overview

GemStone IV sends game data as a mix of plain text and XML tags. The XML tags provide structured information about game state, while plain text contains narrative content.

Example Stream

<prompt time="1699900000">&gt;</prompt>
<pushStream id="room"/>
<compDef id='room desc'/>
[Town Square Central]
<popStream/>
This is the center of town.
<compass>
<dir value="n"/>
<dir value="e"/>
<dir value="s"/>
<dir value="w"/>
</compass>

Core Tags

`<prompt>`

Indicates command prompt, includes server timestamp.

<prompt time="1699900000">&gt;</prompt>

Attribute	Description
`time`	Unix timestamp from server

`<pushStream>` / `<popStream>`

Redirects content to a named stream.

<pushStream id="combat"/>
You attack the troll!
<popStream/>

Common stream IDs:

main - Primary game output
room - Room descriptions
combat - Combat messages
speech - Character speech
whisper - Private messages
thoughts - Mental communications
death - Death messages
experience - Experience gains
logons - Login/logout notices
atmosphere - Ambient messages

`<clearStream>`

Clears a stream’s content.

<clearStream id="room"/>

`<component>`

Named data component for widgets.

<component id="room objs">a troll</component>
<component id="room players">Playername</component>
<component id="room exits">Obvious paths: north, south</component>

Common component IDs:

room objs - Objects in room
room players - Players in room
room exits - Exits description
room desc - Room description
room name - Room title

`<compDef>`

Component definition (marks component location).

<compDef id='room desc'/>

Vitals Tags

Health/Mana/Stamina/Spirit

<progressBar id="health" value="95"/>
<progressBar id="mana" value="100"/>
<progressBar id="stamina" value="87"/>
<progressBar id="spirit" value="100"/>

Attribute	Description
`id`	Vital type
`value`	0-100 percentage

Experience

<progressBar id="encumbrance" value="50"/>
<progressBar id="mindState" value="5"/>

Encumbrance Levels

Value	Description
0	None
1-20	Light
21-40	Moderate
41-60	Heavy
61-80	Very Heavy
81-100	Encumbered

Timing Tags

`<roundTime>`

Sets roundtime value.

<roundTime value="1699900005"/>

Attribute	Description
`value`	Unix timestamp when RT ends

`<castTime>`

Sets casttime value.

<castTime value="1699900003"/>

`<compass>`

Navigation directions available.

<compass>
<dir value="n"/>
<dir value="ne"/>
<dir value="e"/>
<dir value="se"/>
<dir value="s"/>
<dir value="sw"/>
<dir value="w"/>
<dir value="nw"/>
<dir value="up"/>
<dir value="down"/>
<dir value="out"/>
</compass>

Direction values:

n, ne, e, se, s, sw, w, nw - Cardinal/ordinal
up, down, out - Vertical/exit

Status Tags

`<indicator>`

Boolean status indicator.

<indicator id="IconHIDDEN" visible="y"/>
<indicator id="IconSTUNNED" visible="n"/>

Attribute	Description
`id`	Indicator identifier
`visible`	“y” or “n”

Common indicators:

IconHIDDEN - Hidden status
IconSTUNNED - Stunned
IconBLEEDING - Bleeding
IconPOISONED - Poisoned
IconDISEASED - Diseased
IconKNEELING - Kneeling
IconPRONE - Lying down
IconSITTING - Sitting
IconSTANDING - Standing
IconJOINED - In a group
IconDEAD - Dead

`<left>` / `<right>`

Hand contents.

<left>a steel sword</left>
<right>a wooden shield</right>

Empty hands show as:

<left>Empty</left>

`<spell>`

Currently prepared spell.

<spell>Fire Spirit</spell>

Combat Tags

`<a>` (Anchor/Link)

Clickable links in game text.

<a exist="123456" noun="troll">troll</a>

Attribute	Description
`exist`	Object existence ID
`noun`	Base noun for commands

Target Information

<component id="target">a massive troll</component>

Spell/Effect Tags

Active Spells

Spell list updates:

<pushStream id="spells"/>
<clearStream id="spells"/>
<spell>Spirit Warding I (101)</spell> - 30 min remaining
<spell>Spirit Defense (103)</spell> - 25 min remaining
<popStream/>

Active Effects

<dialogData id="ActiveSpells">
<progressBar id="spell_101" value="90" text="Spirit Warding I"/>
</dialogData>

Inventory Tags

Container Contents

<inv id="1234">
<item>a steel sword</item>
<item>3 silver coins</item>
</inv>

Equipment

<pushStream id="inv"/>
Equipment:
  armor: some full leather
  weapon: a steel broadsword
<popStream/>

Injury Tags

Body Part Injuries

<component id="injury_head">0</component>
<component id="injury_neck">0</component>
<component id="injury_chest">1</component>
<component id="injury_back">0</component>
<component id="injury_leftArm">2</component>
<component id="injury_rightArm">0</component>
<component id="injury_leftHand">0</component>
<component id="injury_rightHand">0</component>
<component id="injury_abdomen">0</component>
<component id="injury_leftLeg">0</component>
<component id="injury_rightLeg">0</component>
<component id="injury_leftFoot">0</component>
<component id="injury_rightFoot">0</component>
<component id="injury_leftEye">0</component>
<component id="injury_rightEye">0</component>
<component id="injury_nsys">0</component>

Injury values:

0 - No injury
1 - Minor injury
2 - Moderate injury
3 - Severe injury

Style Tags

`<preset>`

Applies named color preset.

<preset id="speech">Someone says, "Hello"</preset>
<preset id="whisper">Someone whispers, "Hello"</preset>

Common presets:

speech - Character speech
whisper - Whispers
thought - Mental communication
roomName - Room title
roomDesc - Room description
bold - Bold text

`<b>` / `<i>` / `<u>`

Basic text formatting.

<b>Bold text</b>
<i>Italic text</i>
<u>Underlined text</u>

`<d cmd="...>`

Command suggestion (clickable).

<d cmd="look troll">look at the troll</d>

Control Tags

`<mode>`

Client mode setting.

<mode id="GAME"/>

`<app>`

Application character information.

<app char="Charactername" game="GS4" />

`<output>`

Output control.

<output class="mono"/>

Special Tags

`<resource>`

External resource reference.

<resource picture="12345"/>

`<style>`

Inline style application.

<style id="roomName"/>

`<nav>`

Navigation region.

<nav rm="12345"/>

Parsing Considerations

Entity Encoding

Special characters are XML-encoded:

> → >
< → <
& → &
" → "
' → '

Nested Tags

Tags can nest:

<pushStream id="combat">
<preset id="thought">You sense <a exist="123" noun="creature">the creature</a></preset>
<popStream/>

Unclosed Tags

Some tags are self-closing or have implicit closure:

<prompt time="123">&gt;</prompt>
<dir value="n"/>
<progressBar id="health" value="95"/>

Implementation Notes

Stream Management

Push/pop streams form a stack
Multiple streams can be active
Text goes to all active streams
Clear affects only named stream

Component Updates

Components update atomically
Same ID replaces previous value
Clear stream clears related components

Timing Precision

Timestamps are Unix seconds
Client should convert to local time
Roundtime countdown based on server time

Keyboard shortcuts

Two-Face Documentation