Banner with text that reads 'Lurk Protocol'


Lurk Protocol version 2.3


This page contains the specifications of the Lurk Protocol, the binary network communications protocol by which the LURKMAN client and the ttydServ Lurk server abide. It was written by Dr. Seth Long.

Sections [hide]




Overview

The Lurk protocol is intended to support text-based MMORPG-style games, also known as MUDs (Multi-User Dimension). It consists of 14 types of message, some of which are primarily sent by servers and some by clients. Behavior and game rules are primarily defined by the server, and clients should expect that their character may be updated with different health, location, and wealth at any time. The server is responsible for all computation related to game rules, results of battles, or collecting gold. The client is responsible for communicating with the server and interacting with the player. The lurk protocol does not specifically contain support for increasing the experience of players. However, the server can allow players to increase their stats. For example, a server could allow an initial stat total of 150, but then for each 1,000 gold collected, increase the player's stats. This behavior is not required, but would allow gold to take on a role more like XP.

All protocol message begin with an 8-bit type, followed by 0 or more bytes of further information. The amount of bytes to be read can be determined by the type, and in some cases a message length field further into the message. Messages are listed below by type. Notes:
  • Variable-length text fields are sent without a null terminator. This doesn't include fixed-length text fields like room and player names. Fixed-length text fields must be null-terminated unless they are exactly the maximum size.
  • All numbers are sent little-endian. This makes things easy for x86 users at the expense of being unusual.
  • Except as noted (health), all integer fields are unsigned.


Protocol Messages


Message

Sent by the client to message other players. Can also be used by the server to send "presentable" information to the client (information that can be displayed to the user with no further processing). Clients should expect to receive this type of message at any time, and servers should expect to relay messages for clients at any time. If using this to send game information, the server should mark the message as narration.

Byte Meaning
0 Type, 1
1-2 Message Length, 16 bits unsigned.
3-34 Recipient Name, 32 bytes total.
35-64 Sender Name, 30 bytes total.
65-66 End of sender name, or narration marker.
67+ Message. Length was specified earlier.

Narration marking: For messages which are related to game narration, as opposed to from one player to another, the last two bytes of the sender name should be 0, then 1 (bytes 65 and 66). This does disallow narrator names longer than 30 characters. When relaying a message from one player to another, server authors should be careful to set byte 66 to 0 unless it is the last character of the player name. The recipient name is either 32 characters or null-terminated in the normal manner.


Change Room

Sent by the client only, to change rooms. If the server changes the room a client is in, it should send an updated room, character, and connection message(s) to explain the new location. If not, for example because the client is not ready to start or specified an inappropriate choice, and error should be sent.

Byte Meaning
0 Type, 2
1-2 Number of the room to change to. The server will send an error if an inappropriate choice is made.

Sequence for room entry: The server must accomplish a number of tasks when a player enters a room. The player should receive a ROOM, an updated CHARACTER for the player who just entered the room, 0-n CHARACTER messages describing other players or monsters in the room, and 0-n CONNECTION messages advertising connections from the current room. It should also send a CHARACTER message to every other player in the room announcing the new entry into the room. The server should send the ROOM message to the player first, followed by the new CHARACTER message showing the updated room, and then CONNECTION and CHARACTER in any order.


Fight

Initiate a fight against monsters. This will start a fight in the current room against the monsters which are presently in the room. Players with the join battle flag set, who are in the same room, will automatically join in the fight. The server will allocate damage and rewards after the battle, and inform clients appropriately. Clients should expect a slew of messages after starting a fight, especially in a crowded room. This message is sent by the client. If a fight should ensue in the room the player is in, the server should notify the client, but not by use of this message. Instead, the players not initiating the fight should receive an updated CHARACTER message for each entity in the room. If the server wishes to send additional narrative text, this can be sent as a MESSAGE. Note that this is not the only way a fight against monsters can be initiated. The server can initiate a fight at any time.

Byte Meaning
0 Type, 3


PVP Fight

