Proposed xGM protocol specifications

Table of Contents
• Revision information
• How to contribute
• Purpose of xGM
• Existing shortcomings
• Goals
• Data Types
• Client=>Server packets
  • Login Request (0x00)
  • Access Level Change Request (0x01)
  • Who's Online Request (0x02)
  • Who's Offline Request (0x03)
  • Who's Logging Out Request (0x04)
  • Show Queue Request (0x05)
  • Handle Queue Entry Request (0x06)
  • Account command request (0x07)
  • XGM Client Protocol Version (0x08)
  • XGM Server Protocol Version Request (0x09)
  • Reload script (0x0A)
  • Installed Scripts Request (0x0B)
  • Get Installed Script (0x0C)
  • Get Script Section Names Request (0x0D)
  • Get Script Section Request (0x0E)
  • Get Server Stats (0x0F)
  • Create Items (0x10)
• Server=>Client packets
  • Login Response (0x00)
  • Access Level Change Response (0x01)
  • Who's On/off/logging Response (0x02)
  • Show Queue Response (0x03)
  • Handle Queue Entry Response 1 (0x04)
  • Handle Queue Entry Response 2 (0x05)
  • Retrieve account names (0x06)
  • Retrieve account details (0x07)
  • Ban Duration response (0x08)
  • Account Add/Update/Remove response (0x09)
  • XGM Server Protocol Version Response (0x0A)
  • Script Reload response (0x0B)
  • Installed Scripts response (0x0C)
  • Get Script Response (0x0D)
  • Get Script Data Chunk (0x0E)
  • Get Script Section Names Response (0x0F)
  • Get Script Section Names Data Chunk (0x10)
  • Get Script Section Response (0x11)
  • Server Stat response (0x12)

Got any suggestions, criticisms or queries? Feel free to discuss them on the General discussions forum at sourceforge. Alternatively, you can email the details to any of the members of the project.

The xGM protocol is being devised to overcome some of the existing issues which relate to the way GM tools work.

• Require that a GM log into a normal UO client
• Requires the execution of speech commands, which kicks in the spam filter of the client
• Insufficient fine grained control over behaviour of commands
• Requires the overhead of items/characters that need to be created to support
• Does not support true administration of the server (only GM/counselor commands)

• Provide 4 layered security and access model providing layered functionality (player, counselor, GM, admin)
• Provide a fast and efficient mechanism for sending commands to the server (bypassing client)
• Provide a way to execute JS administration scripts on the server

Common Packets

UI08 commandByte;		// 0x00
UI08 username[30];
UI08 password[30];
UI08 clearanceRequested;	// takes values of 0->3

UI08 commandByte;		// 0x01
UI08 clearanceRequested;	// takes values of 0->3

UI08 commandByte;		// 0x02

UI08 commandByte;		// 0x03

UI08 commandByte;		// 0x04

UI08 commandByte;		// 0x05
UI08 queueNumber;		// 0 == counselor, 1 == GM

UI08 commandByte;		// 0x06
UI08 queueNumber;		// 0 == counselor, 1 == GM
SERIAL queryID;			// the query ID #

UI08 commandByte;		// 0x08
UI32 xgmClientVersion;

UI08 commandByte;		// 0x09

UI08 commandByte;		// 0x0F
UI08 statID;			// ID of the stat you want
//		0		# players online
//		1		# characters total
//		2		# items total
//		3		ping response
//		4		# accounts
//		5		Simulation cycles
//		6		# of races
//		7		# of regions
//		8		# of weather systems
//		9		time since last restart
//		10		time since last world save
//		11		last player logged in
//		12		# of GM pages
//		13		# of CNS pages
//		14		# of ghosts
//		15		# of murderers
//		16		# of blues
//		17		# of houses
//		18		total gold in circulation
//		19		peak connection count
//		20		# of GMs logged in
//		21		# of counselors logged in

Player packets

Counselor packets

GM packets

UI08 commandByte;		// 0x10
UI08 addType;			// 0 - single item, based on ID
				// 1 - single item, based on script #
				// 2 - single item, based on itemlist #
				// 3 - tiled items, based on ID
				// 4 - tiled items, based on script #
				// 5 - tiled items, based on itemlist #
SI16 x;				// x location to add to
SI16 y;				// y location to add to
SI08 z;				// z location to add to

