# The dopewars network protocol

- Syntax used in this document
- General message format
- Starting a game from the client
- Server to client message reference
- Client to server message reference

## Syntax used in this document

`(runhere)`
  A single character field (equivalent to C's %c format).
`<ID>`
  A numeric field - an integer printed in text form, without spaces, commas or other punctuation. Note that the number is not stored directly as its binary representation, but as a string - i.e. "100" takes 3 characters (bytes), not one. Equivalent to C's %d format.
`"text"`
  Freeform text, equivalent to C's %s format.

Anything else should be taken as literal characters, which should appear in the message exactly as printed here.

## General message format

dopewars clients communicate with the dopewars server by means of a TCP/IP connection. Messages are sent in plain text, are of variable length, and are always terminated by a linefeed character ('\n', ASCII code 10)

Messages themselves are typically split into 'words', delimited by the caret (^) character. The underline character (_) is also used to break up translatable strings (tstrings), if the A_TSTRING ability is active, and thus these two characters, together with the \n character, should normally be avoided in message data.

Messages are usually of the format:-

`<ID>^(A)(C)"data"`
  `ID` = player ID (may also be blank if this is not applicable)
  `A` = one-letter message subtype code (used by AI players)
  `C` = one-letter message type code
  `data` = message-dependent information

e.g. "1^AFHello player"

If ID is not specified, it should be left blank when sending to the server, and should be ignored in reading messages from the server.

The "data" field often contains multiple items, separated by ^ characters. Note that the last field in such a message should not be assumed to be terminated by the message terminator, \n - although it always will be, it should also be first terminated by the field separator, the ^ character. This allows the client to ignore extra fields, if later versions of the protocol should add them. (N.B. This does not apply to free-form text fields, as in the C_QUESTION, C_PRINTMESSAGE, C_MSG, C_MSGTO, and C_FIGHTPRINT messages, which _do_ extend to the end of the message; for these messages, the caret is generally interpreted as a line break.) Note also that older servers may not send all the fields, so if fewer fields than expected are received, the client should substitute default values.

Message codes are shown below, together with the symbolic constants used in the dopewars code for clarity (e.g. the 'A' code is represented by C_PRINTMESSAGE)

For the AI codes, see the AICode type in src/message.h

N.B. Older versions of dopewars used a less sophisticated protocol:-

`"From"^"To"^(A)(C)"data"`
  `A`, `C`, and `data` are the same; however `"From"` and `"To"` are the player names (not IDs) of the players that the message is coming from and going to. Again, these can often be left blank. This old protocol is used if the A_PLAYERID ability is not present.

e.g. "Fred^Bert^AFHello player"

## Starting a game from the client

To start a game, the client must first notify the server of the protocol it can support (with the C_ABILITIES message) and then provide a suitable player name (with the C_NAME message). Note that both of these messages must be sent using the old protocol, as before protocol negotiation is complete (both server and client have sent a C_ABILITIES message) the server will default to using this protocol, for backwards compatibility. After sending these two messages, the game is run mainly by the server; the client should listen for incoming messages, and respond appropriately.

## Server to client message reference

The messages listed below may be sent from a dopewars server to the client. Most of these messages require some kind of processing to be done, and may require a response. The client cannot safely ignore such messages, as the server will not "retry" if the client does not respond.

C_PRINTMESSAGE ('`A`')
  Sent when the server wishes the client to display some text
  `data` = The text that the client should display; any ^ delimiters in this text should be taken to mean a new line.
  e.g. "^AAGame over^You made the high score list"
  Answer required: no

C_LIST ('`B`')
  Used by the server to tell the client about other logged on players
  `data` = `"name"^<ID>`
  `name` = the name of the player
  `ID` = the numeric ID that should be used to communicate with this player
  e.g. "^ABFred^1"
  Answer required: no

C_ENDLIST ('`C`')
  Signals that all players have been listed (no more C_LIST messages to come)
  e.g. "^AC"
  Answer required: no

C_NEWNAME ('`D`')
  Signals that the name provided by the client is unsuitable (usually, this is because it's already been taken by another player)
  N.B. This is always sent at the start of the game, before protocol negotiation, so uses the old format, e.g. "^^AD"
  Answer required: yes - must send a suitable C_NAME message to proceed

C_MSG ('`E`')
  Contains a message from one player (or the server admin) broadcast to all connected players.
  `data` = the message to display
  `ID` = the ID of the player that sent the message
  e.g. "1^AEHello world"
  Answer required: no

C_MSGTO ('`F`')
  Contains a private message from one player to another
  `data` = the message to display
  `ID` = the ID of the player that sent the message
  e.g. "1^AFHello player"
  Answer required: no

C_JOIN ('`G`')
  Sent by the server to all players when a new player joins the game (See C_LIST for format)
  Answer required: no

C_LEAVE ('`H`')
  Sent by the server to all players when a player leaves the game
  `data` = the name of the player that's leaving
  `ID` = the ID of the player
  e.g. "1^AHFred"
  Answer required: no

C_SUBWAYFLASH ('`I`')
  Used by the server to tell a client that it has just moved to a new location. (The client is not told where this location is, since this is information is contained in a C_UPDATE message.) Clients usually reset any location-dependent state (e.g. fights) on receiving this message, and flash a "subway" indicator or similar
  e.g. "^AI"
  Answer required: no

C_UPDATE ('`J`')
  Used by the server to update client state. This is also used to tell the player about the state of another player (a report from a spy)
  `data` = `<cash>^<debt>^<bank>^<health>^<coatsize>^<locn>^<turn>^<flags>^<GUNS>^<DRUGS>^<DRUGVALUE>^<bitches>`
  `cash`, `debt`, `bank` = money available, owed to the loan shark, in the bank
  `coatsize` = amount of space available for drugs/guns
  `locn` = zero-based game location
  `turn` = turn number
  `flags` = player status flags - see PlayerFlags in src/dopewars.h for the individual binary bits. The only one currently used is SPYINGON (16) which is set if the player is currently spying on one or more other players
  `GUNS` = the numbers of each gun carried, separated by ^ characters (there should be NumGun numbers in this list - see the C_INIT message)
  `DRUGS` = similar, for carried drugs
  `DRUGVALUE` = similar, but contains the total cash value of each drug; N.B. this field is only sent if the ability A_DRUGVALUE is present
  `bitches` = number of accompanying bitches
  `ID` = blank for a status update, otherwise the ID of the player that you're spying on
  Answer required: no

C_DRUGHERE ('`K`')
  Tells the client which drugs are available to buy at the current location
  `data` = drug prices, separated by ^ characters. If a price is zero, that drug is not available here
  Answer required: no

C_GUNSHOP ('`L`')
  Tells the client to start up the "gun shop", for buying/selling guns
  e.g. "^AL"
  Answer required: yes - zero or more C_BUYOBJECT messages, followed by a C_DONE message

C_LOANSHARK ('`M`')
  Tells the client that the player has a chance to pay back the loan
  e.g. "^AM"
  Answer required: yes - an optional C_PAYLOAN message, followed by a C_DONE message

C_BANK ('`N`')
  Tells the client that the player has a chance to visit the bank
  e.g. "^AN"
  Answer required: yes - an optional C_DEPOSIT message, followed by a C_DONE message

C_QUESTION ('`O`')
  Used to display a message from the server that requires a response
  `data` = `"keys"^"message"`
  `keys` = a list of the valid single-character responses - e.g. "YN" for a yes/no question; the client may use these keys directly, or expand them to complete words (e.g. YN -> Yes/No)
  `message` = the message to display
  e.g. "^AOYN^Would you like to visit the bank?"
  Answer required: yes - a C_ANSWER message, containing one of the valid response keys

C_HISCORE ('`Q`')
  Used for the server to tell the client about a high score; C_HISCORE messages should only ever be sent after a C_STARTHISCORE message and before a C_ENDHISCORE message
  `data` = `<index>^(B)"score"`
  `index` = the zero-based index of the high score (0 is the top score)
  `B` = the single character 'B' if this score should be displayed in bold (usually to indicate that it's "your" score) or 'N' otherwise
  `score` = the text containing the score, date, and player name
  Answer required: no

C_STARTHISCORE ('`R`')
  Tells the client that the server is about to send it a list of high scores; usually used by the client to display the title of a high score screen
  e.g. "^AR"
  Answer required: no

C_ENDHISCORE ('`S`')
  Tells the client that the server has sent all of the high scores; usually used by the client to display a prompt to end the game (if data="end") or to return to the game (if data is not "end")
  `data` = "end" if the game has finished, blank otherwise
  e.g. "^ASend"
  Answer required: no, but the client should disconnect if data="end"

C_PUSH ('`Z`')
  Requests that the client leave the server
  e.g. "^AZ"
  Answer required: no, but the client should disconnect

C_QUIT ('`a`')
  Notifies the client that the server is about to terminate
  e.g. "^Aa"
  Answer required: no, but the client should disconnect

C_RENAME ('`b`')
  Instructs the client that another player has changed his/her name
  `data` = the new player name
  `ID` = the player's ID
  e.g. "1^AbFred"
  Answer required: no

C_INIT ('`k`')
  Tells the client about various global game settings
  `data` = `"version"^<numloc>^<numgun>^<numdrug>^"bitch"^"bitches"^"gun"^"guns"^"drug"^"drugs"^"month"^"year"^<ID>^"loanshark"^"bank"^"gunshop"^"pub"^(prefix)"currency"`
  `version` = dopewars version of the server - e.g. "1.5.2"
  `numloc` = the number of locations in the game
  `numgun` = the number of guns in the game
  `numdrug` = the number of drugs in the game
  `bitch`, `bitches`, `gun`, `guns`, `drug`, `drugs`, `month`, `year`, `loanshark`, `bank`, `gunshop`, `pub` = various names used in the game
  `ID` = the ID that the client should use to refer to itself
  `prefix` = '1' if the currency symbol (e.g. $) should be printed before prices in the game, '0' otherwise
  `currency` = the currency symbol to use
  e.g. "^Ak1.5.2^8^4^12^bitch^bitches^gun^guns^drug^drugs^12-^-1984^0^the Loan Shark^the Bank^Dan's House of Guns^the pub"^1$
  Answer required: no

C_DATA ('`l`')
  Tells the client about various game settings - 4 variants on this message are possible:-
  Information about locations in the game
    `data` = `<index>^A"name"`
    `index` = zero-based index of the location
    `name` = name of the location
    e.g. "^Al0^ABronx"

  Information about drugs
    `data` = `<index>^B"name"^<min>^<max>` `index` = zero-based index of the drug
    `name` = name of the drug
    `min` = the minimum price of the drug
    `max` = the maximum price of the drug
    e.g. "^Al1^BCocaine^15000^29000"

  Information about guns
    `data` = `<index>^C"name"^<price>^<space>^<damage>`
    `index` = zero-based index of the gun
    `name` = name of the gun
    `price` = the normal cost of the gun
    `damage` = the maximum damage that the gun can do
    e.g. "^Al2^CRuger^2900^4^4"

  Miscellaneous information
    `data` = `0^D<spy>^<tipoff>`
    `spy` = the price to spy on another player
    `tipoff` = the price to tip off the cops to another player
    e.g. "^Al0^D20000^10000"
  Answer required: no

C_FIGHTPRINT ('`m`')
  `data` = `"attack"^"defend"^<health>^<bitches>^"bitchname"^<killed>^<armpct>^(fightpoint)(runhere)(loot)(canfire)^"text"`
  `attack` = name of the attacker player/cop if applicable (if blank, it's you)
  `defend` = name of the defending player/cop if applicable (if blank, it's you)
  `health` = defender's health, if applicable
  `bitches` = number of bitches/deputies accompanying the defending player
  `bitchname` = usually "bitch", "bitches", "deputy" or "deputies"
  `killed` = number of bitches killed in this attack
  `armpct` = a number between 0 and 100 showing how heavily armed the attacker is
  `fightpoint` =
  '`A`' (F_ARRIVED)
    The "defending" player has just arrived on the scene
  '`S`' (F_STAND)
    The "attacking" player chose not to shoot
  '`H`' (F_HIT)
    The "attacking" player fired on the defender, and hit
  '`M`' (F_MISS)
    The "attacking" player fired on the defender, and missed
  '`R`' (F_RELOAD)
    The "attacking" player is ready to fire again
  '`L`' (F_LEAVE)
    The "attacking" player has fled the fight, but other opponents remain
  '`D`' (F_LASTLEAVE)
    The "attacking" player has fled, and nobody else is present, so the fight is over
  '`F`' (F_FAILFLEE)
    The "attacking" player tried to get away, but failed
  '`G`' (F_MSG)
    Nothing exciting has happened, but "text" should still be displayed
  `runhere` = '1' if running should take you to the current location (if '0', you should jet to another location)
  `loot` = '1' if the attack resulted in a kill and a loot of the body
  `canfire` = '1' if you are allowed to shoot at other players right now
  `text` = explanatory text from the server, to be printed
  Answer required: yes, depending on the message contents: usually a C_REQUESTJET or C_FIGHTACT message

C_ABILITIES ('`r`')
  Negotiates protocol extensions between client and server
  `data` = `(playerid)(drugvalue)(newfight)(tstring)(donefight)`

  `playerid` = '1' if we use player IDs rather than player names to identify players in network messages ('0' otherwise). It is strongly recommended that this new protocol be used, as the old protocol is difficult to properly support, and is deprecated. However, the new protocol is only supported by servers of version 1.5.0 or above. (N.B. Since the old protocol does not support the C_ABILITIES message either, before the client and server have exchanged C_ABILITIES messages the server will "talk" using the old protocol. Thus, the C_ABILITIES message itself from the client, and any succeeding messages sent before the server sends C_ABILITIES back, must be sent using the old protocol. "Old" servers will ignore the C_ABILITIES message.) Ability name in dopewars code: A_PLAYERID

  `drugvalue` = '1' if the server should keep track of how much players paid for their drugs, so that they can see whether they're getting a good deal when they come to sell them ('0' otherwise). Ability name in dopewars code: A_DRUGVALUE

  `newfight` = '1' if we use the "new" fighting interface (documented here). Highly recommended. Ability name in dopewars code: A_NEWFIGHT

  `tstring` = '1' if names of drugs etc. should be sent in the translated string (tstring) notation; only necessary if you are supporting non-English languages. Ability name in dopewars code: A_TSTRING

  `donefight` = '1' if, when a fight finishes, the client is expected to send a C_DONE message to instruct the server to move on. (This is to allow the user to close the fight dialog before any new dialogs pop up.) Ability name in dopewars code: A_DONEFIGHT

  N.B. Only five abilities are listed here. Older servers or clients may not only not support some of these abilities, they may not even know of their existence (conversely, newer versions may add new abilities). Thus all servers and clients, if passed an unexpectedly short abilities string, should pad it out with zeroes. If passed a long string, it should be truncated. This will cause these extra (or unspecified) abilities to be unsupported. (The order of the abilities string should never change.)

  e.g. "^^Ar10100" (N.B. the double ^ is a feature of the "old" protocol)

## Client to server message reference

The messages are below are typically sent from the client to the server. Note that players do not communicate directly between each other, but always via. the server. Note also that some of these messages are also valid when sent from the server to the client.

C_MSG ('`E`')
  Contains a message from one player to be broadcast to all connected players
  `data` = the message to display
  e.g. "^AEHello world"

C_MSGTO ('`F`')
  Contains a private message from one player to another
  `data` = the message to display
  `ID` = the ID of the player to send the message to
  e.g. "1^AFHello player"

C_BUYOBJECT ('`T`')
  Requests the server to buy or sell an object
  `data` = `"type"^<index>^<amount>`
  `type` = "bitch", "gun" or "drug"
  `index` = the zero-based index of the gun/drug that you want to buy/sell, or zero if type="bitch"
  `amount` = the number of objects to buy (or, if negative, to sell)
  e.g. "^ATbitch^0^1"

C_DONE ('`U`')
  Sent by the client when it's finished with the loan shark, bank, or gun shop
  e.g. "^AU"

C_REQUESTJET ('`V`')
  Asks the server to jet to a new location (or to run from a fight)
  `data` = the numeric, zero-based, location to jet to
  e.g. "^AV2"

C_PAYLOAN ('`W`')
  Asks to pay back a loan to the loan shark
  `data` = the amount of money to pay back
  e.g. "^AW5000"

C_ANSWER ('`X`')
  Sends the reply to a previous question from the server
  `data` = the single character response
  e.g. "^AXY"

C_DEPOSIT ('`Y`')
  Asks to deposit money into (or withdraw money from) the bank
  `data` = the amount of money to deposit, or (if negative) the amount to withdraw
  e.g. "^AY10000"

C_NAME ('`c`')
  Sent by the client to register the player name with the server
  `data` = the player's name
  N.B. this is always sent at the start of the game, in which case the old format should be used, e.g. "^^AcFred"

C_SACKBITCH ('`d`')
  Requests that a bitch should be sacked
  e.g. "^Ad"

C_TIPOFF ('`e`')
  Asks the server to tip off the cops to another player
  `ID` = the player ID to tip off the cops to
  e.g. "1^Ae"

C_SPYON ('`f`')
  Asks the server to spy on another player
  `ID` = the player ID to spy on
  e.g. "1^Af"

C_WANTQUIT ('`g`')
  Tells the server that the client wishes to leave the game early
  e.g. "^Ag"

C_CONTACTSPY ('`h`')
  Asks the server to send back reports about all the players that we are currently spying on
  e.g. "^Ah"

C_REQUESTSCORE ('`j`')
  Asks the server to send back the high score list
  e.g. "^Aj"

C_FIGHTACT ('`n`')
  Responds to a previous C_FIGHTPRINT message
  `data` = "`F`", "`S`", or "`R`"
  `F` = return fire
  `S` = stand and take it (do not return fire)
  `R` = try to run away
  N.B. If "runhere" is not set in the C_FIGHTPRINT message, the "R" response should not be sent - a C_REQUESTJET message should be sent instead.
  e.g. "^AnF"

C_ABILITIES ('`r`')
  Notifies the server of supported protocol features. See the explanation for the corresponding server message.

  The client will receive this message in response to a previous C_ABILITIES message that it sent to the server. This reply message contains the abilities that the server is willing to support. The client should compare these to those that it previously offered, and then use only those abilities that both client and server support. (If the server does not support the new protocol, no C_ABILITIES reply message will be sent, and the client should assume that no abilities are supported.) The server will expect all client messages after the C_ABILITIES message to be compliant with these abilities.

  e.g.
  - client sends "11101" (supports everything except A_TSTRING)
  - server responds with "10110" (supports everything except A_DRUGVALUE and A_DONEFIGHT)
  - client should adopt the abilities "10100" ( A_PLAYERID and A_NEWFIGHT)

- Main index
  - Notes for developers

Last update: 29-04-2002