Initiate a fight against another player. The server will determine the results of the fight, and allocate damage and rewards appropriately. The server may include players with join battle in the fight, on either side. Monsters may or may not be involved in the fight as well. This message is sent by the client. If the server does not support PVP, it should send error 8 to the client.

Byte Meaning
0 Type, 4
1-32 Name of target player


Loot

Loot gold from a dead player or monster. The server may automatically gift gold from dead monsters to the players who have killed them, or wait for a LOOT message. The server is responsible for communicating the results of the LOOT to the player, by sending an updated CHARACTER message. This message is sent by the client.

Byte Meaning
0 Type, 5
1-32 Name of target player


Start

Start playing the game. A client will send a CHARACTER message to the server to explain character stats, which the server may either accept or deny (by use of an ERROR message). If the stats are accepted, the server will not enter the player into the game world until it has received START. This is sent by the client. Generally, the server will reply with a ROOM, a CHARACTER message showing the updated room, and a CHARACTER message for each player in the initial room of the game.

Byte Meaning
0 Type, 6


Error

Notify the client of an error. This is used to indicate stat violations, inappropriate room connections, attempts to loot nonexistent or living players, attempts to attack players or monsters in different rooms, etc.

Byte Meaning
0 Type, 7
1 Error code. List is given below.
2-3 Error message length.
4+ Actual error message, of the specified length.
Error Codes
Code Meaning
0 Other (not covered by any below error code)
1 Bad room. Attempt to change to an inappropriate room
2 Player Exists. Attempt to create a player that already exists.
3 Bad Monster. Attempt to loot a nonexistent or not present monster.
4 Stat error. Caused by setting inappropriate player stats.
5 Not Ready. Caused by attempting an action too early, for example changing rooms before sending START or CHARACTER.
6 No target. Sent in response to attempts to loot nonexistent players, fight players in different rooms, etc.
7 No fight. Sent if the requested fight cannot happen for other reasons (i.e. no live monsters in room)
8 No player vs. player combat on the server. Servers do not have to support player-vs-player combat.


Accept

Sent by the server to acknowledge a non-error-causing action which has no other direct result. This is not needed for actions which cause other results, such as changing rooms or beginning a fight. It should be sent in response to clients sending messages, setting character stats, etc.

Byte Meaning
0 Type, 8
1 Type of action accepted.


Room

Sent by the server to describe the room that the player is in. This should be an expected response to CHANGEROOM or START. Can be re-sent at any time, for example if the player is teleported or falls through a floor. Outgoing connections will be specified with a series of CONNECTION messages. Monsters and players in the room should be listed using a series of CHARACTER messages.

Byte Meaning
0 Type, 9
1-2 Room number. This is the same room number used for CHANGEROOM
3-34 Room name, 32 bytes in length
35-36 Room description length
37+ Room description. This can be shown to the player.


Character

Sent by both the client and the server. The server will send this message to show the client changes to their player's status, such as in health or gold. The server will also use this message to show other players or monsters in the room the player is in or elsewhere. The client should expect to receive character messages at any time, which may be updates to the player or others. If the player is in a room with another player, and the other player leaves, a CHARACTER message should be sent to indicate this. In many cases, the appropriate room for the outgoing player is the room they have gone to. If the player goes to an unknown room, the room number may be set to a room that the player will not encounter (does not have to be part of the map). This could be accompanied by a narrative message (for example, "Glorfindel vanishes into a puff of smoke"), but this is not required.
The client will use this message to set the name, description, attack, defense, regen, and flags when the character is created. It can also be used to reprise an abandoned or deceased character.