Subcommand 0

UI16 itemID;			// Item ID
UI16 colour;			// item colour
UI08 type;			// item type
UI32 morex;			// morex
UI32 morey;			// morey
UI32 morez;			// morez
SI32 amount;			// amount to add

Subcommand 1

UI08 itemSect[32];		// Item entry number, 32 byte string (for DFNs)
UI16 colour;			// item colour
UI08 type;			// item type
UI32 morex;			// morex
UI32 morey;			// morey
UI32 morez;			// morez
SI32 amount;			// amount to add

Subcommand 2

UI08 itemlist[32];		// Item list number, 32 byte string (for DFNs)
UI16 colour;			// item colour
UI08 type;			// item type
UI32 morex;			// morex
UI32 morey;			// morey
UI32 morez;			// morez
SI32 amount;			// amount to add

Subcommand 3

UI16 itemID;			// Item ID
UI16 colour;			// item colour
UI08 type;			// item type
UI32 morex;			// morex
UI32 morey;			// morey
UI32 morez;			// morez
SI32 amount;			// amount to add
SI16 targX;			// target x
SI16 targY;			// target y
SI08 targZ;			// target z

Subcommand 4

UI08 itemSect[32];		// Item entry number, 32 byte string (for DFNs)
UI16 colour;			// item colour
UI08 type;			// item type
UI32 morex;			// morex
UI32 morey;			// morey
UI32 morez;			// morez
SI32 amount;			// amount to add
SI16 targX;			// target x
SI16 targY;			// target y
SI08 targZ;			// target z

Subcommand 5

UI08 itemlist[32];		// Item list number, 32 byte string (for DFNs)
UI16 colour;			// item colour
UI08 type;			// item type
UI32 morex;			// morex
UI32 morey;			// morey
UI32 morez;			// morez
SI32 amount;			// amount to add
SI16 targX;			// target x
SI16 targY;			// target y
SI08 targZ;			// target z

Administration packets

UI08 commandByte;		// 0x07
UI08 subCommand;
UI16 packetLength;
UI08 extraData[];		// any extra data (can be 0 length)

Subcommand 0 - Retrieve account names

No extra data

Subcommand 1 - Retrieve account details

SI32 acctID;

Subcommand 2 - Ban account

SI32 acctID;
SI32 banDuration;

Subcommand 3 - Add Account

UI08 username[30];
UI08 password[30];
UI08 comment[128];
SI32 status;
UI08 public;	// 0 == false, 1 == true
UI08 isxgm;	// 0 == false, 1 == true

Subcommand 4 - Remove Account

SI32 acctID;

Subcommand 5 - Update Account

SI32 acctID;
UI08 username[30];
UI08 password[30];
UI08 comment[128];
UI32 ipAddy[2];
UI32 ban_date;
UI32 ban_duration;
SI32 status;
UI08 public;	// 0 == false, 1 == true
UI08 isxgm;	// 0 == false, 1 == true

UI08 commandByte;		// 0x0A
UI08 scriptType;
//	items_def		0
//	npc_def			1
//	create_def		2
//	regions_def		3
//	misc_def		4
//	skills_def		5
//	location_def		6
//	menus_def		7
//	spells_def		8
//	tracking_def		9
//	newbie_def		10
//	titles_def		11
//	advance_def		12
//	trigger_def		13
//	necro_def		14
//	house_def		15
//	colors_def		16
//	spawn_def		17
//	html_def		18
//	race_def		19
//	polymorph_def		20
//	weathab_def		21
//	hard_items_def		22
//	command_def		23
//	msgboard_def		24
//	carve_def		25

//	INI file		50
//	Spawn Regions 		51
//	Regions 		51
//	Server.scp 		51
//	Spells.scp		51
//	commands.scp		51
//	JS scripts (all)	52

UI08 commandByte;		// 0x0B
UI08 scriptType;

UI08 commandByte;		// 0x0C
UI08 scriptType;
UI08 scriptName[64];

UI08 commandByte;		// 0x0D
UI08 scriptType;
UI08 scriptName[64];

UI08 commandByte;		// 0x0E
UI08 scriptType;
UI08 scriptName[64];
UI08 sectionName[64];

Common Packets