Byte Meaning
0 Type, 10
1-32 Name of the player
33 Flags: Starting from the highest bit, Alive, Join Battle, Monster, Started, Ready. The lowest three are reserved for future use.
34-35 Attack
36-37 Defense
38-39 Regen
40-41 Health (signed)
42-43 Gold
44-45 Current room number (may be unknown to the player)
46-47 Description length
48+ Player description
Meaning of Flags
Flag Meaning
Alive Character is alive (1 = alive, 0 = not alive)
Join Battle Character will automatically join battles in the room they are in (1 = join battles, 0 = do not join battles)
Monster Character is a monster (1 = monster, 0 = player)
Started Character has started the game (1 = started, 0 = not started
Ready Character is ready to start the game (1 = started, 0 = not started

When a client uses CHARACTER to describe a new player, the server may (should) ignore the client's initial specification for health, gold, and room. The monster flag is used when describing monsters found in the game rather than other human players.


Game

Used by the server to describe the game. The initial points is a combination of attack, defense, and regen, and cannot be exceeded by the client when defining a new character. The stat limit is a hard limit for the combination for any player on the server regardless of experience. If unused, it should be set to 65535, the limit of the unsigned 16-bit integer. This message will be sent upon connecting to the server, and not re-sent.

Byte Meaning
0 Type, 11
1-2 Initial Points
3-4 Stat limit
5-6 Description Length
7+ Game description


Leave

Used by the client to leave the game. This is a graceful way to disconnect. The server never terminates, so it doesn't send LEAVE.

Byte Meaning
0 Type, 12


Connection

Used by the server to describe rooms connected to the room the player is in. The client should expect a series of these when changing rooms, but they may be sent at any time. For example, after a fight, a secret staircase may extend out of the ceiling enabling another connection. Note that the room description may be an abbreviated version of the description sent when a room is actually entered. The server may also provide a different room description depending on which room the player is in. So a description on the connection could read "A strange whirr is heard through the solid oak door", and the description attached to the message once the player has entered could read "Servers line the walls, softly lighting the room in a cacophony of red, green, blue, and yellow flashes".

Byte Meaning
0 Type, 13
1-2 Room number. This is the same room number used for CHANGEROOM
3-34 Room name, 32 bytes in length
35-36 Room description length
37+ Room description. This can be shown to the player.


Version

Sent by the server upon initial connection along with GAME. If no VERSION is received, the server can be assumed to support only LURK 2.0 or 2.1.

Byte Meaning
0 Type, 14
1 LURK major revision, as an 8-bit unsigned int
2 LURK minor revision, as an 8-bit unsigned int
3-4 Size of the list of extensions, in bytes.
5+ List of extensions.

The list of extensions is formatted like this:

Byte Meaning
0-1 Length of the first extension, as an unsigned 16-bit integer.
2+ First extension

At the end of the first extension, if there are more extensions, the length of the second extension will be found, then the second extension, and so on. The length of the list of extensions must be the same as stated in the "size of the list of extensions" above. Note that servers and clients are not required to support any extensions at all, and in this case are free to ignore the list. If no extensions are to be sent, the size of the list of extensions is 0. Clients are not required to send this message to the server unless they wish to notify the server that they support extensions. If no extensions are supported, clients can ignore the list of extensions by ignoring the number of bytes specified in the size of the list of extensions. In order to use an extension, the client must send the server a VERSION message indicating the version and list of extensions the client intends to use, which must be selected from the extensions the server offered when the initial connection was made.


Notes


Consider the following player and monster:

Name: Trudy
Description: Black Hat Security Expert
Gold: 10
Attack: 60
Defense: 30
Regen: 10
Status: ALIVE
Location: Broom Closet
Health: 100
Started: YES


Name: Glog
Description: A slimy and toothy character
Gold: 50
Attack: 20
Defense: 30
Regen: 100
Monster
Health: 100

 Trudy may or may not be able to defeat this monster, depending on the way the server calculates fight results. Suppose for example that in fighting each sustains the attack of the other in damage, minus the defense. In this case, Trudy receives no damage at all (20 attack from Glog, minus Trudy's 30 defense, leaves no damage). Glog receives 30 damage (60 attack from Trudy, minus 30 defense from Glog). However, Glog has a very high regen of 100. If the server allocates 10\% of the regen to health per turn, than Glog will receive a 10 point health increase, and Trudy will receive only 1 point increase. Still, in a few turns, Trudy defeats Glog. If, on the other hand, the server were to allocate 30\% of regen as gained health each turn, neither would defeat the other.
The exact method of calculation is a game design decision made at the server level. Clients should not attempt to calculate damage themselves, but expect to receive a CHARACTER message after each fight their player is involved in.