UI08 commandByte;		// 0x00
UI08 responseError;		// if any.  0 is clear, 1 == bad username/password, 2 == invalid clearance level
UI08 clearanceGranted;		// takes values of 0->3 (player->admin)

UI08 commandByte;		// 0x01
UI08 responseError;		// if any.  0 is clearance granted, 1 is clearance denied
UI08 clearanceGranted;		// takes values of 0->3 (player->admin)

UI08 commandByte;		// 0x02
UI16 numPlayers;
UI08 statusType;		// 0 == online, 1 == offline, 2 == logging		
struct
{
	SERIAL playerSerial;
	char   playerName[31];
} playerList[];

UI08 commandByte;		// 0x03
UI08 querySuccessful;		// 1 if true, 0 if false
UI16 numEntries;
struct
{
	SERIAL queryID;		// will be unique, handle to the request #
	SERIAL playerSerial;
	char   playerName[31];
	time_t startTime;
	UI08   priority;
	SERIAL personHandling;	// 0xFFFFFFFF if not being handled
} queueEntry[];

UI08 commandByte;		// 0x04
UI08 errorLevel;		// 0 if okay, 1 if insufficient privs, 2 if already taken

UI08 commandByte;		// 0x05
UI08 commandQueue;		// queue #, 0 == counselor, 1 == GM
SERIAL queryID;			// query identification
SERIAL playerHandling;		// serial of GM who will handle the ID

UI08 commandByte;	// 0x0A
UI32 serverXGMVersion;

UI08 commandByte;	// 0x12
UI08 statID;		// stat number, see CS0F

Subcommands 0, 1, 2, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21

UI32 count;		// count of item

Subcommand 3

time_t currentServerTime;	// the time of the server, as from a C time( NULL ) call

Subcommand 11

SERIAL character;

Player packets

Counselor packets

GM packets

Administration packets

UI08 commandByte;	// 0x06
SI32 accountCount;
struct
{
	UI08 name[30];
} accountNames[];

UI08 commandByte;	// 0x07
SI32 acctID;
UI08 username[30];
UI08 password[30];
UI08 comment[128];
UI32 ipAddy[2];
UI32 ban_date;
UI32 ban_duration;
SERIAL characters[5];
SI32 status;
UI08 countOfChars;
UI08 public;	// 0 == false, 1 == true
UI08 isbanned;	// 0 == false, 1 == true
UI08 isxgm;	// 0 == false, 1 == true
UI08 acctInUse;	// 0 == false, 1 == true
SERIAL inworld;	// serial of character in world

UI08 commandByte;	// 0x08
UI08 statusOK;		// 0 == ban accepted, 1 == not possible
SI32 acctID;
SI32 banDuration;
SI32 banStart;

UI08 commandByte;	// 0x09
UI08 statusOK;		// 0 == add accepted, 1 == add not possible, 2 == remove accepted, 3 == remove not possible, 4 == update accepted, 5 == update not possible
SI32 acctID;

UI08 commandByte;	// 0x0B
UI08 scriptReloaded;	
UI08 scriptReloadedError;	// 0 == no error, 1 == couldn't reload

UI08 commandByte;	// 0x0C
UI08 scriptReloaded;	
struct
{
	UI08 	scriptName[64];
	time_t	lastModifiedTime;
} scripts[];

UI08 commandByte;	// 0x0D
UI08 scriptNum;		
UI16 numChunks;		// Number of data chunks that will follow
UI32 scriptSize;	// size of script.  Do not rely on this for packet size

UI08 commandByte;	// 0x0E
UI08 scriptNum;		
UI16 chunkNum;		// chunk #
UI16 chunkSize;		// size of chunk
UI08 chunkData[];

UI08 commandByte;	// 0x0D
UI08 scriptNum;		
UI16 numChunks;		// Number of data chunks that will follow
UI32 scriptSections;	// Number of script sections

UI08 commandByte;	// 0x0E
UI08 scriptNum;		
UI16 chunkNum;		// chunk #
UI16 chunkSize;		// size of chunk
UI08 chunkData[];

UI08 commandByte;	// 0x0D
UI08 scriptNum;
UI08 sectionName[64];	// Section name being retrieved	
struct
{
	UI08 tagData[32];
	UI16 dataLength;
	UI08 data[dataLength];
};